Commit | Line | Data |
8b978dd5 |
1 | |
2 | package Class::MOP::Attribute; |
3 | |
4 | use strict; |
5 | use warnings; |
6 | |
ba38bf08 |
7 | use Class::MOP::Method::Accessor; |
8 | |
2eb717d5 |
9 | use Carp 'confess'; |
9b522fc4 |
10 | use Scalar::Util 'blessed', 'weaken'; |
2eb717d5 |
11 | |
e00524a0 |
12 | our $VERSION = '0.83'; |
d519662a |
13 | $VERSION = eval $VERSION; |
f0480c45 |
14 | our $AUTHORITY = 'cpan:STEVAN'; |
8b978dd5 |
15 | |
b1897d4d |
16 | use base 'Class::MOP::Object'; |
17 | |
727919c5 |
18 | # NOTE: (meta-circularity) |
1d68af04 |
19 | # This method will be replaced in the |
20 | # boostrap section of Class::MOP, by |
21 | # a new version which uses the |
727919c5 |
22 | # &Class::MOP::Class::construct_instance |
23 | # method to build an attribute meta-object |
24 | # which itself is described with attribute |
1d68af04 |
25 | # meta-objects. |
727919c5 |
26 | # - Ain't meta-circularity grand? :) |
8b978dd5 |
27 | sub new { |
649efb63 |
28 | my ( $class, @args ) = @_; |
29 | |
30 | unshift @args, "name" if @args % 2 == 1; |
31 | my %options = @args; |
32 | |
33 | my $name = $options{name}; |
1d68af04 |
34 | |
cbd9f942 |
35 | (defined $name && $name) |
8b978dd5 |
36 | || confess "You must provide a name for the attribute"; |
1d68af04 |
37 | |
38 | $options{init_arg} = $name |
5659d76e |
39 | if not exists $options{init_arg}; |
1d68af04 |
40 | if(exists $options{builder}){ |
41 | confess("builder must be a defined scalar value which is a method name") |
42 | if ref $options{builder} || !(defined $options{builder}); |
43 | confess("Setting both default and builder is not allowed.") |
44 | if exists $options{default}; |
8fe581e5 |
45 | } else { |
46 | (is_default_a_coderef(\%options)) |
47 | || confess("References are not allowed as default values, you must ". |
3c0a8087 |
48 | "wrap the default of '$name' in a CODE reference (ex: sub { [] } and not [])") |
8fe581e5 |
49 | if exists $options{default} && ref $options{default}; |
1d68af04 |
50 | } |
2e877f58 |
51 | if( $options{required} and not( defined($options{builder}) || defined($options{init_arg}) || exists $options{default} ) ) { |
52 | confess("A required attribute must have either 'init_arg', 'builder', or 'default'"); |
53 | } |
8683db0e |
54 | |
cb75020f |
55 | $class->_new(\%options); |
4b698b1a |
56 | } |
57 | |
58 | sub _new { |
0bfc85b8 |
59 | my $class = shift; |
60 | my $options = @_ == 1 ? $_[0] : {@_}; |
4b698b1a |
61 | |
8b978dd5 |
62 | bless { |
d9d99689 |
63 | 'name' => $options->{name}, |
64 | 'accessor' => $options->{accessor}, |
65 | 'reader' => $options->{reader}, |
66 | 'writer' => $options->{writer}, |
67 | 'predicate' => $options->{predicate}, |
68 | 'clearer' => $options->{clearer}, |
69 | 'builder' => $options->{builder}, |
70 | 'init_arg' => $options->{init_arg}, |
71 | 'default' => $options->{default}, |
72 | 'initializer' => $options->{initializer}, |
73 | 'definition_context' => $options->{definition_context}, |
1d68af04 |
74 | # keep a weakened link to the |
9ec169fe |
75 | # class we are associated with |
8683db0e |
76 | 'associated_class' => undef, |
1d68af04 |
77 | # and a list of the methods |
3545c727 |
78 | # associated with this attr |
8683db0e |
79 | 'associated_methods' => [], |
dc9d420c |
80 | # this let's us keep track of |
81 | # our order inside the associated |
82 | # class |
83 | 'insertion_order' => undef, |
0bfc85b8 |
84 | }, $class; |
8b978dd5 |
85 | } |
86 | |
7b31baf4 |
87 | # NOTE: |
1d68af04 |
88 | # this is a primative (and kludgy) clone operation |
16e960bd |
89 | # for now, it will be replaced in the Class::MOP |
1d68af04 |
90 | # bootstrap with a proper one, however we know |
5659d76e |
91 | # that this one will work fine for now. |
92 | sub clone { |
93 | my $self = shift; |
94 | my %options = @_; |
95 | (blessed($self)) |
96 | || confess "Can only clone an instance"; |
b3fa93c7 |
97 | return bless { %{$self}, %options } => ref($self); |
5659d76e |
98 | } |
99 | |
bd4e03f9 |
100 | sub initialize_instance_slot { |
f892c0f0 |
101 | my ($self, $meta_instance, $instance, $params) = @_; |
8683db0e |
102 | my $init_arg = $self->{'init_arg'}; |
103 | |
bd4e03f9 |
104 | # try to fetch the init arg from the %params ... |
8d2d4c67 |
105 | |
1d68af04 |
106 | # if nothing was in the %params, we can use the |
bd4e03f9 |
107 | # attribute's default value (if it has one) |
2e877f58 |
108 | if(defined $init_arg and exists $params->{$init_arg}){ |
8ee74136 |
109 | $self->_set_initial_slot_value( |
110 | $meta_instance, |
0ab65f99 |
111 | $instance, |
0ab65f99 |
112 | $params->{$init_arg}, |
0ab65f99 |
113 | ); |
b7bdffc3 |
114 | } |
8683db0e |
115 | elsif (defined $self->{'default'}) { |
8ee74136 |
116 | $self->_set_initial_slot_value( |
117 | $meta_instance, |
0ab65f99 |
118 | $instance, |
0ab65f99 |
119 | $self->default($instance), |
0ab65f99 |
120 | ); |
b7bdffc3 |
121 | } |
8683db0e |
122 | elsif (defined( my $builder = $self->{'builder'})) { |
b7bdffc3 |
123 | if ($builder = $instance->can($builder)) { |
8ee74136 |
124 | $self->_set_initial_slot_value( |
125 | $meta_instance, |
0ab65f99 |
126 | $instance, |
0ab65f99 |
127 | $instance->$builder, |
0ab65f99 |
128 | ); |
b7bdffc3 |
129 | } |
130 | else { |
b3fa93c7 |
131 | confess(ref($instance)." does not support builder method '". $self->{'builder'} ."' for attribute '" . $self->name . "'"); |
8fe581e5 |
132 | } |
1d68af04 |
133 | } |
bd4e03f9 |
134 | } |
135 | |
8ee74136 |
136 | sub _set_initial_slot_value { |
137 | my ($self, $meta_instance, $instance, $value) = @_; |
138 | |
139 | my $slot_name = $self->name; |
140 | |
141 | return $meta_instance->set_slot_value($instance, $slot_name, $value) |
142 | unless $self->has_initializer; |
143 | |
144 | my $callback = sub { |
145 | $meta_instance->set_slot_value($instance, $slot_name, $_[0]); |
146 | }; |
147 | |
148 | my $initializer = $self->initializer; |
149 | |
150 | # most things will just want to set a value, so make it first arg |
151 | $instance->$initializer($value, $callback, $self); |
152 | } |
153 | |
5659d76e |
154 | # NOTE: |
1d68af04 |
155 | # the next bunch of methods will get bootstrapped |
7b31baf4 |
156 | # away in the Class::MOP bootstrapping section |
157 | |
8683db0e |
158 | sub associated_class { $_[0]->{'associated_class'} } |
159 | sub associated_methods { $_[0]->{'associated_methods'} } |
160 | |
b3fa93c7 |
161 | sub has_accessor { defined($_[0]->{'accessor'}) } |
162 | sub has_reader { defined($_[0]->{'reader'}) } |
163 | sub has_writer { defined($_[0]->{'writer'}) } |
164 | sub has_predicate { defined($_[0]->{'predicate'}) } |
165 | sub has_clearer { defined($_[0]->{'clearer'}) } |
166 | sub has_builder { defined($_[0]->{'builder'}) } |
167 | sub has_init_arg { defined($_[0]->{'init_arg'}) } |
168 | sub has_default { defined($_[0]->{'default'}) } |
169 | sub has_initializer { defined($_[0]->{'initializer'}) } |
dc9d420c |
170 | sub has_insertion_order { defined($_[0]->{'insertion_order'}) } |
8683db0e |
171 | |
d9d99689 |
172 | sub accessor { $_[0]->{'accessor'} } |
173 | sub reader { $_[0]->{'reader'} } |
174 | sub writer { $_[0]->{'writer'} } |
175 | sub predicate { $_[0]->{'predicate'} } |
176 | sub clearer { $_[0]->{'clearer'} } |
177 | sub builder { $_[0]->{'builder'} } |
178 | sub init_arg { $_[0]->{'init_arg'} } |
179 | sub initializer { $_[0]->{'initializer'} } |
180 | sub definition_context { $_[0]->{'definition_context'} } |
dc9d420c |
181 | sub insertion_order { $_[0]->{'insertion_order'} } |
c50c603e |
182 | |
7b31baf4 |
183 | # end bootstrapped away method section. |
184 | # (all methods below here are kept intact) |
185 | |
9e517e01 |
186 | sub has_read_method { $_[0]->has_reader || $_[0]->has_accessor } |
187 | sub has_write_method { $_[0]->has_writer || $_[0]->has_accessor } |
188 | |
d14f6cbe |
189 | sub get_read_method { |
190 | my $self = shift; |
191 | my $reader = $self->reader || $self->accessor; |
192 | # normal case ... |
193 | return $reader unless ref $reader; |
194 | # the HASH ref case |
195 | my ($name) = %$reader; |
196 | return $name; |
197 | } |
198 | |
199 | sub get_write_method { |
200 | my $self = shift; |
201 | my $writer = $self->writer || $self->accessor; |
202 | # normal case ... |
203 | return $writer unless ref $writer; |
204 | # the HASH ref case |
205 | my ($name) = %$writer; |
206 | return $name; |
207 | } |
b25109b1 |
208 | |
5da16d1b |
209 | sub get_read_method_ref { |
210 | my $self = shift; |
742fb371 |
211 | if ((my $reader = $self->get_read_method) && $self->associated_class) { |
5da16d1b |
212 | return $self->associated_class->get_method($reader); |
213 | } |
214 | else { |
def5c0b5 |
215 | my $code = sub { $self->get_value(@_) }; |
216 | if (my $class = $self->associated_class) { |
217 | return $class->method_metaclass->wrap( |
218 | $code, |
219 | package_name => $class->name, |
220 | name => '__ANON__' |
221 | ); |
222 | } |
223 | else { |
224 | return $code; |
225 | } |
5da16d1b |
226 | } |
227 | } |
228 | |
229 | sub get_write_method_ref { |
230 | my $self = shift; |
d14f6cbe |
231 | if ((my $writer = $self->get_write_method) && $self->associated_class) { |
742fb371 |
232 | return $self->associated_class->get_method($writer); |
5da16d1b |
233 | } |
234 | else { |
def5c0b5 |
235 | my $code = sub { $self->set_value(@_) }; |
236 | if (my $class = $self->associated_class) { |
237 | return $class->method_metaclass->wrap( |
238 | $code, |
239 | package_name => $class->name, |
240 | name => '__ANON__' |
241 | ); |
242 | } |
243 | else { |
244 | return $code; |
245 | } |
5da16d1b |
246 | } |
247 | } |
248 | |
1d68af04 |
249 | sub is_default_a_coderef { |
4e55a580 |
250 | ('CODE' eq ref($_[0]->{'default'})) |
c0cbf4d9 |
251 | } |
252 | |
1d68af04 |
253 | sub default { |
c0cbf4d9 |
254 | my ($self, $instance) = @_; |
9363ea89 |
255 | if (defined $instance && $self->is_default_a_coderef) { |
1d68af04 |
256 | # if the default is a CODE ref, then |
727919c5 |
257 | # we pass in the instance and default |
1d68af04 |
258 | # can return a value based on that |
727919c5 |
259 | # instance. Somewhat crude, but works. |
8683db0e |
260 | return $self->{'default'}->($instance); |
1d68af04 |
261 | } |
8683db0e |
262 | $self->{'default'}; |
c50c603e |
263 | } |
8b978dd5 |
264 | |
c57c8b10 |
265 | # slots |
266 | |
267 | sub slots { (shift)->name } |
268 | |
1d68af04 |
269 | # class association |
727919c5 |
270 | |
9ec169fe |
271 | sub attach_to_class { |
272 | my ($self, $class) = @_; |
273 | (blessed($class) && $class->isa('Class::MOP::Class')) |
274 | || confess "You must pass a Class::MOP::Class instance (or a subclass)"; |
8683db0e |
275 | weaken($self->{'associated_class'} = $class); |
9ec169fe |
276 | } |
277 | |
278 | sub detach_from_class { |
279 | my $self = shift; |
8683db0e |
280 | $self->{'associated_class'} = undef; |
9ec169fe |
281 | } |
282 | |
1d68af04 |
283 | # method association |
3545c727 |
284 | |
285 | sub associate_method { |
286 | my ($self, $method) = @_; |
8683db0e |
287 | push @{$self->{'associated_methods'}} => $method; |
3545c727 |
288 | } |
289 | |
16e960bd |
290 | ## Slot management |
291 | |
ef91a0e2 |
292 | sub set_initial_value { |
293 | my ($self, $instance, $value) = @_; |
e76b01fb |
294 | $self->_set_initial_slot_value( |
b3fa93c7 |
295 | Class::MOP::Class->initialize(ref($instance))->get_meta_instance, |
8ee74136 |
296 | $instance, |
297 | $value |
298 | ); |
ef91a0e2 |
299 | } |
300 | |
16e960bd |
301 | sub set_value { |
1396f86b |
302 | my ($self, $instance, $value) = @_; |
16e960bd |
303 | |
b3fa93c7 |
304 | Class::MOP::Class->initialize(ref($instance)) |
da34f054 |
305 | ->get_meta_instance |
306 | ->set_slot_value($instance, $self->name, $value); |
16e960bd |
307 | } |
308 | |
309 | sub get_value { |
1396f86b |
310 | my ($self, $instance) = @_; |
16e960bd |
311 | |
b3fa93c7 |
312 | Class::MOP::Class->initialize(ref($instance)) |
da34f054 |
313 | ->get_meta_instance |
314 | ->get_slot_value($instance, $self->name); |
16e960bd |
315 | } |
316 | |
3545c727 |
317 | sub has_value { |
318 | my ($self, $instance) = @_; |
1d68af04 |
319 | |
b3fa93c7 |
320 | Class::MOP::Class->initialize(ref($instance)) |
da34f054 |
321 | ->get_meta_instance |
322 | ->is_slot_initialized($instance, $self->name); |
3545c727 |
323 | } |
324 | |
325 | sub clear_value { |
326 | my ($self, $instance) = @_; |
1d68af04 |
327 | |
b3fa93c7 |
328 | Class::MOP::Class->initialize(ref($instance)) |
da34f054 |
329 | ->get_meta_instance |
330 | ->deinitialize_slot($instance, $self->name); |
3545c727 |
331 | } |
332 | |
ba38bf08 |
333 | ## load em up ... |
c0cbf4d9 |
334 | |
ba38bf08 |
335 | sub accessor_metaclass { 'Class::MOP::Method::Accessor' } |
c0cbf4d9 |
336 | |
9ec169fe |
337 | sub process_accessors { |
c7e28c19 |
338 | Carp::cluck('The process_accessors method has been made private.' |
339 | . " The public version is deprecated and will be removed in a future release.\n"); |
e056bd42 |
340 | shift->_process_accessors(@_); |
45a183fb |
341 | } |
342 | |
343 | sub _process_accessors { |
c0cbf4d9 |
344 | my ($self, $type, $accessor, $generate_as_inline_methods) = @_; |
d9d99689 |
345 | |
346 | my $method_ctx; |
347 | |
348 | if ( my $ctx = $self->definition_context ) { |
349 | $method_ctx = { %$ctx }; |
350 | } |
351 | |
9b522fc4 |
352 | if (ref($accessor)) { |
353 | (ref($accessor) eq 'HASH') |
7d28758b |
354 | || confess "bad accessor/reader/writer/predicate/clearer format, must be a HASH ref"; |
4d47b77f |
355 | my ($name, $method) = %{$accessor}; |
4c105333 |
356 | $method = $self->accessor_metaclass->wrap( |
357 | $method, |
358 | package_name => $self->associated_class->name, |
359 | name => $name, |
d9d99689 |
360 | definition_context => $method_ctx, |
4c105333 |
361 | ); |
3545c727 |
362 | $self->associate_method($method); |
1d68af04 |
363 | return ($name, $method); |
2eb717d5 |
364 | } |
9ec169fe |
365 | else { |
1d68af04 |
366 | my $inline_me = ($generate_as_inline_methods && $self->associated_class->instance_metaclass->is_inlinable); |
ba38bf08 |
367 | my $method; |
368 | eval { |
d9d99689 |
369 | if ( $method_ctx ) { |
370 | my $desc = "accessor $accessor"; |
371 | if ( $accessor ne $self->name ) { |
372 | $desc .= " of attribute " . $self->name; |
373 | } |
374 | |
375 | $method_ctx->{description} = $desc; |
376 | } |
377 | |
ba38bf08 |
378 | $method = $self->accessor_metaclass->new( |
379 | attribute => $self, |
d90b42a6 |
380 | is_inline => $inline_me, |
ba38bf08 |
381 | accessor_type => $type, |
4c105333 |
382 | package_name => $self->associated_class->name, |
383 | name => $accessor, |
d9d99689 |
384 | definition_context => $method_ctx, |
1d68af04 |
385 | ); |
ba38bf08 |
386 | }; |
1d68af04 |
387 | confess "Could not create the '$type' method for " . $self->name . " because : $@" if $@; |
3545c727 |
388 | $self->associate_method($method); |
ba38bf08 |
389 | return ($accessor, $method); |
1d68af04 |
390 | } |
9ec169fe |
391 | } |
392 | |
393 | sub install_accessors { |
c0cbf4d9 |
394 | my $self = shift; |
395 | my $inline = shift; |
396 | my $class = $self->associated_class; |
1d68af04 |
397 | |
9ec169fe |
398 | $class->add_method( |
45a183fb |
399 | $self->_process_accessors('accessor' => $self->accessor(), $inline) |
9ec169fe |
400 | ) if $self->has_accessor(); |
401 | |
1d68af04 |
402 | $class->add_method( |
45a183fb |
403 | $self->_process_accessors('reader' => $self->reader(), $inline) |
9ec169fe |
404 | ) if $self->has_reader(); |
405 | |
406 | $class->add_method( |
45a183fb |
407 | $self->_process_accessors('writer' => $self->writer(), $inline) |
9ec169fe |
408 | ) if $self->has_writer(); |
409 | |
410 | $class->add_method( |
45a183fb |
411 | $self->_process_accessors('predicate' => $self->predicate(), $inline) |
9ec169fe |
412 | ) if $self->has_predicate(); |
1d68af04 |
413 | |
7d28758b |
414 | $class->add_method( |
45a183fb |
415 | $self->_process_accessors('clearer' => $self->clearer(), $inline) |
7d28758b |
416 | ) if $self->has_clearer(); |
1d68af04 |
417 | |
9ec169fe |
418 | return; |
2eb717d5 |
419 | } |
420 | |
b51af7f9 |
421 | { |
422 | my $_remove_accessor = sub { |
423 | my ($accessor, $class) = @_; |
9b522fc4 |
424 | if (ref($accessor) && ref($accessor) eq 'HASH') { |
c50c603e |
425 | ($accessor) = keys %{$accessor}; |
1d68af04 |
426 | } |
427 | my $method = $class->get_method($accessor); |
428 | $class->remove_method($accessor) |
b3fa93c7 |
429 | if (ref($method) && $method->isa('Class::MOP::Method::Accessor')); |
b51af7f9 |
430 | }; |
1d68af04 |
431 | |
b51af7f9 |
432 | sub remove_accessors { |
9ec169fe |
433 | my $self = shift; |
2367814a |
434 | # TODO: |
1d68af04 |
435 | # we really need to make sure to remove from the |
436 | # associates methods here as well. But this is |
437 | # such a slimly used method, I am not worried |
2367814a |
438 | # about it right now. |
9ec169fe |
439 | $_remove_accessor->($self->accessor(), $self->associated_class()) if $self->has_accessor(); |
440 | $_remove_accessor->($self->reader(), $self->associated_class()) if $self->has_reader(); |
441 | $_remove_accessor->($self->writer(), $self->associated_class()) if $self->has_writer(); |
442 | $_remove_accessor->($self->predicate(), $self->associated_class()) if $self->has_predicate(); |
7d28758b |
443 | $_remove_accessor->($self->clearer(), $self->associated_class()) if $self->has_clearer(); |
1d68af04 |
444 | return; |
b51af7f9 |
445 | } |
446 | |
8b978dd5 |
447 | } |
448 | |
449 | 1; |
450 | |
451 | __END__ |
452 | |
453 | =pod |
454 | |
1d68af04 |
455 | =head1 NAME |
8b978dd5 |
456 | |
457 | Class::MOP::Attribute - Attribute Meta Object |
458 | |
459 | =head1 SYNOPSIS |
1d68af04 |
460 | |
2e23f7dc |
461 | Class::MOP::Attribute->new( |
462 | foo => ( |
463 | accessor => 'foo', # dual purpose get/set accessor |
464 | predicate => 'has_foo', # predicate check for defined-ness |
465 | init_arg => '-foo', # class->new will look for a -foo key |
466 | default => 'BAR IS BAZ!' # if no -foo key is provided, use this |
467 | ) |
468 | ); |
469 | |
470 | Class::MOP::Attribute->new( |
471 | bar => ( |
472 | reader => 'bar', # getter |
473 | writer => 'set_bar', # setter |
474 | predicate => 'has_bar', # predicate check for defined-ness |
475 | init_arg => ':bar', # class->new will look for a :bar key |
476 | # no default value means it is undef |
477 | ) |
478 | ); |
8b978dd5 |
479 | |
480 | =head1 DESCRIPTION |
481 | |
2e23f7dc |
482 | The Attribute Protocol is almost entirely an invention of |
483 | C<Class::MOP>. Perl 5 does not have a consistent notion of |
484 | attributes. There are so many ways in which this is done, and very few |
485 | (if any) are easily discoverable by this module. |
552e3d24 |
486 | |
2e23f7dc |
487 | With that said, this module attempts to inject some order into this |
1d68af04 |
488 | chaos, by introducing a consistent API which can be used to create |
fe122940 |
489 | object attributes. |
552e3d24 |
490 | |
491 | =head1 METHODS |
492 | |
493 | =head2 Creation |
494 | |
495 | =over 4 |
496 | |
2e23f7dc |
497 | =item B<< Class::MOP::Attribute->new($name, ?%options) >> |
fe122940 |
498 | |
1d68af04 |
499 | An attribute must (at the very least), have a C<$name>. All other |
2e23f7dc |
500 | C<%options> are added as key-value pairs. |
fe122940 |
501 | |
2e23f7dc |
502 | =over 8 |
fe122940 |
503 | |
76187047 |
504 | =item * init_arg |
fe122940 |
505 | |
2e23f7dc |
506 | This is a string value representing the expected key in an |
507 | initialization hash. For instance, if we have an C<init_arg> value of |
508 | C<-foo>, then the following code will Just Work. |
fe122940 |
509 | |
d69fb6b3 |
510 | MyClass->meta->new_object( -foo => 'Hello There' ); |
fe122940 |
511 | |
2e23f7dc |
512 | If an init_arg is not assigned, it will automatically use the |
513 | attribute's name. If C<init_arg> is explicitly set to C<undef>, the |
514 | attribute cannot be specified during initialization. |
7b31baf4 |
515 | |
76187047 |
516 | =item * builder |
1d68af04 |
517 | |
2e23f7dc |
518 | This provides the name of a method that will be called to initialize |
519 | the attribute. This method will be called on the object after it is |
520 | constructed. It is expected to return a valid value for the attribute. |
fe122940 |
521 | |
76187047 |
522 | =item * default |
4c4a6c41 |
523 | |
2e23f7dc |
524 | This can be used to provide an explicit default for initializing the |
525 | attribute. If the default you provide is a subroutine reference, then |
526 | this reference will be called I<as a method> on the object. |
4c4a6c41 |
527 | |
2e23f7dc |
528 | If the value is a simple scalar (string or number), then it can be |
529 | just passed as is. However, if you wish to initialize it with a HASH |
530 | or ARRAY ref, then you need to wrap that inside a subroutine |
531 | reference: |
fe122940 |
532 | |
2e23f7dc |
533 | Class::MOP::Attribute->new( |
534 | 'foo' => ( |
535 | default => sub { [] }, |
536 | ) |
537 | ); |
1d68af04 |
538 | |
539 | # or ... |
540 | |
2e23f7dc |
541 | Class::MOP::Attribute->new( |
542 | 'foo' => ( |
543 | default => sub { {} }, |
544 | ) |
545 | ); |
546 | |
547 | If you wish to initialize an attribute with a subroutine reference |
548 | itself, then you need to wrap that in a subroutine as well: |
549 | |
550 | Class::MOP::Attribute->new( |
551 | 'foo' => ( |
552 | default => sub { |
553 | sub { print "Hello World" } |
554 | }, |
555 | ) |
556 | ); |
557 | |
558 | And lastly, if the value of your attribute is dependent upon some |
559 | other aspect of the instance structure, then you can take advantage of |
560 | the fact that when the C<default> value is called as a method: |
561 | |
562 | Class::MOP::Attribute->new( |
563 | 'object_identity' => ( |
564 | default => sub { Scalar::Util::refaddr( $_[0] ) }, |
565 | ) |
566 | ); |
567 | |
568 | Note that there is no guarantee that attributes are initialized in any |
569 | particular order, so you cannot rely on the value of some other |
570 | attribute when generating the default. |
fe122940 |
571 | |
76187047 |
572 | =item * initializer |
0ef07b33 |
573 | |
2e23f7dc |
574 | This option can be either a method name or a subroutine |
575 | reference. This method will be called when setting the attribute's |
576 | value in the constructor. Unlike C<default> and C<builder>, the |
577 | initializer is only called when a value is provided to the |
578 | constructor. The initializer allows you to munge this value during |
579 | object construction. |
580 | |
581 | The initializer is called as a method with three arguments. The first |
582 | is the value that was passed to the constructor. The second is a |
583 | subroutine reference that can be called to actually set the |
584 | attribute's value, and the last is the associated |
585 | C<Class::MOP::Attribute> object. |
586 | |
587 | This contrived example shows an initializer that sets the attribute to |
588 | twice the given value. |
589 | |
590 | Class::MOP::Attribute->new( |
591 | 'doubled' => ( |
592 | initializer => sub { |
593 | my ( $instance, $value, $set ) = @_; |
594 | $set->( $value * 2 ); |
595 | }, |
596 | ) |
597 | ); |
598 | |
599 | Since an initializer can be a method name, you can easily make |
0ef07b33 |
600 | attribute initialization use the writer: |
601 | |
2e23f7dc |
602 | Class::MOP::Attribute->new( |
603 | 'some_attr' => ( |
604 | writer => 'some_attr', |
605 | initializer => 'some_attr', |
606 | ) |
607 | ); |
0ef07b33 |
608 | |
2e23f7dc |
609 | Your writer will need to examine C<@_> and determine under which |
610 | context it is being called. |
127d39a7 |
611 | |
fe122940 |
612 | =back |
613 | |
2e23f7dc |
614 | The C<accessor>, C<reader>, C<writer>, C<predicate> and C<clearer> |
615 | options all accept the same parameters. You can provide the name of |
616 | the method, in which case an appropriate default method will be |
617 | generated for you. Or instead you can also provide hash reference |
618 | containing exactly one key (the method name) and one value. The value |
619 | should be a subroutine reference, which will be installed as the |
620 | method itself. |
59e7697f |
621 | |
76187047 |
622 | =over 8 |
59e7697f |
623 | |
76187047 |
624 | =item * accessor |
59e7697f |
625 | |
2e23f7dc |
626 | An C<accessor> is a standard Perl-style read/write accessor. It will |
627 | return the value of the attribute, and if a value is passed as an |
628 | argument, it will assign that value to the attribute. |
fe122940 |
629 | |
2e23f7dc |
630 | Note that C<undef> is a legitimate value, so this will work: |
fe122940 |
631 | |
632 | $object->set_something(undef); |
633 | |
76187047 |
634 | =item * reader |
59e7697f |
635 | |
2e23f7dc |
636 | This is a basic read-only accessor. It returns the value of the |
637 | attribute. |
fe122940 |
638 | |
76187047 |
639 | =item * writer |
59e7697f |
640 | |
1d68af04 |
641 | This is a basic write accessor, it accepts a single argument, and |
2e23f7dc |
642 | assigns that value to the attribute. |
59e7697f |
643 | |
2e23f7dc |
644 | Note that C<undef> is a legitimate value, so this will work: |
59e7697f |
645 | |
2e23f7dc |
646 | $object->set_something(undef); |
fe122940 |
647 | |
76187047 |
648 | =item * predicate |
fe122940 |
649 | |
2e23f7dc |
650 | The predicate method returns a boolean indicating whether or not the |
651 | attribute has been explicitly set. |
07dca7e3 |
652 | |
2e23f7dc |
653 | Note that the predicate returns true even if the attribute was set to |
654 | a false value (C<0> or C<undef>). |
07dca7e3 |
655 | |
76187047 |
656 | =item * clearer |
7d28758b |
657 | |
2e23f7dc |
658 | This method will uninitialize the attribute. After an attribute is |
659 | cleared, its C<predicate> will return false. |
7d28758b |
660 | |
76187047 |
661 | =item * definition_context |
f8813817 |
662 | |
663 | Mostly, this exists as a hook for the benefit of Moose. |
664 | |
665 | This option should be a hash reference containing several keys which |
666 | will be used when inlining the attribute's accessors. The keys should |
667 | include C<line>, the line number where the attribute was created, and |
668 | either C<file> or C<description>. |
669 | |
670 | This information will ultimately be used when eval'ing inlined |
671 | accessor code so that error messages report a useful line and file |
672 | name. |
673 | |
59e7697f |
674 | =back |
552e3d24 |
675 | |
2e23f7dc |
676 | =item B<< $attr->clone(%options) >> |
bd4e03f9 |
677 | |
2e23f7dc |
678 | This clones the attribute. Any options you provide will override the |
679 | settings of the original attribute. You can change the name of the new |
680 | attribute by passing a C<name> key in C<%options>. |
127d39a7 |
681 | |
2e23f7dc |
682 | =back |
bd4e03f9 |
683 | |
2e23f7dc |
684 | =head2 Informational |
127d39a7 |
685 | |
2e23f7dc |
686 | These are all basic read-only accessors for the values passed into |
687 | the constructor. |
552e3d24 |
688 | |
2e23f7dc |
689 | =over 4 |
16e960bd |
690 | |
2e23f7dc |
691 | =item B<< $attr->name >> |
2367814a |
692 | |
76187047 |
693 | Returns the attribute's name. |
694 | |
2e23f7dc |
695 | =item B<< $attr->accessor >> |
2367814a |
696 | |
2e23f7dc |
697 | =item B<< $attr->reader >> |
16e960bd |
698 | |
2e23f7dc |
699 | =item B<< $attr->writer >> |
16e960bd |
700 | |
2e23f7dc |
701 | =item B<< $attr->predicate >> |
16e960bd |
702 | |
2e23f7dc |
703 | =item B<< $attr->clearer >> |
c0921932 |
704 | |
2e23f7dc |
705 | The C<accessor>, C<reader>, C<writer>, C<predicate>, and C<clearer> |
706 | methods all return exactly what was passed to the constructor, so it |
a6710c60 |
707 | can be either a string containing a method name, or a hash reference. |
c0921932 |
708 | |
2e23f7dc |
709 | =item B<< $attr->initializer >> |
16e960bd |
710 | |
a6710c60 |
711 | Returns the initializer as passed to the constructor, so this may be |
2e23f7dc |
712 | either a method name or a subroutine reference. |
16e960bd |
713 | |
2e23f7dc |
714 | =item B<< $attr->init_arg >> |
3545c727 |
715 | |
2e23f7dc |
716 | =item B<< $attr->is_default_a_coderef >> |
2367814a |
717 | |
2e23f7dc |
718 | =item B<< $attr->default($instance) >> |
3545c727 |
719 | |
2e23f7dc |
720 | The C<$instance> argument is optional. If you don't pass it, the |
721 | return value for this method is exactly what was passed to the |
722 | constructor, either a simple scalar or a subroutine reference. |
2367814a |
723 | |
2e23f7dc |
724 | If you I<do> pass an C<$instance> and the default is a subroutine |
725 | reference, then the reference is called as a method on the |
726 | C<$instance> and the generated value is returned. |
16e960bd |
727 | |
2e23f7dc |
728 | =item B<< $attr->slots >> |
552e3d24 |
729 | |
2e23f7dc |
730 | Return a list of slots required by the attribute. This is usually just |
731 | one, the name of the attribute. |
fe122940 |
732 | |
2e23f7dc |
733 | A slot is the name of the hash key used to store the attribute in an |
734 | object instance. |
552e3d24 |
735 | |
2e23f7dc |
736 | =item B<< $attr->get_read_method >> |
552e3d24 |
737 | |
2e23f7dc |
738 | =item B<< $attr->get_write_method >> |
552e3d24 |
739 | |
2e23f7dc |
740 | Returns the name of a method suitable for reading or writing the value |
741 | of the attribute in the associated class. |
552e3d24 |
742 | |
2e23f7dc |
743 | If an attribute is read- or write-only, then these methods can return |
744 | C<undef> as appropriate. |
552e3d24 |
745 | |
2e23f7dc |
746 | =item B<< $attr->has_read_method >> |
c50c603e |
747 | |
2e23f7dc |
748 | =item B<< $attr->has_write_method >> |
7d28758b |
749 | |
2e23f7dc |
750 | This returns a boolean indicating whether the attribute has a I<named> |
751 | read or write method. |
0ab65f99 |
752 | |
2e23f7dc |
753 | =item B<< $attr->get_read_method_ref >> |
552e3d24 |
754 | |
2e23f7dc |
755 | =item B<< $attr->get_write_method_ref >> |
495af518 |
756 | |
2e23f7dc |
757 | Returns the subroutine reference of a method suitable for reading or |
758 | writing the attribute's value in the associated class. These methods |
759 | always return a subroutine reference, regardless of whether or not the |
760 | attribute is read- or write-only. |
761 | |
762 | =back |
fe122940 |
763 | |
2e23f7dc |
764 | =head2 Informational predicates |
92d2abfa |
765 | |
2e23f7dc |
766 | These are all basic predicate methods for the values passed into C<new>. |
552e3d24 |
767 | |
2e23f7dc |
768 | =over 4 |
c57c8b10 |
769 | |
2e23f7dc |
770 | =item B<< $attr->has_accessor >> |
c57c8b10 |
771 | |
2e23f7dc |
772 | =item B<< $attr->has_reader >> |
b25109b1 |
773 | |
2e23f7dc |
774 | =item B<< $attr->has_writer >> |
b25109b1 |
775 | |
2e23f7dc |
776 | =item B<< $attr->has_predicate >> |
5da16d1b |
777 | |
2e23f7dc |
778 | =item B<< $attr->has_clearer >> |
5da16d1b |
779 | |
2e23f7dc |
780 | =item B<< $attr->has_initializer >> |
5da16d1b |
781 | |
2e23f7dc |
782 | =item B<< $attr->has_init_arg >> |
5da16d1b |
783 | |
2e23f7dc |
784 | This will be I<false> if the C<init_arg> was set to C<undef>. |
b25109b1 |
785 | |
2e23f7dc |
786 | =item B<< $attr->has_default >> |
9e517e01 |
787 | |
2e23f7dc |
788 | This will be I<false> if the C<default> was set to C<undef>, since |
789 | C<undef> is the default C<default> anyway. |
9e517e01 |
790 | |
2e23f7dc |
791 | =item B<< $attr->has_builder >> |
9e517e01 |
792 | |
552e3d24 |
793 | =back |
794 | |
2e23f7dc |
795 | =head2 Value management |
552e3d24 |
796 | |
a6710c60 |
797 | These methods are basically "back doors" to the instance, and can be |
2e23f7dc |
798 | used to bypass the regular accessors, but still stay within the MOP. |
799 | |
800 | These methods are not for general use, and should only be used if you |
801 | really know what you are doing. |
fe122940 |
802 | |
552e3d24 |
803 | =over 4 |
804 | |
2e23f7dc |
805 | =item B<< $attr->initialize_instance_slot($meta_instance, $instance, $params) >> |
806 | |
807 | This method is used internally to initialize the attribute's slot in |
808 | the object C<$instance>. |
809 | |
810 | The C<$params> is a hash reference of the values passed to the object |
811 | constructor. |
812 | |
813 | It's unlikely that you'll need to call this method yourself. |
552e3d24 |
814 | |
2e23f7dc |
815 | =item B<< $attr->set_value($instance, $value) >> |
552e3d24 |
816 | |
2e23f7dc |
817 | Sets the value without going through the accessor. Note that this |
818 | works even with read-only attributes. |
552e3d24 |
819 | |
2e23f7dc |
820 | =item B<< $attr->set_initial_value($instance, $value) >> |
c50c603e |
821 | |
2e23f7dc |
822 | Sets the value without going through the accessor. This method is only |
823 | called when the instance is first being initialized. |
7d28758b |
824 | |
2e23f7dc |
825 | =item B<< $attr->get_value($instance) >> |
0ab65f99 |
826 | |
2e23f7dc |
827 | Returns the value without going through the accessor. Note that this |
828 | works even with write-only accessors. |
552e3d24 |
829 | |
2e23f7dc |
830 | =item B<< $attr->has_value($instance) >> |
552e3d24 |
831 | |
2e23f7dc |
832 | Return a boolean indicating whether the attribute has been set in |
833 | C<$instance>. This how the default C<predicate> method works. |
834 | |
835 | =item B<< $attr->clear_value($instance) >> |
836 | |
837 | This will clear the attribute's value in C<$instance>. This is what |
838 | the default C<clearer> calls. |
839 | |
840 | Note that this works even if the attribute does not have any |
841 | associated read, write or clear methods. |
bf731086 |
842 | |
552e3d24 |
843 | =back |
844 | |
9ec169fe |
845 | =head2 Class association |
846 | |
1d68af04 |
847 | These methods allow you to manage the attributes association with |
848 | the class that contains it. These methods should not be used |
2367814a |
849 | lightly, nor are they very magical, they are mostly used internally |
850 | and by metaclass instances. |
851 | |
9ec169fe |
852 | =over 4 |
853 | |
2e23f7dc |
854 | =item B<< $attr->associated_class >> |
855 | |
856 | This returns the C<Class::MOP::Class> with which this attribute is |
857 | associated, if any. |
858 | |
859 | =item B<< $attr->attach_to_class($metaclass) >> |
9ec169fe |
860 | |
2e23f7dc |
861 | This method stores a weakened reference to the C<$metaclass> object |
862 | internally. |
2367814a |
863 | |
2e23f7dc |
864 | This method does not remove the attribute from its old class, |
865 | nor does it create any accessors in the new class. |
9ec169fe |
866 | |
2e23f7dc |
867 | It is probably best to use the L<Class::MOP::Class> C<add_attribute> |
868 | method instead. |
2367814a |
869 | |
2e23f7dc |
870 | =item B<< $attr->detach_from_class >> |
9ec169fe |
871 | |
2e23f7dc |
872 | This method removes the associate metaclass object from the attribute |
873 | it has one. |
874 | |
875 | This method does not remove the attribute itself from the class, or |
876 | remove its accessors. |
877 | |
878 | It is probably best to use the L<Class::MOP::Class> |
879 | C<remove_attribute> method instead. |
2367814a |
880 | |
9ec169fe |
881 | =back |
882 | |
552e3d24 |
883 | =head2 Attribute Accessor generation |
884 | |
885 | =over 4 |
886 | |
2e23f7dc |
887 | =item B<< $attr->accessor_metaclass >> |
ba38bf08 |
888 | |
2e23f7dc |
889 | Accessor methods are generated using an accessor metaclass. By |
890 | default, this is L<Class::MOP::Method::Accessor>. This method returns |
2367814a |
891 | the name of the accessor metaclass that this attribute uses. |
892 | |
2e23f7dc |
893 | =item B<< $attr->associate_method($method) >> |
2367814a |
894 | |
2e23f7dc |
895 | This associates a L<Class::MOP::Method> object with the |
896 | attribute. Typically, this is called internally when an attribute |
897 | generates its accessors. |
3545c727 |
898 | |
2e23f7dc |
899 | =item B<< $attr->associated_methods >> |
3545c727 |
900 | |
2e23f7dc |
901 | This returns the list of methods which have been associated with the |
902 | attribute. |
2367814a |
903 | |
2e23f7dc |
904 | =item B<< $attr->install_accessors >> |
2eb717d5 |
905 | |
2e23f7dc |
906 | This method generates and installs code the attributes various |
907 | accessors. It is typically called from the L<Class::MOP::Class> |
908 | C<add_attribute> method. |
2eb717d5 |
909 | |
2e23f7dc |
910 | =item B<< $attr->remove_accessors >> |
2eb717d5 |
911 | |
2e23f7dc |
912 | This method removes all of the accessors associated with the |
913 | attribute. |
2eb717d5 |
914 | |
2e23f7dc |
915 | This does not currently remove methods from the list returned by |
916 | C<associated_methods>. |
2367814a |
917 | |
2eb717d5 |
918 | =back |
919 | |
920 | =head2 Introspection |
921 | |
922 | =over 4 |
552e3d24 |
923 | |
45b4c423 |
924 | =item B<< Class::MOP::Attribute->meta >> |
552e3d24 |
925 | |
2e23f7dc |
926 | This will return a L<Class::MOP::Class> instance for this class. |
fe122940 |
927 | |
2e23f7dc |
928 | It should also be noted that L<Class::MOP> will actually bootstrap |
929 | this module by installing a number of attribute meta-objects into its |
930 | metaclass. |
fe122940 |
931 | |
552e3d24 |
932 | =back |
933 | |
1a09d9cc |
934 | =head1 AUTHORS |
8b978dd5 |
935 | |
a2e85e6c |
936 | Stevan Little E<lt>stevan@iinteractive.comE<gt> |
8b978dd5 |
937 | |
938 | =head1 COPYRIGHT AND LICENSE |
939 | |
070bb6c9 |
940 | Copyright 2006-2009 by Infinity Interactive, Inc. |
8b978dd5 |
941 | |
942 | L<http://www.iinteractive.com> |
943 | |
944 | This library is free software; you can redistribute it and/or modify |
1d68af04 |
945 | it under the same terms as Perl itself. |
8b978dd5 |
946 | |
16e960bd |
947 | =cut |
948 | |
7d28758b |
949 | |