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