Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Devel::Constants(3)   User Contributed Perl Documentation  Devel::Constants(3)

NAME
       Devel::Constants	- translates constants back to 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
       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.

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

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

       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	known bitwise flags that are
	   combinations	of named constants.  It	can be very handy though.
	   $flag is the	flag to	decompose.  The	function does not modify it.
	   The $package	parameter 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 ])"
	   This	function resolves a value into its constant name.  This	does
	   not mean that the value necessarily comes from the constant,	but
	   merely 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, 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.

TODO
       o   figure out a	better way to handle "flag_to_names" (inefficient
	   algorithm)

       o   allow potential capture lists?

       o   sync	up better with allowed constant	names in "constant"

       o   evil	nasty Damianesque idea:	locally	redefining constants

AUTHOR
       chromatic "chromatic at wgz dot 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.

       Version 1.01 released by	Neil Bowers <neilb at cpan dot org>.

REPOSITORY
       <https://github.com/neilb/Devel-Constants>

COPYRIGHT
       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.

SEE ALSO
       o   constant

       o   Constant::Generate

	   Provides the	ability	to define constants, a reverse mapping
	   function, and more besides.

       o   <http://neilb.org/reviews/constants.html>

	   A review of all CPAN	modules	related	to the definition and
	   manipulation	of constants and read-only variables.

perl v5.24.1			  2015-10-21		   Devel::Constants(3)

NAME | SYNOPSIS | DESCRIPTION | FUNCTIONS | TODO | AUTHOR | REPOSITORY | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Devel::Constants&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help