Object::InsideOut(3) User Contributed Perl Documentation Object::InsideOut(3)NAMEObject::InsideOut - Comprehensive inside-out object support module
VERSION
This document describes Object::InsideOut version 3.81
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:
· Encapsulation
Object data is enclosed within the class's code and is accessible
only through the class-defined interface.
· 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.
· 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 "perl -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:
· 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.
· Threads
Object::InsideOut is thread safe, and thoroughly supports sharing
objects between threads using threads::shared.
· Flexibility
Allows control over object ID specification, accessor naming,
parameter name matching, and much more.
· Runtime Support
Supports classes that may be loaded at runtime (i.e., using
"eval { require ...; };"). This makes it usable from within
mod_perl, as well. Also supports additions to class hierarchies,
and dynamic creation of object fields during runtime.
· Exception Objects
Object::InsideOut uses Exception::Class for handling errors in an
OO-compatible manner.
· 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.
· 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.
· Introspection
Obtain constructor parameters and method metadata for
Object::InsideOut classes.
CLASSES
To use this module, each of your classes will start with
"use 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
"use base ..." 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 "key => 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' => 'bar', "My::Class" will also get 'param' => 'value', and
"Parent::Class" will also get 'data' => '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' => 'bar', and "Parent::Class" will get
'default' => '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
"key => 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 "{ 'MY_PARAM' => $param }"
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:
my @data :Field
:Arg('Name' => 'data', 'Default' => 'foo');
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., "{ 'data' => 'foo' }").
"Default" may be abbreviated to "Def".
Fields can also be assigned a default value even if not associated with
an initialization parameter:
my @data :Field
:Default('foo');
Note that when using ":Default", the value must be properly specified
(e.g., strings must be quoted as illustrated above).
Using an array or hash reference as a default will probably not produce
the result that you might expect:
my @foo :Field
:Default({});
This does not result in a new empty hash reference being created for
each new object. Rather, a single empty hash reference is created when
the module is loaded, and then that reference is assigned to each newly
created object. In other words, it is equivalent to:
my %bar = ();
my @foo :Field
:Default(\%bar);
To get the other result, assign a new empty hash reference using an
":Init" subroutine:
sub _init :Init
{
my ($self, $args) = @_;
if (! exists($foo[$$self])) {
$self->set(\@foo, {});
}
}
":Default" may be abbreviated to ":Def".
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 "{ 'Param' => $data }" 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' => '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 substituion 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');
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 "use Object::InsideOut ..."
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 CHECKINGObject::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 "key => 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(top 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(bottom 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(top down)" to make this more explicit.
If you label the method with the ":Chained(bottom 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(bottom up)" works.
ARGUMENT MERGING
As mentioned under "Object Creation", the "->new()" method can take
parameters that are passed in as combinations of "key => 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
"key => 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 "key => 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::InsideOutqw(Storable);
...
}
and adding "use 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 COERCIONObject::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:
· The name of the class associated with the parameter
This would be "My::Class" in the example above.
· The name of the parameter
Either "DATA" or "PARAM" in the example above.
· 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.
· The object being initialized
· 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:
· Overriding the supplied value (or even deleting it by returning
"undef")
· 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:
· The object used to invoke the accessor
· A reference to the field associated with the accessor
· 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 INHERITANCEObject::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.,
"use Object::InsideOut 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 "use 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
"use Object::InsideOut qw(Foreign::Class);" for consistency, or use
"use base 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.,
"use Object::InsideOut 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 "use 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
"use threads;" at the beginning of the application. (The use of
"require threads;" after the program is running is not supported.) If
object sharing is to be utilized, then "use threads::shared;" should
follow.
If you just "use threads;", then objects from one thread will be copied
and made available in a child thread.
The addition of "use 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
"use 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
"use Object::InsideOut ..." 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 "use Object::InsideOut ..." 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
"use Object::InsideOut ..." 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 HANDLERSObject::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);
}
}
DIAGNOSTICSObject::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 "local $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.
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();
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:
· Runtime loading of Object::InsideOut classes
· 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
"package 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::InsideOutqw(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
<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 ALSOObject::InsideOut Discussion Forum on CPAN:
http://www.cpanforum.com/dist/Object-InsideOut
<http://www.cpanforum.com/dist/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
ACKNOWLEDGEMENTS
Abigail <perl AT abigail DOT nl> for inside-out objects in general.
Damian Conway <dconway AT cpan DOT org> for Class::Std.
David A. Golden <dagolden AT cpan DOT org> for thread handling for
inside-out objects.
Dan Kubb <dan.kubb-cpan AT autopilotmarketing DOT com> for ":Chained"
methods.
AUTHOR
Jerry D. Hedden, <jdhedden AT cpan DOT org>
COPYRIGHT AND LICENSE
Copyright 2005 - 2009 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
<tsun DOT nt AT gmail DOT com> is available at
<http://perldoc.jp/docs/modules/>.
perl v5.14.1 2011-03-22 Object::InsideOut(3)
