package Moose::Meta::Attribute::Native;
-our $VERSION = '1.15';
-$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 traits
+
+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.
+
+=head2 isa
+
+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>.
=head2 handles
-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 >>.
+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.
+
+See the docs for each native trait for details on what methods are available.
-=head1 NATIVE TYPES
+=head2 is
+
+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.
+
+=head2 default or builder
+
+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.
+
+=head1 TRAITS FOR NATIVE DELEGATIONS
=over
=item L<Array|Moose::Meta::Attribute::Native::Trait::Array>
-Common methods for array references.
-
has 'queue' => (
- traits => ['Array'],
- is => 'ro',
- isa => 'ArrayRef[Str]',
- default => sub { [] },
- handles => {
+ 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<Code|Moose::Meta::Attribute::Native::Trait::Code>
-Common methods for code references.
-
has 'callback' => (
- traits => ['Code'],
- is => 'ro',
- isa => 'CodeRef',
- default => sub { sub { 'called' } },
- handles => {
+ traits => ['Code'],
+ is => 'ro',
+ isa => 'CodeRef',
+ default => sub {
+ sub {'called'}
+ },
+ handles => {
call => 'execute',
# ...
}
=item L<Counter|Moose::Meta::Attribute::Native::Trait::Counter>
-Methods for incrementing and decrementing a counter attribute.
-
has 'counter' => (
- traits => ['Counter'],
- is => 'ro',
- isa => 'Num',
- default => 0,
- handles => {
+ 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>
-Common methods for hash references.
-
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<Number|Moose::Meta::Attribute::Native::Trait::Number>
-Common numerical operations.
-
has 'integer' => (
- traits => ['Number'],
- is => 'ro',
- isa => 'Int',
- default => 5,
- handles => {
+ traits => ['Number'],
+ is => 'ro',
+ isa => 'Int',
+ default => 5,
+ handles => {
set => 'set',
add => 'add',
sub => 'sub',
=item L<String|Moose::Meta::Attribute::Native::Trait::String>
-Common methods for string operations.
-
has 'text' => (
- traits => ['String'],
- is => 'rw',
- isa => 'Str',
- default => q{},
- handles => {
+ 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
-
-Robert (phaylon) Sedlacek
+=head1 COMPATIBILITY WITH MooseX::AttributeHelpers
-Tom (dec) Lanyon
+This feature used to be a separated CPAN distribution called
+L<MooseX::AttributeHelpers>.
-Yuval Kogman
+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.
-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