Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Object::InsideOut::MetUseraContributed Perl DocuObject::InsideOut::Metadata(3)

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:

	   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,	<jdheddenA ATA cpanA DOTA 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.

perl v5.32.1			  2018-11-27	Object::InsideOut::Metadata(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METADATA OBJECT | CLASS HIERARCHY | CONSTRUCTOR PARAMETERS | METHODS METADATA | TO DO | REQUIREMENTS | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Object::InsideOut::Metadata&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help