/ 
Enum-Declare-0.03
/ Enum::Declare

NAME

Enum::Declare - Declarative enums with compile-time constants

SYNOPSIS

use Enum::Declare;

# Basic integer enum (auto-increments from 0)
enum Colour {
    Red,
    Green,
    Blue,
}

say Red;    # 0
say Green;  # 1
say Blue;   # 2

# Explicit values
enum HttpStatus {
    OK = 200,
    NotFound = 404,
    ServerError = 500,
}

# String enum
enum LogLevel :Str {
    Debug,
    Info,
    Warn = "warning",
}

say Debug;  # "debug"
say Warn;   # "warning"

# Bitflag enum (powers of 2)
enum Perms :Flags {
    Read,
    Write,
    Execute,
}

say Read;              # 1
say Write;             # 2
say Read | Write;      # 3

# Auto-exported constants
enum Colour :Export {
    Red,
    Green,
    Blue,
}

# Meta introspection
my $meta = Colour();
say $meta->count;              # 3
say $meta->name(0);            # "Red"
say $meta->value('Green');     # 1
say $meta->valid(2);           # 1
my @pairs = $meta->pairs;      # (Red => 0, Green => 1, Blue => 2)
my $names  = $meta->names;     # ['Red', 'Green', 'Blue']
my $values = $meta->values;    # [0, 1, 2]

DESCRIPTION

Enum::Declare provides a declarative enum keyword for defining enumerated types in Perl. Constants are installed as true constant subs at compile time and a metadata object is accessible via the enum name.

Attributes

Attributes are specified after the enum name with a colon prefix. Multiple attributes may be combined.

:Str

Values are strings. Variants without an explicit value default to their lowercased name.

:Flags

Values are assigned as ascending powers of 2 (1, 2, 4, 8, ...), suitable for use as bitflags.

:Export

Populates @EXPORT and @EXPORT_OK in the declaring package and adds Exporter to @ISA, allowing consumers to import the constants via use.

Explicit Values

Any variant may be given an explicit value with = VALUE. For integer enums subsequent variants auto-increment from the last explicit value. For string enums the value must be a quoted string.

enum Example {
    A = 10,
    B,          # 11
    C = 20,
    D,          # 21
}

Meta Object

Calling the enum name as a function returns an Enum::Declare::Meta object:

my $meta = EnumName();

Methods on the meta object:

names

Returns an arrayref of variant names.

values

Returns an arrayref of variant values.

name($value)

Returns the variant name for the given value.

value($name)

Returns the value for the given variant name.

valid($value)

Returns true if the value belongs to the enum.

pairs

Returns a flat list of name/value pairs.

count

Returns the number of variants.

match($value, \%handlers)

Exhaustive pattern match. Every variant must have a corresponding handler in the hash, or a _ wildcard default must be present. Dies with a Non-exhaustive match error if any variants are unhandled.

my $hex = Color()->match($val, {
    Red   => sub { '#ff0000' },
    Green => sub { '#00ff00' },
    Blue  => sub { '#0000ff' },
});

A wildcard _ handler catches any unmatched or unknown value:

my $label = Color()->match($val, {
    Red => sub { 'stop' },
    _   => sub { 'go' },
});

Each handler receives the matched value as its argument.

AUTHOR

LNATION <email@lnation.org>

BUGS

Please report any bugs or feature requests to bug-enum-declare at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Enum-Declare. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Enum::Declare

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION <email@lnation.org>.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)