package Moose::Meta::Attribute::Native;
-our $VERSION = '0.93_03';
-$VERSION = eval $VERSION;
-our $AUTHORITY = 'cpan:STEVAN';
+use Class::Load qw(load_class);
my @trait_names = qw(Bool Counter Number String Array Hash Code);
);
if ($meta->find_method_by_name('register_implementation')) {
my $class = $meta->name->register_implementation;
- Moose->throw_error(
+ Moose::Util::throw(
"An implementation for $trait_name already exists " .
"(found '$class' when trying to register '$trait_class')"
);
$meta->add_method(register_implementation => sub {
# resolve_metatrait_alias will load classes anyway, but throws away
# their error message; we WANT to die if there's a problem
- Class::MOP::load_class($trait_class);
+ load_class($trait_class);
return $trait_class;
});
}
1;
+# ABSTRACT: Delegate to native Perl types
+
__END__
=pod
-=head1 NAME
-
-Moose::Meta::Attribute::Native - Extend your attribute interfaces
-
=head1 SYNOPSIS
package MyClass;
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>
+=head2 handles
-Common numerical operations.
+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.
- 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',
- }
- );
+See the docs for each native trait for details on what methods are available.
-=item L<String|Moose::Meta::Attribute::Native::Trait::String>
+=head2 is
-Common methods for string operations.
+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, not passing the C<is>
+option will prevent standard accessor generation.
- has 'text' => (
- traits => ['String'],
- is => 'rw',
- isa => 'Str',
- default => q{},
- handles => {
- add_text => 'append',
- replace_text => 'replace',
- }
- );
+=head2 default or builder
-=item L<Counter|Moose::Meta::Attribute::Native::Trait::Counter>
+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.
-Methods for incrementing and decrementing a counter attribute.
+=head1 TRAITS FOR NATIVE DELEGATIONS
- has 'counter' => (
- traits => ['Counter'],
- is => 'ro',
- isa => 'Num',
- default => 0,
- handles => {
- inc_counter => 'inc',
- dec_counter => 'dec',
- reset_counter => 'reset',
+=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',
is_dark => 'not',
+ # ...
}
);
-=item L<Hash|Moose::Meta::Attribute::Native::Trait::Hash>
+=item L<Code|Moose::Meta::Attribute::Native::Trait::Code>
+
+ 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',
+ # ...
+ }
+ );
-Common methods for hash references.
+=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 BUGS
-
-See L<Moose/BUGS> for details on reporting bugs.
-
-=head1 AUTHOR
-
-Stevan Little E<lt>stevan@iinteractive.comE<gt>
-
-B<with contributions from:>
-
-Robert (rlb3) Boone
-
-Paul (frodwith) Driver
-
-Shawn (Sartak) Moore
-
-Chris (perigrin) Prather
+=head1 COMPATIBILITY WITH MooseX::AttributeHelpers
-Robert (phaylon) Sedlacek
+This feature used to be a separated CPAN distribution called
+L<MooseX::AttributeHelpers>.
-Tom (dec) Lanyon
+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.
-Yuval Kogman
-
-Jason May
-
-Cory (gphat) Watson
-
-Florian (rafl) Ragwitz
-
-Evan Carroll
-
-Jesse (doy) Luehrs
-
-Jay Hannah
-
-Robert Buels
-
-=head1 COPYRIGHT AND LICENSE
-
-Copyright 2007-2009 by Infinity Interactive, Inc.
-
-L<http://www.iinteractive.com>
+=head1 BUGS
-This library is free software; you can redistribute it and/or modify
-it under the same terms as Perl itself.
+See L<Moose/BUGS> for details on reporting bugs.
=cut
projects / gitmo/Moose.git / blobdiff