NAME

Class::Constant - Build constant classes

SYNOPSIS

    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 };

DESCRIPTION

the Class::Constant manpage 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.

SIMPLE USAGE

The simplese usage of the Class::Constant manpage 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 the Class::Constant manpage constants and constants created by the constant pragma:

the Class::Constant manpage 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";
    }
```
the Class::Constant manpage 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.

CONSTANT VALUES

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 the Class::Constant manpage 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);
    }

OVERLOADING

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

the Class::Constant::Object manpage 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 the Class::Constant::Object manpage will arrange to call your methods instead.

DIAGNOSTICS

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.

AUTHOR

Robert Norris (rob@cataclysm.cx)

COPYRIGHT

Class::Constant - Build constant classes