.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Type::Tiny::Enum 3"
.TH Type::Tiny::Enum 3 2024-03-13 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Type::Tiny::Enum \- string enum type constraints
.SH SYNOPSIS
.IX Header "SYNOPSIS"
Using via Types::Standard:
.PP
.Vb 3
\&  package Horse {
\&    use Moo;
\&    use Types::Standard qw( Str Enum );
\&    
\&    has name    => ( is => \*(Aqro\*(Aq, isa => Str );
\&    has status  => ( is => \*(Aqro\*(Aq, isa => Enum[ \*(Aqalive\*(Aq, \*(Aqdead\*(Aq ] );
\&    
\&    sub neigh {
\&      my ( $self ) = @_;
\&      return if $self\->status eq \*(Aqdead\*(Aq;
\&      ...;
\&    }
\&  }
.Ve
.PP
Using Type::Tiny::Enum's export feature:
.PP
.Vb 4
\&  package Horse {
\&    use Moo;
\&    use Types::Standard qw( Str );
\&    use Type::Tiny::Enum Status => [ \*(Aqalive\*(Aq, \*(Aqdead\*(Aq ];
\&    
\&    has name    => ( is => \*(Aqro\*(Aq, isa => Str );
\&    has status  => ( is => \*(Aqro\*(Aq, isa => Status, default => STATUS_ALIVE );
\&    
\&    sub neigh {
\&      my ( $self ) = @_;
\&      return if $self\->status eq STATUS_DEAD;
\&      ...;
\&    }
\&  }
.Ve
.PP
Using Type::Tiny::Enum's object-oriented interface:
.PP
.Vb 4
\&  package Horse {
\&    use Moo;
\&    use Types::Standard qw( Str );
\&    use Type::Tiny::Enum;
\&    
\&    my $Status = Type::Tiny::Enum\->new(
\&      name   => \*(AqStatus\*(Aq,
\&      values => [ \*(Aqalive\*(Aq, \*(Aqdead\*(Aq ],
\&    );
\&    
\&    has name    => ( is => \*(Aqro\*(Aq, isa => Str );
\&    has status  => ( is => \*(Aqro\*(Aq, isa => $Status, default => $Status\->[0] );
\&    
\&    sub neigh {
\&      my ( $self ) = @_;
\&      return if $self\->status eq $Status\->[0];
\&      ...;
\&    }
\&  }
.Ve
.SH STATUS
.IX Header "STATUS"
This module is covered by the
Type-Tiny stability policy.
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Enum type constraints.
.PP
This package inherits from Type::Tiny; see that for most documentation.
Major differences are listed below:
.SS Constructors
.IX Subsection "Constructors"
The \f(CW\*(C`new\*(C'\fR constructor from Type::Tiny still works, of course. But there
is also:
.ie n .IP """new_union( type_constraints => \e@enums, %opts )""" 4
.el .IP "\f(CWnew_union( type_constraints => \e@enums, %opts )\fR" 4
.IX Item "new_union( type_constraints => @enums, %opts )"
Creates a new enum type constraint which is the union of existing enum
type constraints.
.ie n .IP """new_intersection( type_constraints => \e@enums, %opts )""" 4
.el .IP "\f(CWnew_intersection( type_constraints => \e@enums, %opts )\fR" 4
.IX Item "new_intersection( type_constraints => @enums, %opts )"
Creates a new enum type constraint which is the intersection of existing enum
type constraints.
.SS Attributes
.IX Subsection "Attributes"
.ie n .IP """values""" 4
.el .IP \f(CWvalues\fR 4
.IX Item "values"
Arrayref of allowable value strings. Non-string values (e.g. objects with
overloading) will be stringified in the constructor.
.ie n .IP """constraint""" 4
.el .IP \f(CWconstraint\fR 4
.IX Item "constraint"
Unlike Type::Tiny, you \fIcannot\fR pass a constraint coderef to the constructor.
Instead rely on the default.
.ie n .IP """inlined""" 4
.el .IP \f(CWinlined\fR 4
.IX Item "inlined"
Unlike Type::Tiny, you \fIcannot\fR pass an inlining coderef to the constructor.
Instead rely on the default.
.ie n .IP """parent""" 4
.el .IP \f(CWparent\fR 4
.IX Item "parent"
Parent is always \fBTypes::Standard::Str\fR, and cannot be passed to the
constructor.
.ie n .IP """unique_values""" 4
.el .IP \f(CWunique_values\fR 4
.IX Item "unique_values"
The list of \f(CW\*(C`values\*(C'\fR but sorted and with duplicates removed. This cannot
be passed to the constructor.
.ie n .IP """coercion""" 4
.el .IP \f(CWcoercion\fR 4
.IX Item "coercion"
If \f(CW\*(C`coercion => 1\*(C'\fR is passed to the constructor, the type will have a
coercion using the \f(CW\*(C`closest_match\*(C'\fR method.
.SS Methods
.IX Subsection "Methods"
.ie n .IP """as_regexp""" 4
.el .IP \f(CWas_regexp\fR 4
.IX Item "as_regexp"
Returns the enum as a regexp which strings can be checked against. If you're
checking \fIa lot\fR of strings, then using this regexp might be faster than
checking each string against
.Sp
.Vb 3
\&  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;
.Ve
.Sp
You can get a case-insensitive regexp using \f(CW\*(C`$enum\->as_regexp(\*(Aqi\*(Aq)\*(C'\fR.
.ie n .IP """closest_match""" 4
.el .IP \f(CWclosest_match\fR 4
.IX Item "closest_match"
Returns the closest match in the enum for a string.
.Sp
.Vb 3
\&  my $enum = Type::Tiny::Enum\->new(
\&    values => [ qw( foo bar baz quux ) ],
\&  );
\&  
\&  say $enum\->closest_match("FO");   # ==> foo
.Ve
.Sp
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.
.Sp
.Vb 3
\&  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
.Ve
.ie n .IP """is_word_safe""" 4
.el .IP \f(CWis_word_safe\fR 4
.IX Item "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.
.SS Exports
.IX Subsection "Exports"
Type::Tiny::Enum can be used as an exporter.
.PP
.Vb 1
\&  use Type::Tiny::Enum Status => [ \*(Aqdead\*(Aq, \*(Aqalive\*(Aq ];
.Ve
.PP
This will export the following functions into your namespace:
.ie n .IP """Status""" 4
.el .IP \f(CWStatus\fR 4
.IX Item "Status"
.PD 0
.ie n .IP "is_Status( $value )" 4
.el .IP "\f(CWis_Status( $value )\fR" 4
.IX Item "is_Status( $value )"
.ie n .IP "assert_Status( $value )" 4
.el .IP "\f(CWassert_Status( $value )\fR" 4
.IX Item "assert_Status( $value )"
.ie n .IP "to_Status( $value )" 4
.el .IP "\f(CWto_Status( $value )\fR" 4
.IX Item "to_Status( $value )"
.ie n .IP """STATUS_DEAD""" 4
.el .IP \f(CWSTATUS_DEAD\fR 4
.IX Item "STATUS_DEAD"
.ie n .IP """STATUS_ALIVE""" 4
.el .IP \f(CWSTATUS_ALIVE\fR 4
.IX Item "STATUS_ALIVE"
.PD
.PP
Multiple enumerations can be exported at once:
.PP
.Vb 4
\&  use Type::Tiny::Enum (
\&    Status    => [ \*(Aqdead\*(Aq, \*(Aqalive\*(Aq ],
\&    TaxStatus => [ \*(Aqpaid\*(Aq, \*(Aqpending\*(Aq ],
\&  );
.Ve
.SS Overloading
.IX Subsection "Overloading"
.IP \(bu 4
Arrayrefification calls \f(CW\*(C`values\*(C'\fR.
.SH BUGS
.IX Header "BUGS"
Please report any bugs to
<https://github.com/tobyink/p5\-type\-tiny/issues>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Type::Tiny::Manual.
.PP
Type::Tiny.
.PP
Moose::Meta::TypeConstraint::Enum.
.SH AUTHOR
.IX Header "AUTHOR"
Toby Inkster <tobyink@cpan.org>.
.SH "COPYRIGHT AND LICENCE"
.IX Header "COPYRIGHT AND LICENCE"
This software is copyright (c) 2013\-2014, 2017\-2023 by Toby Inkster.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
.SH "DISCLAIMER OF WARRANTIES"
.IX Header "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.