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

FreeBSD Manual Pages

  
 
  

home | help
Object::InsideOut(3)  User Contributed Perl Documentation Object::InsideOut(3)

NAME
       Object::InsideOut - Comprehensive inside-out object support module

VERSION
       This document describes Object::InsideOut version 4.05

SYNOPSIS
	package	My::Class; {
	    use	Object::InsideOut;

	    # Numeric field
	    #	With combined get+set accessor
	    my @data
		   :Field
		   :Type(numeric)
		   :Accessor(data);

	    # Takes 'INPUT' (or	'input', etc.) as a mandatory parameter	to ->new()
	    my %init_args :InitArgs = (
		'INPUT'	=> {
		    'Regex'	=> qr/^input$/i,
		    'Mandatory'	=> 1,
		    'Type'	=> 'numeric',
		},
	    );

	    # Handle class-specific args as part of ->new()
	    sub	init :Init
	    {
		my ($self, $args) = @_;

		# Put 'input' parameter	into 'data' field
		$self->set(\@data, $args->{'INPUT'});
	    }
	}

	package	My::Class::Sub;	{
	    use	Object::InsideOut qw(My::Class);

	    # List field
	    #	With standard 'get_X' and 'set_X' accessors
	    #	Takes 'INFO' as	an optional list parameter to ->new()
	    #	  Value	automatically added to @info array
	    #	  Defaults to [	'empty'	]
	    my @info
		   :Field
		   :Type(list)
		   :Standard(info)
		   :Arg('Name' => 'INFO', 'Default' => 'empty');
	}

	package	Foo; {
	    use	Object::InsideOut;

	    # Field containing My::Class objects
	    #	With combined accessor
	    #	Plus automatic parameter processing on object creation
	    my @foo
		   :Field
		   :Type(My::Class)
		   :All(foo);
	}

	package	main;

	my $obj	= My::Class::Sub->new('Input' => 69);
	my $info = $obj->get_info();		   # [ 'empty' ]
	my $data = $obj->data();		   # 69
	$obj->data(42);
	$data =	$obj->data();			   # 42

	$obj = My::Class::Sub->new('INFO' => 'help', 'INPUT' =>	86);
	$data =	$obj->data();			   # 86
	$info =	$obj->get_info();		   # [ 'help' ]
	$obj->set_info(qw(foo bar baz));
	$info =	$obj->get_info();		   # [ 'foo', 'bar', 'baz' ]

	my $foo_obj = Foo->new('foo' =>	$obj);
	$foo_obj->foo()->data();		   # 86

DESCRIPTION
       This module provides comprehensive support for implementing classes
       using the inside-out object model.

       Object::InsideOut implements inside-out objects as anonymous scalar
       references that are blessed into	a class	with the scalar	containing the
       ID for the object (usually a sequence number).  For Perl	5.8.3 and
       later, the scalar reference is set as read-only to prevent accidental
       modifications to	the ID.	 Object	data (i.e., fields) are	stored within
       the class's package in either arrays indexed by the object's ID,	or
       hashes keyed to the object's ID.

       The virtues of the inside-out object model over the blessed hash	object
       model have been extolled	in detail elsewhere.  See the informational
       links under "SEE	ALSO".	Briefly, inside-out objects offer the
       following advantages over blessed hash objects:

       o   Encapsulation

	   Object data is enclosed within the class's code and is accessible
	   only	through	the class-defined interface.

       o   Field Name Collision	Avoidance

	   Inheritance using blessed hash classes can lead to conflicts	if any
	   classes use the same	name for a field (i.e.,	hash key).  Inside-out
	   objects are immune to this problem because object data is stored
	   inside each class's package,	and not	in the object itself.

       o   Compile-time	Name Checking

	   A common error with blessed hash classes is the misspelling of
	   field names:

	    $obj->{'coment'} = 'Say what?';   #	Should be 'comment' not	'coment'

	   As there is no compile-time checking	on hash	keys, such errors do
	   not usually manifest	themselves until runtime.

	   With	inside-out objects, text hash keys are not used	for accessing
	   field data.	Field names and	the data index (i.e., $$self) are
	   checked by the Perl compiler	such that any typos are	easily caught
	   using "perlA	-c".

	    $coment[$$self] = $value;	 # Causes a compile-time error
	       # or with hash-based fields
	    $comment{$$self} = $value;	 # Also	causes a compile-time error

       Object::InsideOut offers	all the	capabilities of	other inside-out
       object modules with the following additional key	advantages:

       o   Speed

	   When	using arrays to	store object data, Object::InsideOut objects
	   are as much as 40% faster than blessed hash objects for fetching
	   and setting data, and even with hashes they are still several
	   percent faster than blessed hash objects.

       o   Threads

	   Object::InsideOut is	thread safe, and thoroughly supports sharing
	   objects between threads using threads::shared.

       o   Flexibility

	   Allows control over object ID specification,	accessor naming,
	   parameter name matching, and	much more.

       o   Runtime Support

	   Supports classes that may be	loaded at runtime (i.e., using
	   "evalA {A requireA ...;A };").  This	makes it usable	from within
	   mod_perl, as	well.  Also supports additions to class	hierarchies,
	   and dynamic creation	of object fields during	runtime.

       o   Exception Objects

	   Object::InsideOut uses Exception::Class for handling	errors in an
	   OO-compatible manner.

       o   Object Serialization

	   Object::InsideOut has built-in support for object dumping and
	   reloading that can be accomplished in either	an automated fashion
	   or through the use of class-supplied	subroutines.  Serialization
	   using Storable is also supported.

       o   Foreign Class Inheritance

	   Object::InsideOut allows classes to inherit from foreign (i.e.,
	   non-Object::InsideOut) classes, thus	allowing you to	sub-class
	   other Perl class, and access	their methods from your	own objects.

       o   Introspection

	   Obtain constructor parameters and method metadata for
	   Object::InsideOut classes.

CLASSES
       To use this module, each	of your	classes	will start with
       "useA Object::InsideOut;":

	package	My::Class; {
	    use	Object::InsideOut;
	    ...
	}

       Sub-classes (child classes) inherit from	base classes (parent classes)
       by telling Object::InsideOut what the parent class is:

	package	My::Sub; {
	    use	Object::InsideOut qw(My::Parent);
	    ...
	}

       Multiple	inheritance is also supported:

	package	My::Project; {
	    use	Object::InsideOut qw(My::Class Another::Class);
	    ...
	}

       Object::InsideOut acts as a replacement for the "base" pragma:  It
       loads the parent	module(s), calls their "->import()" methods, and sets
       up the sub-class's @ISA array.  Therefore, you should not
       "useA baseA ..."	yourself, nor try to set up @ISA arrays.  Further, you
       should not use a	class's	@ISA array to determine	a class's hierarchy:
       See "INTROSPECTION" for details on how to do this.

       If a parent class takes parameters (e.g., symbols to be exported	via
       Exporter), enclose them in an array ref (mandatory) following the name
       of the parent class:

	package	My::Project; {
	    use	Object::InsideOut 'My::Class'	   => [	'param1', 'param2' ],
				  'Another::Class' => [	'param'	];
	    ...
	}

OBJECTS
   Object Creation
       Objects are created using the "->new()" method which is exported	by
       Object::InsideOut to each class,	and is invoked in the following
       manner:

	my $obj	= My::Class->new();

       Object::InsideOut then handles all the messy details of initializing
       the object in each of the classes in the	invoking class's hierarchy.
       As such,	classes	do not (normally) implement their own "->new()"
       method.

       Usually,	object fields are initially populated with data	as part	of the
       object creation process by passing parameters to	the "->new()" method.
       Parameters are passed in	as combinations	of "keyA =>A value" pairs
       and/or hash refs:

	my $obj	= My::Class->new('param1' => 'value1');
	    # or
	my $obj	= My::Class->new({'param1' => 'value1'});
	    # or even
	my $obj	= My::Class->new(
	    'param_X' => 'value_X',
	    'param_Y' => 'value_Y',
	    {
		'param_A' => 'value_A',
		'param_B' => 'value_B',
	    },
	    {
		'param_Q' => 'value_Q',
	    },
	);

       Additionally, parameters	can be segregated in hash refs for specific
       classes:

	my $obj	= My::Class->new(
	    'foo' => 'bar',
	    'My::Class'	     =>	{ 'param' => 'value' },
	    'Parent::Class'  =>	{ 'data'  => 'info'  },
	);

       The initialization methods for both classes in the above	will get
       'foo'A =>A 'bar', "My::Class" will also get 'param'A =>A	'value', and
       "Parent::Class" will also get 'data'A =>A 'info'.  In this scheme,
       class-specific parameters will override general parameters specified at
       a higher	level:

	my $obj	= My::Class->new(
	    'default' => 'bar',
	    'Parent::Class'  =>	{ 'default' => 'baz' },
	);

       "My::Class" will	get 'default'A =>A 'bar', and "Parent::Class" will get
       'default'A =>A 'baz'.

       Calling "->new()" on an object works, too, and operates the same	as
       calling "->new()" for the class of the object (i.e., "$obj->new()" is
       the same	as "ref($obj)->new()").

       How the parameters passed to the	"->new()" method are used to
       initialize the object is	discussed later	under "OBJECT INITIALIZATION".

       NOTE: You cannot	create objects from Object::InsideOut itself:

	# This is an error
	# my $obj = Object::InsideOut->new();

       In this way, Object::InsideOut is not an	object class, but functions
       more like a pragma.

   Object IDs
       As stated earlier, this module implements inside-out objects as
       anonymous, read-only scalar references that are blessed into a class
       with the	scalar containing the ID for the object.

       Within methods, the object is passed in as the first argument:

	sub my_method
	{
	    my $self = shift;
	    ...
	}

       The object's ID is then obtained	by dereferencing the object:  $$self.
       Normally, this is only needed when accessing the	object's field data:

	my @my_field :Field;

	sub my_method
	{
	    my $self = shift;
	    ...
	    my $data = $my_field[$$self];
	    ...
	}

       At all other times, and especially in application code, the object
       should be treated as an opaque entity.

ATTRIBUTES
       Much of the power of Object::InsideOut comes from the use of
       attributes: Tags	on variables and subroutines that the attributes
       module sends to Object::InsideOut at compile time.  Object::InsideOut
       then makes use of the information in these tags to handle such
       operations as object construction, automatic accessor generation, and
       so on.

       (Note:  The use of attributes is	not the	same thing as source
       filtering.)

       An attribute consists of	an identifier preceded by a colon, and
       optionally followed by a	set of parameters in parentheses.  For
       example,	the attributes on the following	array declare it as an object
       field, and specify the generation of an accessor	method for that	field:

	my @level :Field :Accessor(level);

       When multiple attributes	are assigned to	a single entity, they may all
       appear on the same line (as shown above), or on separate	lines:

	my @level
	    :Field
	    :Accessor(level);

       However,	due to limitations in the Perl parser, the entirety of any one
       attribute must be on a single line:

	# This doesn't work
	# my @level
	#     :Field
	#     :Accessor('Name'	 => 'level',
	#		'Return' => 'Old');

	# Each attribute must be all on	one line
	my @level
	    :Field
	    :Accessor('Name' =>	'level', 'Return' => 'Old');

       For Object::InsideOut's purposes, the case of an	attribute's name does
       not matter:

	my @data :Field;
	   # or
	my @data :FIELD;

       However,	by convention (as denoted in the attributes module), an
       attribute's name	should not be all lowercase.

FIELDS
   Field Declarations
       Object data fields consist of arrays within a class's package into
       which data are stored using the object's	ID as the array	index.	An
       array is	declared as being an object field by following its declaration
       with the	":Field" attribute:

	my @info :Field;

       Object data fields may also be hashes:

	my %data :Field;

       However,	as array access	is as much as 40% faster than hash access, you
       should stick to using arrays.  See "HASH	ONLY CLASSES" for more
       information on when hashes may be required.

   Getting Data
       In class	code, data can be fetched directly from	an object's field
       array (hash) using the object's ID:

	$data =	$field[$$self];
	    # or
	$data =	$field{$$self};

   Setting Data
       Analogous to the	above, data can	be put directly	into an	object's field
       array (hash) using the object's ID:

	$field[$$self] = $data;
	    # or
	$field{$$self} = $data;

       However,	in threaded applications that use data sharing (i.e., use
       "threads::shared"), the above will not work when	the object is shared
       between threads and the data being stored is either an array, hash or
       scalar reference	(this includes other objects).	This is	because	the
       $data must first	be converted into shared data before it	can be put
       into the	field.

       Therefore, Object::InsideOut automatically exports a method called
       "->set()" to each class.	 This method should be used in class code to
       put data	into object fields whenever there is the possibility that the
       class code may be used in an application	that uses threads::shared
       (i.e., to make your class code thread-safe).  The "->set()" method
       handles all details of converting the data to a shared form, and
       storing it in the field.

       The "->set()" method, requires two arguments:  A	reference to the
       object field array/hash,	and the	data (as a scalar) to be put in	it:

	my @my_field :Field;

	sub store_data
	{
	    my ($self, $data) =	@_;
	    ...
	    $self->set(\@my_field, $data);
	}

       To be clear, the	"->set()" method is used inside	class code; not
       application code.  Use it inside	any object methods that	set data in
       object field arrays/hashes.

       In the event of a method	naming conflict, the "->set()" method can be
       called using its	fully-qualified	name:

	$self->Object::InsideOut::set(\@field, $data);

OBJECT INITIALIZATION
       As stated in "Object Creation", object fields are initially populated
       with data as part of the	object creation	process	by passing
       "keyA =>A value"	parameters to the "->new()" method.  These parameters
       can be processed	automatically into object fields, or can be passed to
       a class-specific	object initialization subroutine.

   Field-Specific Parameters
       When an object creation parameter corresponds directly to an object
       field, you can specify for Object::InsideOut to automatically place the
       parameter into the field	by adding the ":Arg" attribute to the field
       declaration:

	my @foo	:Field :Arg(foo);

       For the above, the following would result in $val being placed in
       "My::Class"'s @foo field	during object creation:

	my $obj	= My::Class->new('foo' => $val);

   Object Initialization Subroutines
       Many times, object initialization parameters do not correspond directly
       to object fields, or they may require special handling.	For these,
       parameter processing is accomplished through a combination of an
       ":InitArgs" labeled hash, and an	":Init"	labeled	subroutine.

       The ":InitArgs" labeled hash specifies the parameters to	be extracted
       from the	argument list supplied to the "->new()"	method.	 Those
       parameters (and only those parameters) which match the keys in the
       ":InitArgs" hash	are then packaged together into	a single hash ref.
       The newly created object	and this parameter hash	ref are	then sent to
       the ":Init" subroutine for processing.

       Here is an example of a class with an automatically handled field and
       an :Init	handled	field:

	package	My::Class; {
	    use	Object::InsideOut;

	    # Automatically handled field
	    my @my_data	 :Field	 :Acc(data)  :Arg(MY_DATA);

	    # ':Init' handled field
	    my @my_field :Field;

	    my %init_args :InitArgs = (
		'MY_PARAM' => '',
	    );

	    sub	_init :Init
	    {
		my ($self, $args) = @_;

		if (exists($args->{'MY_PARAM'})) {
		    $self->set(\@my_field, $args->{'MY_PARAM'});
		}
	    }

	    ...
	}

       An object for this class	would be created as follows:

	my $obj	= My::Class->new('MY_DATA'  => $dat,
				 'MY_PARAM' => $parm);

       This results in,	first of all, $dat being placed	in the object's
       @my_data	field because the "MY_DATA" key	is specified in	the ":Arg"
       attribute for that field.

       Then, "_init" is	invoked	with arguments consisting of the object	(i.e.,
       $self) and a hash ref consisting	only of	"{A 'MY_PARAM'A	=>A $paramA }"
       because the key "MY_PARAM" is specified in the ":InitArgs" hash.
       "_init" checks that the parameter "MY_PARAM" exists in the hash ref,
       and then	(since it does exist) adds $parm to the	object's @my_field
       field.

       Setting Data
	   Data	processed by the ":Init" subroutine may	be placed directly
	   into	the class's field arrays (hashes) using	the object's ID	(i.e.,
	   $$self):

	    $my_field[$$self] =	$args->{'MY_PARAM'};

	   However, as shown in	the example above, it is strongly recommended
	   that	you use	the ->set() method:

	    $self->set(\@my_field, $args->{'MY_PARAM'});

	   which handles converting the	data to	a shared format	when needed
	   for applications using threads::shared.

       All Parameters
	   The ":InitArgs" hash	and the	":Arg" attribute on fields act as
	   filters that	constrain which	initialization parameters are and are
	   not sent to the ":Init" subroutine.	If, however, a class does not
	   have	an ":InitArgs" hash and	does not use the ":Arg"	attribute on
	   any of its fields, then its ":Init" subroutine (if it exists, of
	   course) will	get all	the initialization parameters supplied to the
	   "->new()" method.

   Mandatory Parameters
       Field-specific parameters may be	declared mandatory as follows:

	my @data :Field
		 :Arg('Name' =>	'data',	'Mandatory' => 1);

       If a mandatory parameter	is missing from	the argument list to
       "->new()", an error is generated.

       For ":Init" handled parameters, use:

	my %init_args :InitArgs	= (
	    'data' => {
		'Mandatory' => 1,
	    },
	);

       "Mandatory" may be abbreviated to "Mand", and "Required"	or "Req" are
       synonymous.

   Default Values
       For optional parameters,	defaults can be	specified for field-specific
       parameters using	either of these	syntaxes:

	my @data :Field
		 :Arg('Name' =>	'data',	'Default' => 'foo');

	my @info :Field	 :Arg(info)  :Default('bar');

       If an optional parameter	with a specified default is missing from the
       argument	list to	"->new()", then	the default is assigned	to the field
       when the	object is created (before the ":Init" subroutine, if any, is
       called).

       The format for ":Init" handled parameters is:

	my %init_args :InitArgs	= (
	    'data' => {
		'Default' => 'foo',
	    },
	);

       In this case, if	the parameter is missing from the argument list	to
       "->new()", then the parameter key is paired with	the default value and
       added to	the ":Init" argument hash ref (e.g.,
       "{A 'data'A =>A 'foo'A }").

       Fields can also be assigned a default value even	if not associated with
       an initialization parameter:

	my @hash  :Field  :Default({});
	my @tuple :Field  :Default([1, 'bar']);

       Note that when using ":Default",	the value must be properly structured
       Perl code (e.g.,	strings	must be	quoted as illustrated above).

       "Default" and ":Default"	may be abbreviated to "Def" and	":Def"
       respectively.

       Generated Default Values

       It is also possible to generate default values on a per object basis by
       using code in the ":Default" directive.

	my @IQ :Field  :Default(50 + rand 100);
	my @ID :Field  :Default(our $next; ++$next);

       The above, for example, will initialize the "IQ"	attribute of each new
       object to a different random number, while its "ID" attribute will be
       initialized with	a sequential integer.

       The code	in a ":Default"	specifier can also refer to the	object being
       initialized, either as $_[0] or as $self.  For example:

	my @unique_ID :Field  :Default($self->gen_unique_ID);

       Any code	specified as a default will not	have access to the surrounding
       lexical scope.  For example, this will not work:

	my $MAX	= 100;
	my $MIN	= 0;

	my @bar	:Field
		:Default($MIN +	rand($MAX-$MIX));     #	Error

       For anything lexical or complex,	you should factor the initializer out
       into a utility subroutine:

	sub _rand_max :Restricted
	{
	    $MIN + rand($MAX-$MIX)
	}

	my @bar	:Field
		:Default(_rand_max);

       When specifying a generated default using the "Default" tag inside an
       ":Arg" directive, you will need to wrap the code	in a "sub { }",	and
       $_[0] (but not $self) can be used to access the object being
       initialized:

	my @baz	:Field
		:Arg(Name => 'baz', Default => sub { $_[0]->biz	});

       System functions	need to	similarly be wrapped in	"sub { }":

	my @rand :Field
		 :Type(numeric)
		 :Arg(Name => 'Rand', Default => sub { rand });

       Subroutines can be accessed using a code	reference:

	my @data :Field
		 :Arg(Name => 'Data', Default => \&gen_default);

       On the other hand, the above can	also be	simplified by using the
       ":Default" directive instead:

	my @baz	 :Field	 :Arg(baz)   :Default($self->biz);
	my @rand :Field	 :Arg(Rand)  :Default(rand)  :Type(numeric);
	my @data :Field	 :Arg(Data)  :Default(gen_default);

       Using generated defaults	in the ":InitArgs" hash	requires the use of
       the same	types of syntax	as with	the "Default" tag in an	":Arg"
       directive:

	my %init_args :InitArgs	= (
	    'Baz' => {
		'Default' => sub { $_[0]->biz },
	    },
	    'Rand' => {
		'Default' => sub { rand	},
	    },
	    'Data' => {
		'Default' => \&gen_default,
	    },
	);

       Sequential defaults

       In the previous section,	one of the examples is not as safe or as
       convenient as it	should be:

	my @ID :Field  :Default(our $next; ++$next);

       The problem is the shared variable ($next) that's needed	to track the
       allocation of "ID" values.  Because it has to persist between calls,
       that variable has to be a package variable, except under	Perl 5.10 or
       later where it could be a state variable	instead:

	use feature 'state';

	my @ID :Field  :Default(state $next; ++$next);

       The version with	the package variable is	unsafe,	because	anyone could
       then spoof ID numbers just by reassigning that universally accessible
       variable:

	   $MyClass::next = 0;	      #	Spoof the next object
	   my $obj = MyClass->new;    #	Object now has ID 1

       The state-variable version avoids this problem, but even	that version
       is more complicated (and	hence more error-prone)	than it	needs to be.

       The ":SequenceFrom" directive (which can	be abbreviated to ":SeqFrom"
       or ":Seq") makes	it much	easier to specify that an attribute's default
       value is	taken from a linearly increasing sequence.  For	instance, the
       ID example above	could be rewritten as:

	my @ID :Field  :SequenceFrom(1);

       This directive automatically creates a hidden variable, initializes it
       to the initial value specified, generates a sequence starting at	that
       initial value, and then uses successive elements	of that	sequence each
       time a default value is needed for that attribute during	object
       creation.

       If the initial value is a scalar, then the default sequence is
       generated by by computing "$previous_value++".  If it is	an object, it
       is generated by calling "$obj->next()" (or by calling "$obj++" if the
       object doesn't have a "next()" method).

       This makes it simple to create a	series of objects with attributes
       whose values default to simple numeric, alphabetic, or alphanumeric
       sequences, or to	the sequence specified by an iterator object of	some
       kind:

	my @ID :Field  :SeqFrom(1);		    # 1, 2, 3...

	my @ID :Field  :SeqFrom('AAA');		    # 'AAA', 'AAB', 'AAC'...

	my @ID :Field  :SeqFrom('A01');		    # 'A01', 'A02', 'A03'...

	my @ID :Field  :SeqFrom(ID_Iterator->new);  # ->next, ->next, ->next...

       In every	other respect a	":SequenceFrom"	directive is just like a
       ":Default".  For	example, it can	be used	in conjunction with the	":Arg"
       directive as follows:

	my @ID :Field  :Arg(ID)	 :SeqFrom(1);

       However,	not as a tag inside the	":Arg" directive:

	my @ID :Field  :Arg('Name' => 'ID', 'SeqFrom' => 1)   #	WRONG

       For the ":InitArgs" hash, you will need to roll your own	sequential
       defaults	if required:

	use feature 'state';

	my %init_args :InitArgs	= (
	    'Counter' => {
		'Default' => sub { state $next;	++$next	}
	    },
	);

   Parameter Name Matching
       Rather than having to rely on exact matches to parameter	keys in	the
       "->new()" argument list,	you can	specify	a regular expressions to be
       used to match them to field-specific parameters:

	my @param :Field
		  :Arg('Name' => 'param', 'Regexp' => qr/^PARA?M$/i);

       In this case, the parameter's key could be any of the following:	PARAM,
       PARM, Param, Parm, param, parm, and so on.  And the following would
       result in $data being placed in "My::Class"'s @param field during
       object creation:

	my $obj	= My::Class->new('Parm'	=> $data);

       For ":Init" handled parameters, you would similarly use:

	my %init_args :InitArgs	= (
	    'Param' => {
		'Regex'	=> qr/^PARA?M$/i,
	    },
	);

       In this case, the match results in "{A 'Param'A =>A $dataA }" being
       sent to the ":Init" subroutine as the argument hash.  Note that the
       ":InitArgs" hash	key is substituted for the original argument key.
       This eliminates the need	for any	parameter key pattern matching within
       the ":Init" subroutine.

       "Regexp"	may be abbreviated to "Regex" or "Re".

   Object Pre-initialization
       Occasionally, a child class may need to send a parameter	to a parent
       class as	part of	object initialization.	This can be accomplished by
       supplying a ":PreInit" labeled subroutine in the	child class.  These
       subroutines, if found, are called in order from the bottom of the class
       hierarchy upward	(i.e., child classes first).

       The subroutine should expect two	arguments:  The	newly created
       (uninitialized) object (i.e., $self), and a hash	ref of all the
       parameters from the "->new()" method call, including any	additional
       parameters added	by other ":PreInit" subroutines.

	sub pre_init :PreInit
	{
	    my ($self, $args) =	@_;
	    ...
	}

       The parameter hash ref will not be exactly as supplied to "->new()",
       but will	be flattened into a single hash	ref.  For example,

	my $obj	= My::Class->new(
	    'param_X' => 'value_X',
	    {
		'param_A' => 'value_A',
		'param_B' => 'value_B',
	    },
	    'My::Class'	=> { 'param' =>	'value'	},
	);

       would produce

	{
	    'param_X' => 'value_X',
	    'param_A' => 'value_A',
	    'param_B' => 'value_B',
	    'My::Class'	=> { 'param' =>	'value'	}
	}

       as the hash ref to the ":PreInit" subroutine.

       The ":PreInit" subroutine may then add, modify or even remove any
       parameters from the hash	ref as needed for its purposes.	 After all the
       ":PreInit" subroutines have been	executed, object initialization	will
       then proceed using the resulting	parameter hash.

       The ":PreInit" subroutine should	not try	to set data in its class's
       fields or in other class's fields (e.g.,	using set methods) as such
       changes will be overwritten during initialization phase which follows
       pre-initialization.  The	":PreInit" subroutine is only intended for
       modifying initialization	parameters prior to initialization.

   Initialization Sequence
       For the most part, object initialization	can be conceptualized as
       proceeding from parent classes down through child classes.  As such,
       calling child class methods from	a parent class during object
       initialization may not work because the object will not have been fully
       initialized in the child	classes.

       Knowing the order of events during object initialization	may help in
       determining when	this can be done safely:

       1.  The scalar reference	for the	object is created, populated with an
       "Object ID", and	blessed	into the appropriate class.
       2.  :PreInit subroutines	are called in order from the bottom of the
       class hierarchy upward (i.e., child classes first).
       3.  From	the top	of the class hierarchy downward	(i.e., parent classes
       first), "Default	Values"	are assigned to	fields.	 (These	may be
       overwritten by subsequent steps below.)
       4.  From	the top	of the class hierarchy downward, parameters to the
       "->new()" method	are processed for ":Arg" field attributes and entries
       in the ":InitArgs" hash:
	   a.  "Parameter Preprocessing" is performed.
	   b.  Checks for "Mandatory Parameters" are made.
	   c.  "Default	Values"	specified in the ":InitArgs" hash are added
	   for subsequent processing by	the ":Init" subroutine.
	   d.  Type checking is	performed.
	   e.  "Field-Specific Parameters" are assigned	to fields.
       5.  From	the top	of the class hierarchy downward, :Init subroutines are
       called with parameters specified	in the ":InitArgs" hash.
       6.  Checks are made for any parameters to "->new()" that	were not
       handled in the above.  (See next	section.)

   Unhandled Parameters
       It is an	error to include any parameters	to the "->new()" method	that
       are not handled by at least one class in	the hierarchy.	The primary
       purpose of this is to catch typos in parameter names:

	 my $obj = Person->new('nane' => 'John');   # Should be	'name'

       The only	time that checks for unhandled parameters are not made is when
       at least	one class in the hierarchy does	not have an ":InitArgs"	hash
       and does	not use	the ":Arg" attribute on	any of its fields and uses an
       :Init subroutine	for processing parameters.  In such a case, it is not
       possible	for Object::InsideOut to determine which if any	of the
       parameters are not handled by the ":Init" subroutine.

       If you add the following	construct to the start of your application:

	BEGIN {
	    no warnings	'once';
	    $OIO::Args::Unhandled::WARN_ONLY = 1;
	}

       then unhandled parameters will only generate warnings rather than
       causing exceptions to be	thrown.

   Modifying ":InitArgs"
       For performance purposes, Object::InsideOut normalizes each class's
       ":InitArgs" hash	by creating keys in the	form of	'_X' for the various
       options it handles (e.g., '_R' for 'Regexp').

       If a class has the unusual requirement to modify	its ":InitArgs"	hash
       during runtime, then it must renormalize	the hash after making such
       changes by invoking "Object::InsideOut::normalize()" on it so that
       Object::InsideOut will pick up the changes:

	Object::InsideOut::normalize(\%init_args);

ACCESSOR GENERATION
       Accessors are object methods used to get	data out of and	put data into
       an object.  You can, of course, write your own accessor code, but this
       can get a bit tedious, especially if your class has lots	of fields.
       Object::InsideOut provides the capability to automatically generate
       accessors for you.

   Basic Accessors
       A get accessor is vary basic:  It just returns the value	of an object's
       field:

	my @data :Field;

	sub fetch_data
	{
	    my $self = shift;
	    return ($data[$$self]);
	}

       and you would use it as follows:

	my $data = $obj->fetch_data();

       To have Object::InsideOut generate such a get accessor for you, add a
       ":Get" attribute	to the field declaration, specifying the name for the
       accessor	in parentheses:

	my @data :Field	:Get(fetch_data);

       Similarly, a set	accessor puts data in an object's field.  The set
       accessors generated by Object::InsideOut	check that they	are called
       with at least one argument.  They are specified using the ":Set"
       attribute:

	my @data :Field	:Set(store_data);

       Some programmers	use the	convention of naming get and set accessors
       using get_ and set_ prefixes.  Such standard accessors can be generated
       using the ":Standard" attribute (which may be abbreviated to ":Std"):

	my @data :Field	:Std(data);

       which is	equivalent to:

	my @data :Field	:Get(get_data) :Set(set_data);

       Other programmers prefer	to use a single	combination accessors that
       performs	both functions:	 When called with no arguments,	it gets, and
       when called with	an argument, it	sets.  Object::InsideOut will generate
       such accessors with the ":Accessor" attribute.  (This can be
       abbreviated to ":Acc", or you can use ":Get_Set"	or ":Combined" or
       ":Combo"	or even	"Mutator".)  For example:

	my @data :Field	:Acc(data);

       The generated accessor would be used in this manner:

	$obj->data($val);	    # Puts data	into the object's field
	my $data = $obj->data();    # Fetches the object's field data

   Set Accessor	Return Value
       For any of the automatically generated methods that perform set
       operations, the default for the method's	return value is	the value
       being set (i.e.,	the new	value).

       You can specify the set accessor's return value using the "Return"
       attribute parameter (which may be abbreviated to	"Ret").	 For example,
       to explicitly specify the default behavior use:

	my @data :Field	:Set('Name' => 'store_data', 'Return' => 'New');

       You can specify that the	accessor should	return the old (previous)
       value (or "undef" if unset):

	my @data :Field	:Acc('Name' => 'data', 'Ret' =>	'Old');

       You may use "Previous", "Prev" or "Prior" as synonyms for "Old".

       Finally,	you can	specify	that the accessor should return	the object
       itself:

	my @data :Field	:Std('Name' => 'data', 'Ret' =>	'Object');

       "Object"	may be abbreviated to "Obj", and is also synonymous with
       "Self".

   Method Chaining
       An obvious case where method chaining can be used is when a field is
       used to store an	object:	 A method for the stored object	can be chained
       to the get accessor call	that retrieves that object:

	$obj->get_stored_object()->stored_object_method()

       Chaining	can be done off	of set accessors based on their	return value
       (see above).  In	this example with a set	accessor that returns the new
       value:

	$obj->set_stored_object($stored_obj)->stored_object_method()

       the set_stored_object() call stores the new object, returning it	as
       well, and then the stored_object_method() call is invoked via the
       stored/returned object.	The same would work for	set accessors that
       return the old value, too, but in that case the chained method is
       invoked via the previously stored (and now returned) object.

       If the Want module (version 0.12	or later) is available,	then
       Object::InsideOut also tries to do the right thing with method chaining
       for set accessors that don't store/return objects.  In this case, the
       object used to invoke the set accessor will also	be used	to invoke the
       chained method (just as though the set accessor were declared with
       'Return'A =>A 'Object'):

	$obj->set_data('data')->do_something();

       To make use of this feature, just add "use Want;" to the	beginning of
       your application.

       Note, however, that this	special	handling does not apply	to get
       accessors, nor to combination accessors invoked without an argument
       (i.e., when used	as a get accessor).  These must	return objects in
       order for method	chaining to succeed.

   :lvalue Accessors
       As documented in	"Lvalue	subroutines" in	perlsub, an ":lvalue"
       subroutine returns a modifiable value.  This modifiable value can then,
       for example, be used on the left-hand side (hence "LVALUE") of an
       assignment statement, or	a substitution regular expression.

       For Perl	5.8.0 and later, Object::InsideOut supports the	generation of
       ":lvalue" accessors such	that their use in an "LVALUE" context will set
       the value of the	object's field.	 Just add "'lvalue' => 1" to the set
       accessor's attribute.  ('lvalue'	may be abbreviated to 'lv'.)

       Additionally, ":Lvalue" (or its abbreviation ":lv") may be used for a
       combined	get/set	:lvalue	accessor.  In other words, the following are
       equivalent:

	:Acc('Name' => 'email',	'lvalue' => 1)

	:Lvalue(email)

       Here is a detailed example:

	package	Contact; {
	    use	Object::InsideOut;

	    # Create separate a	get accessor and an :lvalue set	accessor
	    my @name  :Field
		      :Get(name)
		      :Set('Name' => 'set_name', 'lvalue' => 1);

	    # Create a standard	get_/set_ pair of accessors
	    #	The set_ accessor will be an :lvalue accessor
	    my @phone :Field
		      :Std('Name' => 'phone', 'lvalue' => 1);

	    # Create a combined	get/set	:lvalue	accessor
	    my @email :Field
		      :Lvalue(email);
	}

	package	main;

	my $obj	= Contact->new();

	# Use :lvalue accessors	in assignment statements
	$obj->set_name()  = 'Jerry D. Hedden';
	$obj->set_phone() = '800-555-1212';
	$obj->email()	  = 'jdhedden AT cpan DOT org';

	# Use :lvalue accessor in substitution regexp
	$obj->email() =~ s/ AT (\w+) DOT /\@$1./;

	# Use :lvalue accessor in a 'substr' call
	substr($obj->set_phone(), 0, 3)	= '888';

	print("Contact info:\n");
	print("\tName:	", $obj->name(),      "\n");
	print("\tPhone:	", $obj->get_phone(), "\n");
	print("\tEmail:	", $obj->email(),     "\n");

       The use of ":lvalue" accessors requires the installation	of the Want
       module (version 0.12 or later) from CPAN.  See particularly the section
       "Lvalue subroutines:" in	Want for more information.

       ":lvalue" accessors also	work like regular set accessors	in being able
       to accept arguments, return values, and so on:

	my @pri	:Field
		:Lvalue('Name' => 'priority', 'Return' => 'Old');
	 ...
	my $old_pri = $obj->priority(10);

       ":lvalue" accessors can be used in method chains.

       Caveats:	While still classified as experimental,	Perl's support for
       ":lvalue" subroutines has been around since 5.6.0, and a	good number of
       CPAN modules make use of	them.

       By definition, because ":lvalue"	accessors return the location of a
       field, they break encapsulation.	 As a result, some OO advocates	eschew
       the use of ":lvalue" accessors.

       ":lvalue" accessors are slower than corresponding non-lvalue accessors.
       This is due to the fact that more code is needed	to handle all the
       diverse ways in which ":lvalue" accessors may be	used.  (I've done my
       best to optimize	the generated code.)  For example, here's the code
       that is generated for a simple combined accessor:

	*Foo::foo = sub	{
	    return ($$field[${$_[0]}]) if (@_ == 1);
	    $$field[${$_[0]}] =	$_[1];
	};

       And the corresponding code for an ":lvalue" combined accessor:

	*Foo::foo = sub	:lvalue	{
	    my $rv = !Want::want_lvalue(0);
	    Want::rreturn($$field[${$_[0]}]) if	($rv &&	(@_ == 1));
	    my $assign;
	    if (my @args = Want::wantassign(1))	{
		@_ = ($_[0], @args);
		$assign	= 1;
	    }
	    if (@_ > 1)	{
		$$field[${$_[0]}] = $_[1];
		Want::lnoreturn	if $assign;
		Want::rreturn($$field[${$_[0]}]) if $rv;
	    }
	    ((@_ > 1) && (Want::wantref() eq 'OBJECT') &&
	     !Scalar::Util::blessed($$field[${$_[0]}]))
		   ? $_[0] : $$field[${$_[0]}];
	};

ALL-IN-ONE
       Parameter naming	and accessor generation	may be combined:

	my @data :Field	:All(data);

       This is syntactic shorthand for:

	my @data :Field	:Arg(data) :Acc(data);

       If you want the accessor	to be ":lvalue", use:

	my @data :Field	:LV_All(data);

       If standard accessors are desired, use:

	my @data :Field	:Std_All(data);

       Attribute parameters affecting the set accessor may also	be used.  For
       example,	if you want standard accessors with an ":lvalue" set accessor:

	my @data :Field	:Std_All('Name'	=> 'data', 'Lvalue' => 1);

       If you want a combined accessor that returns the	old value on set
       operations:

	my @data :Field	:All('Name' => 'data', 'Ret' =>	'Old');

       And so on.

       If you need to add attribute parameters that affect the ":Arg" portion
       (e.g., "Default", "Mandatory", etc.), then you cannot use ":All".  Fall
       back to using the separate attributes.  For example:

	my @data :Field	:Arg('Name' => 'data', 'Mand' => 1)
			:Acc('Name' => 'data', 'Ret' =>	'Old');

READONLY FIELDS
       If you want to declare a	read-only field	(i.e., one that	can be
       initialized and retrieved, but which doesn't have a set accessor):

	my @data :Field	:Arg(data) :Get(data);

       there is	a syntactic shorthand for that,	too:

	my @data :Field	:ReadOnly(data);

       or just:

	my @data :Field	:RO(data);

       If a standard get accessor is desired, use:

	my @data :Field	:Std_RO(data);

       For obvious reasons, attribute parameters affecting the set accessor
       cannot be used with read-only fields, nor can ":ReadOnly" be combined
       with ":LValue".

       As with ":All", if you need to add attribute parameters that affect the
       ":Arg" portion then you cannot use the ":RO" shorthand:	Fall back to
       using the separate attributes in	such cases.  For example:

	my @data :Field	:Arg('Name' => 'data', 'Mand' => 1)
			:Get('Name' => 'data');

DELEGATORS
       In addition to autogenerating accessors for a given field, you can also
       autogenerate delegators to that field.  A delegator is an accessor that
       forwards	its call to one	of the object's	fields.

       For example, if your Car	object has an @engine field, then you might
       need to send all	acceleration requests to the Engine object stored in
       that field.  Likewise, all braking requests may need to be forwarded to
       Car's field that	stores the Brakes object:

	package	Car; {
	    use	Object::InsideOut;

	    my @engine :Field :Get(engine);
	    my @brakes :Field :Get(brakes);

	    sub	_init :Init(private)  {
		my ($self, $args) = @_;

		$self->engine(Engine->new());
		$self->brakes(Brakes->new());
	    }

	    sub	accelerate {
		my ($self) = @_;
		$self->engine->accelerate();
	    }

	    sub	decelerate {
		my ($self) = @_;
		$self->engine->decelerate();
	    }

	    sub	brake {
		my ($self, $foot_pressure) = @_;
		$self->brakes->brake($foot_pressure);
	    }
	}

       If the Car needs	to forward other method	calls to its Engine or Brakes,
       this quickly becomes tedious, repetitive, and error-prone. So, instead,
       you can just tell Object::InsideOut that	a particular method should be
       automatically forwarded to a particular field, by specifying a
       ":Handles" attribute:

	package	Car; {
	    use	Object::InsideOut;

	    my @engine :Field
		       :Get(engine)
		       :Handles(accelerate, decelerate);
	    my @brakes :Field
		       :Get(brakes)
		       :Handles(brake);

	    sub	_init :Init(private)  {
		my ($self, $args) = @_;

		$self->engine(Engine->new());
		$self->brakes(Brakes->new());
	    }
	}

       This option generates and installs a single delegator method for	each
       of its arguments, so the	second example has exactly the same effect as
       the first example. The delegator	simply calls the corresponding method
       on the object stored in the field, passing it the same argument list it
       received.

       Sometimes, however, you may need	to delegate a particular method	to a
       field, but under	a different name.  For example,	if the Brake class
       provides	an "engage()" method, rather than a "brake()" method, then
       you'd need "Car::brake()" to be implemented as:

	    sub	brake {
		my ($self, $foot_pressure) = @_;
		$self->brakes->engage($foot_pressure);
	    }

       You can achieve that using the ":Handles" attribute, like so:

	    my @brakes :Field
		       :Get(brakes)
		       :Handles(brake-->engage);

       The long	arrow version still creates a delegator	method "brake()", but
       makes that method delegate to your Brakes object	by calling its
       "engage()" method instead.

       If you are delegating a large number of methods to a particular field,
       the ":Handles" declarations soon	become tedious:

	my @onboard_computer :Field :Get(comp)
			     :Type(Computer::Onboard)
			     :Handles(engine_monitor engine_diagnostics)
			     :Handles(engine_control airbag_deploy)
			     :Handles(GPS_control GPS_diagnostics GPS_reset)
			     :Handles(climate_control reversing_camera)
			     :Handles(cruise_control auto_park)
			     :Handles(iPod_control cell_phone_connect);

       And, of course, every time the interface	of the "Computer::Onboard"
       class changes, you have to change those ":Handles" declarations,	too.

       Sometimes, all you really want to say is: "This field should handle
       anything	it can handle".	 To do that, you write:

	my @onboard_computer :Field :Get(comp)
			     :Type(Computer::Onboard)
			     :Handles(Computer::Onboard);

       That is,	if a ":Handles"	directive is given a name that includes	a
       "::", it	treats that name as a class name, rather than a	method name.
       Then it checks that class's metadata (see INTROSPECTION), retrieves a
       list of all the method names from the class, and	uses that as the list
       of method names to delegate.

       Unlike an explicit ":Handles( method_name )", a ":Handles( Class::Name
       )" is tolerant of name collisions. If any method	of "Class::Name" has
       the same	name as	another	method or delegator that has already been
       installed in the	current	class, then ":Handles" just silently ignores
       that particular method, and doesn't try to replace the existing one.
       In other	words, a ":Handles(Class::Name)" won't install a delegator to
       a method	in "Class::Name" if that method	is already being handled
       somewhere else by the current class.

       For classes that	don't have a "::" in their name	(e.g., "DateTime" and
       "POE"), just append a "::" to the class name:

	my @init_time :Field :Get(init_time)
			     :Type(    DateTime	       )
			     :Default( DateTime->now() )
			     :Handles( DateTime::      );

       Note that, when using the class-based version of	":Handles", every
       method is delegated with	its name unchanged.  If	some of	the object's
       methods should be delegated under different names, you have to specify
       that explicitly (and beforehand):

	my @onboard_computer :Field :Get(comp) :Type(Computer::Onboard)
		       # rename	this method when delegating...
			     :Handles( iPod_control-->get_iPod )
		       # delegate everything else with names unchanged...
			     :Handles( Computer::Onboard );

       "Handles" may be	abbreviated to "Handle"	or "Hand".

       NOTES: Failure to add the appropriate object to the delegation field
       will lead to errors such	as:  Can't call	method "bar" on	an undefined
       value.

       Typos in	":Handles" attribute declarations will lead to errors such as:
       Can't locate object method "bat"	via package "Foo".  Adding an object
       of the wrong class to the delegation field will lead to the same	error,
       but can be avoided by adding a ":Type" attribute	for the	appropriate
       class.

PERMISSIONS
   Restricted and Private Accessors
       By default, automatically generated accessors, can be called at any
       time.  In other words, their access permission is public.

       If desired, accessors can be made restricted - in which case they can
       only be called from within the class and	any child classes in the
       hierarchy that are derived from it - or private - such that they	can
       only be called from within the accessors' class.	 Here are examples of
       the syntax for adding permissions:

	my @data     :Field :Std('Name'	=> 'data',     'Permission' => 'private');
	my @info     :Field :Set('Name'	=> 'set_info', 'Perm' => 'restricted');
	my @internal :Field :Acc('Name'	=> 'internal', 'Private' => 1);
	my @state    :Field :Get('Name'	=> 'state',    'Restricted' => 1);

       When creating a standard	pair of	get_/set_ accessors, the permission
       setting is applied to both accessors.  If different permissions are
       required	on the two accessors, then you'll have to use separate ":Get"
       and ":Set" attributes on	the field.

	# Create a private set method
	#  and a restricted get	method on the 'foo' field
	my @foo	:Field
		:Set('Name' => 'set_foo', 'Priv' => 1)
		:Get('Name' => 'get_foo', 'Rest' => 1);

	# Create a restricted set method
	#  and a public	get method on the 'bar'	field
	my %bar	:Field
		:Set('Name' => 'set_bar', 'Perm' => 'restrict')
		:Get(get_bar);

       "Permission" may	be abbreviated to "Perm"; "Private" may	be abbreviated
       to "Priv"; and "Restricted" may be abbreviated to "Restrict".

   Restricted and Private Methods
       In the same vein	as describe above, access to methods can be narrowed
       by use of ":Restricted" and ":Private" attributes.

	sub foo	:Restricted
	{
	    my $self = shift;
	    ...
	}

       Without either of these attributes, most	methods	have public access.
       If desired, you may explicitly label them with the ":Public" attribute.

   Exemptions
       It is also possible to specify classes that are exempt from the
       Restricted and Private access permissions (i.e.,	the method may be
       called from those classes as well):

	my %foo	:Field
		:Acc('Name' => 'foo', 'Perm' =>	'Restrict(Exempt::Class)')
		:Get(get_bar);

	sub bar	:Private(Some::Class, Another::Class)
	{
	    my $self = shift;
	    ...
	}

       An example of when this might be	needed is with delegation mechanisms.

   Hidden Methods
       For subroutines marked with the following attributes (most of which are
       discussed later in this document):

       :ID
       :PreInit
       :Init
       :Replicate
       :Destroy
       :Automethod
       :Dumper
       :Pumper
       :MOD_*_ATTRS
       :FETCH_*_ATTRS

       Object::InsideOut normally renders them uncallable (hidden) to class
       and application code (as	they should normally only be needed by
       Object::InsideOut itself).  If needed, this behavior can	be overridden
       by adding the "Public", "Restricted" or "Private" attribute parameters:

	sub _init :Init(private)    # Callable from within this	class
	{
	    my ($self, $args) =	@_;

	    ...
	}

   Restricted and Private Classes
       Permission for object creation on a class can be	narrowed by adding a
       ":Restricted" or	":Private" flag	to its "useA Object::InsideOutA	..."
       declaration.  This basically adds ":Restricted/:Private"	permissions on
       the "->new()" method for	that class.  Exemptions	are also supported.

	package	Foo; {
	    use	Object::InsideOut;
	    ...
	}

	package	Bar; {
	    use	Object::InsideOut 'Foo', ':Restricted(Ping, Pong)';
	    ...
	}

       In the above, class "Bar" inherits from class "Foo", and	its
       constructor is restricted to itself, classes that inherit from "Bar",
       and the classes "Ping" and "Pong".

       As constructors are inherited, any class	that inherits from "Bar" would
       also be a restricted class.  To overcome	this, any child	class would
       need to add its own permission declaration:

	package	Baz; {
	    use	Object::InsideOut qw/Bar :Private(My::Class)/;
	    ...
	}

       Here, class "Baz" inherits from class "Bar", and	its constructor	is
       restricted to itself (i.e., private) and	class "My::Class".

       Inheriting from a ":Private" class is permitted,	but objects cannot be
       created for that	class unless it	has a permission declaration of	its
       own:

	package	Zork; {
	    use	Object::InsideOut qw/:Public Baz/;
	    ...
	}

       Here, class "Zork" inherits from	class "Baz", and its constructor has
       unrestricted access.  (In general, don't	use the	":Public" declaration
       for a class except to overcome constructor permissions inherited	from
       parent classes.)

TYPE CHECKING
       Object::InsideOut can be	directed to add	type-checking code to the
       set/combined accessors it generates, and	to perform type	checking on
       object initialization parameters.

   Field Type Checking
       Type checking for a field can be	specified by adding the	":Type"
       attribute to the	field declaration:

	my @count :Field :Type(numeric);

	my @objs :Field	:Type(list(My::Class));

       The ":Type" attribute results in	type checking code being added to
       set/combined accessors generated	by Object::InsideOut, and will perform
       type checking on	object initialization parameters processed by the
       ":Arg" attribute.

       Available Types are:

       'scalar'
	   Permits anything that is not	a reference.

       'numeric'
	   Can also be specified as "Num" or "Number".	This uses
	   Scalar::Util::looks_like_number() to	test the input value.

       'list' or 'array'
       'list(_subtype_)' or 'array(_subtype_)'
	   This	type permits an	accessor to accept multiple values (which are
	   then	placed in an array ref)	or a single array ref.

	   For object initialization parameters, it permits a single value
	   (which is then placed in an array ref) or an	array ref.

	   When	specified, the contents	of the resulting array ref are checked
	   against the specified subtype:

	   'scalar'
	       Same as for the basic type above.

	   'numeric'
	       Same as for the basic type above.

	   A class name
	       Same as for the basic type below.

	   A reference type
	       Any reference type (in all caps)	as returned by ref()).

       'ARRAY_ref'
       'ARRAY_ref(_subtype_)'
	   This	specifies that only a single array reference is	permitted.
	   Can also be specified as "ARRAYref".

	   When	specified, the contents	of the array ref are checked against
	   the specified subtype as per	the above.

       'HASH'
	   This	type permits an	accessor to accept multiple "keyA =>A value"
	   pairs (which	are then placed	in a hash ref) or a single hash	ref.

	   For object initialization parameters, only a	single ref is
	   permitted.

       'HASH_ref'
	   This	specifies that only a single hash reference is permitted.  Can
	   also	be specified as	"HASHref".

       'SCALAR_ref'
	   This	type permits an	accessor to accept a single scalar reference.
	   Can also be specified as "SCALARref".

       A class name
	   This	permits	only an	object of the specified	class, or one of its
	   sub-classes (i.e., type checking is done using "->isa()").  For
	   example, "My::Class".  The class name "UNIVERSAL" permits any
	   object.  The	class name "Object::InsideOut" permits any object
	   generated by	an Object::InsideOut class.

       Other reference type
	   This	permits	only a reference of the	specified type (as returned by
	   ref()).  The	type must be specified in all caps.  For example,
	   "CODE".

       The ":Type" attribute can also be supplied with a code reference	to
       provide custom type checking.  The code ref may either be in the	form
       of an anonymous subroutine, or a	fully-qualified	subroutine name.  The
       result of executing the code ref	on the input argument should be	a
       boolean value.  Here's some examples:

	package	My::Class; {
	    use	Object::InsideOut;

	    # Type checking using an anonymous subroutine
	    #  (This checks that the argument is an object)
	    my @data :Field :Type(sub {	Scalar::Util::blessed($_[0]) })
			    :Acc(data);

	    # Type checking using a fully-qualified subroutine name
	    my @num  :Field :Type(\&My::Class::positive)
			    :Acc(num);

	    # The type checking	subroutine may be made 'Private'
	    sub	positive :Private
	    {
		return (Scalar::Util::looks_like_number($_[0]) &&
			($_[0] > 0));
	    }
	}

   Type	Checking on ":Init" Parameters
       For object initialization parameters that are sent to the ":Init"
       subroutine during object	initialization,	the parameter's	type can be
       specified in the	":InitArgs" hash for that parameter using the same
       types as	specified in the previous section.  For	example:

	my %init_args :InitArgs	= (
	    'COUNT' => {
		'Type' => 'numeric',
	    },
	    'OBJS' => {
		'Type' => 'list(My::Class)',
	    },
	);

       One exception involves custom type checking:  If	referenced in an
       ":InitArgs" hash, the type checking subroutine cannot be	made
       ":Private":

	package	My::Class; {
	    use	Object::InsideOut;

	    sub	check_type   # Cannot be :Private
	    {
	       ...
	    }

	    my %init_args :InitArgs = (
		'ARG' => {
		    'Type' => \&check_type,
		},
	    );

	    ...
	}

       Also, as	shown, it also doesn't have to be a fully-qualified name.

CUMULATIVE METHODS
       Normally, methods with the same name in a class hierarchy are masked
       (i.e., overridden) by inheritance - only	the method in the most-derived
       class is	called.	 With cumulative methods, this masking is removed, and
       the same-named method is	called in each of the classes within the
       hierarchy.  The return results from each	call (if any) are then
       gathered	together into the return value for the original	method call.
       For example,

	package	My::Class; {
	    use	Object::InsideOut;

	    sub	what_am_i :Cumulative
	    {
		my $self = shift;

		my $ima	= (ref($self) eq __PACKAGE__)
			    ? q/I was created as a /
			    : q/My top class is	/;

		return ($ima . __PACKAGE__);
	    }
	}

	package	My::Foo; {
	    use	Object::InsideOut 'My::Class';

	    sub	what_am_i :Cumulative
	    {
		my $self = shift;

		my $ima	= (ref($self) eq __PACKAGE__)
			    ? q/I was created as a /
			    : q/I'm also a /;

		return ($ima . __PACKAGE__);
	    }
	}

	package	My::Child; {
	    use	Object::InsideOut 'My::Foo';

	    sub	what_am_i :Cumulative
	    {
		my $self = shift;

		my $ima	= (ref($self) eq __PACKAGE__)
			    ? q/I was created as a /
			    : q/I'm in class /;

		return ($ima . __PACKAGE__);
	    }
	}

	package	main;

	my $obj	= My::Child->new();
	my @desc = $obj->what_am_i();
	print(join("\n", @desc), "\n");

       produces:

	My top class is	My::Class
	I'm also a My::Foo
	I was created as a My::Child

       When called in a	list context (as in the	above),	the return results of
       cumulative methods are accumulated, and returned	as a list.

       In a scalar context, a results object is	returned that segregates the
       results by class	for each of the	cumulative method calls.  Through
       overloading, this object	can then be dereferenced as an array, hash,
       string, number, or boolean.  For	example, the above could be rewritten
       as:

	my $obj	= My::Child->new();
	my $desc = $obj->what_am_i();	     # Results object
	print(join("\n", @{$desc}), "\n");   # Dereference as an array

       The following uses hash dereferencing:

	my $obj	= My::Child->new();
	my $desc = $obj->what_am_i();
	while (my ($class, $value) = each(%{$desc})) {
	    print("Class $class	reports:\n\t$value\n");
	}

       and produces:

	Class My::Class	reports:
		My top class is	My::Class
	Class My::Child	reports:
		I was created as a My::Child
	Class My::Foo reports:
		I'm also a My::Foo

       As illustrated above, cumulative	methods	are tagged with	the
       ":Cumulative" attribute (or ":Cumulative(topA down)"), and propagate
       from the	top down through the class hierarchy (i.e., from the parent
       classes down through the	child classes).	 If tagged with
       ":Cumulative(bottomA up)", they will propagated from the	object's class
       upward through the parent classes.

CHAINED	METHODS
       In addition to ":Cumulative", Object::InsideOut provides	a way of
       creating	methods	that are chained together so that their	return values
       are passed as input arguments to	other similarly	named methods in the
       same class hierarchy.  In this way, the chained methods act as though
       they were piped together.

       For example, imagine you	had a method called "format_name" that formats
       some text for display:

	package	Subscriber; {
	    use	Object::InsideOut;

	    sub	format_name {
		my ($self, $name) = @_;

		# Strip	leading	and trailing whitespace
		$name =~ s/^\s+//;
		$name =~ s/\s+$//;

		return ($name);
	    }
	}

       And elsewhere you have a	second class that formats the case of names:

	package	Person;	{
	    use	Lingua::EN::NameCase qw(nc);
	    use	Object::InsideOut;

	    sub	format_name
	    {
		my ($self, $name) = @_;

		# Attempt to properly case names
		return (nc($name));
	    }
	}

       And you decide that you'd like to perform some formatting of your own,
       and then	have all the parent methods apply their	own formatting.
       Normally, if you	have a single parent class, you'd just call the	method
       directly	with "$self->SUPER::format_name($name)", but if	you have more
       than one	parent class you'd have	to explicitly call each	method
       directly:

	package	Customer; {
	    use	Object::InsideOut qw(Person Subscriber);

	    sub	format_name
	    {
		my ($self, $name) = @_;

		# Compress all whitespace into a single	space
		$name =~ s/\s+/	/g;

		$name =	$self->Subscriber::format_name($name);
		$name =	$self->Person::format_name($name);

		return $name;
	    }
	}

       With Object::InsideOut, you'd add the ":Chained"	attribute to each
       class's "format_name" method, and the methods will be chained together
       automatically:

	package	Subscriber; {
	    use	Object::InsideOut;

	    sub	format_name :Chained
	    {
		my ($self, $name) = @_;

		# Strip	leading	and trailing whitespace
		$name =~ s/^\s+//;
		$name =~ s/\s+$//;

		return ($name);
	    }
	}

	package	Person;	{
	    use	Lingua::EN::NameCase qw(nc);
	    use	Object::InsideOut;

	    sub	format_name :Chained
	    {
		my ($self, $name) = @_;

		# Attempt to properly case names
		return (nc($name));
	    }
	}

	package	Customer; {
	    use	Object::InsideOut qw(Person Subscriber);

	    sub	format_name :Chained
	    {
		my ($self, $name) = @_;

		# Compress all whitespace into a single	space
		$name =~ s/\s+/	/g;

		return ($name);
	    }
	}

       So passing in someone's name to "format_name" in	"Customer" would cause
       leading and trailing whitespace to be removed, then the name to be
       properly	cased, and finally whitespace to be compressed to a single
       space.  The resulting $name would be returned to	the caller:

	my ($name) = $obj->format_name($name_raw);

       Unlike ":Cumulative" methods, ":Chained"	methods	always returns an
       array - even if there is	only one value returned.  Therefore,
       ":Chained" methods should always	be called in an	array context, as
       illustrated above.

       The default direction is	to chain methods from the parent classes at
       the top of the class hierarchy down through the child classes.  You may
       use the attribute ":Chained(topA	down)" to make this more explicit.

       If you label the	method with the	":Chained(bottomA up)" attribute, then
       the chained methods are called starting with the	object's class and
       working upward through the parent classes in the	class hierarchy,
       similar to how ":Cumulative(bottomA up)"	works.

ARGUMENT MERGING
       As mentioned under "Object Creation", the "->new()" method can take
       parameters that are passed in as	combinations of	"keyA =>A value" pairs
       and/or hash refs:

	my $obj	= My::Class->new(
	    'param_X' => 'value_X',
	    'param_Y' => 'value_Y',
	    {
		'param_A' => 'value_A',
		'param_B' => 'value_B',
	    },
	    {
		'param_Q' => 'value_Q',
	    },
	);

       The parameters are merged into a	single hash ref	before they are
       processed.

       Adding the ":MergeArgs" attribute to your methods gives them a similar
       capability.  Your method	will then get two arguments:  The object and a
       single hash ref of the merged arguments.	 For example:

	package	Foo; {
	    use	Object::InsideOut;

	    ...

	    sub	my_method :MergeArgs {
		my ($self, $args) = @_;

		my $param = $args->{'param'};
		my $data  = $args->{'data'};
		my $flag  = $args->{'flag'};
		...
	    }
	}

	package	main;

	my $obj	= Foo->new(...);

	$obj->my_method( { 'data' => 42,
			   'flag' => 'true' },
			 'param' => 'foo' );

ARGUMENT VALIDATION
       A number	of users have asked about argument validation for methods:
       <http://www.cpanforum.com/threads/3204>.	 For this, I recommend using
       Params::Validate:

	package	Foo; {
	    use	Object::InsideOut;
	    use	Params::Validate ':all';

	    sub	foo
	    {
		my $self = shift;
		my %args = validate(@_,	{ bar => 1 });
		my $bar	= $args{bar};
		...
	    }
	}

       Using Attribute::Params::Validate, attributes are used for argument
       validation specifications:

	package	Foo; {
	    use	Object::InsideOut;
	    use	Attribute::Params::Validate;

	    sub	foo :method :Validate(bar => 1)
	    {
		my $self = shift;
		my %args = @_;
		my $bar	= $args{bar};
		...
	    }
	}

       Note that in the	above, Perl's ":method"	attribute (in all lowercase)
       is needed.

       There is	some incompatibility between Attribute::Params::Validate and
       some of Object::InsideOut's attributes.	Namely,	you cannot use
       ":Validate" with	":Private", ":Restricted", ":Cumulative", ":Chained"
       or ":MergeArgs".	 In these cases, use the "validate()" function from
       Params::Validate	instead.

AUTOMETHODS
       There are significant issues related to Perl's "AUTOLOAD" mechanism
       that cause it to	be ill-suited for use in a class hierarchy. Therefore,
       Object::InsideOut implements its	own ":Automethod" mechanism to
       overcome	these problems.

       Classes requiring "AUTOLOAD"-type capabilities must provided a
       subroutine labeled with the ":Automethod" attribute.  The ":Automethod"
       subroutine will be called with the object and the arguments in the
       original	method call (the same as for "AUTOLOAD").  The ":Automethod"
       subroutine should return	either a subroutine reference that implements
       the requested method's functionality, or	else just end with "return;"
       to indicate that	it doesn't know	how to handle the request.

       Using its own "AUTOLOAD"	subroutine (which is exported to every class),
       Object::InsideOut walks through the class tree, calling each
       ":Automethod" subroutine, as needed, to fulfill an unimplemented	method
       call.

       The name	of the method being called is passed as	$_ instead of
       $AUTOLOAD, and is not prefixed with the class name.  If the
       ":Automethod" subroutine	also needs to access the $_ from the caller's
       scope, it is available as $CALLER::_.

       Automethods can also be made to act as "CUMULATIVE METHODS" or "CHAINED
       METHODS".  In these cases, the ":Automethod" subroutine should return
       two values: The subroutine ref to handle	the method call, and a string
       designating the type of method.	The designator has the same form as
       the attributes used to designate	":Cumulative" and ":Chained" methods:

	':Cumulative'  or  ':Cumulative(top down)'
	':Cumulative(bottom up)'
	':Chained'     or  ':Chained(top down)'
	':Chained(bottom up)'

       The following skeletal code illustrates how an ":Automethod" subroutine
       could be	structured:

	sub _automethod	:Automethod
	{
	    my $self = shift;
	    my @args = @_;

	    my $method_name = $_;

	    # This class can handle the	method directly
	    if (...) {
		my $handler = sub {
		    my $self = shift;
		    ...
		    return ...;
		};

		### OPTIONAL ###
		# Install the handler so it gets called	directly next time
		# no strict refs;
		# *{__PACKAGE__.'::'.$method_name} = $handler;
		################

		return ($handler);
	    }

	    # This class can handle the	method as part of a chain
	    if (...) {
		my $chained_handler = sub {
		    my $self = shift;
		    ...
		    return ...;
		};

		return ($chained_handler, ':Chained');
	    }

	    # This class cannot	handle the method request
	    return;
	}

       Note: The OPTIONAL code above for installing the	generated handler as a
       method should not be used with ":Cumulative" or ":Chained" automethods.

OBJECT SERIALIZATION
   Basic Serialization
       my $array_ref = $obj->dump();
       my $string = $obj->dump(1);
	   Object::InsideOut exports a method called "->dump()"	to each	class
	   that	returns	either a Perl or a string representation of the	object
	   that	invokes	the method.

	   The Perl representation is returned when "->dump()" is called
	   without arguments.  It consists of an array ref whose first element
	   is the name of the object's class, and whose	second element is a
	   hash	ref containing the object's data.  The object data hash	ref
	   contains keys for each of the classes that make up the object's
	   hierarchy. The values for those keys	are hash refs containing
	   "keyA =>A value" pairs for the object's fields.  For	example:

	    [
	      'My::Class::Sub',
	      {
		'My::Class' => {
				 'data'	=> 'value'
			       },
		'My::Class::Sub' => {
				      'life' =>	42
				    }
	      }
	    ]

	   The name for	an object field	(data and life in the example above)
	   can be specified by adding the ":Name" attribute to the field:

	    my @life :Field :Name(life);

	   If the ":Name" attribute is not used, then the name for a field
	   will	be either the name associated with an ":All" or	":Arg"
	   attribute, its get method name, its set method name,	or, failing
	   all that, a string of the form "ARRAY(0x...)" or "HASH(0x...)".

	   When	called with a true argument, "->dump()"	returns	a string
	   version of the Perl representation using Data::Dumper.

	   Note	that using Data::Dumper	directly on an inside-out object will
	   not produce the desired results (it'll just output the contents of
	   the scalar ref).  Also, if inside-out objects are stored inside
	   other structures, a dump of those structures	will not contain the
	   contents of the object's fields.

	   In the event	of a method naming conflict, the "->dump()" method can
	   be called using its fully-qualified name:

	    my $dump = $obj->Object::InsideOut::dump();

       my $obj = Object::InsideOut->pump($data);
	   "Object::InsideOut->pump()" takes the output	from the "->dump()"
	   method, and returns an object that is created using that data.  If
	   $data is the	array ref returned by using "$obj->dump()", then the
	   data	is inserted directly into the corresponding fields for each
	   class in the	object's class hierarchy.  If $data is the string
	   returned by using "$obj->dump(1)", then it is "eval"ed to turn it
	   into	an array ref, and then processed as above.

	   Caveats: If any of an object's fields are dumped to field name keys
	   of the form "ARRAY(0x...)" or "HASH(0x...)" (see above), then the
	   data	will not be reloadable using "Object::InsideOut->pump()".  To
	   overcome this problem, the class developer must either add ":Name"
	   attributes to the ":Field" declarations (see	above),	or provide a
	   ":Dumper"/":Pumper" pair of subroutines as described	below.

	   Dynamically altering	a class	(e.g., using ->create_field()) after
	   objects have	been dumped will result	in "undef" fields when pumped
	   back	in regardless of whether or not	the added fields have
	   defaults.

	   Modifying the output	from "->dump()", and then feeding it into
	   "Object::InsideOut->pump()" will work, but is not specifically
	   supported.  If you know what	you're doing, fine, but	you're on your
	   own.

       ":Dumper" Subroutine Attribute
	   If a	class requires special processing to dump its data, then it
	   can provide a subroutine labeled with the ":Dumper" attribute.
	   This	subroutine will	be sent	the object that	is being dumped.  It
	   may then return any type of scalar the developer deems appropriate.
	   Usually, this would be a hash ref containing	"keyA =>A value" pairs
	   for the object's fields.  For example:

	    my @data :Field;

	    sub	_dump :Dumper
	    {
		my $obj	= $_[0];

		my %field_data;
		$field_data{'data'} = $data[$$obj];

		return (\%field_data);
	    }

	   Just	be sure	not to call your ":Dumper" subroutine "dump" as	that
	   is the name of the dump method exported by Object::InsideOut	as
	   explained above.

       ":Pumper" Subroutine Attribute
	   If a	class supplies a ":Dumper" subroutine, it will most likely
	   need	to provide a complementary ":Pumper" labeled subroutine	that
	   will	be used	as part	of creating an object from dumped data using
	   "Object::InsideOut->pump()".	 The subroutine	will be	supplied the
	   new object that is being created, and whatever scalar was returned
	   by the ":Dumper" subroutine.	 The corresponding ":Pumper" for the
	   example ":Dumper" above would be:

	    sub	_pump :Pumper
	    {
		my ($obj, $field_data) = @_;

		$obj->set(\@data, $field_data->{'data'});
	    }

   Storable
       Object::InsideOut also supports object serialization using the Storable
       module.	There are two methods for specifying that a class can be
       serialized using	Storable.  The first method involves adding Storable
       to the Object::InsideOut	declaration in your package:

	package	My::Class; {
	    use	Object::InsideOut qw(Storable);
	    ...
	}

       and adding "useA	Storable;" in your application.	 Then you can use the
       "->store()" and "->freeze()" methods to serialize your objects, and the
       "retrieve()" and	"thaw()" subroutines to	de-serialize them.

	package	main;
	use Storable;
	use My::Class;

	my $obj	= My::Class->new(...);
	$obj->store('/tmp/object.dat');
	...
	my $obj2 = retrieve('/tmp/object.dat');

       The other method	of specifying Storable serialization involves setting
       a "::storable" variable inside a	"BEGIN"	block for the class prior to
       its use:

	package	main;
	use Storable;

	BEGIN {
	    $My::Class::storable = 1;
	}
	use My::Class;

       NOTE: The caveats discussed above for the "->pump()" method are also
       applicable when using the Storable module.

OBJECT COERCION
       Object::InsideOut provides support for various forms of object coercion
       through the overload mechanism.	For instance, if you want an object to
       be usable directly in a string, you would supply	a subroutine in	your
       class labeled with the ":Stringify" attribute:

	sub as_string :Stringify
	{
	    my $self = $_[0];
	    my $string = ...;
	    return ($string);
	}

       Then you	could do things	like:

	print("The object says,	'$obj'\n");

       For a boolean context, you would	supply:

	sub as_bool :Boolify
	{
	    my $self = $_[0];
	    my $true_or_false =	...;
	    return ($true_or_false);
	}

       and use it in this manner:

	if (! defined($obj)) {
	    # The object is undefined
	    ....

	} elsif	(! $obj) {
	    # The object returned a false value
	    ...
	}

       The following coercion attributes are supported:

       :Stringify
       :Numerify
       :Boolify
       :Arrayify
       :Hashify
       :Globify
       :Codify

       Coercing	an object to a scalar (":Scalarify") is	not supported as $$obj
       is the ID of the	object and cannot be overridden.

CLONING
   Object Cloning
       Copies of objects can be	created	using the "->clone()" method which is
       exported	by Object::InsideOut to	each class:

	my $obj2 = $obj->clone();

       When called without arguments, "->clone()" creates a shallow copy of
       the object, meaning that	any complex data structures (i.e., array, hash
       or scalar refs) stored in the object will be shared with	its clone.

       Calling "->clone()" with	a true argument:

	my $obj2 = $obj->clone(1);

       creates a deep copy of the object such that internally held array, hash
       or scalar refs are replicated and stored	in the newly created clone.

       Deep cloning can	also be	controlled at the field	level, and is covered
       in the next section.

       Note that cloning does not clone	internally held	objects.  For example,
       if $foo contains	a reference to $bar, a clone of	$foo will also contain
       a reference to $bar; not	a clone	of $bar.  If such behavior is needed,
       it must be provided using a :Replicate subroutine.

   Field Cloning
       Object cloning can be controlled	at the field level such	that specified
       fields are deeply copied	when "->clone()" is called without any
       arguments.  This	is done	by adding the ":Deep" attribute	to the field:

	my @data :Field	:Deep;

WEAK FIELDS
       Frequently, it is useful	to store weakened references to	data or
       objects in a field.  Such a field can be	declared as ":Weak" so that
       data (i.e., references) set via Object::InsideOut generated accessors,
       parameter processing using ":Arg", the "->set()"	method,	etc., will
       automatically be	weakened after being stored in the field array/hash.

	my @data :Field	:Weak;

       NOTE: If	data in	a weak field is	set directly (i.e., the	"->set()"
       method is not used), then weaken() must be invoked on the stored
       reference afterwards:

	$self->set(\@field, $data);
	Scalar::Util::weaken($field[$$self]);

       (This is	another	reason why the "->set()" method	is recommended for
       setting field data within class code.)

DYNAMIC	FIELD CREATION
       Normally, object	fields are declared as part of the class code.
       However,	some classes may need the capability to	create object fields
       on-the-fly, for example,	as part	of an ":Automethod".
       Object::InsideOut provides a class method for this:

	# Dynamically create a hash field with standard	accessors
	My::Class->create_field('%'.$fld, ":Std($fld)");

       The first argument is the class into which the field will be added.
       The second argument is a	string containing the name of the field
       preceded	by either a "@"	or "%" to declare an array field or hash
       field, respectively.  The remaining string arguments should be
       attributes declaring accessors and the like.  The ":Field" attribute is
       assumed,	and does not need to be	added to the attribute list.  For
       example:

	My::Class->create_field('@data', ":Type(numeric)",
					 ":Acc(data)");

	My::Class->create_field('@obj',	":Type(Some::Class)",
					":Acc(obj)",
					":Weak");

       Field creation will fail	if you try to create an	array field within a
       class whose hierarchy has been declared :hash_only.

       Here's an example of an ":Automethod" subroutine	that uses dynamic
       field creation:

	package	My::Class; {
	    use	Object::InsideOut;

	    sub	_automethod :Automethod
	    {
		my $self = $_[0];
		my $class = ref($self) || $self;
		my $method = $_;

		# Extract desired field	name from get_/set_ method name
		my ($fld_name) = $method =~ /^[gs]et_(.*)$/;
		if (! $fld_name) {
		    return;    # Not a recognized method
		}

		# Create the field and its standard accessors
		$class->create_field('@'.$fld_name, ":Std($fld_name)");

		# Return code ref for newly created accessor
		no strict 'refs';
		return *{$class.'::'.$method}{'CODE'};
	    }
	}

RUNTIME	INHERITANCE
       The class method	"->add_class()"	provides the capability	to dynamically
       add classes to a	class hierarchy	at runtime.

       For example, suppose you	had a simple state class:

	package	Trait::State; {
	    use	Object::InsideOut;

	    my %state :Field :Set(state);
	}

       This could be added to another class at runtime using:

	My::Class->add_class('Trait::State');

       This permits, for example, application code to dynamically modify a
       class without having it create an actual	sub-class.

PREPROCESSING
   Parameter Preprocessing
       You can specify a code ref (either in the form of an anonymous
       subroutine, or a	subroutine name) for an	object initialization
       parameter that will be called on	that parameter prior to	taking any of
       the other parameter actions described above.  Here's an example:

	package	My::Class; {
	    use	Object::InsideOut;

	    # The parameter preprocessing subroutine
	    sub	preproc
	    {
		my ($class, $param, $spec, $obj, $value) = @_;

		# Preform parameter preprocessing
		...

		# Return result
		return ...;
	    }

	    my @data :Field
		     :Arg('Name' => 'DATA', 'Preprocess' => \&My::Class::preproc);

	    my %init_args :InitArgs = (
		'PARAM'	=> {
		    'Preprocess' => \&preproc,
		},
	    );

	    ...
	}

       When used in the	":Arg" attribute, the subroutine name must be fully-
       qualified, as illustrated.  Further, if not referenced in the
       ":InitArgs" hash, the preprocessing subroutine can be given the
       ":Private" attribute.

       As the above illustrates, the parameter preprocessing subroutine	is
       sent five arguments:

       o   The name of the class associated with the parameter

	   This	would be "My::Class" in	the example above.

       o   The name of the parameter

	   Either "DATA" or "PARAM" in the example above.

       o   A hash ref of the parameter's specifiers

	   This	is either a hash ref containing	the ":Arg" attribute
	   parameters, or the hash ref paired to the parameter's key in	the
	   ":InitArgs" hash.

       o   The object being initialized

       o   The parameter's value

	   This	is the value assigned to the parameter in the "->new()"
	   method's argument list.  If the parameter was not provided to
	   "->new()", then "undef" will	be sent.

       The return value	of the preprocessing subroutine	will then be assigned
       to the parameter.

       Be careful about	what types of data the preprocessing subroutine	tries
       to make use of "external" to the	arguments supplied.  For instance,
       because the order of parameter processing is not	specified, the
       preprocessing subroutine	cannot rely on whether or not some other
       parameter is set.  Such processing would	need to	be done	in the ":Init"
       subroutine.  It can, however, make use of object	data set by classes
       higher up in the	class hierarchy.  (That	is why the object is provided
       as one of the arguments.)

       Possible	uses for parameter preprocessing include:

       o   Overriding the supplied value (or even deleting it by returning
	   "undef")

       o   Providing a dynamically-determined default value

       Preprocess may be abbreviated to	Preproc	or Pre.

   Set Accessor	Preprocessing
       You can specify a code ref (either in the form of an anonymous
       subroutine, or a	fully-qualified	subroutine name) for a set/combined
       accessor	that will be called on the arguments supplied to the accessor
       prior to	its taking the usual actions of	type checking and adding the
       data to the field.  Here's an example:

	package	My::Class; {
	    use	Object::InsideOut;

	    my @data :Field
		     :Acc('Name' => 'data', 'Preprocess' => \&My::Class::preproc);

	    # The set accessor preprocessing subroutine	may be made 'Private'
	    sub	preproc	:Private
	    {
		my ($self, $field, @args) = @_;

		# Preform preprocessing	on the accessor's arguments
		...

		# Return result
		return ...;
	    }
	}

       As the above illustrates, the accessor preprocessing subroutine is sent
       the following arguments:

       o   The object used to invoke the accessor

       o   A reference to the field associated with the	accessor

       o   The argument(s) sent	to the accessor

	   There will always be	at least one argument.

       Usually,	the preprocessing subroutine would return just a single	value.
       For fields declared as type "List", multiple values may be returned.

       Following preprocessing,	the set	accessor will operate on whatever
       value(s)	are returned by	the preprocessing subroutine.

SPECIAL	PROCESSING
   Object ID
       By default, the ID of an	object is derived from a sequence counter for
       the object's class hierarchy.  This should suffice for nearly all cases
       of class	development.  If there is a special need for the module	code
       to control the object ID	(see Math::Random::MT::Auto as an example),
       then a subroutine labelled with the ":ID" attribute can be specified:

	sub _id	:ID
	{
	    my $class =	$_[0];

	    # Generate/determine a unique object ID
	    ...

	    return ($id);
	}

       The ID returned by your subroutine can be any kind of regular scalar
       (e.g., a	string or a number).  However, if the ID is something other
       than a low-valued integer, then you will	have to	architect all your
       classes using hashes for	the object fields.  See	"HASH ONLY CLASSES"
       for details.

       Within any class	hierarchy, only	one class may specify an ":ID"
       subroutine.

   Object Replication
       Object replication occurs explicitly when the "->clone()" method	is
       called on an object, and	implicitly when	threads	are created in a
       threaded	application.  In nearly	all cases, Object::InsideOut will take
       care of all the details for you.

       In rare cases, a	class may require special handling for object
       replication.  It	must then provide a subroutine labeled with the
       ":Replicate" attribute.	This subroutine	will be	sent three arguments:
       The parent and the cloned objects, and a	flag:

	sub _replicate :Replicate
	{
	    my ($parent, $clone, $flag)	= @_;

	    # Special object replication processing
	    if ($clone eq 'CLONE') {
	       # Handling for thread cloning
	       ...
	    } elsif ($clone eq 'deep') {
	       # Deep copy of the parent
	       ...
	    } else {
	       # Shallow copying
	       ...
	    }
	}

       In the case of thread cloning, $flag will be set	to the 'CLONE',	and
       the $parent object is just a non-blessed	anonymous scalar reference
       that contains the ID for	the object in the parent thread.

       When invoked via	the "->clone()"	method,	$flag will be either an	empty
       string which denotes that a shallow copy	is being produced for the
       clone, or $flag will be set to 'deep' indicating	a deep copy is being
       produced.

       The ":Replicate"	subroutine only	needs to deal with the special
       replication processing needed by	the object:  Object::InsideOut will
       handle all the other details.

   Object Destruction
       Object::InsideOut exports a "DESTROY" method to each class that deletes
       an object's data	from the object	field arrays (hashes).	If a class
       requires	additional destruction processing (e.g., closing filehandles),
       then it must provide a subroutine labeled with the ":Destroy"
       attribute.  This	subroutine will	be sent	the object that	is being
       destroyed:

	sub _destroy :Destroy
	{
	    my $obj = $_[0];

	    # Special object destruction processing
	}

       The ":Destroy" subroutine only needs to deal with the special
       destruction processing:	The "DESTROY" method will handle all the other
       details of object destruction.

FOREIGN	CLASS INHERITANCE
       Object::InsideOut supports inheritance from foreign (i.e.,
       non-Object::InsideOut) classes.	This means that	your classes can
       inherit from other Perl class, and access their methods from your own
       objects.

       One method of declaring foreign class inheritance is to add the class
       name to the Object::InsideOut declaration inside	your package:

	package	My::Class; {
	    use	Object::InsideOut qw(Foreign::Class);
	    ...
	}

       This allows you to access the foreign class's static (i.e., class)
       methods from your own class.  For example, suppose "Foreign::Class" has
       a class method called "foo".  With the above, you can access that
       method using "My::Class->foo()" instead.

       Multiple	foreign	inheritance is supported, as well:

	package	My::Class; {
	    use	Object::InsideOut qw(Foreign::Class Other::Foreign::Class);
	    ...
	}

       $self->inherit($obj, ...);
	   To use object methods from foreign classes, an object must inherit
	   from	an object of that class.  This would normally be done inside a
	   class's ":Init" subroutine:

	    package My::Class; {
		use Object::InsideOut qw(Foreign::Class);

		sub init :Init
		{
		    my ($self, $args) =	@_;

		    my $foreign_obj = Foreign::Class->new(...);
		    $self->inherit($foreign_obj);
		}
	    }

	   Thus, with the above, if "Foreign::Class" has an object method
	   called "bar", you can call that method from your own	objects:

	    package main;

	    my $obj = My::Class->new();
	    $obj->bar();

	   Object::InsideOut's "AUTOLOAD" subroutine handles the dispatching
	   of the "->bar()" method call	using the internally held inherited
	   object (in this case, $foreign_obj).

	   Multiple inheritance	is supported, as well:	You can	call the
	   "->inherit()" method	multiple times,	or make	just one call with all
	   the objects to be inherited from.

	   "->inherit()" is a restricted method.  In other words, you cannot
	   use it on an	object outside of code belonging to the	object's class
	   tree	(e.g., you can't call it from application code).

	   In the event	of a method naming conflict, the "->inherit()" method
	   can be called using its fully-qualified name:

	    $self->Object::InsideOut::inherit($obj);

       my @objs	= $self->heritage();
       my $obj = $self->heritage($class);
       my @objs	= $self->heritage($class1, $class2, ...);
	   Your	class code can retrieve	any inherited objects using the
	   "->heritage()" method. When called without any arguments, it
	   returns a list of any objects that were stored by the calling class
	   using the calling object.  In other words, if class "My::Class"
	   uses	object $obj to store foreign objects $fobj1 and	$fobj2,	then
	   later on in class "My::Class", "$obj->heritage()" will return
	   $fobj1 and $fobj2.

	   "->heritage()" can also be called with one or more class name
	   arguments.  In this case, only objects of the specified class(es)
	   are returned.

	   In the event	of a method naming conflict, the "->heritage()"	method
	   can be called using its fully-qualified name:

	    my @objs = $self->Object::InsideOut::heritage();

       $self->disinherit($class	[, ...])
       $self->disinherit($obj [, ...])
	   The "->disinherit()"	method disassociates (i.e., deletes) the
	   inheritance of foreign object(s) from an object.  The foreign
	   objects may be specified by class, or using the actual inherited
	   object (retrieved via "->heritage()", for example).

	   The call is only effective when called inside the class code	that
	   established the initial inheritance.	 In other words, if an
	   inheritance is set up inside	a class, then disinheritance can only
	   be done from	inside that class.

	   In the event	of a method naming conflict, the "->disinherit()"
	   method can be called	using its fully-qualified name:

	    $self->Object::InsideOut::disinherit($obj [, ...])

       NOTE:  With foreign inheritance,	you only have access to	class and
       object methods.	The encapsulation of the inherited objects is strong,
       meaning that only the class where the inheritance takes place has
       direct access to	the inherited object.  If access to the	inherited
       objects themselves, or their internal hash fields (in the case of
       blessed hash objects), is needed	outside	the class, then	you'll need to
       write your own accessors	for that.

       LIMITATION:  You	cannot use fully-qualified method names	to access
       foreign methods (when encapsulated foreign objects are involved).
       Thus, the following will	not work:

	my $obj	= My::Class->new();
	$obj->Foreign::Class::bar();

       Normally, you shouldn't ever need to do the above:  "$obj->bar()" would
       suffice.

       The only	time this may be an issue is when the native class overrides
       an inherited foreign class's method (e.g., "My::Class" has its own
       "->bar()" method).  Such	overridden methods are not directly callable.
       If such overriding is intentional, then this should not be an issue:
       No one should be	writing	code that tries	to by-pass the override.
       However,	if the overriding is accidentally, then	either the native
       method should be	renamed, or the	native class should provide a wrapper
       method so that the functionality	of the overridden method is made
       available under a different name.

   "use	base" and Fully-qualified Method Names
       The foreign inheritance methodology handled by the above	is predicated
       on non-Object::InsideOut	classes	that generate their own	objects	and
       expect their object methods to be invoked via those objects.

       There are exceptions to this rule:

       1. Foreign object methods that expect to	be invoked via the inheriting
       class's object, or foreign object methods that don't care how they are
       invoked (i.e., they don't make reference	to the invoking	object).
	   This	is the case where a class provides auxiliary methods for your
	   objects, but	from which you don't actually create any objects
	   (i.e., there	is no corresponding foreign object, and
	   "$obj->inherit($foreign)" is	not used.)

	   In this case, you can either:

	   a. Declare the foreign class	using the standard method (i.e.,
	   "useA Object::InsideOutA qw(Foreign::Class);"), and invoke its
	   methods using their full path (e.g.,
	   "$obj->Foreign::Class::method();"); or

	   b. You can use the base pragma so that you don't have to use	the
	   full	path for foreign methods.

	    package My::Class; {
		use Object::InsideOut;
		use base 'Foreign::Class';
		...
	    }

	   The former scheme is	faster.

       2. Foreign class	methods	that expect to be invoked via the inheriting
       class.
	   As with the above, you can either invoke the	class methods using
	   their full path (e.g., "My::Class->Foreign::Class::method();"), or
	   you can "useA base" so that you don't have to use the full path.
	   Again, using	the full path is faster.

	   Class::Singleton is an example of this type of class.

       3. Class	methods	that don't care	how they are invoked (i.e., they don't
       make reference to the invoking class).
	   In this case, you can either	use
	   "useA Object::InsideOutA qw(Foreign::Class);" for consistency, or
	   use "useA baseA qw(Foreign::Class);"	if (slightly) better
	   performance is needed.

       If you're not familiar with the inner workings of the foreign class
       such that you don't know	if or which of the above exceptions applies,
       then the	formulaic approach would be to first use the documented	method
       for foreign inheritance (i.e.,
       "useA Object::InsideOutA	qw(Foreign::Class);").	If that	works, then I
       strongly	recommend that you just	use that approach unless you have a
       good reason not to.  If it doesn't work,	then try "useA base".

INTROSPECTION
       For Perl	5.8.0 and later, Object::InsideOut provides an introspection
       API that	allow you to obtain metadata on	a class's 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:

	    # Get an object's class hierarchy
	    my @classes	= $obj->meta()->get_classes();

	    # Get info on the args for a class's constructor (i.e., ->new() parameters)
	    my %args = My::Class->meta()->get_args();

	    # Get info on the methods that can be called by an object
	    my %methods	= $obj->meta()->get_methods();

       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.

       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 %methods	= $obj->meta()->get_methods();
	    my @methods	= keys(%methods);

	   When	called in a scalar context, it returns an array	ref containing
	   the method names.

       See Object::InsideOut::Metadata for more	details.

THREAD SUPPORT
       For Perl	5.8.1 and later, Object::InsideOut fully supports threads
       (i.e., is thread	safe), and supports the	sharing	of Object::InsideOut
       objects between threads using threads::shared.

       To use Object::InsideOut	in a threaded application, you must put
       "useA threads;" at the beginning	of the application.  (The use of
       "requireA threads;" after the program is	running	is not supported.)  If
       object sharing is to be utilized, then "useA threads::shared;" should
       follow.

       If you just "useA threads;", then objects from one thread will be
       copied and made available in a child thread.

       The addition of "useA threads::shared;" in and of itself	does not alter
       the behavior of Object::InsideOut objects.  The default behavior	is to
       not share objects between threads (i.e.,	they act the same as with
       "useA threads;" alone).

       To enable the sharing of	objects	between	threads, you must specify
       which classes will be involved with thread object sharing.  There are
       two methods for doing this.  The	first involves setting a "::shared"
       variable	(inside	a "BEGIN" block) for the class prior to	its use:

	use threads;
	use threads::shared;

	BEGIN {
	    $My::Class::shared = 1;
	}
	use My::Class;

       The other method	is for a class to add a	":SHARED" flag to its
       "useA Object::InsideOutA	..." declaration:

	package	My::Class; {
	    use	Object::InsideOut ':SHARED';
	    ...
	}

       When either sharing flag	is set for one class in	an object hierarchy,
       then all	the classes in the hierarchy are affected.

       If a class cannot support thread	object sharing (e.g., one of the
       object fields contains code refs	[which Perl cannot share between
       threads]), it should specifically declare this fact:

	package	My::Class; {
	    use	Object::InsideOut ':NOT_SHARED';
	    ...
	}

       However,	you cannot mix thread object sharing classes with non-sharing
       classes in the same class hierarchy:

	use threads;
	use threads::shared;

	package	My::Class; {
	    use	Object::InsideOut ':SHARED';
	    ...
	}

	package	Other::Class; {
	    use	Object::InsideOut ':NOT_SHARED';
	    ...
	}

	package	My::Derived; {
	    use	Object::InsideOut qw(My::Class Other::Class);	# ERROR!
	    ...
	}

       Here is a complete example with thread object sharing enabled:

	use threads;
	use threads::shared;

	package	My::Class; {
	    use	Object::InsideOut ':SHARED';

	    # One list-type field
	    my @data :Field :Type(list)	:Acc(data);
	}

	package	main;

	# New object
	my $obj	= My::Class->new();

	# Set the object's 'data' field
	$obj->data(qw(foo bar baz));

	# Print	out the	object's data
	print(join(', ', @{$obj->data()}), "\n");	# "foo,	bar, baz"

	# Create a thread and manipulate the object's data
	my $rc = threads->create(
		sub {
		    # Read the object's	data
		    my $data = $obj->data();
		    # Print out	the object's data
		    print(join(', ', @{$data}),	"\n");	# "foo,	bar, baz"
		    # Change the object's data
		    $obj->data(@$data[1..2], 'zooks');
		    # Print out	the object's modified data
		    print(join(', ', @{$obj->data()}), "\n");  # "bar, baz, zooks"
		    return (1);
		}
	    )->join();

	# Show that changes in the object are visible in the parent thread
	# I.e.,	this shows that	the object was indeed shared between threads
	print(join(', ', @{$obj->data()}), "\n");	# "bar,	baz, zooks"

HASH ONLY CLASSES
       For performance considerations, it is recommended that arrays be	used
       for class fields	whenever possible.  The	only time when hash-bases
       fields are required is when a class must	provide	its own	object ID, and
       those IDs are something other than low-valued integers.	In this	case,
       hashes must be used for fields not only in the class that defines the
       object ID subroutine, but also in every class in	any class hierarchy
       that include such a class.

       The hash	only requirement can be	enforced by adding the ":HASH_ONLY"
       flag to a class's "useA Object::InsideOutA ..." declaration:

	package	My::Class; {
	    use	Object::InsideOut ':hash_only';

	    ...
	}

       This will cause Object::Inside to check every class in any class
       hierarchy that includes such flagged classes to make sure their fields
       are hashes and not arrays.  It will also	fail any ->create_field() call
       that tries to create an array-based field in any	such class.

SECURITY
       In the default case where Object::InsideOut provides object IDs that
       are sequential integers,	it is possible to hack together	a fake
       Object::InsideOut object, and so	gain access to another object's	data:

	my $fake = bless(\do{my	$scalar}, 'Some::Class');
	$$fake = 86;   # ID of another object
	my $stolen = $fake->get_data();

       Why anyone would	try to do this is unknown.  How	this could be used for
       any sort	of malicious exploitation is also unknown.  However, if
       preventing this sort of security	issue is a requirement,	it can be
       accomplished by adding the ":SECURE" flag to a class's
       "useA Object::InsideOutA	..." declaration:

	package	My::Class; {
	    use	Object::InsideOut ':SECURE';

	    ...
	}

       This places the module "Object::InsideOut::Secure" in the class
       hierarchy.  Object::InsideOut::Secure provides an :ID subroutine	that
       generates random	integers for object IDs, thus preventing other code
       from being able to create fake objects by guessing at IDs.

       Using ":SECURE" mode requires Math::Random::MT::Auto (v5.04 or later).

       Because the object IDs used with	":SECURE" mode are large random
       values, the :HASH_ONLY flag is forced on	all the	classes	in the
       hierarchy.

       For efficiency, it is recommended that the ":SECURE" flag be added to
       the topmost class(es) in	a hierarchy.

ATTRIBUTE HANDLERS
       Object::InsideOut uses attribute	'modify' handlers as described in
       "Package-specific Attribute Handling" in	attributes, and	provides a
       mechanism for adding attribute handlers to your own classes.  Instead
       of naming your attribute	handler	as "MODIFY_*_ATTRIBUTES", name it
       something else and then label it	with the ":MODIFY_*_ATTRIBUTES"
       attribute (or ":MOD_*_ATTRS" for	short).	 Your handler should work just
       as described in "Package-specific Attribute Handling" in	attributes
       with regard to its input	arguments, and must return a list of the
       attributes which	were not recognized by your handler.  Here's an
       example:

	package	My::Class; {
	    use	Object::InsideOut;

	    sub	_scalar_attrs :MOD_SCALAR_ATTRS
	    {
		my ($pkg, $scalar, @attrs) = @_;
		my @unused_attrs;	  # List of any	unhandled attributes

		while (my $attr	= shift(@attrs)) {
		    if ($attr =~ /.../)	{
			# Handle attribute
			...
		    } else {
			# We don't handle this attribute
			push(@unused_attrs, $attr);
		    }
		}

		return (@unused_attrs);	  # Pass along unhandled attributes
	    }
	}

       Attribute 'modify' handlers are called upward through the class
       hierarchy (i.e.,	bottom up).  This provides child classes with the
       capability to override the handling of attributes by parent classes, or
       to add attributes (via the returned list	of unhandled attributes) for
       parent classes to process.

       Attribute 'modify' handlers should be located at	the beginning of a
       package,	or at least before any use of attributes on the	corresponding
       type of variable	or subroutine:

	package	My::Class; {
	    use	Object::InsideOut;

	    sub	_array_attrs :MOD_ARRAY_ATTRS
	    {
	       ...
	    }

	    my @my_array :MyArrayAttr;
	}

       For attribute 'fetch' handlers, follow the same procedures:  Label the
       subroutine with the ":FETCH_*_ATTRIBUTES" attribute (or
       ":FETCH_*_ATTRS"	for short).  Contrary to the documentation in
       "Package-specific Attribute Handling" in	attributes, attribute 'fetch'
       handlers	receive	two arguments: The relevant package name, and a
       reference to a variable or subroutine for which package-defined
       attributes are desired.

       Attribute handlers are normal rendered hidden.

SPECIAL	USAGE
   Usage With "Exporter"
       It is possible to use Exporter to export	functions from one inside-out
       object class to another:

	use strict;
	use warnings;

	package	Foo; {
	    use	Object::InsideOut 'Exporter';
	    BEGIN {
		our @EXPORT_OK = qw(foo_name);
	    }

	    sub	foo_name
	    {
		return (__PACKAGE__);
	    }
	}

	package	Bar; {
	    use	Object::InsideOut 'Foo'	=> [ qw(foo_name) ];

	    sub	get_foo_name
	    {
		return (foo_name());
	    }
	}

	package	main;

	print("Bar got Foo's name as '", Bar::get_foo_name(), "'\n");

       Note that the "BEGIN" block is needed to	ensure that the	Exporter
       symbol arrays (in this case @EXPORT_OK) get populated properly.

   Usage With "require"	and "mod_perl"
       Object::InsideOut usage under mod_perl and with runtime-loaded classes
       is supported automatically; no special coding is	required.

       Caveat: Runtime loading of classes should be performed before any
       objects are created within any of the classes in	their hierarchies.  If
       Object::InsideOut cannot	create a hierarchy because of previously
       created objects (even if	all those objects have been destroyed),	a
       runtime error will be generated.

   Singleton Classes
       A singleton class is a case where you would provide your	own "->new()"
       method that in turn calls Object::InsideOut's "->new()" method:

	package	My::Class; {
	    use	Object::InsideOut;

	    my $singleton;

	    sub	new {
		my $thing = shift;
		if (! $singleton) {
		    $singleton = $thing->Object::InsideOut::new(@_);
		}
		return ($singleton);
	    }
	}

DIAGNOSTICS
       Object::InsideOut uses "Exception::Class" for reporting errors.	The
       base error class	for this module	is "OIO".  Here	is an example of the
       basic manner for	trapping and handling errors:

	my $obj;
	eval { $obj = My::Class->new();	};
	if (my $e = OIO->caught()) {
	    warn('Failure creating object: '.$e);
	    ...
	}

       A more comprehensive approach might employ elements of the following:

	eval { ... };
	if (my $e = OIO->caught()) {
	    # An error generated by Object::InsideOut
	    ...
	} elsif	(my $e = Exception::Class::Base->caught()) {
	    # An error generated by other code that uses Exception::Class
	    ...
	} elsif	($@) {
	    # An unhandled error (i.e.,	generated by code that doesn't use
	    # Exception::Class)
	    ...
	}

       I have tried to make the	messages and information returned by the error
       objects as informative as possible.  Suggested improvements are
       welcome.	 Also, please bring to my attention any	conditions that	you
       encounter where an error	occurs as a result of Object::InsideOut	code
       that doesn't generate an	Exception::Class object.  Here is one such
       error:

       Invalid ARRAY/HASH attribute
	   This	error indicates	you forgot "use	Object::InsideOut;" in your
	   class's code.

       Object::InsideOut installs a "__DIE__" handler (see "die	LIST" in
       perlfunc	and "eval BLOCK" in perlfunc) to catch any errant exceptions
       from class-specific code, namely, ":Init", ":Replicate",	":Destroy",
       etc.  subroutines.  When	using "eval" blocks inside these subroutines,
       you should localize $SIG{'__DIE__'} to keep Object::InsideOut's
       "__DIE__" handler from interfering with exceptions generated inside the
       "eval" blocks.  For example:

	sub _init :Init	{
	    ...
	    eval {
		local $SIG{'__DIE__'};
		...
	    };
	    if $@ {
		# Handle caught	exception
	    }
	    ...
	}

       Here's another example, where the "die" function	is used	as a method of
       flow control for	leaving	an "eval" block:

	eval {
	    local $SIG{'__DIE__'};	     # Suppress	any existing __DIE__ handler
	    ...
	    die({'found' => 1})	if $found;   # Leave the eval block
	    ...
	};
	if ($@)	{
	    die	unless (ref($@)	&& $@->{'found'});   # Propagate any 'real' error
	    # Handle 'found' case
	    ...
	}
	# Handle 'not found' case

       Similarly, if calling code from other modules that use the above	flow
       control mechanism, but without localizing $SIG{'__DIE__'}, you can
       workaround this deficiency with your own	"eval" block:

	eval {
	    local $SIG{'__DIE__'};     # Suppress any existing __DIE__ handler
	    Some::Module::func();      # Call function that fails to localize
	};
	if ($@)	{
	    # Handle caught exception
	}

       In addition, you	should file a bug report against the offending module
       along with a patch that adds the	missing	"localA	$SIG{'__DIE__'};"
       statement.

BUGS AND LIMITATIONS
       If you receive an error similar to this:

	ERROR: Attempt to DESTROY object ID 1 of class Foo twice

       the cause may be	that some module used by your application is doing
       "require	threads" somewhere in the background.  DBI is one such module.
       The workaround is to add	"use threads;" at the start of your
       application.

       Another cause of	the above is returning a non-shared object from	a
       thread either explicitly	or implicitly when the result of the last
       statement in the	thread subroutine is an	object.	 For example:

	sub thr_func {
	    my $obj = MyClass->new();
	}

       which is	equivalent to:

	sub thr_func {
	    return MyClass->new();
	}

       This can	be avoided by ensuring your thread subroutine ends with
       "return;".

       The equality operator (e.g., "if	($obj1 == $obj2) { ...") is overloaded
       for ":SHARED" classes when threads::shared is loaded.  The overload
       subroutine compares object classes and IDs because references to	the
       same thread shared object may have different refaddrs.

       You cannot overload an object to	a scalar context (i.e.,	can't
       ":SCALARIFY").

       You cannot use two instances of the same	class with mixed thread	object
       sharing in same application.

       Cannot use attributes on	subroutine stubs (i.e.,	forward	declaration
       without later definition) with ":Automethod":

	package	My::Class; {
	    sub	method :Private;   # Will not work

	    sub	_automethod :Automethod
	    {
		# Code to handle call to 'method' stub
	    }
	}

       Due to limitations in the Perl parser, the entirety of any one
       attribute must be on a single line.  (However, multiple attributes may
       appear on separate lines.)

       If a set	accessor accepts scalars, then you can store any inside-out
       object type in it.  If its "Type" is set	to "HASH", then	it can store
       any blessed hash	object.

       Returning objects from threads does not work:

	my $obj	= threads->create(sub {	return (Foo->new()); })->join();  # BAD

       Instead,	use thread object sharing, create the object before launching
       the thread, and then manipulate the object inside the thread:

	my $obj	= Foo->new();	# Class	'Foo' is set ':SHARED'
	threads->create(sub { $obj->set_data('bar'); })->join();
	my $data = $obj->get_data();

       Due to a	limitation in threads::shared version 1.39 and earlier,	if
       storing shared objects inside other shared objects, you should use
       "delete()" to remove them from internal fields (e.g.,
       "delete($field[$$self]);") when necessary so that the objects'
       destructor gets called.	Upgrading to version 1.40 or later alleviates
       most of this issue except during	global destruction.  See
       threads::shared for more.

       With Perl 5.8.8 and earlier, there are bugs associated with
       threads::shared that may	prevent	you from storing objects inside	of
       shared objects, or using	foreign	inheritance with shared	objects.  With
       Perl 5.8.9 (and later) together with threads::shared 1.15 (and later),
       you can store shared objects inside of other shared objects, and	you
       can use foreign inheritance with	shared objects (provided the foreign
       class supports shared objects as	well).

       Due to internal complexities, the following actions are not supported
       in code that uses threads::shared while there are any threads active:

       o   Runtime loading of Object::InsideOut	classes

       o   Using ->add_class()

       It is recommended that such activities, if needed, be performed in the
       main application	code before any	threads	are created (or	at least while
       there are no active threads).

       For Perl	5.6.0 through 5.8.0, a Perl bug	prevents package variables
       (e.g., object attribute arrays/hashes) from being referenced properly
       from subroutine refs returned by	an ":Automethod" subroutine.  For Perl
       5.8.0 there is no workaround:  This bug causes Perl to core dump.  For
       Perl 5.6.0 through 5.6.2, the workaround	is to create a ref to the
       required	variable inside	the ":Automethod" subroutine, and use that
       inside the subroutine ref:

	package	My::Class; {
	    use	Object::InsideOut;

	    my %data;

	    sub	auto :Automethod
	    {
		my $self = $_[0];
		my $name = $_;

		my $data = \%data;	# Workaround for 5.6.X bug

		return sub {
			    my $self = shift;
			    if (! @_) {
				return ($$data{$name});
			    }
			    $$data{$name} = shift;
		       };
	    }
	}

       For Perl	5.8.1 through 5.8.4, a Perl bug	produces spurious warning
       messages	when threads are destroyed.  These messages are	innocuous, and
       can be suppressed by adding the following to your application code:

	$SIG{'__WARN__'} = sub {
		if ($_[0] !~ /^Attempt to free unreferenced scalar/) {
		    print(STDERR @_);
		}
	    };

       A better	solution would be to upgrade threads and threads::shared from
       CPAN, especially	if you encounter other problems	associated with
       threads.

       For Perl	5.8.4 and 5.8.5, the "Storable"	feature	does not work due to a
       Perl bug.  Use Object::InsideOut	v1.33 if needed.

       Due to bugs in the Perl interpreter, using the introspection API	(i.e.
       "->meta()", etc.) requires Perl 5.8.0 or	later.

       The version of Want that	is available via PPM for ActivePerl is
       defective, and causes failures when using ":lvalue" accessors.  Remove
       it, and then download and install the Want module using CPAN.

       Devel::StackTrace (used by Exception::Class) makes use of the DB
       namespace.  As a	consequence, Object::InsideOut thinks that
       "packageA DB" is	already	loaded.	 Therefore, if you create a class
       called DB that is sub-classed by	other packages,	you may	need to
       "require" it as follows:

	package	DB::Sub; {
	    require DB;
	    use	Object::InsideOut qw(DB);
	    ...
	}

       View existing bug reports at, and submit	any new	bugs, problems,
       patches,	etc.  to:
       <http://rt.cpan.org/Public/Dist/Display.html?Name=Object-InsideOut>

REQUIREMENTS
       Perl 5.6.0 or later
       Exception::Class	v1.22 or later
       Scalar::Util v1.10 or later
	   It is possible to install a pure perl version of Scalar::Util,
	   however, it will be missing the weaken() function which is needed
	   by Object::InsideOut.  You'll need to upgrade your version of
	   Scalar::Util	to one that supports its "XS" code.

       Test::More v0.50	or later
	   Needed for testing during installation.

       Want v0.12 or later
	   Optional.  Provides support for ":lvalue Accessors".

       Math::Random::MT::Auto v5.04 or later)
	   Optional.  Provides support for :SECURE mode.

       To cover	all of the above requirements and more,	it is recommended that
       you install Bundle::Object::InsideOut using CPAN:

	perl -MCPAN -e 'install	Bundle::Object::InsideOut'

       This will install the latest versions of	all the	required and optional
       modules needed for full support of all of the features provided by
       Object::InsideOut.

SEE ALSO
       Object::InsideOut on MetaCPAN:
       <https://metacpan.org/release/Object-InsideOut>

       Code repository:	<https://github.com/jdhedden/Object-InsideOut>

       Inside-out Object Model:
       <http://www.perlfoundation.org/perl5/index.cgi?inside_out_object>,
       <http://www.perlmonks.org/?node_id=219378>,
       <http://www.perlmonks.org/?node_id=483162>,
       <http://www.perlmonks.org/?node_id=515650>, Chapters 15 and 16 of Perl
       Best Practices by Damian	Conway

       Object::InsideOut::Metadata

       Storable, <Exception:Class>, Want, Math::Random::MT::Auto, attributes,
       overload

       Sample code in the examples directory of	this distribution on CPAN.

ACKNOWLEDGEMENTS
       Abigail <perlA ATA abigailA DOTA	nl> for	inside-out objects in general.

       Damian Conway <dconwayA ATA cpanA DOTA org> for Class::Std, and for
       delegator methods.

       David A.	Golden <dagoldenA ATA cpanA DOTA org> for thread handling for
       inside-out objects.

       Dan Kubb	<dan.kubb-cpanA	ATA autopilotmarketingA	DOTA com> for
       ":Chained" methods.

AUTHOR
       Jerry D.	Hedden,	<jdheddenA ATA cpanA DOTA org>

COPYRIGHT AND LICENSE
       Copyright 2005 -	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.

TRANSLATIONS
       A Japanese translation of this documentation by TSUJII, Naofumi
       <tsunA DOTA ntA ATA gmailA DOTA com> is available at
       <http://perldoc.jp/docs/modules/>.

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

NAME | VERSION | SYNOPSIS | DESCRIPTION | CLASSES | OBJECTS | ATTRIBUTES | FIELDS | OBJECT INITIALIZATION | ACCESSOR GENERATION | ALL-IN-ONE | READONLY FIELDS | DELEGATORS | PERMISSIONS | TYPE CHECKING | CUMULATIVE METHODS | CHAINED METHODS | ARGUMENT MERGING | ARGUMENT VALIDATION | AUTOMETHODS | OBJECT SERIALIZATION | OBJECT COERCION | CLONING | WEAK FIELDS | DYNAMIC FIELD CREATION | RUNTIME INHERITANCE | PREPROCESSING | SPECIAL PROCESSING | FOREIGN CLASS INHERITANCE | INTROSPECTION | THREAD SUPPORT | HASH ONLY CLASSES | SECURITY | ATTRIBUTE HANDLERS | SPECIAL USAGE | DIAGNOSTICS | BUGS AND LIMITATIONS | REQUIREMENTS | SEE ALSO | ACKNOWLEDGEMENTS | AUTHOR | COPYRIGHT AND LICENSE | TRANSLATIONS

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

home | help