NAME¶
Object::InsideOut::Metadata - Introspection for Object::InsideOut classes
VERSION¶
This document describes Object::InsideOut::Metadata version 3.87
SYNOPSIS¶
package My::Class; {
use Object::InsideOut;
use Object::InsideOut::Metadata;
my @data :Field :Arg('data') :Get('data') :Set('put_data');
my @misc :Field;
my %init_args :InitArgs = (
'INFO' => '',
);
sub _init :Init
{
my ($self, $args) = @_;
if (exists($args->{'INFO'})) {
$misc[$$self] = 'INFO: ' . $args->{'INFO'};
}
}
sub misc :lvalue :Method
{
my $self = shift;
$misc[$$self];
}
add_meta(__PACKAGE__, 'misc', { 'lvalue' => 1 });
}
package main;
# Obtain a metadata object for a class
my $meta = My::Class->meta();
# ... or obtain a metadata object for an object
my $obj = My::Class->new();
my $meta = $obj->meta();
# Obtain the class hierarchy from the metadata object
my @classes = $meta->get_classes();
# Obtain infomation on the parameters for a class's construction
my %args = $meta->get_args();
# Obtain information on a class's methods
my %methods = $meta->get_methods();
DESCRIPTION¶
Object::InsideOut provides an introspection API that allows you to obtain
metadata on a class's hierarchy, constructor parameters, and methods. This is
done through the use of metadata objects that are generated by this class.
In addition, developers can specify metadata data for methods they write for
their classes.
To obtain metadata on an Object::InsideOut class or object, you must first
generate a metadata object for that class or object. Using that metadata
object, one can then obtain information on the class hierarchy, constructor
parameters, and methods.
- my $meta = My::Class->meta();
- my $meta = $obj->meta();
- The "->meta()" method, which is exported by
Object::InsideOut to each class, returns an Object::InsideOut::Metadata
object which can then be queried for information about the invoking
class or invoking object's class.
CLASS HIERARCHY¶
Any Object::InsideOut class potentially has four categories of classes
associated with it:
- 1. Object::InsideOut
- While the basis for all Object::InsideOut classes it is not
an object class per se because you can create objects from it (i.e., you
can't do "Object::InsideOut-" new()>). While
"My::Class-"isa('Object::InsideOut')> will return
true, because Object::InsideOut is not an object class, it is not
considered to be part of a class's hierarchy.
- 2. The class itself
- A class's hierarchy always includes itself.
- 3. Parent classes
- These are all the Object::InsideOut classes up the
inheritance tree that a class is derived from.
- 4. Foreign classes
- These are non-Object::InsideOut classes that a class
inherits from. (See "FOREIGN CLASS INHERITANCE" in
Object::InsideOut.) Because of implementation details, foreign classes do
not appear in a class's @ISA array. However, Object::InsideOut implements
a version of "->isa()" that handles foreign classes.
A class's hierarchy consists of any classes in the latter three categories.
- $meta->get_classes();
- When called in an array context, returns a list that
constitutes the class hierarchy for the class or object used to generate
the metadata object. When called in a scalar context, returns an array
ref.
- My::Class->isa();
- $obj->isa();
- When called in an array context, calling
"->isa()" without any arguments on an Object::InsideOut class
or object returns a list of the classes in the class hierarchy for that
class or object, and is equivalent to:
my @classes = $obj->meta()->get_classes();
When called in a scalar context, it returns an array ref containing the
classes.
CONSTRUCTOR PARAMETERS¶
Constructor parameters are the arguments given to a class's
"->new()" call.
- $meta->get_args();
- Returns a hash (hash ref in scalar context) containing
information on the parameters that can be used to construct an object from
the class associated with the metadata object. Here's an example of such a
hash:
{
'My::Class' => {
'data' => {
'field' => 1,
'type' => 'numeric',
},
'misc' => {
'mandatory' => 1,
},
},
'My::Parent' => {
'info' => {
'default' => '<none>',
},
},
}
The keys for this hash are the Object::IsideOut classes in the class
hierarchy. These class keys are paired with hash refs, the keys of
which are the names of the parameters for that class (e.g., 'data' and
'misc' for My::Class, and 'info' for My::Parent). The hashes paired to the
parameters contain information about the parameter:
- field
- The parameter corresponds directly to a class field, and is
automatically processed during object creation. See "Field-Specific
Parameters" in Object::InsideOut.
- mandatory
- The parameter is required for object creation. See
"Mandatory Parameters" in Object::InsideOut.
- default
- The default value assigned to the parameter if it is not
found in the arguments to "->new()". See "Default
Values" in Object::InsideOut.
- preproc
- The code ref for the subroutine that is used to
preprocess a parameter's value. See "Parameter
Preprocessing" in Object::InsideOut
- type
- The form of type checking performed on the parameter. See
"TYPE CHECKING" in Object::InsideOut for more details.
- 'numeric'
- Parameter takes a numeric value as recognized by
Scalar::Util::looks_like_number().
- 'list'
- 'list(_subtype_)'
- Parameter takes a single value (which is then placed in an
array ref) or an array ref.
When specified, the contents of the resulting array ref must be of the
specified subtype:
- 'numeric'
- Same as for the basic type above.
- A class name
- Same as for the basic type below.
- A reference type
- Any reference type as returned by ref()).
- 'ARRAY(_subtype_)'
- Parameter takes an array ref with contents of the specified
subtype as per the above.
- A class name
- Parameter takes an object of a specified class, or one of
its sub-classes as recognized by "->isa()".
- Other reference type
- Parameter takes a reference of the specified type as
returned by ref().
- A code ref
- Parameter takes a value that is type-checked by the code
ref paired to the 'type' key.
The methods returned by a metadata object are those that are currently available
at the time of the "->get_methods()" call.
The presence of ":Automethod" subroutines in an Object::InsideOut
class, or "AUTOLOAD" in a foreign class means that the methods
supported by the class may not be determinable. The presence of
"AUTOLOAD" in the list of methods for a class should alert the
programmer to the fact that more methods may be supported than are listed.
Methods that are excluded are private and hidden methods (see
"PERMISSIONS" in Object::InsideOut), methods that begin with an
underscore (which, by convention, means they are private), and subroutines
named "CLONE", "CLONE_SKIP", and "DESTROY"
(which are not methods). While technically a method, "import" is
also excluded as it is generally not invoked directly (i.e., it's usually
called as part of "use").
- $meta->get_methods();
- Returns a hash (hash ref in scalar context) containing
information on the methods for the class associated with the metadata
object. The keys in the hash are the method names. Paired to the names are
hash refs containing metadata about the methods. Here's an example:
{
# Methods exported by Object::InsideOut
'new' => {
'class' => 'My::Class',
'kind' => 'constructor'
},
'clone' => {
'class' => 'My::Class',
'kind' => 'object'
},
'meta' => {
'class' => 'My::Class'
},
'set' => {
'class' => 'My::Class',
'kind' => 'object',
'restricted' => 1
},
# Methods provided by Object::InsideOut
'dump' => {
'class' => 'Object::InsideOut',
'kind' => 'object'
},
'pump' => {
'class' => 'Object::InsideOut',
'kind' => 'class'
},
'inherit' => {
'class' => 'Object::InsideOut',
'kind' => 'object',
'restricted' => 1
},
'heritage' => {
'class' => 'Object::InsideOut',
'kind' => 'object',
'restricted' => 1
},
'disinherit' => {
'class' => 'Object::InsideOut',
'kind' => 'object',
'restricted' => 1
},
# Methods generated by Object::InsideOut for My::Class
'set_data' => {
'class' => 'My::Class',
'kind' => 'set',
'type' => 'ARRAY',
'return' => 'new'
},
'get_data' => {
'class' => 'My::Class',
'kind' => 'get'
}
# Class method provided by My::Class
'my_method' => {
'class' => 'My::Class',
'kind' => 'class'
}
}
Here are the method metadata that are provided:
- class
- The class in whose symbol table the method resides. The
method may reside in the classes code, it may be exported by another
class, or it may be generated by Object::InsideOut.
Methods that are overridden in child classes are represented as being
associated with the most junior class for which they appear.
- kind
- Designation of the characteristic of the
method:
- constructor
- The "->new()" method, of course.
- get, set or accessor
- A get, set, or combined accessor
generated by Object::InsideOut. See "AcCESSOR GENERATION" in
Object::InsideOut.
- cumulative, or cumulative (bottom up)
- chained, or chained (bottom up)
- A cumulative or chained method. See "CUMULATIVE
METHODS" in Object::InsideOut, and "CHAINED METHODS" in
Object::InsideOut. The class associated with these methods is the most
junior class in which they appears.
- class
- A method that is callable only on a class (e.g.,
"My::Class->my_method()").
- object
- A method that is callable only on a object (e.g.
"$obj->get_data()").
- foreign
- A subroutine found in a foreign class's symbol table.
Programmers must check the class's documentation to determine which are
actually methods, and what kinds of methods they are.
- overload
- A subroutine used for object coercion. These may be called
as methods, but this is not normally how they are used.
- automethod
- Associated with an AUTOLOAD method for an Object::InsideOut
class that implements an ":Automethod" subroutine. See
"AUTOMETHODS" in Object::InsideOut.
- type
- The type checking that is done on arguments to
set/combined accessors generated by Object::InsideOut. See
"TYPE CHECKING" in Object::InsideOut
- return
- The value returned by a set/combined accessor
generated by Object::InsideOut. See " Set Accessor Return
Value" in Object::InsideOut
- lvalue
- The method is an :lvalue accessor.
- restricted
- The method is restricted (i.e., callable only from
within the class hierarchy; not callable from application code). See
"PERMISSIONS" in Object::InsideOut.
- My::Class->can();
- $obj->can();
- When called in an array context, calling
"->can()" without any arguments on an Object::InsideOut class
or object returns a list of the method names for that class or object, and
is equivalent to:
my %meths = $obj->meta()->get_methods();
my @methods = keys(%meths);
When called in a scalar context, it returns an array ref containing the
method names.
Class authors may add the ":Method" attribute to subroutines in their
classes to specifically designate them as OO-callable methods. If a method is
only a
class method or only an
object method, this may be added
as a parameter to the attribute:
sub my_method :Method(class)
{
...
The
class or
object parameter will appear in the metadata for the
method when listed using "->get_methods()".
CAUTION: Be sure not to use ":method" (all lowercase) except as
appropriate (see "ARGUMENT VALIDATION" in Object::InsideOut) as this
is a Perl reserved attribute.
The ":Sub" attribute can be used to designate subroutines that are not
OO-callable methods. These subroutines will not show up as part of the methods
listed by "->get_methods()", etc..
Subroutine names beginning with an underscore are, by convention, considered
private, and will not show up as part of the methods listed by
"->get_methods()", etc..
Class authors may add additional metadata to their methods using the
"add_meta()" subroutine which is exported by this package. For
example, if the class implements it own ":lvalue" method, it should
add that metadata so that it is picked up the "->get_methods()":
package My::Class; {
use Object::InsideOut;
use Object::InsideOut::Metadata;
sub my_method :lvalue :Method(object)
{
....
}
add_meta(__PACKAGE__, 'my_method', 'lvalue', 1);
}
The arguments to "add_meta()" are:
- Class name
- This can usually be designated using the special literal
C__PACKAGE__>.
- Method name
- Metadata name
- This can be any of the metadata names under "METHODS
METADATA", or can be whatever additional name the programmer chooses
to implement.
- Metadata value
When adding multiple metadata for a method, they may be enclosed in a single
hash ref:
add_meta(__PACKAGE__, 'my_method', { 'lvalue' => 1,
'return' => 'old' });
If adding metadata for multiple methods, another level of hash may be used:
add_meta(__PACKAGE__, { 'my_method' => { 'lvalue' => 1,
'return' => 'old' },
'get_info' => { 'my_meta' => 'true' } });
TO DO¶
Provide filtering capabilities on the method information returned by
"->get_methods()".
REQUIREMENTS¶
Perl 5.8.0 or later
SEE ALSO¶
Object::InsideOut
Perl 6 introspection:
<
http://dev.perl.org/perl6/doc/design/apo/A12.html#Introspection>, and
<
http://dev.perl.org/perl6/rfc/335.html>
AUTHOR¶
Jerry D. Hedden, <jdhedden AT cpan DOT org>
COPYRIGHT AND LICENSE¶
Copyright 2006 - 2012 Jerry D. Hedden. All rights reserved.
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.