X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FMoose%2FMeta%2FAttribute%2FNative.pm;h=233c90c75dcd3ab6c1c3ae8c3cf91492591bfe48;hb=d5f6cadef8d83deaf7dd95302908cd4f61aeab8a;hp=105616ff6ce06d9ddaa91b646db4c5a4ddb8f070;hpb=122a129ac1b02a53a4ac31f848a9bc89ce8feacf;p=gitmo%2FMoose.git diff --git a/lib/Moose/Meta/Attribute/Native.pm b/lib/Moose/Meta/Attribute/Native.pm index 105616f..233c90c 100644 --- a/lib/Moose/Meta/Attribute/Native.pm +++ b/lib/Moose/Meta/Attribute/Native.pm @@ -1,10 +1,6 @@ package Moose::Meta::Attribute::Native; -our $VERSION = '0.89'; -$VERSION = eval $VERSION; -our $AUTHORITY = 'cpan:STEVAN'; - -my @trait_names = qw(Bool Counter Number String Array Hash); +my @trait_names = qw(Bool Counter Number String Array Hash Code); for my $trait_name (@trait_names) { my $trait_class = "Moose::Meta::Attribute::Native::Trait::$trait_name"; @@ -28,221 +24,221 @@ for my $trait_name (@trait_names) { 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', set_mapping => 'set', - set_quantity => [ set => [ 'quantity' ] ], + set_quantity => [ set => 'quantity' ], }, ); - - # ... - my $obj = MyClass->new; $obj->set_quantity(10); # quantity => 10 - $obj->set_mapping(4, 'foo'); # 4 => 'foo' - $obj->set_mapping(5, 'bar'); # 5 => 'bar' - $obj->set_mapping(6, 'baz'); # 6 => 'baz' + $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'); - # prints 'bar' - print $obj->get_mapping(5) if $obj->exists_in_mapping(5); - - # prints '4, 5, 6' + # prints 'quantity, foo, bar, baz' print join ', ', $obj->ids_in_mapping; =head1 DESCRIPTION -While L attributes provide you with a way to name your accessors, -readers, writers, clearers and predicates, this library 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 extension via the -C parameter. Available meta classes 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. +=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' => ( - metaclass => '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' => ( - metaclass => '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', is_dark => 'not', + # ... } ); - -=item L - -Common methods for hash references. - - has 'options' => ( - traits => ['Hash'], - is => 'ro', - isa => 'HashRef[Str]', - default => sub { {} }, - handles => { - set_option => 'set', - get_option => 'get', - has_option => 'exists', +=item L + + has 'callback' => ( + traits => ['Code'], + is => 'ro', + isa => 'CodeRef', + default => sub { + sub {'called'} + }, + handles => { + call => 'execute', + # ... } ); -=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 'counter' => ( + traits => ['Counter'], + is => 'ro', + isa => 'Num', + default => 0, + handles => { + inc_counter => 'inc', + dec_counter => 'dec', + reset_counter => 'reset', + # ... + } ); -=back - -=head1 BUGS - -All complex software has bugs lurking in it, and this module is no -exception. If you find a bug please either email me, or add the bug -to cpan-RT. - -=head1 AUTHOR - -Stevan Little Estevan@iinteractive.comE - -B - -Robert (rlb3) Boone - -Paul (frodwith) Driver - -Shawn (Sartak) Moore - -Chris (perigrin) Prather - -Robert (phaylon) Sedlacek +=item L -Tom (dec) Lanyon + has 'options' => ( + traits => ['Hash'], + is => 'ro', + isa => 'HashRef[Str]', + default => sub { {} }, + handles => { + set_option => 'set', + get_option => 'get', + has_option => 'exists', + # ... + } + ); -Yuval Kogman +=item L -Jason May + 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', + # ... + } + ); -Cory (gphat) Watson +=item L -Florian (rafl) Ragwitz + has 'text' => ( + traits => ['String'], + is => 'ro', + isa => 'Str', + default => q{}, + handles => { + add_text => 'append', + replace_text => 'replace', + # ... + } + ); -Evan Carroll +=back -Jesse (doy) Luehrs +=head1 COMPATIBILITY WITH MooseX::AttributeHelpers -=head1 COPYRIGHT AND LICENSE +This feature used to be a separated CPAN distribution called +L. -Copyright 2007-2009 by Infinity Interactive, Inc. +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. -L +=head1 BUGS -This library is free software; you can redistribute it and/or modify -it under the same terms as Perl itself. +See L for details on reporting bugs. =cut