NAME

Object::InsideOut::Metadata - Introspection for Object::InsideOut classes

VERSION

This document describes Object::InsideOut::Metadata version 4.05

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 information 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.

METADATA OBJECT

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:

METHODS METADATA

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:

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.

 sub my_method :Method(class)
 {
     ...

 package My::Class; {
     use Object::InsideOut;
     use Object::InsideOut::Metadata;
     sub my_method :lvalue :Method(object)
     {
         ....
     }
     add_meta(__PACKAGE__, 'my_method', 'lvalue', 1);
 }

 add_meta(__PACKAGE__, 'my_method', { 'lvalue' => 1,
                                      'return' => 'old' });

 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.