++ed by:
JONASBN

1 PAUSE user
3 non-PAUSE users.

David Golden

NAME

Class::InsideOut - a safe, simple inside-out object construction kit

VERSION

This documentation refers to version 1.06

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 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

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.

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.

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.

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

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)

dagolden@cpan.org

http://dagolden.com/

COPYRIGHT AND LICENSE

Copyright (c) 2006, 2007 by David A. Golden

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.