X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FMoose%2FMeta%2FAttribute%2FNative.pm;h=9094fbf2a9996a9ff51bae33f7f0307a1b0e9457;hb=aff6aafcfff96c2a91bd044e35010757feae584c;hp=e0318a2d2459af64b264a22f836a45967a609070;hpb=72643035d73124e0b4ef7a8335cdc4f793732b5a;p=gitmo%2FMoose.git diff --git a/lib/Moose/Meta/Attribute/Native.pm b/lib/Moose/Meta/Attribute/Native.pm index e0318a2..9094fbf 100644 --- a/lib/Moose/Meta/Attribute/Native.pm +++ b/lib/Moose/Meta/Attribute/Native.pm @@ -1,6 +1,6 @@ package Moose::Meta::Attribute::Native; -our $VERSION = '1.08'; +our $VERSION = '1.18'; $VERSION = eval $VERSION; our $AUTHORITY = 'cpan:STEVAN'; @@ -34,7 +34,7 @@ __END__ =head1 NAME -Moose::Meta::Attribute::Native - Extend your attribute interfaces +Moose::Meta::Attribute::Native - Delegate to native Perl types =head1 SYNOPSIS @@ -42,11 +42,11 @@ Moose::Meta::Attribute::Native - Extend your attribute interfaces 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', @@ -55,16 +55,12 @@ Moose::Meta::Attribute::Native - Extend your attribute interfaces }, ); - - # ... - 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'); @@ -73,96 +69,83 @@ Moose::Meta::Attribute::Native - Extend your attribute interfaces =head1 DESCRIPTION -While L 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 you can +see a hash reference being treated as if it has methods named C, +C, C, and C. -As seen in the L, you specify the data structure via the -C parameter. Available traits are below; see L. +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 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 extension. L should -continue to work. +=head1 API -=head1 PARAMETERS +Native delegations are enabled by passing certain options to C when +creating an attribute. -=head2 handles +=head2 traits -This is like C<< handles >> in L, 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 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. -=item L +If you I 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 +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 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 +=head2 default or builder -Methods for incrementing and decrementing a counter attribute. +Some traits provide a default C 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 + + has 'queue' => ( + traits => ['Array'], + is => 'ro', + isa => 'ArrayRef[Str]', + default => sub { [] }, + handles => { + add_item => 'push', + next_item => 'shift', # ... } ); =item L -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', @@ -171,16 +154,44 @@ Common methods for boolean values. } ); -=item L +=item L -Common methods for hash references. + has 'callback' => ( + traits => ['Code'], + is => 'ro', + isa => 'CodeRef', + default => sub { + sub {'called'} + }, + handles => { + call => 'execute', + # ... + } + ); + +=item L + + has 'counter' => ( + traits => ['Counter'], + is => 'ro', + isa => 'Num', + default => 0, + handles => { + inc_counter => 'inc', + dec_counter => 'dec', + reset_counter => 'reset', + # ... + } + ); + +=item L 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', @@ -188,39 +199,50 @@ Common methods for hash references. } ); -=item L - -Common methods for array references. +=item L - 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 - -Common methods for code references. +=item L - 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. + +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 for details on reporting bugs.