Type::Tiny::Enum(3)   User Contributed Perl Documentation  Type::Tiny::Enum(3)


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

SYNOPSIS
       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];
             ...;
           }
         }

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

DESCRIPTION
       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 a lot 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
       o   Arrayrefification calls "values".

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

SEE ALSO
       Type::Tiny::Manual.

       Type::Tiny.

       Moose::Meta::TypeConstraint::Enum.

AUTHOR
       Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE
       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.

DISCLAIMER OF WARRANTIES
       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.38.2                      2024-03-13               Type::Tiny::Enum(3)