Version 1.07
[gitmo/Moose.git] / lib / Moose / Meta / Attribute / Native.pm
CommitLineData
17e5e226 1package Moose::Meta::Attribute::Native;
e3c07b19 2
16db8ee6 3our $VERSION = '1.07';
e3c07b19 4$VERSION = eval $VERSION;
5our $AUTHORITY = 'cpan:STEVAN';
6
cdf3cae6 7my @trait_names = qw(Bool Counter Number String Array Hash Code);
fafc8b9b 8
9for my $trait_name (@trait_names) {
c466e58f 10 my $trait_class = "Moose::Meta::Attribute::Native::Trait::$trait_name";
fafc8b9b 11 my $meta = Class::MOP::Class->initialize(
12 "Moose::Meta::Attribute::Custom::Trait::$trait_name"
13 );
14 if ($meta->find_method_by_name('register_implementation')) {
15 my $class = $meta->name->register_implementation;
16 Moose->throw_error(
17 "An implementation for $trait_name already exists " .
18 "(found '$class' when trying to register '$trait_class')"
19 );
20 }
21 $meta->add_method(register_implementation => sub {
22 # resolve_metatrait_alias will load classes anyway, but throws away
23 # their error message; we WANT to die if there's a problem
24 Class::MOP::load_class($trait_class);
25 return $trait_class;
26 });
27}
e3c07b19 28
e3c07b19 291;
30
31__END__
32
33=pod
34
35=head1 NAME
36
17e5e226 37Moose::Meta::Attribute::Native - Extend your attribute interfaces
e3c07b19 38
39=head1 SYNOPSIS
40
41 package MyClass;
42 use Moose;
e3c07b19 43
44 has 'mapping' => (
a40b446a 45 traits => [ 'Hash' ],
e3c07b19 46 is => 'rw',
47 isa => 'HashRef[Str]',
48 default => sub { {} },
49 handles => {
50 exists_in_mapping => 'exists',
51 ids_in_mapping => 'keys',
52 get_mapping => 'get',
53 set_mapping => 'set',
cb562ad2 54 set_quantity => [ set => 'quantity' ],
e3c07b19 55 },
56 );
57
58
59 # ...
60
61 my $obj = MyClass->new;
62 $obj->set_quantity(10); # quantity => 10
2420461c 63 $obj->set_mapping('foo', 4); # foo => 4
64 $obj->set_mapping('bar', 5); # bar => 5
65 $obj->set_mapping('baz', 6); # baz => 6
e3c07b19 66
67
2420461c 68 # prints 5
69 print $obj->get_mapping('bar') if $obj->exists_in_mapping('bar');
e3c07b19 70
2420461c 71 # prints 'quantity, foo, bar, baz'
e3c07b19 72 print join ', ', $obj->ids_in_mapping;
73
74=head1 DESCRIPTION
75
9958cbe1 76While L<Moose> attributes provide a way to name your accessors, readers,
2420461c 77writers, clearers and predicates, this set of traits provides commonly
e3c07b19 78used attribute helper methods for more specific types of data.
79
9958cbe1 80As seen in the L</SYNOPSIS>, you specify the data structure via the
2420461c 81C<trait> parameter. Available traits are below; see L</METHOD PROVIDERS>.
e3c07b19 82
87b4e821 83This module used to exist as the L<MooseX::AttributeHelpers> extension. It was
84very commonly used, so we moved it into core Moose. Since this gave us a chance
85to change the interface, you will have to change your code or continue using
2420461c 86the L<MooseX::AttributeHelpers> extension. L<MooseX::AttributeHelpers> should
87continue to work.
87b4e821 88
e3c07b19 89=head1 PARAMETERS
90
91=head2 handles
92
5f3663b2 93This is like C<< handles >> in L<Moose/has>, but only HASH references are
94allowed. Keys are method names that you want installed locally, and values are
87b4e821 95methods from the method providers (below). Currying with delegated methods
96works normally for C<< handles >>.
e3c07b19 97
98=head1 METHOD PROVIDERS
99
100=over
101
c466e58f 102=item L<Number|Moose::Meta::Attribute::Native::Trait::Number>
e3c07b19 103
104Common numerical operations.
105
52e0d71f 106 has 'integer' => (
9958cbe1 107 traits => ['Number'],
52e0d71f 108 is => 'ro',
109 isa => 'Int',
110 default => 5,
9958cbe1 111 handles => {
52e0d71f 112 set => 'set',
113 add => 'add',
114 sub => 'sub',
115 mul => 'mul',
116 div => 'div',
117 mod => 'mod',
118 abs => 'abs',
39ab25ce 119 # ...
52e0d71f 120 }
121 );
122
c466e58f 123=item L<String|Moose::Meta::Attribute::Native::Trait::String>
e3c07b19 124
125Common methods for string operations.
126
52e0d71f 127 has 'text' => (
9958cbe1 128 traits => ['String'],
52e0d71f 129 is => 'rw',
130 isa => 'Str',
131 default => q{},
9958cbe1 132 handles => {
52e0d71f 133 add_text => 'append',
134 replace_text => 'replace',
39ab25ce 135 # ...
52e0d71f 136 }
137 );
138
c466e58f 139=item L<Counter|Moose::Meta::Attribute::Native::Trait::Counter>
e3c07b19 140
141Methods for incrementing and decrementing a counter attribute.
142
52e0d71f 143 has 'counter' => (
9958cbe1 144 traits => ['Counter'],
52e0d71f 145 is => 'ro',
146 isa => 'Num',
147 default => 0,
148 handles => {
149 inc_counter => 'inc',
150 dec_counter => 'dec',
151 reset_counter => 'reset',
39ab25ce 152 # ...
52e0d71f 153 }
154 );
155
c466e58f 156=item L<Bool|Moose::Meta::Attribute::Native::Trait::Bool>
e3c07b19 157
158Common methods for boolean values.
159
52e0d71f 160 has 'is_lit' => (
9958cbe1 161 traits => ['Bool'],
52e0d71f 162 is => 'rw',
163 isa => 'Bool',
164 default => 0,
165 handles => {
166 illuminate => 'set',
167 darken => 'unset',
168 flip_switch => 'toggle',
169 is_dark => 'not',
39ab25ce 170 # ...
52e0d71f 171 }
172 );
173
c466e58f 174=item L<Hash|Moose::Meta::Attribute::Native::Trait::Hash>
e3c07b19 175
176Common methods for hash references.
177
52e0d71f 178 has 'options' => (
179 traits => ['Hash'],
180 is => 'ro',
181 isa => 'HashRef[Str]',
182 default => sub { {} },
183 handles => {
9958cbe1 184 set_option => 'set',
185 get_option => 'get',
186 has_option => 'exists',
39ab25ce 187 # ...
52e0d71f 188 }
189 );
e3c07b19 190
c466e58f 191=item L<Array|Moose::Meta::Attribute::Native::Trait::Array>
e3c07b19 192
193Common methods for array references.
194
52e0d71f 195 has 'queue' => (
754a4833 196 traits => ['Array'],
197 is => 'ro',
198 isa => 'ArrayRef[Str]',
199 default => sub { [] },
200 handles => {
201 add_item => 'push',
202 next_item => 'shift',
203 # ...
204 }
52e0d71f 205 );
e3c07b19 206
b86a4688 207=item L<Code|Moose::Meta::Attribute::Native::Trait::Code>
208
209Common methods for code references.
210
211 has 'callback' => (
754a4833 212 traits => ['Code'],
213 is => 'ro',
214 isa => 'CodeRef',
215 default => sub { sub { 'called' } },
216 handles => {
217 call => 'execute',
218 # ...
219 }
b86a4688 220 );
221
e3c07b19 222=back
223
e3c07b19 224=head1 BUGS
225
d4048ef3 226See L<Moose/BUGS> for details on reporting bugs.
e3c07b19 227
228=head1 AUTHOR
229
230Stevan Little E<lt>stevan@iinteractive.comE<gt>
231
232B<with contributions from:>
233
234Robert (rlb3) Boone
235
236Paul (frodwith) Driver
237
238Shawn (Sartak) Moore
239
240Chris (perigrin) Prather
241
242Robert (phaylon) Sedlacek
243
244Tom (dec) Lanyon
245
246Yuval Kogman
247
248Jason May
249
250Cory (gphat) Watson
251
252Florian (rafl) Ragwitz
253
254Evan Carroll
255
256Jesse (doy) Luehrs
257
52a98907 258Jay Hannah
259
260Robert Buels
261
e3c07b19 262=head1 COPYRIGHT AND LICENSE
263
264Copyright 2007-2009 by Infinity Interactive, Inc.
265
266L<http://www.iinteractive.com>
267
268This library is free software; you can redistribute it and/or modify
269it under the same terms as Perl itself.
270
271=cut