NAME
    MooseX::Enumeration - a native attribute trait for enums

SYNOPSIS
    Given this class:

       package MyApp::Result {
          use Moose;
          use Types::Standard qw(Enum);
          has status => (
             is        => "rw",
             isa       => Enum[qw/ pass fail /],
          );
       }

    It's quite common to do this kind of thing:

       if ( $result->status eq "pass" ) { ... }

    But if you're throwing strings around, it can be quite easy to mistype
    them:

       if ( $result->status eq "apss" ) { ... }

    And the comparison silently fails. Instead, let's define the class like
    this:

       package MyApp::Result {
          use Moose;
          use Types::Standard qw(Enum);
          has status => (
             traits    => ["Enumeration"],
             is        => "rw",
             isa       => Enum[qw/ pass fail /],
             handles   => [qw/ is_pass is_fail /],
          );
       }

    So you can use the class like this:

       if ( $result->is_pass ) { ... }

    Yay!

DESCRIPTION
    This attribute trait makes it easier to work with enumerated types in
    Moose. (Hopefully a Moo implementation will follow soon.)

    It will only work on attributes which have an enum type constraint. This
    may be a Type::Tiny::Enum or may be a type constraint defined using
    Moose's built-in enum types.

  Type Constraint Shortcut
    This trait gives you a shortcut for specifying an enum type constraint:

       has status => (
          traits    => ["Enumeration"],
          is        => "rw",
          enum      => [qw/ pass fail /],   # instead of isa
       );

  Delegation
    The trait also allows you to delegate "is" to the attribute value.

       # the most longhanded form...
       #
       has status => (
          traits    => ["Enumeration"],
          is        => "rw",
          enum      => [qw/ pass fail /],
          handles   => {
             is_pass  => ["is", "pass"],
             is_fail  => ["is", "fail"],
          }
       );

    Note that above, we might have called the delegated method "did_pass"
    instead of "is_pass". You can call it what you like.

    To save typing, we offer some shorthands for common patterns.

       has status => (
          traits    => ["Enumeration"],
          is        => "rw",
          enum      => [qw/ pass fail /],
          handles   => {
             is_pass  => "is_pass",
             is_fail  => "is_fail",
          }
       );

    In the hashref values, we implicitly split on the first underscore, so
    "is_pass" is equivalent to `["is", "pass"]`.

    This is still repetitive, so how about...

       has status => (
          traits    => ["Enumeration"],
          is        => "rw",
          enum      => [qw/ pass fail /],
          handles   => [ "is_pass", "is_fail" ],
       );

    If an arrayref of delegates is given, it mapped like this:

       my %delegate_hash = map { $_ => $_ } @delegate_array;

    We can still go one better...

       has status => (
          traits    => ["Enumeration"],
          is        => "rw",
          enum      => [qw/ pass fail /],
          handles   => 1,
       );

    This will create a delegated method for each value in the enumeration.

PERFORMANCE
    As of version 0.003, `$obj->is_pass` actually benchmarks *faster* than
    `$obj->status eq "pass"`. The latter comparison can be accelerated using
    MooseX::XSAccessor but this module can not (yet) provide an XS version for
    `is_pass`. :-(

BUGS
    Please report any bugs to
    <http://rt.cpan.org/Dist/Display.html?Queue=MooseX-Enumeration>.

SEE ALSO
    Moose::Meta::TypeConstraint::Enum, Type::Tiny::Enum,
    Moose::Meta::Attribute::Native.

AUTHOR
    Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE
    This software is copyright (c) 2014 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.

