Type::Tiny::Enum - string enum type constraints
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];
...;
}
}This module is covered by the Type-Tiny stability policy.
Enum type constraints.
This package inherits from Type::Tiny; see that for most documentation. Major differences are listed below:
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.
valuesArrayref of allowable value strings. Non-string values (e.g. objects with overloading) will be stringified in the constructor.
constraintUnlike Type::Tiny, you cannot pass a constraint coderef to the constructor. Instead rely on the default.
inlinedUnlike Type::Tiny, you cannot pass an inlining coderef to the constructor. Instead rely on the default.
parentParent is always Types::Standard::Str, and cannot be passed to the constructor.
sorterSorters passed to the constructor. Instead, enum types can sort values based on the order the enum was originally defined in.
unique_valuesThe list of values but sorted and with duplicates removed. This cannot be passed to the constructor.
coercionIf coercion => 1 is passed to the constructor, the type will have a coercion using the closest_match method.
use_eqWhen generating Perl type checking code, Type::Tiny::Enum will traditionally test incoming strings for being valid using a single regular expression, unless Type::Tiny::XS is available and a faster XS check is possible.
From version 2.008006 onwards, if Type::Tiny::XS is unavailable, and the enum is "small" (five possible values or less), Type::Tiny::Enum will instead generate code like:
( $_ eq "foo" or $_ eq "bar" or $_ eq "baz" )... which benchmarks around 5% to 20% faster than /(?:ba[rz]|foo)/.
However, it is possible to manually indicate whether you prefer it to generate code using eq or regexps by setting use_eq to a boolean value in the constructor. (If use_eq is not passed to the constructor at all, Type::Tiny::Enum will try to guess the most efficient technique.)
If you know that certain values in your enumeration are more common than others, you can "front load" your enumeration with the most common values so that eq checks those first. This may allow you to speed up certain checks.
has car_colour => (
is => 'rw',
isa => Type::Tiny::Enum->new( use_eq => 1, values => [qw/
blue
red
grey
white
black
green
yellow
orange
purple
pink
/] );
);as_regexpReturns 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_matchReturns 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"); # ==> fooIt 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 ); # ==> quuxis_word_safeReturns 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.
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:
Statusis_Status( $value )assert_Status( $value )to_Status( $value )STATUS_DEADSTATUS_ALIVEMultiple enumerations can be exported at once:
use Type::Tiny::Enum (
Status => [ 'dead', 'alive' ],
TaxStatus => [ 'paid', 'pending' ],
);Arrayrefification calls values.
Please report any bugs to https://github.com/tobyink/p5-type-tiny/issues.
Moose::Meta::TypeConstraint::Enum.
Toby Inkster <tobyink@cpan.org>.
This software is copyright (c) 2013-2014, 2017-2025 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.
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.