1 package Moose::Meta::Attribute::Native;
3 our $AUTHORITY = 'cpan:STEVAN';
5 my @trait_names = qw(Bool Counter Number String Array Hash Code);
7 for my $trait_name (@trait_names) {
8 my $trait_class = "Moose::Meta::Attribute::Native::Trait::$trait_name";
9 my $meta = Class::MOP::Class->initialize(
10 "Moose::Meta::Attribute::Custom::Trait::$trait_name"
12 if ($meta->find_method_by_name('register_implementation')) {
13 my $class = $meta->name->register_implementation;
15 "An implementation for $trait_name already exists " .
16 "(found '$class' when trying to register '$trait_class')"
19 $meta->add_method(register_implementation => sub {
20 # resolve_metatrait_alias will load classes anyway, but throws away
21 # their error message; we WANT to die if there's a problem
22 Class::MOP::load_class($trait_class);
29 # ABSTRACT: Delegate to native Perl types
43 isa => 'HashRef[Str]',
44 default => sub { {} },
46 exists_in_mapping => 'exists',
47 ids_in_mapping => 'keys',
50 set_quantity => [ set => 'quantity' ],
54 my $obj = MyClass->new;
55 $obj->set_quantity(10); # quantity => 10
56 $obj->set_mapping('foo', 4); # foo => 4
57 $obj->set_mapping('bar', 5); # bar => 5
58 $obj->set_mapping('baz', 6); # baz => 6
61 print $obj->get_mapping('bar') if $obj->exists_in_mapping('bar');
63 # prints 'quantity, foo, bar, baz'
64 print join ', ', $obj->ids_in_mapping;
68 Native delegations allow you to delegate to native Perl data
69 structures as if they were objects. For example, in the L</SYNOPSIS> you can
70 see a hash reference being treated as if it has methods named C<exists()>,
71 C<keys()>, C<get()>, and C<set()>.
73 The delegation methods (mostly) map to Perl builtins and operators. The return
74 values of these delegations should be the same as the corresponding Perl
75 operation. Any deviations will be explicitly documented.
79 Native delegations are enabled by passing certain options to C<has> when
80 creating an attribute.
84 To enable this feature, pass the appropriate name in the C<traits> array
85 reference for the attribute. For example, to enable this feature for hash
86 reference, we include C<'Hash'> in the list of traits.
90 You will need to make sure that the attribute has an appropriate type. For
91 example, to use this with a Hash you must specify that your attribute is some
94 If you I<don't> specify a type, each trait has a default type it will use.
98 This is just like any other delegation, but only a hash reference is allowed
99 when defining native delegations. The keys are the methods to be created in
100 the class which contains the attribute. The values are the methods provided by
101 the associated trait. Currying works the same way as it does with any other
104 See the docs for each native trait for details on what methods are available.
108 Some traits provide a default C<is> for historical reasons. This behavior is
109 deprecated, and you are strongly encouraged to provide a value. If you don't
110 plan to read and write the attribute value directly, you can set C<< is =>
111 'bare' >> to prevent standard accessor generation.
113 =head2 default or builder
115 Some traits provide a default C<default> for historical reasons. This behavior
116 is deprecated, and you are strongly encouraged to provide a default value or
117 make the attribute required.
119 =head1 TRAITS FOR NATIVE DELEGATIONS
123 =item L<Array|Moose::Meta::Attribute::Native::Trait::Array>
128 isa => 'ArrayRef[Str]',
129 default => sub { [] },
132 next_item => 'shift',
137 =item L<Bool|Moose::Meta::Attribute::Native::Trait::Bool>
147 flip_switch => 'toggle',
153 =item L<Code|Moose::Meta::Attribute::Native::Trait::Code>
168 =item L<Counter|Moose::Meta::Attribute::Native::Trait::Counter>
171 traits => ['Counter'],
176 inc_counter => 'inc',
177 dec_counter => 'dec',
178 reset_counter => 'reset',
183 =item L<Hash|Moose::Meta::Attribute::Native::Trait::Hash>
188 isa => 'HashRef[Str]',
189 default => sub { {} },
193 has_option => 'exists',
198 =item L<Number|Moose::Meta::Attribute::Native::Trait::Number>
201 traits => ['Number'],
217 =item L<String|Moose::Meta::Attribute::Native::Trait::String>
220 traits => ['String'],
225 add_text => 'append',
226 replace_text => 'replace',
233 =head1 COMPATIBILITY WITH MooseX::AttributeHelpers
235 This feature used to be a separated CPAN distribution called
236 L<MooseX::AttributeHelpers>.
238 When the feature was incorporated into the Moose core, some of the API details
239 were changed. The underlying capabilities are the same, but some details of
240 the API were changed.
244 See L<Moose/BUGS> for details on reporting bugs.