Type::Tiny::Enum

(source, CPAN)

version 2.006000

NAME
SYNOPSIS
STATUS
DESCRIPTION
BUGS
SEE ALSO
AUTHOR
COPYRIGHT AND LICENCE
DISCLAIMER OF WARRANTIES

#NAME

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

#SYNOPSIS

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

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 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.

CONTENTS