Devel::Constants - translates constants back to named symbols
# 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";
Declaring constants is very convenient for writing programs, but as Perl often inlines them, retrieving their symbolic names can be tricky. This 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, from which you can retrieve their names as necessary.
Note that you must use Devel::Constants before
constant, 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 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. You can override both of these.
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 the main package you 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 in which to store the constant values and names:
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";
By default, Devel::Constants exports no subroutines. You can import its two helper functions optionally 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);
You may also import these functions with different names, if necessary. Pass the alternate name after the function name. Beware that this is the most fragile of all options. If you do not pass a name, 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;
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.
flag_to_names($flag, [ $package ])
$flagis the flag to decompose. The function does not modify it. The
$packageparameter is optional. If provided, it will use flags set in another package. In the NetPacket::TCP example above, you can use it to find the symbolic names of TCP packets, such as SYN or RST set on a NetPacket::TCP object.
to_name($value, [ $package ])
to_nameonly guarantees the same value, not the same semantics. See PSI::ESP if this is not acceptable.) As with flag_to_names, the optional
$packageparameter will look for constants declared in a package other than the current.
chromatic at wgz dot org, with thanks to "Benedict" at
Perlmonks.org for the germ of the idea
Thanks also to Tim Potter and Stephanie Wehner for NetPacket::TCP.
Version 1.01 released by Neil Bowers <neilb at cpan dot org>.
Copyright (c) 2001, 2005 chromatic. Some rights reserved.
This is free software. You may use, modify, and distribute it under the same terms as Perl 5.8.x itself.