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

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.

SIMPLE USAGE

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.

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

ORDINAL VALUES

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

OVERLOADING

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.

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@eatenbyagrue.org>

REPOSITORY

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

COPYRIGHT

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.

cpanm Class::Constant

perl -MCPAN -e shell
install Class::Constant