GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Class::Constant(3) User Contributed Perl Documentation Class::Constant(3)

Class::Constant - Build constant classes

    use Class::Constant NORTH, EAST, SOUTH, WEST;
    
    use Class::Constant
        NORTH => "north",
        EAST  => "east",
        SOUTH => "south",
        WEST  => "west;
    
    use Class::Constant
        NORTH => { x =>  0, y => -1 },
        EAST  => { x => -1, y =>  0 },
        SOUTH => { x =>  0, y =>  1 },
        WEST  => { x =>  1, y =>  0 };
    
    use Class::Constant
        NORTH => "north",
                 { x =>  0, y => -1 },
        EAST  => "east",
                 { x => -1, y =>  0 },
        SOUTH => "south",
                 { x =>  0, y =>  1 },
        WEST  => "west",
                 { x =>  1, y =>  0 };

Class::Constant allows you declaratively created so-called "constant classes". These are very much like enumerated types (as close as a typeless language like Perl can get, at least).

The classes generated by this module are modeled closely after Java's "typesafe enumeration" pattern, but with some added spice to make them more useful to Perl programs.

The simplese usage of Class::Constant is to use it to define a set of values for a user-defined "type". Consider a class that defines the four main compass points:

    package Direction;
    
    use Class::Constant NORTH, EAST, SOUTH, WEST;

This generates four constants which can be assigned to some variable:

    my $facing = Direction::NORTH;

There are two major differences between Class::Constant constants and constants created by the constant pragma:

  • Class::Constant constants have no inherent value, and as such only compare equal to themselves (but see "ORDINAL VALUES", eg:

        if ($facing == Direction::EAST) {
            print "you are facing east\n";
        }
        
  • Class::Constant constants are actually objects blessed into the package that created them, so they have a "type", of sorts:

        if ($facing->isa("Direction")) {
            ...
        }
        

Neither of these distinctions are particularly useful in this simple usage, but are useful when using the more advanced features of this module, described below.

Althought constants don't have a value as such, real values can be attached to them to be used when appropriate.

Stringification

Constants can be declared with a string that will be returned when the constant is stringified (eg by "print"). For example:

    use Class::Constant
        NORTH => "north",
        EAST  => "east",
        SOUTH => "south",
        WEST  => "west";

This makes the following possible:

    print "you are facing $facing\n";

Named sub-constants

You can also declare other constant values that are associated with a constant:

    use Class::Constant
        NORTH => { x =>  0, y => -1 },
        EAST  => { x => -1, y =>  0 },
        SOUTH => { x =>  0, y =>  1 },
        WEST  => { x =>  1, y =>  0 };

These sub-constants are accessed via "get_*" methods called on the constant object:

    move_player($facing->get_x, $facing->get_y);

Combining the two

Of course both a string value and named sub-constants can be declared at the same time:

    use Class::Constant
        NORTH => "north",
                 { x =>  0, y => -1 },
        EAST  => "east",
                 { x => -1, y =>  0 },
        SOUTH => "south",
                 { x =>  0, y =>  1 },
        WEST  => "west",
                 { x =>  1, y =>  0 };

Each constant has an internal value which is generated by Class::Constant as it creates the constants. These ordinal values are unique to a package, and are assigned sequentially to each constant create in that package. For example, in our Direction packages, the constants would receive ordinal values as follows:

    NORTH   0
    EAST    2
    SOUTH   1
    WEST    3

The ordinal value for a constant can be retrieved by calling the "get_ordinal" method on a constant object:

    my $ordinal = Direction::EAST->get_ordinal;

You can also retrieve a constant by its ordinal value using the class method "by_ordinal"

    my $west = Direction->by_ordinal(3);

These two methods are typically used together to fetch the "next" or "previous" constant in the sequence, eg:

    sub turn_left {
        my ($facing) = @_;
        return Direction->by_ordinal(($facing->get_ordinal - 1) % 4);
    }

Constant objects are blessed into the package in which they were declared. The Class::Constant "import" method also updates the packages' @ISA to make constant objects subclass Class::Constant::Object

Class::Constant::Object has "as_string" and "equals" methods, and also sets up overloading for the "" (stringification) and "==" and "!=" (equality) operators to use these methods. If you override these methods in your package, then Class::Constant::Object will arrange to call your methods instead.

"Can't locate constant with ordinal "%s" in package "%s""
The value passed to "by_ordinal" does not corespond to any constant in the named package. This usually means the value you've specified is greater than the number of declared constants.
"Can't locate named constant "%s" for "%s""
A named constant associated with a declared constant was not found. It was probably not defined; check your declarations.

Robert Norris <rob@eatenbyagrue.org>

<https://github.com/robn/Class-Constant>

Copyright (c) 2006-2010 Robert Norris. This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License v2.
2016-07-09 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.