MooseX::Enumeration - a native attribute trait for enums
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!
This attribute trait makes it easier to work with enumerated types in Moose.
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.
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 );
is
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.
"did_pass"
"is_pass"
has status => ( traits => ["Enumeration"], is => "rw", enum => [qw/ pass fail /], handles => { did_pass => ["is", "pass"], didnt_pass => ["is", "fail"], } );
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"].
["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.
As a slightly more advanced option, which will only work for the long-hand version, you may match the value against a regular expression or any other value that may serve as a right-hand side for a match::simple match operation:
has status => ( traits => ["Enumeration"], is => "rw", enum => [qw/ pass fail skip todo /], handles => { is_pass => [ "is", qr{^pass$} ], is_fail => [ "is", "fail" ], is_other => [ "is", [qw(skip todo)] ], } );
assign
The Enumeration trait allows you to delegate to "assign":
has status => ( traits => ["Enumeration"], is => "ro", enum => [qw/ pass fail unknown /], handles => { "set_status_pass" => [ "assign", "pass" ], "set_status_fail" => [ "assign", "fail" ], "clear_status" => [ "assign", "unknown" ], } ); ...; $obj->set_status_pass; # sets the object's status to "pass"
It is possible to restrict allowed transitions by adding an extra parameter. In the following example you can only set the status to "pass" if the current status is "unknown", and you can only set the status to "fail" if the current status begins with "u" (effectively the same thing).
has status => ( traits => ["Enumeration"], is => "ro", enum => [qw/ pass fail unknown /], handles => { "set_status_pass" => [ "assign", "pass", "unknown" ], "set_status_fail" => [ "assign", "fail", qr{^u} ], "clear_status" => [ "assign", "unknown" ], } );
Calling set_status_pass if the status is already "pass" is conceptually a no-op, so is always allowed.
set_status_pass
Methods delegated to assign always return $self so are suitable for chaining.
$self
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. :-(
$obj->is_pass
$obj->status eq "pass"
is_pass
Please report any bugs to http://rt.cpan.org/Dist/Display.html?Queue=MooseX-Enumeration.
MooX::Enumeration — implementation of this for Moo.
Moose::Meta::TypeConstraint::Enum, Type::Tiny::Enum, Moose::Meta::Attribute::Native.
Toby Inkster <tobyink@cpan.org>.
This software is copyright (c) 2014, 2018 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.
To install MooseX::Enumeration, copy and paste the appropriate command in to your terminal.
cpanm
cpanm MooseX::Enumeration
CPAN shell
perl -MCPAN -e shell install MooseX::Enumeration
For more information on module installation, please visit the detailed CPAN module installation guide.