1Class::MOP::Attribute(3U)ser Contributed Perl DocumentatiColnass::MOP::Attribute(3)
2
6 Class::MOP::Attribute - Attribute Meta Object
7
9 Class::MOP::Attribute->new('$foo' => (
10 accessor => 'foo', # dual purpose get/set accessor
11 predicate => 'has_foo' # predicate check for defined-ness
12 init_arg => '-foo', # class->new will look for a -foo key
13 default => 'BAR IS BAZ!' # if no -foo key is provided, use this
14 ));
15 Class::MOP::Attribute->new('$.bar' => (
17 reader => 'bar', # getter
18 writer => 'set_bar', # setter
19 predicate => 'has_bar' # predicate check for defined-ness
20 init_arg => ':bar', # class->new will look for a :bar key
21 # no default value means it is undef
22 ));
23
25 The Attribute Protocol is almost entirely an invention of this module,
26 and is completely optional to this MOP. This is because Perl 5 does not
27 have consistent notion of what is an attribute of a class. There are so
28 many ways in which this is done, and very few (if any) are easily dis‐
29 coverable by this module.
30 So, all that said, this module attempts to inject some order into this
32 chaos, by introducing a consistent API which can be used to create
33 object attributes.
34
36 Creation
37 new ($name, ?%options)
39 An attribute must (at the very least), have a $name. All other
40 %options are contained added as key-value pairs. Acceptable keys
41 are as follows:
42 init_arg
44 This should be a string value representing the expected key in
45 an initialization hash. For instance, if we have an init_arg
46 value of "-foo", then the following code will Just Work.
47 MyClass->meta->construct_instance(-foo => "Hello There");
49 In an init_arg is not assigned, it will automatically use the
51 value of $name.
52 default
54 The value of this key is the default value which
55 "Class::MOP::Class::construct_instance" will initialize the
56 attribute to.
57 builder
59 The value of this key is the name of the method that will be
60 called to obtain the value used to initialize the attribute.
61 This should be a method in the class associated with the
62 attribute, not a method in the attribute class itself.
63 NOTE: If the value is a simple scalar (string or number), then
65 it can be just passed as is. However, if you wish to initialize
66 it with a HASH or ARRAY ref, then you need to wrap that inside
67 a CODE reference, like so:
68 Class::MOP::Attribute->new('@foo' => (
70 default => sub { [] },
71 ));
72 # or ...
74 Class::MOP::Attribute->new('%foo' => (
76 default => sub { {} },
77 ));
78 If you wish to initialize an attribute with a CODE reference
80 itself, then you need to wrap that in a subroutine as well,
81 like so:
82 Class::MOP::Attribute->new('&foo' => (
84 default => sub { sub { print "Hello World" } },
85 ));
86 And lastly, if the value of your attribute is dependent upon
88 some other aspect of the instance structure, then you can take
89 advantage of the fact that when the default value is a CODE
90 reference, it is passed the raw (unblessed) instance structure
91 as it's only argument. So you can do things like this:
92 Class::MOP::Attribute->new('$object_identity' => (
94 default => sub { Scalar::Util::refaddr($_[0]) },
95 ));
96 This last feature is fairly limited as there is no gurantee of
98 the order of attribute initializations, so you cannot perform
99 any kind of dependent initializations. However, if this is
100 something you need, you could subclass Class::MOP::Class and
101 this class to acheive it. However, this is currently left as an
102 exercise to the reader :).
103 The accessor, reader, writer, predicate and clearer keys can con‐
105 tain either; the name of the method and an appropriate default one
106 will be generated for you, or a HASH ref containing exactly one key
107 (which will be used as the name of the method) and one value, which
108 should contain a CODE reference which will be installed as the
109 method itself.
110 accessor
112 The accessor is a standard perl-style read/write accessor. It
113 will return the value of the attribute, and if a value is
114 passed as an argument, it will assign that value to the
115 attribute.
116 NOTE: This method will properly handle the following code, by
118 assigning an "undef" value to the attribute.
119 $object->set_something(undef);
121 reader
123 This is a basic read-only accessor, it will just return the
124 value of the attribute.
125 writer
127 This is a basic write accessor, it accepts a single argument,
128 and assigns that value to the attribute. This method does not
129 intentially return a value, however perl will return the result
130 of the last expression in the subroutine, which returns in this
131 returning the same value that it was passed.
132 NOTE: This method will properly handle the following code, by
134 assigning an "undef" value to the attribute.
135 $object->set_something();
137 predicate
139 This is a basic test to see if the value of the attribute is
140 not "undef". It will return true (1) if the attribute's value
141 is defined, and false (0) otherwise.
142 clearer
144 This is the a method that will uninitialize the attr, reverting
145 lazy values back to their "unfulfilled" state.
146 clone (%options)
148 initialize_instance_slot ($instance, $params)
149 Value management
151 These methods are basically "backdoors" to the instance, which can be
153 used to bypass the regular accessors, but still stay within the context
154 of the MOP.
155 These methods are not for general use, and should only be used if you
157 really know what you are doing.
158 set_value ($instance, $value)
160 Set the value without going through the accessor. Note that this
161 may be done to even attributes with just read only accessors.
162 get_value ($instance)
164 Return the value without going through the accessor. Note that this
165 may be done even to attributes with just write only accessors.
166 has_value ($instance)
168 Returns a boolean indicating if the item in the $instance has a
169 value in it. This is basically what the default "predicate" method
170 calls.
171 clear_value ($instance)
173 This will clear the value in the $instance. This is basically what
174 the default "clearer" would call. Note that this may be done even
175 if the attirbute does not have any associated read, write or clear
176 methods.
177 Informational
179 These are all basic read-only value accessors for the values passed
181 into "new". I think they are pretty much self-explanitory.
182 name
184 accessor
185 reader
186 writer
187 predicate
188 clearer
189 init_arg
190 is_default_a_coderef
191 default (?$instance)
192 As noted in the documentation for "new" above, if the default value
193 is a CODE reference, this accessor will pass a single additional
194 argument $instance into it and return the value.
195 slots
197 Returns a list of slots required by the attribute. This is usually
198 just one, which is the name of the attribute.
199 get_read_method
201 get_write_method
202 Return the name of a method name suitable for reading / writing the
203 value of the attribute in the associated class. Suitable for use
204 whether "reader" and "writer" or "accessor" was used.
205 get_read_method_ref
207 get_write_method_ref
208 Return the CODE reference of a method suitable for reading / writ‐
209 ing the value of the attribute in the associated class. Suitable
210 for use whether "reader" and "writer" or "accessor" was specified
211 or not.
212 NOTE: If not reader/writer/accessor was specified, this will use
214 the attribute get_value/set_value methods, which can be very inef‐
215 ficient.
216 Informational predicates
218 These are all basic predicate methods for the values passed into "new".
220 has_accessor
222 has_reader
223 has_writer
224 has_predicate
225 has_clearer
226 has_init_arg
227 has_default
228 has_builder
229 Class association
231 These methods allow you to manage the attributes association with the
233 class that contains it. These methods should not be used lightly, nor
234 are they very magical, they are mostly used internally and by metaclass
235 instances.
236 associated_class
238 This returns the metaclass this attribute is associated with.
239 attach_to_class ($class)
241 This will store a weaken reference to $class internally. You should
242 note that just changing the class assocation will not remove the
243 attribute from it's old class, and initialize it (and it's acces‐
244 sors) in the new $class. It is up to you to do this manually.
245 detach_from_class
247 This will remove the weakened reference to the class. It does not
248 remove the attribute itself from the class (or remove it's acces‐
249 sors), you must do that yourself if you want too. Actually if that
250 is what you want to do, you should probably be looking at
251 Class::MOP::Class::remove_attribute instead.
252 Attribute Accessor generation
254 accessor_metaclass
256 Accessors are generated by an accessor metaclass, which is usually
257 a subclass of "Class::MOP::Method::Accessor". This method returns
258 the name of the accessor metaclass that this attribute uses.
259 associate_method ($method)
261 This will associate a $method with the given attribute which is
262 used internally by the accessor generator.
263 associated_methods
265 This will return the list of methods which have been associated
266 with the "associate_method" methods.
267 install_accessors
269 This allows the attribute to generate and install code for it's own
270 accessor/reader/writer/predicate methods. This is called by
271 "Class::MOP::Class::add_attribute".
272 This method will call "process_accessors" for each of the possible
274 method types (accessor, reader, writer & predicate).
275 process_accessors ($type, $value)
277 This takes a $type (accessor, reader, writer or predicate), and a
278 $value (the value passed into the constructor for each of the dif‐
279 ferent types). It will then either generate the method itself
280 (using the "generate_*_method" methods listed below) or it will use
281 the custom method passed through the constructor.
282 remove_accessors
284 This allows the attribute to remove the method for it's own acces‐
285 sor/reader/writer/predicate/clearer. This is called by
286 "Class::MOP::Class::remove_attribute".
287 NOTE: This does not currently remove methods from the list returned
289 by "associated_methods", that is on the TODO list.
290 Introspection
292 meta
294 This will return a Class::MOP::Class instance which is related to
295 this class.
296 It should also be noted that Class::MOP will actually bootstrap
298 this module by installing a number of attribute meta-objects into
299 it's metaclass. This will allow this class to reap all the benifits
300 of the MOP when subclassing it.
301
303 Stevan Little <stevan@iinteractive.com>
304
306 Copyright 2006, 2007 by Infinity Interactive, Inc.
307 <http://www.iinteractive.com>
309 This library is free software; you can redistribute it and/or modify it
311 under the same terms as Perl itself.
312perl v5.8.8 2007-11-07 Class::MOP::Attribute(3)