1Object::InsideOut::MetaUdsaetra(C3o)ntributed Perl DocumOebnjteactti:o:nInsideOut::Metadata(3)
2
6 Object::InsideOut::Metadata - Introspection for Object::InsideOut
7 classes
8
10 This document describes Object::InsideOut::Metadata version 2.06
11
13 package My::Class; {
14 use Object::InsideOut;
15 use Object::InsideOut::Metadata;
16 my @data :Field :Arg('data') :Get('data') :Set('put_data');
18 my @misc :Field;
19 my %init_args :InitArgs = (
21 'INFO' => '',
22 );
23 sub _init :Init
25 {
26 my ($self, $args) = @_;
27 if (exists($args->{'INFO'})) {
28 $misc[$$self] = 'INFO: ' . $args->{'INFO'};
29 }
30 }
31 sub misc :lvalue :Method
33 {
34 my $self = shift;
35 $misc[$$self];
36 }
37 add_meta(__PACKAGE__, 'misc', { 'lvalue' => 1 });
38 }
39 package main;
41 # Obtain a metadata object for a class
43 my $meta = My::Class->meta();
44 # ... or obtain a metadata object for an object
46 my $obj = My::Class->new();
47 my $meta = $obj->meta();
48 # Obtain the class hierarchy from the metadata object
50 my @classes = $meta->get_classes();
51 # Obtain infomation on the parameters for a class's construction
53 my %args = $meta->get_args();
54 # Obtain information on a class's methods
56 my %methods = $meta->get_methods();
57
59 Object::InsideOut provides an introspection API that allows you to
60 obtain metadata on a class's hierarchy, constructor parameters, and
61 methods. This is done through the use of metadata objects that are
62 generated by this class.
63 In addition, developers can specify metadata data for methods they
65 write for their classes.
66
68 To obtain metadata on an Object::InsideOut class or object, you must
69 first generate a metadata object for that class or object. Using that
70 metadata object, one can then obtain information on the class hierar‐
71 chy, constructor parameters, and methods.
72 my $meta = My::Class->meta();
74 my $meta = $obj->meta();
75 The "->meta()" method, which is exported by Object::InsideOut to
76 each class, returns an Object::InsideOut::Metadata object which can
77 then be queried for information about the invoking class or invok‐
78 ing object's class.
79
81 Any Object::InsideOut class potentially has four categories of classes
82 associated with it:
83 1. Object::InsideOut
85 While the basis for all Object::InsideOut classes it is not an
86 object class per se because you can create objects from it (i.e.,
87 you can't do "Object::InsideOut-"new()>). While
88 "My::Class-"isa('Object::InsideOut')> will return true, because
89 Object::InsideOut is not an object class, it is not considered to
90 be part of a class's hierarchy.
91 2. The class itself
93 A class's hierarchy always includes itself.
94 3. Parent classes
96 These are all the Object::InsideOut classes up the inheritance tree
97 that a class is derived from.
98 4. Foreign classes
100 These are non-Object::InsideOut classes that a class inherits from.
101 (See "FOREIGN CLASS INHERITANCE" in Object::InsideOut.) Because of
102 implementation details, foreign classes do not appear in a class's
103 @ISA array. However, Object::InsideOut implements a version of
104 "->isa()" that handles foreign classes.
105 A class's hierarchy consists of any classes in the latter three cate‐
107 gories.
108 $meta->get_classes();
110 When called in an array context, returns a list that constitutes
111 the class hierarchy for the class or object used to generate the
112 metadata object. When called in a scalar context, returns an array
113 ref.
114 My::Class->isa();
116 $obj->isa();
117 When called in an array context, calling "->isa()" without any
118 arguments on an Object::InsideOut class or object returns a list of
119 the classes in the class hierarchy for that class or object, and is
120 equivalent to:
121 my @classes = $obj->meta()->get_classes();
123 When called in a scalar context, it returns an array ref containing
125 the classes.
126
128 Constructor parameters are the arguments given to a class's "->new()"
129 call.
130 $meta->get_args();
132 Returns a hash (hash ref in scalar context) containing information
133 on the parameters that can be used to construct an object from the
134 class associated with the metadata object. Here's an example of
135 such a hash:
136 {
138 'My::Class' => {
139 'data' => {
140 'field' => 1,
141 'type' => numeric,
142 },
143 'misc' => {
144 'mandatory' => 1,
145 },
146 },
147 'My::Parent' => {
148 'info' => {
149 'default' => '<none>',
150 },
151 },
152 }
153 The keys for this hash are the Object::IsideOut classes in the
155 class hierarchy. These class keys are paired with hash refs, the
156 keys of which are the names of the parameters for that class (e.g.,
157 'data' and 'misc' for My::Class, and 'info' for My::Parent). The
158 hashes paired to the parameters contain information about the
159 parameter:
160 field
162 The parameter corresponds directly to a class field, and is
163 automatically processed during object creation. See
164 "Field-Specific Parameters" in Object::InsideOut.
165 mandatory
167 The parameter is required for object creation. See "Mandatory
168 Parameters" in Object::InsideOut.
169 default
171 The default value assigned to the parameter if it is not found
172 in the arguments to "->new()". See "Default Values" in
173 Object::InsideOut.
174 preproc
176 The code ref for the subroutine that is used to preprocess a
177 parameter's value. See "Parameter Preprocessing" in
178 Object::InsideOut
179 type
181 The form of type checking performed on the parameter. See
182 "TYPE CHECKING" in Object::InsideOut
183 'numeric'
185 Parameter takes a numeric value as recognized by
186 Scalar::Util::looks_like_number().
187 'list'
189 Parameter takes a single value (which is then placed in an
190 array ref) or an array ref.
191 A class name
193 Parameter takes an object of a specified class, or one of
194 its sub-classes as recognized by "->isa()".
195 Other reference type
197 Parameter takes a reference of the specified type as
198 returned by ref().
199 A code ref
201 Parameter takes a value that is type-checked by the code
202 ref paired to the 'type' key.
203
205 The methods returned by a metadata object are those that are currently
206 available at the time of the "->get_methods()" call.
207 The presense of ":Automethod" subroutines in an Object::InsideOut
209 class, or "AUTOLOAD" in a foreign class means that the methods sup‐
210 ported by the class may not be determinable. The presense of
211 "AUTOLOAD" in the list of methods for a class should alert the program‐
212 mer to the fact that more methods may be supported than are listed.
213 Methods that are excluded are private and hidden methods (see "PERMIS‐
215 SIONS" in Object::InsideOut), methods that begin with an underscore
216 (which, by convention, means they are private), and subroutines named
217 "CLONE", "CLONE_SKIP", and "DESTROY" (which are not methods). While
218 technically a method, "import" is also excluded as it is generally not
219 used as such.
220 $meta->get_methods();
222 Returns a hash (hash ref in scalar context) containing information
223 on the methods for the class associated with the metadata object.
224 The keys in the hash are the method names. Paired to the names are
225 hash refs containing metadata about the methods. Here's an exam‐
226 ple:
227 {
229 # Methods exported by Object::InsideOut
230 'new' => {
231 'class' => 'My::Class',
232 'kind' => 'constructor'
233 },
234 'clone' => {
235 'class' => 'My::Class',
236 'kind' => 'object'
237 },
238 'meta' => {
239 'class' => 'My::Class'
240 },
241 'set' => {
242 'class' => 'My::Class',
243 'kind' => 'object',
244 'restricted' => 1
245 },
246 # Methods provided by Object::InsideOut
247 'dump' => {
248 'class' => 'Object::InsideOut',
249 'kind' => 'object'
250 },
251 'pump' => {
252 'class' => 'Object::InsideOut',
253 'kind' => 'class'
254 },
255 'inherit' => {
256 'class' => 'Object::InsideOut',
257 'kind' => 'object',
258 'restricted' => 1
259 },
260 'heritage' => {
261 'class' => 'Object::InsideOut',
262 'kind' => 'object',
263 'restricted' => 1
264 },
265 'disinherit' => {
266 'class' => 'Object::InsideOut',
267 'kind' => 'object',
268 'restricted' => 1
269 },
270 # Methods generated by Object::InsideOut for My::Class
271 'set_data' => {
272 'class' => 'My::Class',
273 'kind' => 'set',
274 'type' => 'ARRAY',
275 'return' => 'new'
276 },
277 'get_data' => {
278 'class' => 'My::Class',
279 'kind' => 'get'
280 }
281 # Class method provided by My::Class
282 'my_method' => {
283 'class' => 'My::Class',
284 'kind' => 'class'
285 }
286 }
287 Here are the method metadata that are provided:
289 class
291 The class in whose symbol table the method resides. The method
292 may reside in the classes code, it may be exported by another
293 class, or it may be generated by Object::InsideOut.
294 Methods that are overridden in child classes are represented as
296 being associated with the most junior class for which they
297 appear.
298 kind
300 Designation of the characteristic of the method:
301 constructor
303 The "->new()" method, of course.
304 get, set or accessor
306 A get, set, or combined accessor generated by
307 Object::InsideOut. See "AcCESSOR GENERATION" in
308 Object::InsideOut.
309 cumulative, or cumulative (bottom up)
311 chained, or chained (bottom up)
312 A cumulative or chained method. See "CUMULATIVE METHODS"
313 in Object::InsideOut, and "CHAINED METHODS" in
314 Object::InsideOut. The class associated with these methods
315 is the most junior class in which they appears.
316 class
318 A method that is callable only on a class (e.g.,
319 "My::Class->my_method()").
320 object
322 A method that is callable only on a object (e.g.
323 "$obj->get_data()").
324 foreign
326 A subroutine found in a foreign class's symbol table. Pro‐
327 grammers must check the class's documentation to determine
328 which are actually methods, and what kinds of methods they
329 are.
330 overload
332 A subroutine used for object coercion. These may be called
333 as methods, but this is not normally how they are used.
334 automethod
336 Associated with an AUTOLOAD method for an Object::InsideOut
337 class that implements an ":Automethod" subroutine. See
338 "AUTOMETHODS" in Object::InsideOut.
339 type
341 The type checking that is done on arguments to set/combined
342 accessors generated by Object::InsideOut. See "TYPE CHECKING"
343 in Object::InsideOut
344 return
346 The value returned by a set/combined accessor generated by
347 Object::InsideOut. See "Set Accessor Return Value" in
348 Object::InsideOut
349 lvalue
351 The method is an :lvalue accessor.
352 restricted
354 The method is restricted (i.e., callable only from within the
355 class hierarchy; not callable from application code). See
356 "PERMISSIONS" in Object::InsideOut.
357 My::Class->can();
359 $obj->can();
360 When called in an array context, calling "->can()" without any
361 arguments on an Object::InsideOut class or object returns a list of
362 the method names for that class or object, and is equivalent to:
363 my %meths = $obj->meta()->get_methods();
365 my @methods = keys(%meths);
366 When called in a scalar context, it returns an array ref containing
368 the method names.
369 METADATA ATTRIBUTES
371 Class authors may add the ":Method" attribute to subroutines in their
373 classes to specifically design them as OO-callable methods. If a
374 method is only a class method or only an object method, this may be
375 added as a parameter to the attribute:
376 sub my_method :Method(class)
378 {
379 ...
380 The class or object parameter will appear in the metadata for the
382 method when listed using "->get_methods()".
383 CAUTION: Be sure not to use ":method" (all lowercase) as this is a
385 Perl reserved attribute.
386 The ":Sub" attribute can be used to designate subroutines that are not
388 OO-callable methods. These subroutines will not show up as part of the
389 methods listed by "->get_methods()", etc..
390 Subroutine names beginning with an underscore are, by convention, con‐
392 sidered private, and will not show up as part of the methods listed by
393 "->get_methods()", etc..
394 ADDING METADATA
396 Class authors may add additional metadata to their methods using the
398 "add_meta()" subroutine which is exported by this package. For exam‐
399 ple, if the class implements it own ":lvalue" method, it should add
400 that metadata so that it is picked up the "->get_methods()":
401 package My::Class; {
403 use Object::InsideOut;
404 use Object::InsideOut::Metadata;
405 sub my_method :lvalue :Method(object)
407 {
408 ....
409 }
410 add_meta(__PACKAGE__, 'my_method', 'lvalue', 1);
411 }
412 The arguments to "add_meta()" are:
414 Class name
416 This can usually be designated using the special literal C__PACK‐
417 AGE__>.
418 Method name
420 Metadata name
421 This can be any of the metadata names under "METHODS METADATA", or
422 can be whatever additional name the programmer chooses to imple‐
423 ment.
424 Metadata value
426 When adding multiple metadata for a method, they may be enclosed in a
428 single hash ref:
429 add_meta(__PACKAGE__, 'my_method', { 'lvalue' => 1,
431 'return' => 'old' });
432 If adding metadata for multiple methods, another level of hash may be
434 used:
435 add_meta(__PACKAGE__, { 'my_method' => { 'lvalue' => 1,
437 'return' => 'old' },
438 'get_info' => { 'my_meta' => 'true' } });
439
441 Provide filtering capabilities on the method information returned by
442 "->get_methods()".
443
445 Object::InsideOut
446 Perl 6 introspection:
448 <http://dev.perl.org/perl6/doc/design/apo/A12.html#Introspection>, and
449 <http://dev.perl.org/perl6/rfc/335.html>
450
452 Jerry D. Hedden, <jdhedden AT cpan DOT org>
453
455 Copyright 2006 Jerry D. Hedden. All rights reserved.
456 This program is free software; you can redistribute it and/or modify it
458 under the same terms as Perl itself.
459perl v5.8.8 2006-10-09 Object::InsideOut::Metadata(3)