enum(3pm)

💖 enum — C style enumerated types and bitmask flags in Perl 💖

okay bestie, so this is enum(3pm) from the User Contributed Perl Documentation, and it's genuinely one of my faves. It is not a man page, it is a whole personality. 🌸

---

✨ NAME ✨

enum — C style enumerated types and bitmask flags in Perl

---

🦋 SYNOPSIS 🦋

like, just look at her:

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.

yes you read that right, you can change the start indexs mid-list, and the note about FreeBSD-2.2.5 is real, do NOT actually do the LOCK_ thing, import from Fnctl instead 💅

---

👑 DESCRIPTION 👑

So this module is for defining a set of constants with ordered numeric values, similar to the "enum" type in the C programming language. And also — plot twist — you can define bitmask constants, where every constant gets a value with exactly one bit set (like 1, 2, 4, 8, etc).

Now. What are enumerations even for, bestie? 🫶 Typical use: giving mnemonic names to indexes of arrays. Like, arrays 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";
}

The way that this not only reads easier but also gets typo-checked at compile time when you run under use strict?? Obsessed. Like, if you misspell Days_Fri as Days_Fry, you'll generate a compile error. slay ✨

---

🎀 BITMASKS 🎀

The BITMASK option lets you easily create the bitmask constants that functions like flock() and sysopen() use. And ngl they're highkey useful in your own code too, because they let you efficiently store many true/false options within a single integer. iconic behaviour fr fr.

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)

⚠️ warning bestie ⚠️ when you're using bitmasks, remember 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. 😭 The docs for these operators live 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 💀

not the bugs section, it's giving honesty:

• 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. lowkey important, don't forget it.
• 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.

---

okay that's the whole thing bestie, go forth and use enum, and remember: manual name enum, section 3pm, built for perl v5.36.0, dated 2022-10-13 🫶✨ no cap, you're gonna be so good at constants now. 💖