NAME

Devel::Constants - Perl module to translate constants back to their named symbols

SYNOPSIS

        # must precede use constant
        use Devel::Constants 'flag_to_names';

        use constant A => 1;
        use constant B => 2;
        use constant C => 4;

        my $flag = A | B;
        print "Flag is: ", join(' and ', flag_to_names($flag) ), "\n";

DESCRIPTION

Declaring constants is very convenient for writing programs, but as they're often inlined by Perl, retrieving their symbolic names can be tricky. This is made worse with lowlevel modules that use constants for bit-twiddling.

Devel::Constants makes this much more manageable.

It silently wraps around the constant module, intercepting all constant declarations. It builds a hash, associating the values to their names. The names can then be retrieved as necessary.

Note that Devel::Constants must be used before constant is, or the magic will not work and you will be very disappointed. This is very important, and if you ignore this warning, the authors will feel free to laugh at you. At least a little.

By default, Devel::Constants will only intercept constant declarations within the same package that used the module. Also by default, it stores the constants for a package within a private (read, otherwise inaccessible) variable. Both of these can be overridden.

Passing the package flag to Devel::Constants with a valid package name will make the module intercept all constants subsequently declared within that package. For example, in package main one might say:

        use Devel::Constants package => NetPacket::TCP;
        use NetPacket::TCP;

All of the TCP flags declared within NetPacket::TCP are now available.

It is also possible to pass in a hash reference where the constant values and names wil be stored:

        my %constant_map;
        use Devel::Constants \%constant_map;

        use constant NAME       => 1;
        use constant RANK       => 2;
        use constant SERIAL     => 4;

        print join(' ', values %constant_map), "\n";

EXPORT

By default, Devel::Constants exports no subroutines. Its two helper functions can optionally be exported by passing them on the use line:

        use Devel::Constants qw( flag_to_names to_name );

        use constant FOO => 1;
        use constant BAR => 2;

        print flag_to_names(2);
        print to_name(1);

These functions may also be imported with different names, if necessary. Pass the alternate name after the function name. Beware that this is the most fragile of all options. If a name is not passed, Devel::Constants may become confused:

        # good
        use Devel::Constants 
                flag_to_names => 'resolve',
                'to_name';
        
        # WILL WORK IN SPITE OF POOR FORM (the author thinks he's clever)
        use Devel::Constants
                'to_name',
                flag_to_names => 'resolve';

        # WILL PROBABLY BREAK, SO DO NOT USE
        use Devel::Constants
                'to_name',
                package => WD::Kudra;

Passing the import flag will import any requested functions into the named package. This is occasionally helpful, but it will overwrite any existing functions in the named package. Be a good neighbor:

        use Devel::Constants
                import => 'my::other::namespace',
                'flag_to_names',
                'to_name';

Note that constant also exports subroutines, by design.

FUNCTIONS

flag_to_names($flag, [ $package ])

This function resolves a flag into its component named bits. This is generally only useful for flags known to be composed of named constants logically combined. It can be very handy though. The first parameter is required, and must be the flag to decompose. It is not modified. The second parameter is optional. If provided, it will use flags set in another package. In the NetPacket::TCP example above, it could be used to find the symbolic names of TCP packets, such as SYN or RST set on a NetPacket::TCP object.

to_name($value, [ $package ])

This function resolves a value into its constant name. This does not mean that the value was set by the constant, only that it has the same value as the constant. (For example, 2 could be the result of a mathematical operation, or it could be a sign to dump core and bail out. to_name only guarantees the same value, and not the same semantics. See PSI::ESP if this is not acceptable.) As with flag_to_names, the optional $package parameter will look for constants declared in a package other than the current.

HISTORY

• 0.20 (9 October 2001)

  Added to_name, %EXPORT_OK, 'import' flag Many small tweaks and renames Another step toward World Domination

• 0.10 (7 October 2001)

  Initial version.

TODO

• figure out a better way to handle flag_to_names (inefficient algorithm)

• allow potential capture lists?

• sync up better with allowed constant names in constant

• evil nasty Damianesque idea: locally redefining constants

AUTHOR

chromatic <chromatic@wgz.org>, with thanks to "Benedict" at Perlmonks.org for the germ of the idea (http://perlmonks.org/index.pl?node_id=117146).

Thanks also to Tim Potter and Stephanie Wehner for NetPacket::TCP, though they don't know it yet. :)

SEE ALSO

constant

cpanm Devel::Constants

perl -MCPAN -e shell
install Devel::Constants