package Moose::Meta::Attribute::Native;
-our $VERSION = '1.12';
+our $VERSION = '1.18';
$VERSION = eval $VERSION;
our $AUTHORITY = 'cpan:STEVAN';
=head1 NAME
-Moose::Meta::Attribute::Native - Extend your attribute interfaces
+Moose::Meta::Attribute::Native - Delegate to native Perl types
=head1 SYNOPSIS
use Moose;
has 'mapping' => (
- traits => [ 'Hash' ],
- is => 'rw',
- isa => 'HashRef[Str]',
- default => sub { {} },
- handles => {
+ traits => ['Hash'],
+ is => 'rw',
+ isa => 'HashRef[Str]',
+ default => sub { {} },
+ handles => {
exists_in_mapping => 'exists',
ids_in_mapping => 'keys',
get_mapping => 'get',
},
);
-
- # ...
-
my $obj = MyClass->new;
$obj->set_quantity(10); # quantity => 10
$obj->set_mapping('foo', 4); # foo => 4
$obj->set_mapping('bar', 5); # bar => 5
$obj->set_mapping('baz', 6); # baz => 6
-
# prints 5
print $obj->get_mapping('bar') if $obj->exists_in_mapping('bar');
=head1 DESCRIPTION
-While L<Moose> attributes provide a way to name your accessors, readers,
-writers, clearers and predicates, this set of traits provides commonly
-used attribute helper methods for more specific types of data.
+Native delegations allow you to delegate to native Perl data
+structures as if they were objects. For example, in the L</SYNOPSIS> you can
+see a hash reference being treated as if it has methods named C<exists()>,
+C<keys()>, C<get()>, and C<set()>.
-As seen in the L</SYNOPSIS>, you specify the data structure via the
-C<trait> parameter. Available traits are below; see L</METHOD PROVIDERS>.
+The delegation methods (mostly) map to Perl builtins and operators. The return
+values of these delegations should be the same as the corresponding Perl
+operation. Any deviations will be explicitly documented.
-This module used to exist as the L<MooseX::AttributeHelpers> extension. It was
-very commonly used, so we moved it into core Moose. Since this gave us a chance
-to change the interface, you will have to change your code or continue using
-the L<MooseX::AttributeHelpers> extension. L<MooseX::AttributeHelpers> should
-continue to work.
+=head1 API
-=head1 PARAMETERS
+Native delegations are enabled by passing certain options to C<has> when
+creating an attribute.
-=head2 handles
+=head2 traits
-This is like C<< handles >> in L<Moose/has>, but only HASH references are
-allowed. Keys are method names that you want installed locally, and values are
-methods from the method providers (below). Currying with delegated methods
-works normally for C<< handles >>.
+To enable this feature, pass the appropriate name in the C<traits> array
+reference for the attribute. For example, to enable this feature for hash
+reference, we include C<'Hash'> in the list of traits.
-=head1 METHOD PROVIDERS
+=head2 isa
-=over
+You will need to make sure that the attribute has an appropriate type. For
+example, to use this with a Hash you must specify that your attribute is some
+sort of C<HashRef>.
-=item L<Number|Moose::Meta::Attribute::Native::Trait::Number>
+If you I<don't> specify a type, each trait has a default type it will use.
-Common numerical operations.
+=head2 handles
- has 'integer' => (
- traits => ['Number'],
- is => 'ro',
- isa => 'Int',
- default => 5,
- handles => {
- set => 'set',
- add => 'add',
- sub => 'sub',
- mul => 'mul',
- div => 'div',
- mod => 'mod',
- abs => 'abs',
- # ...
- }
- );
+This is just like any other delegation, but only a hash reference is allowed
+when defining native delegations. The keys are the methods to be created in
+the class which contains the attribute. The values are the methods provided by
+the associated trait. Currying works the same way as it does with any other
+delegation.
-=item L<String|Moose::Meta::Attribute::Native::Trait::String>
+See the docs for each native trait for details on what methods are available.
-Common methods for string operations.
+=head2 is
- has 'text' => (
- traits => ['String'],
- is => 'rw',
- isa => 'Str',
- default => q{},
- handles => {
- add_text => 'append',
- replace_text => 'replace',
- # ...
- }
- );
+Some traits provide a default C<is> for historical reasons. This behavior is
+deprecated, and you are strongly encouraged to provide a value. If you don't
+plan to read and write the attribute value directly, you can set C<< is =>
+'bare' >> to prevent standard accessor generation.
-=item L<Counter|Moose::Meta::Attribute::Native::Trait::Counter>
+=head2 default or builder
-Methods for incrementing and decrementing a counter attribute.
+Some traits provide a default C<default> for historical reasons. This behavior
+is deprecated, and you are strongly encouraged to provide a default value or
+make the attribute required.
- has 'counter' => (
- traits => ['Counter'],
- is => 'ro',
- isa => 'Num',
- default => 0,
- handles => {
- inc_counter => 'inc',
- dec_counter => 'dec',
- reset_counter => 'reset',
+=head1 TRAITS FOR NATIVE DELEGATIONS
+
+=over
+
+=item L<Array|Moose::Meta::Attribute::Native::Trait::Array>
+
+ has 'queue' => (
+ traits => ['Array'],
+ is => 'ro',
+ isa => 'ArrayRef[Str]',
+ default => sub { [] },
+ handles => {
+ add_item => 'push',
+ next_item => 'shift',
# ...
}
);
=item L<Bool|Moose::Meta::Attribute::Native::Trait::Bool>
-Common methods for boolean values.
-
has 'is_lit' => (
- traits => ['Bool'],
- is => 'rw',
- isa => 'Bool',
- default => 0,
- handles => {
+ traits => ['Bool'],
+ is => 'ro',
+ isa => 'Bool',
+ default => 0,
+ handles => {
illuminate => 'set',
darken => 'unset',
flip_switch => 'toggle',
}
);
-=item L<Hash|Moose::Meta::Attribute::Native::Trait::Hash>
+=item L<Code|Moose::Meta::Attribute::Native::Trait::Code>
-Common methods for hash references.
+ has 'callback' => (
+ traits => ['Code'],
+ is => 'ro',
+ isa => 'CodeRef',
+ default => sub {
+ sub {'called'}
+ },
+ handles => {
+ call => 'execute',
+ # ...
+ }
+ );
+
+=item L<Counter|Moose::Meta::Attribute::Native::Trait::Counter>
+
+ has 'counter' => (
+ traits => ['Counter'],
+ is => 'ro',
+ isa => 'Num',
+ default => 0,
+ handles => {
+ inc_counter => 'inc',
+ dec_counter => 'dec',
+ reset_counter => 'reset',
+ # ...
+ }
+ );
+
+=item L<Hash|Moose::Meta::Attribute::Native::Trait::Hash>
has 'options' => (
- traits => ['Hash'],
- is => 'ro',
- isa => 'HashRef[Str]',
- default => sub { {} },
- handles => {
+ traits => ['Hash'],
+ is => 'ro',
+ isa => 'HashRef[Str]',
+ default => sub { {} },
+ handles => {
set_option => 'set',
get_option => 'get',
has_option => 'exists',
}
);
-=item L<Array|Moose::Meta::Attribute::Native::Trait::Array>
-
-Common methods for array references.
+=item L<Number|Moose::Meta::Attribute::Native::Trait::Number>
- has 'queue' => (
- traits => ['Array'],
- is => 'ro',
- isa => 'ArrayRef[Str]',
- default => sub { [] },
- handles => {
- add_item => 'push',
- next_item => 'shift',
+ has 'integer' => (
+ traits => ['Number'],
+ is => 'ro',
+ isa => 'Int',
+ default => 5,
+ handles => {
+ set => 'set',
+ add => 'add',
+ sub => 'sub',
+ mul => 'mul',
+ div => 'div',
+ mod => 'mod',
+ abs => 'abs',
# ...
}
);
-=item L<Code|Moose::Meta::Attribute::Native::Trait::Code>
-
-Common methods for code references.
+=item L<String|Moose::Meta::Attribute::Native::Trait::String>
- has 'callback' => (
- traits => ['Code'],
- is => 'ro',
- isa => 'CodeRef',
- default => sub { sub { 'called' } },
- handles => {
- call => 'execute',
+ has 'text' => (
+ traits => ['String'],
+ is => 'ro',
+ isa => 'Str',
+ default => q{},
+ handles => {
+ add_text => 'append',
+ replace_text => 'replace',
# ...
}
);
=back
+=head1 COMPATIBILITY WITH MooseX::AttributeHelpers
+
+This feature used to be a separated CPAN distribution called
+L<MooseX::AttributeHelpers>.
+
+When the feature was incorporated into the Moose core, some of the API details
+were changed. The underlying capabilities are the same, but some details of
+the API were changed.
+
=head1 BUGS
See L<Moose/BUGS> for details on reporting bugs.