/ 
Class-Enumeration-v1.2.0
/ Class::Enumeration::Builder

NAME

Class::Enumeration::Builder - Builder module for enum classes

SYNOPSIS

# Setup enum class in a separate module and build it at compile time
use strict;
use warnings;
use feature 'state';

package TrafficLight;

# Pre-declare the to_string() method to prepare overriding stringification
use subs 'to_string';

# The 'counter' option overwrites the default ordinal number generator
# 'action' is a custom attribute
use Class::Enumeration::Builder (
  { counter => sub { state $i = 0; my $r = $i; $i += 2; $r } },
  GREEN  => { action => 'go' },
  ORANGE => { action => 'slow down' },
  RED    => { action => 'stop' }
);

sub to_string {
  my ( $self ) = @_;

  $self->action . ' if ' . $self->name
}

1

# Build enum class at compile time and export enum constants
use strict;
use warnings;

package ToastStatus;

# Choose an exporter module and set the 'export' option to true
use Exporter qw( import );
use Class::Enumeration::Builder
  { export => 1 },
  qw( bread toasting toast burnt );

1

# Build enum class at runtime
my $class = Class::Enumeration::Builder->import(
  { class => 'CoffeeSize' },
  BIG          => { ounces => 8 },
  HUGE         => { ounces => 10 },
  OVERWHELMING => { ounces => 16 }
);

DESCRIPTION

Class::Enumration::Builder builds enum classes. Each such class will be a child class of the abstract parent class Class::Enumeration. The builder prepares a list of enum objects. It optionally creates getters for custom attributes for each such object.

The import() class method implements the build process. The method returns the name of the enum class. The first argument of the import() method is an optional options HASH reference. The allowed options are:

  • class (a non-empty string)

    An enum class can be build at runtime. In this case The class option should be used to set the enum class name.

  • counter (a CODE reference)

    The counter option can be used to overwrite the default ordinal number generator. It should return a unique value for each enum object in the list. The values should be numeric and comparable in pairs using the <=> operator.

  • export (a boolean value)

    If the export option is set to true, the builder prepares enum constants that are stored in the variable @EXPORT_OK and it creates an :all tag that is part of the variable %EXPORT_TAGS. Any separately loaded exporter module like for example Exporter enables the feature to export enum constants.

  • predicate (a boolean value)

    If the predicate option is set to true, the builder creates is_*() predicate methods (object methods) for each enum object in the list.

  • prefix (a non-empty string)

    The prefix option can be used to specify a common prefix for the names of the enum objects in the list.

The remaining arguments of the import() method are the names of the enum objects in the list. If the enum objects have custom attributes, an additional attributes HASH reference is assigned to each name. If present all enum objects in the list have to have the same attribute names.

Class::Enumration::Builder is usually used in a separate module. In this case the build process happens at compile time. The enum class name equals the package name.

If you want to override the default stringification you have to pre-declare the to_string() before loading the builder.

AUTHOR

Sven Willenbuecher <sven.willenbuecher@gmx.de>

COPYRIGHT AND LICENSE

This software is copyright (c) 2025 by Sven Willenbuecher.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.