Class::InsideOut(3) User Contributed Perl Documentation Class::InsideOut(3)NAMEClass::InsideOut - a safe, simple inside-out object construction kit
VERSION
This documentation refers to version 1.10
SYNOPSIS
package My::Class;
use Class::InsideOut qw( public readonly private register id );
public name => my %name; # accessor: name()
readonly ssn => my %ssn; # read-only accessor: ssn()
private age => my %age; # no accessor
sub new { register( shift ) }
sub greeting {
my $self = shift;
return "Hello, my name is $name{ id $self }";
}
DESCRIPTION
This is a simple, safe and streamlined toolkit for building inside-out
objects. Unlike most other inside-out object building modules already
on CPAN, this module aims for minimalism and robustness:
· Does not require derived classes to subclass it
· Uses no source filters, attributes or "CHECK" blocks
· Supports any underlying object type including black-box inheritance
· Does not leak memory on object destruction
· Overloading-safe
· Thread-safe for Perl 5.8.5 or better
· "mod_perl" compatible
· Makes no assumption about inheritance or initializer needs
It provides the minimal support necessary for creating safe inside-out
objects and generating flexible accessors.
Additional documentation
· Class::InsideOut::Manual::About -- Guide to the inside-out
technique, the "Class::InsideOut" philosophy, and other inside-out
implementations
· Class::InsideOut::Manual::Advanced -- Advanced topics including
customizing accessors, black-box inheritance, serialization and
thread safety
USAGE
Importing "Class::InsideOut"
"Class::InsideOut" automatically imports several critical methods into
the calling package, including "DESTROY" and support methods for
serializing objects with "Storable". These methods are intimately tied
to correct functioning of inside-out objects and will always be
imported regardless of whether additional functions are requested.
Additional functions may be imported as usual by including them as
arguments to "use". For example:
use Class::InsideOut qw( register public );
public name => my %name;
sub new { register( shift ) }
As a shortcut, "Class::InsideOut" supports two tags for importing sets
of functions:
· ":std" provides "id", "private", "public", "readonly" and
"register"
· ":all" imports all functions (including an optional constructor)
Note: Automatic imports can be bypassed via "require" or by passing an
empty list to "use Class::InsideOut". There is almost no circumstance
in which this is a good idea.
Object properties and accessors
Object properties are declared with the "public", "readonly" and
"private" functions. They must be passed a label and the lexical hash
that will be used to store object properties:
public name => my %name;
readonly ssn => my %ssn;
private age => my %age;
Properties for an object are accessed through an index into the lexical
hash based on the memory address of the object. This memory address
must be obtained via "Scalar::Util::refaddr". The alias "id" may be
imported for brevity.
$name{ refaddr $self } = "James";
$ssn { id $self } = 123456789;
$age { id $self } = 32;
Tip: since "refaddr" and "id" are function calls, it may be efficient
to store the value once at the beginning of a method, particularly if
it is being called repeatedly, e.g. within a loop.
Object properties declared with "public" will have an accessor created
with the same name as the label. If the accessor is passed an
argument, the property will be set to the argument. The accessor
always returns the value of the property.
# Outside the class
$person = My::Class->new;
$person->name( "Larry" );
Object properties declared with "readonly" will have a read-only
accessor created. The accessor will die if passed an argument to set
the property value. The property may be set directly in the hash from
within the class package as usual.
# Inside the class
$ssn { id $person } = 987654321;
# Inside or outside the class
$person->ssn( 123456789 ); # dies
Property accessors may also be hand-written by declaring the property
"private" and writing whatever style of accessor is desired. For
example:
sub age { $age{ id $_[0] } }
sub set_age { $age{ id $_[0] } = $_[1] }
Hand-written accessors will be very slightly faster as generated
accessors hold a reference to the property hash rather than accessing
the property hash directly.
It is also possible to use a package hash instead of a lexical hash to
store object properties:
public name => our %name;
However, this makes private object data accessable outside the class
and incurs a slight performance penalty when accessing the property
hash directly; it is not recommended to do this unless you really need
it for some specialized reason.
Object construction
"Class::InsideOut" provides no default constructor method as there are
many possible ways of constructing an inside-out object. This avoids
constraining users to any particular object initialization or
superclass initialization methodology.
By using the memory address of the object as the index for properties,
any type of reference may be used as the basis for an inside-out object
with "Class::InsideOut".
sub new {
my $class = shift;
my $self = \( my $scalar ); # anonymous scalar
# my $self = {}; # anonymous hash
# my $self = []; # anonymous array
# open my $self, "<", $filename; # filehandle reference
bless $self, $class;
register( $self );
}
However, to ensure that the inside-out object is thread-safe, the
"register" function must be called on the newly created object. The
"register" function may also be called with just the class name for the
common case of blessing an anonymous scalar.
register( $class ); # same as register( bless \(my $s), $class )
As a convenience, "Class::InsideOut" provides an optional "new"
constructor for simple objects. This constructor automatically
initializes the object from key/value pairs passed to the constructor
for all keys matching the name of a property (including otherwise
"private" or "readonly" properties).
A more advanced technique for object construction uses another object,
usually a superclass object, as the object reference. See "black-box
inheritance" in Class::InsideOut::Manual::Advanced.
Object destruction
"Class::InsideOut" automatically exports a special "DESTROY" function.
This function cleans up object property memory for all declared
properties the class and for all "Class::InsideOut" based classes in
the @ISA array to avoid memory leaks or data collision.
Additionally, if a user-supplied "DEMOLISH" function is available in
the same package, it will be called with the object being destroyed as
its argument. "DEMOLISH" can be used for custom destruction behavior
such as updating class properties, closing sockets or closing database
connections. Object properties will not be deleted until after
"DEMOLISH" returns.
# Sample DEMOLISH: Count objects demolished (for whatever reason)
my $objects_destroyed;
sub DEMOLISH {
$objects_destroyed++;
}
"DEMOLISH" will only be called if it exists for an object's actual
class. "DEMOLISH" will not be inherited and "DEMOLISH" will not be
called automatically for any superclasses.
"DEMOLISH" should manage any necessary calls to superclass "DEMOLISH"
methods. As with "new", implementation details are left to the user
based on the user's approach to object inheritance. Depending on how
the inheritance chain is constructed and how "DEMOLISH" is being used,
users may wish to entirely override superclass "DEMOLISH" methods, rely
upon "SUPER::DEMOLISH", or may prefer to walk the entire @ISA tree:
use Class::ISA;
sub DEMOLISH {
my $self = shift;
# class specific demolish actions
# DEMOLISH for all parent classes, but only once
my @parents = Class::ISA::super_path( __PACKAGE__ );
my %called;
for my $p ( @parents ) {
my $demolish = $p->can('DEMOLISH');
$demolish->($self) if not $called{ $demolish }++;
}
}
FUNCTIONS
"id"
$name{ id $object } = "Larry";
This is a shorter, mnemonic alias for "Scalar::Util::refaddr". It
returns the memory address of an object (just like "refaddr") as the
index to access the properties of an inside-out object.
"new"
My::Class->new( name => "Larry", age => 42 );
This simplistic constructor is provided as a convenience and is only
exported on request. When called as a class method, it returns a
blessed anonymous scalar. Arguments will be used to initialize all
matching inside-out class properties in the @ISA tree. The argument
may be a hash or hash reference.
Note: Properties are set directly, not via accessors. This means
"set_hook" functions will not be called. For more robust argument
checking, you will need to implement your own constructor.
"options"
Class::InsideOut::options( \%new_options );
%current_options = Class::InsideOut::options();
The "options" function sets default options for use with all subsquent
property definitions for the calling package. If called without
arguments, this function will return the options currently in effect.
When called with a hash reference of options, these will be joined with
the existing defaults, overriding any options of the same name.
"private"
private weight => my %weight;
private haircolor => my %hair_color, { %options };
This is an alias to "property" that also sets the privacy option to
'private'. It will override default options or options passed as an
argument.
"property"
property name => my %name;
property rank => my %rank, { %options };
Declares an inside-out property. Two arguments are required and a
third is optional. The first is a label for the property; this label
will be used for introspection and generating accessors and thus must
be a valid perl identifier. The second argument must be the lexical
hash that will be used to store data for that property. Note that the
"my" keyword can be included as part of the argument rather than as a
separate statement. The property will be tracked for memory cleanup
during object destruction and for proper thread-safety.
If a third, optional argument is provided, it must be a reference to a
hash of options that will be applied to the property and will override
any default options that have been set.
"public"
public height => my %height;
public age => my %age, { %options };
This is an alias to "property" that also sets the privacy option to
'public'. It will override default options or options passed as an
argument.
"readonly"
readonly ssn => my %ssn;
readonly fingerprint => my %fingerprint, { %options };
This is an alias to "property" that sets the privacy option to 'public'
and adds a "set_hook" option that dies if an attempt is made to use the
accessor to change the property. It will override default options or
options passed as an argument.
"register"
register( bless( $object, $class ) ); # register the object
register( $reference, $class ); # automatic bless
register( $class ); # automatic blessed scalar
Registers objects for thread-safety. This should be called as part of
a constructor on a object blessed into the current package. Returns
the resulting object. When called with only a class name, "register"
will bless an anonymous scalar reference into the given class. When
called with both a reference and a class name, "register" will bless
the reference into the class.
OPTIONS
Options customize how properties are generated. Options may be set as
a default with the "options" function or passed as a hash reference to
"public", "private" or "property".
Valid options include:
"privacy"
property rank => my %rank, { privacy => 'public' };
property serial => my %serial, { privacy => 'private' };
If the privacy option is set to public, an accessor will be created
with the same name as the label. If the accessor is passed an
argument, the property will be set to the argument. The accessor
always returns the value of the property.
"get_hook"
public list => my %list, {
get_hook => sub { @$_ }
};
Defines an accessor hook for when values are retrieved. $_ is locally
aliased to the property value for the object. The return value of the
hook is passed through as the return value of the accessor. See
"Customizing Accessors" in Class::InsideOut::Manual::Advanced for
details.
"set_hook"
public age => my %age, {
set_hook => sub { /^\d+$/ or die "must be an integer" }
};
Defines an accessor hook for when values are set. The hook subroutine
receives the entire argument list. $_ is locally aliased to the first
argument for convenience. The property receives the value of $_. See
"Customizing Accessors" in Class::InsideOut::Manual::Advanced for
details.
SEE ALSO
Programmers seeking a more full-featured approach to inside-out objects
are encouraged to explore Object::InsideOut. Other implementations are
also noted in Class::InsideOut::Manual::About.
KNOWN LIMITATIONS
Requires weak reference support (Perl >= 5.6) and
Scalar::Util::weaken() to avoid memory leaks and to provide thread-
safety.
ROADMAP
Features slated for after the 1.0 release include:
· Adding support for Data::Dump::Streamer serialization hooks
· Adding additional accessor styles (e.g. get_name()/set_name())
· Further documentation revisions and clarification
BUGS
Please report bugs or feature requests using the CPAN Request Tracker:
http://rt.cpan.org/Public/Dist/Display.html?Name=Class-InsideOut
<http://rt.cpan.org/Public/Dist/Display.html?Name=Class-InsideOut>
When submitting a bug or request, please include a test-file or a patch
to an existing test-file that illustrates the bug or desired feature.
AUTHOR
David A. Golden (DAGOLDEN)
COPYRIGHT AND LICENSE
Copyright (c) 2006, 2007 by David A. Golden
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may
obtain a copy of the License at
L<http://www.apache.org/licenses/LICENSE-2.0>
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied. See the License for the specific language governing
permissions and limitations under the License.
perl v5.14.0 2009-08-25 Class::InsideOut(3)
