Commit | Line | Data |
17e5e226 |
1 | package Moose::Meta::Attribute::Native; |
e3c07b19 |
2 | |
efa728b4 |
3 | our $VERSION = '1.15'; |
e3c07b19 |
4 | $VERSION = eval $VERSION; |
5 | our $AUTHORITY = 'cpan:STEVAN'; |
6 | |
cdf3cae6 |
7 | my @trait_names = qw(Bool Counter Number String Array Hash Code); |
fafc8b9b |
8 | |
9 | for 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 |
29 | 1; |
30 | |
31 | __END__ |
32 | |
33 | =pod |
34 | |
35 | =head1 NAME |
36 | |
e132fd56 |
37 | Moose::Meta::Attribute::Native - Delegate to native Perl types |
e3c07b19 |
38 | |
39 | =head1 SYNOPSIS |
40 | |
41 | package MyClass; |
42 | use Moose; |
e3c07b19 |
43 | |
44 | has 'mapping' => ( |
e132fd56 |
45 | traits => ['Hash'], |
46 | is => 'rw', |
47 | isa => 'HashRef[Str]', |
48 | default => sub { {} }, |
49 | handles => { |
e3c07b19 |
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 | |
e3c07b19 |
58 | my $obj = MyClass->new; |
59 | $obj->set_quantity(10); # quantity => 10 |
2420461c |
60 | $obj->set_mapping('foo', 4); # foo => 4 |
61 | $obj->set_mapping('bar', 5); # bar => 5 |
62 | $obj->set_mapping('baz', 6); # baz => 6 |
e3c07b19 |
63 | |
2420461c |
64 | # prints 5 |
65 | print $obj->get_mapping('bar') if $obj->exists_in_mapping('bar'); |
e3c07b19 |
66 | |
2420461c |
67 | # prints 'quantity, foo, bar, baz' |
e3c07b19 |
68 | print join ', ', $obj->ids_in_mapping; |
69 | |
70 | =head1 DESCRIPTION |
71 | |
e132fd56 |
72 | Native delegations allow you to delegate to native Perl data |
73 | structure as if they were objects. For example, in the L</SYNOPSIS> you can |
74 | see a hash reference being treated as if it has methods named C<exists()>, |
75 | C<keys()>, C<get()>, and C<set()>. |
76 | |
77 | The delegation methods (mostly) map to Perl builtins and operators. The return |
78 | values of these delegations should be the same as the corresponding Perl |
79 | operation. Any deviations will be explicitly documented. |
80 | |
81 | =head1 API |
e3c07b19 |
82 | |
e132fd56 |
83 | Native delegations are enabled by passing certain options to C<has> when |
84 | creating an attribute. |
e3c07b19 |
85 | |
e132fd56 |
86 | =head2 traits |
87b4e821 |
87 | |
e132fd56 |
88 | To enable this feature, pass the appropriate name in the C<traits> array |
89 | reference for the attribute. For example, to enable this feature for hash |
90 | reference, we include C<'Hash'> in the list of traits. |
91 | |
92 | =head2 isa |
93 | |
94 | You will need to make sure that the attribute has an appropriate type. For |
95 | example, to use this with a Hash you must specify that your attribute is some |
96 | sort of C<HashRef>. |
97 | |
98 | If you I<don't> specify a type, each trait has a default type it will use. |
e3c07b19 |
99 | |
100 | =head2 handles |
101 | |
e132fd56 |
102 | This is just like any other delegation, but only a hash reference is allowed |
103 | when defining native delegations. The keys are the methods to be created in |
104 | the class which contains the attribute. The values are the methods provided by |
105 | the associated trait. Currying works the same way as it does with any other |
106 | delegation. |
e3c07b19 |
107 | |
e132fd56 |
108 | See the docs for each native trait for details on what methods are available. |
109 | |
110 | =head1 TRAITS FOR NATIVE DELEGATIONS |
e3c07b19 |
111 | |
112 | =over |
113 | |
66cce11c |
114 | =item L<Array|Moose::Meta::Attribute::Native::Trait::Array> |
e3c07b19 |
115 | |
66cce11c |
116 | has 'queue' => ( |
e132fd56 |
117 | traits => ['Array'], |
118 | is => 'ro', |
119 | isa => 'ArrayRef[Str]', |
120 | default => sub { [] }, |
121 | handles => { |
66cce11c |
122 | add_item => 'push', |
123 | next_item => 'shift', |
39ab25ce |
124 | # ... |
52e0d71f |
125 | } |
126 | ); |
127 | |
66cce11c |
128 | =item L<Bool|Moose::Meta::Attribute::Native::Trait::Bool> |
e3c07b19 |
129 | |
66cce11c |
130 | has 'is_lit' => ( |
e132fd56 |
131 | traits => ['Bool'], |
132 | is => 'ro', |
133 | isa => 'Bool', |
134 | default => 0, |
135 | handles => { |
66cce11c |
136 | illuminate => 'set', |
137 | darken => 'unset', |
138 | flip_switch => 'toggle', |
139 | is_dark => 'not', |
140 | # ... |
141 | } |
142 | ); |
143 | |
144 | =item L<Code|Moose::Meta::Attribute::Native::Trait::Code> |
145 | |
66cce11c |
146 | has 'callback' => ( |
e132fd56 |
147 | traits => ['Code'], |
148 | is => 'ro', |
149 | isa => 'CodeRef', |
150 | default => sub { |
151 | sub {'called'} |
152 | }, |
153 | handles => { |
66cce11c |
154 | call => 'execute', |
39ab25ce |
155 | # ... |
52e0d71f |
156 | } |
157 | ); |
158 | |
c466e58f |
159 | =item L<Counter|Moose::Meta::Attribute::Native::Trait::Counter> |
e3c07b19 |
160 | |
52e0d71f |
161 | has 'counter' => ( |
e132fd56 |
162 | traits => ['Counter'], |
163 | is => 'ro', |
164 | isa => 'Num', |
165 | default => 0, |
166 | handles => { |
52e0d71f |
167 | inc_counter => 'inc', |
168 | dec_counter => 'dec', |
169 | reset_counter => 'reset', |
39ab25ce |
170 | # ... |
52e0d71f |
171 | } |
172 | ); |
173 | |
c466e58f |
174 | =item L<Hash|Moose::Meta::Attribute::Native::Trait::Hash> |
e3c07b19 |
175 | |
52e0d71f |
176 | has 'options' => ( |
e132fd56 |
177 | traits => ['Hash'], |
178 | is => 'ro', |
179 | isa => 'HashRef[Str]', |
180 | default => sub { {} }, |
181 | handles => { |
9958cbe1 |
182 | set_option => 'set', |
183 | get_option => 'get', |
184 | has_option => 'exists', |
39ab25ce |
185 | # ... |
52e0d71f |
186 | } |
187 | ); |
e3c07b19 |
188 | |
66cce11c |
189 | =item L<Number|Moose::Meta::Attribute::Native::Trait::Number> |
e3c07b19 |
190 | |
66cce11c |
191 | has 'integer' => ( |
e132fd56 |
192 | traits => ['Number'], |
193 | is => 'ro', |
194 | isa => 'Int', |
195 | default => 5, |
196 | handles => { |
66cce11c |
197 | set => 'set', |
198 | add => 'add', |
199 | sub => 'sub', |
200 | mul => 'mul', |
201 | div => 'div', |
202 | mod => 'mod', |
203 | abs => 'abs', |
754a4833 |
204 | # ... |
205 | } |
52e0d71f |
206 | ); |
e3c07b19 |
207 | |
66cce11c |
208 | =item L<String|Moose::Meta::Attribute::Native::Trait::String> |
b86a4688 |
209 | |
66cce11c |
210 | has 'text' => ( |
e132fd56 |
211 | traits => ['String'], |
212 | is => 'ro', |
213 | isa => 'Str', |
214 | default => q{}, |
215 | handles => { |
66cce11c |
216 | add_text => 'append', |
217 | replace_text => 'replace', |
754a4833 |
218 | # ... |
219 | } |
b86a4688 |
220 | ); |
221 | |
e3c07b19 |
222 | =back |
223 | |
e132fd56 |
224 | =head1 COMPATIBILITY WITH MooseX::AttributeHelpers |
225 | |
226 | This feature used to be a separated CPAN distribution called |
227 | L<MooseX::AttributeHelpers>. |
228 | |
229 | When the feature was incorporated into the Moose core, some of the API details |
230 | were changed. The underlying capabilities are the same, but some details of |
231 | the API were changed. |
232 | |
e3c07b19 |
233 | =head1 BUGS |
234 | |
d4048ef3 |
235 | See L<Moose/BUGS> for details on reporting bugs. |
e3c07b19 |
236 | |
237 | =head1 AUTHOR |
238 | |
239 | Stevan Little E<lt>stevan@iinteractive.comE<gt> |
240 | |
241 | B<with contributions from:> |
242 | |
243 | Robert (rlb3) Boone |
244 | |
245 | Paul (frodwith) Driver |
246 | |
247 | Shawn (Sartak) Moore |
248 | |
249 | Chris (perigrin) Prather |
250 | |
251 | Robert (phaylon) Sedlacek |
252 | |
253 | Tom (dec) Lanyon |
254 | |
255 | Yuval Kogman |
256 | |
257 | Jason May |
258 | |
259 | Cory (gphat) Watson |
260 | |
261 | Florian (rafl) Ragwitz |
262 | |
263 | Evan Carroll |
264 | |
265 | Jesse (doy) Luehrs |
266 | |
52a98907 |
267 | Jay Hannah |
268 | |
269 | Robert Buels |
270 | |
e3c07b19 |
271 | =head1 COPYRIGHT AND LICENSE |
272 | |
273 | Copyright 2007-2009 by Infinity Interactive, Inc. |
274 | |
275 | L<http://www.iinteractive.com> |
276 | |
277 | This library is free software; you can redistribute it and/or modify |
278 | it under the same terms as Perl itself. |
279 | |
280 | =cut |