perldoc > Type::Tiny::Enum

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