Type::Tiny::Enum - string enum type constraints

       Toby Inkster <tobyink@cpan.org>.

       Please report any bugs to <https://github.com/tobyink/p5-type-tiny/issues>.

       This software is copyright (c) 2013-2014, 2017-2023 by Toby Inkster.

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

       Enum type constraints.

       This package inherits from Type::Tiny; see that for most documentation.  Major differences are listed
       below:

   Constructors
       The "new" constructor from Type::Tiny still works, of course. But there is also:

       "new_union( type_constraints => \@enums, %opts )"
           Creates a new enum type constraint which is the union of existing enum type constraints.

       "new_intersection( type_constraints => \@enums, %opts )"
           Creates a new enum type constraint which is the intersection of existing enum type constraints.

   Attributes
       "values"
           Arrayref  of  allowable  value  strings.  Non-string  values  (e.g. objects with overloading) will be
           stringified in the constructor.

       "constraint"
           Unlike Type::Tiny, you cannot pass a constraint coderef to the  constructor.   Instead  rely  on  the
           default.

       "inlined"
           Unlike  Type::Tiny,  you  cannot  pass  an  inlining coderef to the constructor.  Instead rely on the
           default.

       "parent"
           Parent is always Types::Standard::Str, and cannot be passed to the constructor.

       "unique_values"
           The list of "values"  but  sorted  and  with  duplicates  removed.  This  cannot  be  passed  to  the
           constructor.

       "coercion"
           If  "coercion  =>  1"  is  passed  to  the  constructor,  the  type  will  have  a coercion using the
           "closest_match" method.

   Methods
       "as_regexp"
           Returns the enum as a regexp which strings can be checked  against.  If  you're  checking  alot  of
           strings, then using this regexp might be faster than checking each string against

             my $enum  = Type::Tiny::Enum->new(...);
             my $check = $enum->compiled_check;
             my $re    = $enum->as_regexp;

             # fast
             my @valid_tokens = grep $enum->check($_), @all_tokens;

             # faster
             my @valid_tokens = grep $check->($_), @all_tokens;

             # fastest
             my @valid_tokens = grep /$re/, @all_tokens;

           You can get a case-insensitive regexp using "$enum->as_regexp('i')".

       "closest_match"
           Returns the closest match in the enum for a string.

             my $enum = Type::Tiny::Enum->new(
               values => [ qw( foo bar baz quux ) ],
             );

             say $enum->closest_match("FO");   # ==> foo

           It  will  try  to find an exact match first, fall back to a case-insensitive match, if it still can't
           find one, will try to find a head substring match, and finally, if given an integer, will use that as
           an index.

             my $enum = Type::Tiny::Enum->new(
               values => [ qw( foo bar baz quux ) ],
             );

             say $enum->closest_match(  0 );  # ==> foo
             say $enum->closest_match(  1 );  # ==> bar
             say $enum->closest_match(  2 );  # ==> baz
             say $enum->closest_match( -1 );  # ==> quux

       "is_word_safe"
           Returns true if none of the values in the enumeration contain a non-word character.  Word  characters
           include letters, numbers, and underscores, but not most punctuation or whitespace.

   Exports
       Type::Tiny::Enum can be used as an exporter.

         use Type::Tiny::Enum Status => [ 'dead', 'alive' ];

       This will export the following functions into your namespace:

       "Status"
       is_Status( $value )
       assert_Status( $value )
       to_Status( $value )
       "STATUS_DEAD"
       "STATUS_ALIVE"

       Multiple enumerations can be exported at once:

         use Type::Tiny::Enum (
           Status    => [ 'dead', 'alive' ],
           TaxStatus => [ 'paid', 'pending' ],
         );

   Overloading
       •   Arrayrefification calls "values".

       THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT  ANY  EXPRESS  OR  IMPLIED  WARRANTIES,  INCLUDING,  WITHOUT
       LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

perl v5.40.1                                       2025-05-06                              Type::Tiny::Enum(3pm)

       Type::Tiny::Enum - string enum type constraints

       Type::Tiny::Manual.

       Type::Tiny.

       Moose::Meta::TypeConstraint::Enum.

       This module is covered by the Type-Tiny stability policy.

       Using via Types::Standard:

         package Horse {
           use Moo;
           use Types::Standard qw( Str Enum );

           has name    => ( is => 'ro', isa => Str );
           has status  => ( is => 'ro', isa => Enum[ 'alive', 'dead' ] );

           sub neigh {
             my ( $self ) = @_;
             return if $self->status eq 'dead';
             ...;
           }
         }

       Using Type::Tiny::Enum's export feature:

         package Horse {
           use Moo;
           use Types::Standard qw( Str );
           use Type::Tiny::Enum Status => [ 'alive', 'dead' ];

           has name    => ( is => 'ro', isa => Str );
           has status  => ( is => 'ro', isa => Status, default => STATUS_ALIVE );

           sub neigh {
             my ( $self ) = @_;
             return if $self->status eq STATUS_DEAD;
             ...;
           }
         }

       Using Type::Tiny::Enum's object-oriented interface:

         package Horse {
           use Moo;
           use Types::Standard qw( Str );
           use Type::Tiny::Enum;

           my $Status = Type::Tiny::Enum->new(
             name   => 'Status',
             values => [ 'alive', 'dead' ],
           );

           has name    => ( is => 'ro', isa => Str );
           has status  => ( is => 'ro', isa => $Status, default => $Status->[0] );

           sub neigh {
             my ( $self ) = @_;
             return if $self->status eq $Status->[0];
             ...;
           }
         }