Provided by: libobject-insideout-perl_4.04-1_all bug

NAME

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

VERSION

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

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:

           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.

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:

           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.

   METADATA ATTRIBUTES
       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..

   ADDING METADATA
       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.