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

FreeBSD Manual Pages

  
 
  

home | help
enum(3)		      User Contributed Perl Documentation	       enum(3)

NAME
       enum - C	style enumerated types and bitmask flags in Perl

SYNOPSIS
	 use enum qw(Sun Mon Tue Wed Thu Fri Sat);
	 # Sun == 0, Mon == 1, etc

	 use enum qw(Forty=40 FortyOne Five=5 Six Seven);
	 # Yes,	you can	change the start indexs	at any time as in C

	 use enum qw(:Prefix_ One Two Three);
	 ## Creates Prefix_One,	Prefix_Two, Prefix_Three

	 use enum qw(:Letters_ A..Z);
	 ## Creates Letters_A, Letters_B, Letters_C, ...

	 use enum qw(
	     :Months_=0	Jan Feb	Mar Apr	May Jun	Jul Aug	Sep Oct	Nov Dec
	     :Days_=0	Sun Mon	Tue Wed	Thu Fri	Sat
	     :Letters_=20 A..Z
	 );
	 ## Prefixes can be changed mid	list and can have index	changes	too

	 use enum qw(BITMASK:LOCK_ SH EX NB UN);
	 ## Creates bitmask constants for LOCK_SH == 1,	LOCK_EX	== 2,
	 ## LOCK_NB == 4, and LOCK_UN == 8.
	 ## NOTE: This example is only valid on	FreeBSD-2.2.5 however, so don't
	 ## actually do	this.  Import from Fnctl instead.

DESCRIPTION
       This module is used to define a set of constants	with ordered numeric
       values, similar to the "enum" type in the C programming language.  You
       can also	define bitmask constants, where	the value assigned to each
       constant	has exactly one	bit set	(eg 1, 2, 4, 8,	etc).

       What are	enumerations good for?	Typical	uses would be for giving
       mnemonic	names to indexes of arrays.  Such arrays might be a list of
       months, days, or	a return value index from a function such as
       localtime():

	 use enum qw(
	     :Months_=0	Jan Feb	Mar Apr	May Jun	Jul Aug	Sep Oct	Nov Dec
	     :Days_=0	Sun Mon	Tue Wed	Thu Fri	Sat
	     :LC_=0	Sec Min	Hour MDay Mon Year WDay	YDay Isdst
	 );

	 if ((localtime)[LC_Mon] == Months_Jan)	{
	     print "It's January!\n";
	 }
	 if ((localtime)[LC_WDay] == Days_Fri) {
	     print "It's Friday!\n";
	 }

       This not	only reads easier, but can also	be typo-checked	at compile
       time when run under use strict.	That is, if you	misspell Days_Fri as
       Days_Fry, you'll	generate a compile error.

BITMASKS
       The BITMASK option allows the easy creation of bitmask constants	such
       as functions like flock() and sysopen() use.  These are also very
       useful for your own code	as they	allow you to efficiently store many
       true/false options within a single integer.

	   use enum qw(BITMASK:	MY_ FOO	BAR CAT	DOG);

	   my $foo = 0;
	   $foo	|= MY_FOO;
	   $foo	|= MY_DOG;

	   if ($foo & MY_DOG) {
	       print "foo has the MY_DOG option	set\n";
	   }
	   if ($foo & (MY_BAR |	MY_DOG)) {
	       print "foo has either the MY_BAR	or MY_DOG option set\n"
	   }

	   $foo	^= MY_DOG;  ## Turn MY_DOG option off (set its bit to false)

       When using bitmasks, remember that you must use the bitwise operators,
       |, &, ^,	and ~.	If you try to do an operation like "$foo += MY_DOG;"
       and the MY_DOG bit has already been set,	you'll end up setting other
       bits you	probably didn't	want to	set.  You'll find the documentation
       for these operators in the perlop manpage.

       You can set a starting index for	bitmasks just as you can for normal
       enum values.  But if the	given index isn't a power of 2,	then it	won't
       resolve to a single bit and therefore will generate a compile error.
       Because of this,	whenever you set the BITFIELD: directive, the index is
       automatically set to 1.	If you wish to go back to normal enum mode,
       use the ENUM: directive.	 Similarly to the BITFIELD directive, the
       ENUM: directive resets the index	to 0.  Here's an example:

	 use enum qw(
	     BITMASK:BITS_ FOO BAR CAT DOG
	     ENUM: FALSE TRUE
	     ENUM: NO YES
	     BITMASK: ONE TWO FOUR EIGHT SIX_TEEN
	 );

       In this case, BITS_FOO, BITS_BAR, BITS_CAT, and BITS_DOG	equal 1, 2, 4
       and 8 respectively.  FALSE and TRUE equal 0 and 1.  NO and YES also
       equal 0 and 1.  And ONE,	TWO, FOUR, EIGHT, and SIX_TEEN equal, you
       guessed it, 1, 2, 4, 8, and 16.

BUGS
       Enum names can not be the same as method, function, or constant names.
       This is probably	a Good Thing[tm].

       No way (that I know of) to cause	compile	time errors when one of	these
       enum names get redefined.  IMHO,	there is absolutely no time when
       redefining a sub	is a Good Thing[tm], and should	be taken out of	the
       language, or at least have a pragma that	can cause it to	be a compile
       time error.

       Enumerated types	are package scoped just	like constants,	not block
       scoped as some other pragma modules are.

       It supports A..Z	nonsense.  Can anyone give me a	Real World[tm] reason
       why anyone would	ever use this feature...?

SEE ALSO
       There are a number of modules that can be used to define	enumerations:
       Class::Enum, enum::fields, enum::hash, Readonly::Enum, Object::Enum,
       Enumeration.

       If you're using Moose, then MooseX::Enumeration may be of interest.
       Type::Tiny::Enum	is part	of the Type-Tiny
       <https://metacpan.org/release/Type-Tiny>	distribution.

       There are many CPAN modules related to defining constants in Perl; here
       are some	of the best ones: constant, Const::Fast, constant::lexical,
       constant::our.

       Neil Bowers has written a review	of CPAN	modules	for definining
       constants <http://neilb.org/reviews/constants.html>, which covers all
       such modules.

REPOSITORY
       <https://github.com/neilb/enum>

AUTHOR
       Originally written by Byron Brummer (ZENIN), now	maintained by Neil
       Bowers <neilb@cpan.org>.

       Based on	early versions of the constant module by Tom Phoenix.

       Original	implementation of an interface of Tom Phoenix's	design by
       Benjamin	Holzman, for which we borrow the basic parse algorithm layout.

COPYRIGHT AND LICENSE
       Copyright 1998 (c) Byron	Brummer.  Copyright 1998 (c) OMIX, Inc.

       Permission to use, modify, and redistribute this	module granted under
       the same	terms as Perl itself.

perl v5.24.1			  2015-10-27			       enum(3)

NAME | SYNOPSIS | DESCRIPTION | BITMASKS | BUGS | SEE ALSO | REPOSITORY | AUTHOR | COPYRIGHT AND LICENSE

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

home | help