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 4.05
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 information 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
71 hierarchy, 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
78 invoking 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
107 categories.
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 "Field-
164 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 for more details.
183 'numeric'
185 Parameter takes a numeric value as recognized by
186 Scalar::Util::looks_like_number().
187 'list'
189 'list(_subtype_)'
190 Parameter takes a single value (which is then placed in an
191 array ref) or an array ref.
192 When specified, the contents of the resulting array ref
194 must be of the specified subtype:
195 'numeric'
197 Same as for the basic type above.
198 A class name
200 Same as for the basic type below.
201 A reference type
203 Any reference type as returned by ref()).
204 'ARRAY(_subtype_)'
206 Parameter takes an array ref with contents of the specified
207 subtype as per the above.
208 A class name
210 Parameter takes an object of a specified class, or one of
211 its sub-classes as recognized by "->isa()".
212 Other reference type
214 Parameter takes a reference of the specified type as
215 returned by ref().
216 A code ref
218 Parameter takes a value that is type-checked by the code
219 ref paired to the 'type' key.
220
222 The methods returned by a metadata object are those that are currently
223 available at the time of the "->get_methods()" call.
224 The presence of ":Automethod" subroutines in an Object::InsideOut
226 class, or "AUTOLOAD" in a foreign class means that the methods
227 supported by the class may not be determinable. The presence of
228 "AUTOLOAD" in the list of methods for a class should alert the
229 programmer to the fact that more methods may be supported than are
230 listed.
231 Methods that are excluded are private and hidden methods (see
233 "PERMISSIONS" in Object::InsideOut), methods that begin with an
234 underscore (which, by convention, means they are private), and
235 subroutines named "CLONE", "CLONE_SKIP", and "DESTROY" (which are not
236 methods). While technically a method, "import" is also excluded as it
237 is generally not invoked directly (i.e., it's usually called as part of
238 "use").
239 $meta->get_methods();
241 Returns a hash (hash ref in scalar context) containing information
242 on the methods for the class associated with the metadata object.
243 The keys in the hash are the method names. Paired to the names are
244 hash refs containing metadata about the methods. Here's an
245 example:
246 {
248 # Methods exported by Object::InsideOut
249 'new' => {
250 'class' => 'My::Class',
251 'kind' => 'constructor'
252 },
253 'clone' => {
254 'class' => 'My::Class',
255 'kind' => 'object'
256 },
257 'meta' => {
258 'class' => 'My::Class'
259 },
260 'set' => {
261 'class' => 'My::Class',
262 'kind' => 'object',
263 'restricted' => 1
264 },
265 # Methods provided by Object::InsideOut
266 'dump' => {
267 'class' => 'Object::InsideOut',
268 'kind' => 'object'
269 },
270 'pump' => {
271 'class' => 'Object::InsideOut',
272 'kind' => 'class'
273 },
274 'inherit' => {
275 'class' => 'Object::InsideOut',
276 'kind' => 'object',
277 'restricted' => 1
278 },
279 'heritage' => {
280 'class' => 'Object::InsideOut',
281 'kind' => 'object',
282 'restricted' => 1
283 },
284 'disinherit' => {
285 'class' => 'Object::InsideOut',
286 'kind' => 'object',
287 'restricted' => 1
288 },
289 # Methods generated by Object::InsideOut for My::Class
290 'set_data' => {
291 'class' => 'My::Class',
292 'kind' => 'set',
293 'type' => 'ARRAY',
294 'return' => 'new'
295 },
296 'get_data' => {
297 'class' => 'My::Class',
298 'kind' => 'get'
299 }
300 # Class method provided by My::Class
301 'my_method' => {
302 'class' => 'My::Class',
303 'kind' => 'class'
304 }
305 }
306 Here are the method metadata that are provided:
308 class
310 The class in whose symbol table the method resides. The method
311 may reside in the classes code, it may be exported by another
312 class, or it may be generated by Object::InsideOut.
313 Methods that are overridden in child classes are represented as
315 being associated with the most junior class for which they
316 appear.
317 kind
319 Designation of the characteristic of the method:
320 constructor
322 The "->new()" method, of course.
323 get, set or accessor
325 A get, set, or combined accessor generated by
326 Object::InsideOut. See "AcCESSOR GENERATION" in
327 Object::InsideOut.
328 cumulative, or cumulative (bottom up)
330 chained, or chained (bottom up)
331 A cumulative or chained method. See "CUMULATIVE METHODS"
332 in Object::InsideOut, and "CHAINED METHODS" in
333 Object::InsideOut. The class associated with these methods
334 is the most junior class in which they appears.
335 class
337 A method that is callable only on a class (e.g.,
338 "My::Class->my_method()").
339 object
341 A method that is callable only on a object (e.g.
342 "$obj->get_data()").
343 foreign
345 A subroutine found in a foreign class's symbol table.
346 Programmers must check the class's documentation to
347 determine which are actually methods, and what kinds of
348 methods they are.
349 overload
351 A subroutine used for object coercion. These may be called
352 as methods, but this is not normally how they are used.
353 automethod
355 Associated with an AUTOLOAD method for an Object::InsideOut
356 class that implements an ":Automethod" subroutine. See
357 "AUTOMETHODS" in Object::InsideOut.
358 type
360 The type checking that is done on arguments to set/combined
361 accessors generated by Object::InsideOut. See "TYPE CHECKING"
362 in Object::InsideOut
363 return
365 The value returned by a set/combined accessor generated by
366 Object::InsideOut. See "Set Accessor Return Value" in
367 Object::InsideOut
368 lvalue
370 The method is an :lvalue accessor.
371 restricted
373 The method is restricted (i.e., callable only from within the
374 class hierarchy; not callable from application code). See
375 "PERMISSIONS" in Object::InsideOut.
376 My::Class->can();
378 $obj->can();
379 When called in an array context, calling "->can()" without any
380 arguments on an Object::InsideOut class or object returns a list of
381 the method names for that class or object, and is equivalent to:
382 my %meths = $obj->meta()->get_methods();
384 my @methods = keys(%meths);
385 When called in a scalar context, it returns an array ref containing
387 the method names.
388 METADATA ATTRIBUTES
390 Class authors may add the ":Method" attribute to subroutines in their
391 classes to specifically designate them as OO-callable methods. If a
392 method is only a class method or only an object method, this may be
393 added as a parameter to the attribute:
394 sub my_method :Method(class)
396 {
397 ...
398 The class or object parameter will appear in the metadata for the
400 method when listed using "->get_methods()".
401 CAUTION: Be sure not to use ":method" (all lowercase) except as
403 appropriate (see "ARGUMENT VALIDATION" in Object::InsideOut) as this is
404 a Perl reserved attribute.
405 The ":Sub" attribute can be used to designate subroutines that are not
407 OO-callable methods. These subroutines will not show up as part of the
408 methods listed by "->get_methods()", etc..
409 Subroutine names beginning with an underscore are, by convention,
411 considered private, and will not show up as part of the methods listed
412 by "->get_methods()", etc..
413 ADDING METADATA
415 Class authors may add additional metadata to their methods using the
416 "add_meta()" subroutine which is exported by this package. For
417 example, if the class implements it own ":lvalue" method, it should add
418 that metadata so that it is picked up the "->get_methods()":
419 package My::Class; {
421 use Object::InsideOut;
422 use Object::InsideOut::Metadata;
423 sub my_method :lvalue :Method(object)
425 {
426 ....
427 }
428 add_meta(__PACKAGE__, 'my_method', 'lvalue', 1);
429 }
430 The arguments to "add_meta()" are:
432 Class name
434 This can usually be designated using the special literal
435 C__PACKAGE__>.
436 Method name
438 Metadata name
439 This can be any of the metadata names under "METHODS METADATA", or
440 can be whatever additional name the programmer chooses to
441 implement.
442 Metadata value
444 When adding multiple metadata for a method, they may be enclosed in a
446 single hash ref:
447 add_meta(__PACKAGE__, 'my_method', { 'lvalue' => 1,
449 'return' => 'old' });
450 If adding metadata for multiple methods, another level of hash may be
452 used:
453 add_meta(__PACKAGE__, { 'my_method' => { 'lvalue' => 1,
455 'return' => 'old' },
456 'get_info' => { 'my_meta' => 'true' } });
457
459 Provide filtering capabilities on the method information returned by
460 "->get_methods()".
461
463 Perl 5.8.0 or later
464
466 Object::InsideOut
467 Perl 6 introspection:
469 <http://dev.perl.org/perl6/doc/design/apo/A12.html#Introspection>, and
470 <http://dev.perl.org/perl6/rfc/335.html>
471
473 Jerry D. Hedden, <jdhedden AT cpan DOT org>
474
476 Copyright 2006 - 2012 Jerry D. Hedden. All rights reserved.
477 This program is free software; you can redistribute it and/or modify it
479 under the same terms as Perl itself.
480perl v5.28.1 2018-11-27 Object::InsideOut::Metadata(3)