.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Class::EHierarchy 3pm"
.TH Class::EHierarchy 3pm "2016-06-29" "perl v5.22.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Class::EHierarchy \- Base class for hierarchally ordered objects
.SH "VERSION"
.IX Header "VERSION"
\&\f(CW$Id:\fR EHierarchy.pm,v 0.93 2013/07/07 00:17:27 acorliss Exp $
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    package TelDirectory;
\&
\&    use Class::EHierarchy qw(:all);
\&    use vars qw(@ISA @_properties @_methods);
\&
\&    @ISA = qw(Class::EHierarchy);
\&    @_properties = (
\&        [ CEH_PRIV | CEH_SCALAR, \*(Aqcounter\*(Aq,  0 ],
\&        [ CEH_PUB | CEH_SCALAR,  \*(Aqfirst\*(Aq,   \*(Aq\*(Aq ],
\&        [ CEH_PUB | CEH_SCALAR,  \*(Aqlast\*(Aq,    \*(Aq\*(Aq ],
\&        [ CEH_PUB | CEH_ARRAY,   \*(Aqtelephone\*(Aq   ]
\&        );
\&    @_methods = (
\&        [ CEH_PRIV,    \*(Aq_incrCounter\*(Aq ],
\&        [ CEH_PUB,     \*(AqaddTel\*(Aq       ]
\&        );
\&
\&    sub _initalize {
\&        my $obj     = shift;
\&        my %args    = @_;
\&        my $rv      = 1;
\&
\&        # Statically defined properties and methods are 
\&        # defined above.  Dynamically generated/defined 
\&        # poperties and methods can be done here.
\&
\&        return $rv;
\&    }
\&
\&    ...
\&
\&    package main;
\&
\&    use TelDirectory;
\&
\&    my $entry = new TelDirectory;
\&
\&    $entry\->property(\*(Aqfirst\*(Aq, \*(AqJohn\*(Aq);
\&    $entry\->property(\*(Aqlast\*(Aq,  \*(AqDoe\*(Aq);
\&    $entry\->push(\*(Aqtelephone\*(Aq, \*(Aq555\-111\-2222\*(Aq, \*(Aq555\-555\*(Aq5555\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBClass::EHierarchy\fR is intended for use as a base class for custom objects,
but objects that need one or more of the following features:
.IP "\(bu" 4
orderly bottom-up destruction of objects
.IP "\(bu" 4
opaque objects
.IP "\(bu" 4
class-based access restrictions for properties and methods
.IP "\(bu" 4
primitive strict property type awareness
.IP "\(bu" 4
alias-based object retrieval
.PP
Each of the above features are described in more depth in the following
subsections:
.SS "\s-1ORDERLY DESTRUCTION\s0"
.IX Subsection "ORDERLY DESTRUCTION"
Objects can \fIadopt\fR other objects which creates a tracked relationship 
within the class itself.  Those child objects can, in turn, adopt objects 
of their own.  The result is a hierarchal tree of objects, with the parent 
being the trunk.
.PP
Perl uses a reference-counting garbage collection system which destroys
objects and data structures as the last reference to it goes out of scope.
This results in an object being destroyed before any internal data structures
or objects referenced internally.  In most cases this works just fine since
many programs really don't care how things are destroyed, just as long as they
are.
.PP
Occasionally, though, we do care.  Take, for instance, a database-backed
application that delays commits to the database until after all changes are
made.  Updates made to a collection of records can be flushed as as the parent
object goes out of scope.  In a regular object framework the parent object
would be released, which could be a problem if it owned the database
connection object.  In this framework, though, the children are pre-emptively
released first, triggering their \s-1DESTROY\s0 methods beforehand, in which the
database commit is made:
.PP
.Vb 6
\&    Database Object
\&        +\-\-> Table1
\&        |       +\-\-> Row1
\&        |       +\-\-> Row2
\&        +\-\-> Table2
\&                +\-\-> Row1
.Ve
.PP
This, in a nutshell, is the primary purpose of this class.
.SS "\s-1OPAQUE OBJECTS\s0"
.IX Subsection "OPAQUE OBJECTS"
Objects based on this class will be opaque objects instead of the traditional
blessed hash references in which the hash elements could be access directly
through dereferencing.  This prevents access to internal data structures 
outside of the published interface.  This does mean, though, that you can't
access your data directly, either.  You must use a provided method to
retrieve that data from the class storage.
.SS "\s-1ACCESS RESTRICTIONS\s0"
.IX Subsection "ACCESS RESTRICTIONS"
A benefit of having an opaque object is that allows for scoping of both
properties and methods.  This provides for the following access restrictions:
.PP
.Vb 4
\&    private         accessible only to members of this object\*(Aqs class
\&    restricted      accessible to members of this object\*(Aqs class  
\&                    and subclasses
\&    public          globally accessible
.Ve
.PP
Attempts to access either from outside the approved scope will cause the code
to croak.  There is an exception, however:  private properties.  This aren't
just protected, they're hidden.  This allows various subclasses to use the
same names for internal properties without fear of name space violations.
.SS "\s-1PROPERTY TYPE AWARENESS\s0"
.IX Subsection "PROPERTY TYPE AWARENESS"
Properties can be explicitly declared to be of certain primitive data types.
This allows some built in validation of values being set.  Known scalar value
types are scalar, code, glob, and reference.
.PP
Properties can also house hashes and arrays.  When this is leveraged it allows
for properties contents to be managed in ways similar to their raw
counterparts.  You can retrieve individual elements, add, set, test for, and
so on.
.SS "\s-1ALIASES\s0"
.IX Subsection "ALIASES"
In a hierarchal system of object ownership the parent objects have strong
references to their children.  This frees you from having to code and track
object references yourself.  Sometimes, however, it's not always convenient or
intuitive to remember which parent owns what objects when you have a
multilevel hierarchy.  Because of that this class implements an alias system
to make retrieval simpler.
.PP
Aliases are unique within each hierarchy or tree.  Consider the following
hierarchy in which every node is an object member:
.PP
.Vb 10
\&  Application
\&     +\-\-> Display
\&     |       +\-\-> Window1
\&     |       |      +\-\-> Widget1
\&     |       |      +\-\-> Widget2
\&     |       |      +\-\-> Widget3
\&     |       +\-\-> Window2
\&     |              +\-\-> Widget1
\&     +\-\-> Database Handle
\&     +\-\-> Network Connections
.Ve
.PP
Giving each node a plain name, where it makes sense, makes it trivial for a
widget to retrieve a reference to the database object to get or update data.
.PP
Aliases can also be search via base names, making it trival to get a list of
windows that may need to be updated in a display.
.SH "SUBROUTINES/METHODS"
.IX Header "SUBROUTINES/METHODS"
Subroutines and constants are provided strictly for use by derived classes 
within their defined methods.  To avoid any confusion all of our exportable 
symbols are *not* exported by default.  You have to specifically import the 
\&\fBall\fR tag set.  Because these subroutines should not be used outside of the 
class they are all preceded by an underscore, like any other private function.
.PP
Methods, on the other hand, are meant for direct and global use.  With the
exception of \fBnew\fR and \fB\s-1DESTROY\s0\fR they should all be safe to override.
.PP
The following subroutines, methods, and/or constants are are orgnanized
according to their functional domain (as outlined above).
.SS "\s-1INSTANTIATION/DESTRUCTION\s0"
.IX Subsection "INSTANTIATION/DESTRUCTION"
All classes based on this class must use the \fInew\fR constructor and \fI\s-1DESTROY\s0\fR
deconstructor provided by this class.  That said, subclasses still have an
opportunity to do work in both phases.
.PP
Before that, however, \fBClass::EHierarchy\fR prepares the base object, defining
and scoping properties and methods automatically based on the presence of
class variables \fI\f(CI@_properties\fI\fR and \fI\f(CI@_methods\fI\fR:
.PP
.Vb 1
\&    package Contact;
\&
\&    use Class::EHierarchy qw(:all);
\&    use vars qw(@ISA @_properties @_methods);
\&
\&    @ISA = qw(Class::EHierarchy);
\&    @_properties = (
\&        [ CEH_PUB | CEH_SCALAR, \*(Aqfirst\*(Aq ],
\&        [ CEH_PUB | CEH_SCALAR, \*(Aqlast\*(Aq ],
\&        [ CEH_PUB | CEH_ARRAY,  \*(Aqtelephone\*(Aq ],
\&        [ CEH_PUB | CEH_SCALAR, \*(Aqemail\*(Aq ],
\&        );
\&    @_methods = (
\&        [ CEH_PUB, \*(Aqfull_name\*(Aq ],
\&        );
\&
\&    sub _initialize {
\&        my $obj = shift;
\&        my $rv  = 1;
\&
\&        ....
\&
\&        return $rv;
\&    }
\&
\&    sub _deconstruct {
\&        my $obj = shift;
\&        my $rv  = 1;
\&
\&        ....
\&
\&        return $rv;
\&    }
\&
\&    sub full_name {
\&        my $obj = shift;
\&
\&        return $obj\->property(\*(Aqfirst\*(Aq) . \*(Aq \*(Aq .
\&               $obj\->property(\*(Aqlast\*(Aq);
\&    }
.Ve
.PP
Both methods and properties are defined by their access scope.  Properties
also add in primitive data types.  The constants used to designate these
attributes are as follows:
.PP
.Vb 5
\&    Scope
\&    \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&    CEH_PRIV        private scope
\&    CEH_RESTR       restricted scope
\&    CEH_PUB         public scope
\&
\&    Type
\&    \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&    CEH_SCALAR      scalar value or reference
\&    CEH_ARRAY       array
\&    CEH_HASH        hash
\&    CEH_CODE        code reference
\&    CEH_GLOB        glob reference
\&    CEH_REF         object reference
\&
\&    Flag
\&    \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&    CEH_NO_UNDEF    No undef values are allowed to be 
\&                    assigned to the property
.Ve
.PP
You'll note that both \fI\f(CI@_properties\fI\fR and \fI\f(CI@_methods\fI\fR are arrays of arrays,
which each subarray containing the elements for each property or method.  The
first element is always the attributes and the second the name of the property
or method.  In the case of the former a third argument is also allowed:  a
default value for the property:
.PP
.Vb 6
\&  @_properties = (
\&        [ CEH_PUB | CEH_SCALAR, \*(Aqfirst\*(Aq,     \*(AqJohn\*(Aq ],
\&        [ CEH_PUB | CEH_SCALAR, \*(Aqlast\*(Aq,      \*(AqDoe\*(Aq ],
\&        [ CEH_PUB | CEH_ARRAY,  \*(Aqtelephone\*(Aq, 
\&            [ qw(555\-555\-1212 555\-555\-5555) ] ],
\&    );
.Ve
.PP
Properties lacking a data type attribute default to \fB\s-1CEH_SCALAR\s0\fR.  Likewise,
scope defaults to \fB\s-1CEH_PUB\s0\fR.  Public methods can be omitted from \fI\f(CI@_methods\fI\fR 
since they will be assumed to be public.
.PP
\fInew\fR
.IX Subsection "new"
.PP
.Vb 1
\&    $obj = Class::Foo\->new(@args);
.Ve
.PP
This method must not be overridden in any subclass, but be used as-is.  That
said, subclasses still have complete control over whether this method call
succeeds via the \fB_initialize\fR method, which all subclasses must provide
themselves.
.PP
When the object contsructor is called an object is instantiated, then
\&\fB_initialize\fR is called with all of the \fBnew\fR arguments passed on unaltered.
The \fB_initialize\fR method is responsible for an internal initialization
necessary as well as any validation.  It must return a boolean value which
determines whether a valid object reference is returned by the \fBnew\fR method,
or undef.
.PP
\&\fB\s-1NOTE:\s0\fR all superclasses based on Class::EHierarchy containing a 
\&\fB_initialize\fR method will also be called, all prior to the current subclass' 
method.
.PP
\fI_initialize\fR
.IX Subsection "_initialize"
.PP
.Vb 4
\&    sub _initialize {
\&        my $obj  = shift;
\&        my %args = @_;       # or @args = $_;
\&        my $rv   = 1;
\&
\&        # Random initialization stuff here
\&
\&        return $rv;
\&    }
.Ve
.PP
Once the basic object has been constructed it calls the \fI_initialize\fR method,
giving it a complete set of the arguments the constructor was called with.
The form of those arguments, whether as an associative array or simple array,
is up to the coder.
.PP
You can do whatever you want in this method, including creating and adopting
child objects.  You can also dynamically generate properties and methods using
the \fI_declProp\fR and \fI_declMethod\fR class functions.  Both are documented below.
.PP
This method must return a boolean value.  A false return value will cause the
constructor to tear everything back down and return \fBundef\fR to the caller.
.PP
\fI_declProp\fR
.IX Subsection "_declProp"
.PP
.Vb 1
\&    $rv = _declProp($obj, SCOPE | TYPE | FLAG, @propNames);
.Ve
.PP
This function is used to create named properties while declaring they access 
scope and type.
.PP
Constants describing property attributes are \s-1OR\s0'ed together, and only one
scope and one type from each list should be used at a time.  Using multiple
types or scopes to describe any particular property will make it essentially
inaccessible.
.PP
Type, if omitted, defaults to \fI\s-1CEH_SCALAR\s0\fR,  Scope defaults to \fI\s-1CEH_PUB\s0\fR.
.PP
\&\fB\s-1NOTE:\s0\fR  \fI\s-1CEH_NO_UNDEF\s0\fR only applies to psuedo-scalar types like proper
scalars, references, etc.  This has no effect on array members or hash values.
.PP
\fI_declMethod\fR
.IX Subsection "_declMethod"
.PP
.Vb 1
\&    $rv = _declMethod($attr, @methods);
.Ve
.PP
This function is is used to create wrappers for those functions whose access 
you want to restrict.  It works along the same lines as properties and uses 
the same scoping constants for the attribute.
.PP
Only methods defined within the subclass can have scoping declared.  You
cannot call this method for inherited methods.
.PP
\&\fB\s-1NOTE:\s0\fR Since scoping is applied to the class symbol table (\fBnot\fR on a 
per object basis) any given method can only be scoped once.  That means you 
can't do crazy things like make public methods private, or vice-versa.
.PP
\fI\s-1DESTROY\s0\fR
.IX Subsection "DESTROY"
.PP
A \fB\s-1DESTROY\s0\fR method is provided by this class and must not be overridden by
any subclass.  It is this method that provides the ordered termination
property of hierarchal objects.  Any code you wish to be executed during this
phase can be put into a \fB_deconstruct\fR method in your subclass.  If it's
available it will be executed after any children have been released.
.PP
\fI_deconstruct\fR
.IX Subsection "_deconstruct"
.PP
.Vb 3
\&    sub _deconstruct {
\&        my $obj = shift;
\&        my $rv  = 1;
\&
\&        # Do random cleanup stuff here
\&
\&        return $rv;
\&    }
.Ve
.PP
This method is optional, but if needed must be provided by the subclass.  It
will be called during the \fB\s-1DESTROY\s0\fR phase of the object.
.SS "\s-1ORDERLY DESTRUCTION\s0"
.IX Subsection "ORDERLY DESTRUCTION"
In order for objects to be destroyed from the bottom up it is important to
track the hierarchal relationship between them.  This class uses a familial
parent/child paradigm for doing so.
.PP
In short, objects can \fIadopt\fR and \fIdisown\fR other objects.  Adopted objects
become children of the parent object.  Any object being destroyed preemptively
triggers deconstruction routines on all of its children before cleaning up
itself.  This ensures that any child needing parental resources for final
commits, etc., has those available.
.PP
Additional methods are also present to make it easier for objects to interact
with their immediate family of objects.  Those are documented in this section.
More powerful methods also exist as part of the alias system and are
documented in their own section.
.PP
\fIadopt\fR
.IX Subsection "adopt"
.PP
.Vb 1
\&    $rv = $obj\->adopt($cobj1, $cobj2);
.Ve
.PP
This method attempts to adopt the passed objects as children.  It returns a
boolean value which is true only if all objects were successfully adopted.
Only subclasses for Class::EHierarchy can be adopted.  Any object that
isn't based on this class will cause this method to return a false value.
.PP
\fIdisown\fR
.IX Subsection "disown"
.PP
.Vb 1
\&    $rv = $obj\->disown($cobj1, $cobj2);
.Ve
.PP
This method attempts to disown all the passed objects as children.  It returns
a boolean value based on its success in doing so.  Asking it to disown an
object it had never adopted in the first place will be silently ignored and
still return true.
.PP
Disowning objects is a prerequisite for Perl's garbage collection to work and
release those objects completely from memory.  The \fB\s-1DESTROY\s0\fR method provided
by this class automatically does this for parent objects going out of scope.
You may still need to do this explicitly if your parent object manages objects
which may need to be released well prior to any garbage collection on the
parent.
.PP
\fIparent\fR
.IX Subsection "parent"
.PP
.Vb 1
\&    $parent = $obj\->parent;
.Ve
.PP
This method returns a reference to this object's parent object, or undef if it
has no parent.
.PP
\fIchildren\fR
.IX Subsection "children"
.PP
.Vb 1
\&    @crefs = $obj\->children;
.Ve
.PP
This method returns an array of object references to every object that was
adopted by the current object.
.PP
\fIdescendants\fR
.IX Subsection "descendants"
.PP
.Vb 1
\&    @descendants = $obj\->descendants;
.Ve
.PP
This method returns an array of object references to every object descended
from the current object.
.PP
\fIsiblings\fR
.IX Subsection "siblings"
.PP
.Vb 1
\&    @crefs = $obj\->siblings;
.Ve
.PP
This method returns an array of object references to every object that shares
the same parent as the current object.
.PP
\fIroot\fR
.IX Subsection "root"
.PP
.Vb 1
\&    $root = $obj\->root;
.Ve
.PP
This method returns a reference to the root object in this object's ancestral
tree.  In other words, the senior most parent in the current hierarchy.
.SS "\s-1OPAQUE OBJECTS\s0"
.IX Subsection "OPAQUE OBJECTS"
Opaque objects can't access their own data directly, and so must use methods
to access them.  There is one principle method for doing so, but note that in
a later section a whole suite of convenience functions also exist to make hash
and array property access easier.
.PP
\fIproperty\fR
.IX Subsection "property"
.PP
.Vb 6
\&    $val = $obj\->property(\*(AqFooScalar\*(Aq);
\&    @val = $obj\->property(\*(AqFooArray\*(Aq);
\&    %val = $obj\->property(\*(AqFooHash\*(Aq);
\&    $rv  = $obj\->property(\*(AqFooScalar\*(Aq, \*(Aqrandom text or reference\*(Aq);
\&    $rv  = $obj\->property(\*(AqFooArray\*(Aq, @foo);
\&    $rv  = $obj\->property(\*(AqFooHash\*(Aq,  %foo);
.Ve
.PP
This method provides a generic property accessor that abides by the scoping
attributes given by \fB_declProp\fR.  This means that basic reference types are
checked for during assignment, as well as flags like \fB\s-1CEH_NO_UNDEF\s0\fR.
.PP
A boolean value is returned on attempts to set values.
.PP
Any attempt to access a nonexistent property will cause the code to croak.
.PP
\&\fB\s-1NOTE:\s0\fR Given that the presence of additional arguments after the property
name sets this method into 'write' mode, there is obviously no way to use this
to empty a hash or array property.  For that please see the purge method 
below.
.PP
\fIpropertyNames\fR
.IX Subsection "propertyNames"
.PP
.Vb 1
\&    @properties = $obj\->propertyNames;
.Ve
.PP
This method returns a list of all registered properties for the current
object.  Property names will be filtered appropriately by the caller's 
context.
.SS "\s-1ACCESS RESTRICTIONS\s0"
.IX Subsection "ACCESS RESTRICTIONS"
This section is actually covered as part of \*(L"\s-1DESTRUCTION\*(R"\s0 in \s-1INSTANTIATION\s0
above.
.SS "\s-1PROPERTY TYPE AWARENESS\s0"
.IX Subsection "PROPERTY TYPE AWARENESS"
Properties are validated automatically on set attempts for the various scalar
types (code, glob, reference, scalar value), as well as arrays and hashes.
Working through a single accessor method for individual array or hash
elements, however, can be very inconvenient.  For that reason many common
array/hash functions have been implemented as methods.
.PP
\fIpush\fR
.IX Subsection "push"
.PP
.Vb 1
\&    $rv = $obj\->push($prop, @values);
.Ve
.PP
This method pushes additional elements onto the specified array property.
Calling this method on any non-array property will cause the program to croak.
It returns the return value from the \fBpush\fR function.
.PP
\fIpop\fR
.IX Subsection "pop"
.PP
.Vb 1
\&    $rv = $obj\->pop($prop);
.Ve
.PP
This method pops an element off of the specified array property.  Calling 
this method on any non-array property will cause the program to croak.  It 
returns the return value from the \fBpop\fR function.
.PP
\fIunshift\fR
.IX Subsection "unshift"
.PP
.Vb 1
\&    $rv = $obj\->unshift($prop, @values);
.Ve
.PP
This method unshifts additional elements onto the specified array property.
Calling this method on any non-array property will cause the program to croak.
It returns the return value from the \fBunshift\fR operation.
.PP
\fIshift\fR
.IX Subsection "shift"
.PP
.Vb 1
\&    $rv = $obj\->shift($prop);
.Ve
.PP
This method shifts an element off of the specified array property.  Calling 
this method on any non-array property will cause the program to croak.  It 
returns the return value from the \fBshift\fR operation.
.PP
\fIexists\fR
.IX Subsection "exists"
.PP
.Vb 1
\&    $rv = $obj\->exists($prop, $key);
.Ve
.PP
This method checks for the existence of the specified key in the hash
property.  Calling this method on any non-hash property will cause the program
to croack.  It returns the return value from the \fBexists\fR function.
.PP
\fIkeys\fR
.IX Subsection "keys"
.PP
.Vb 1
\&    @keys = $obj\->keys($prop);
.Ve
.PP
This method returns a list of keys from the specified hash property.  Calling
this method on any non-hash property will cause the program to croak.  It
returns the return value from the \fBkeys\fR function.
.PP
\fIstore\fR
.IX Subsection "store"
.PP
.Vb 2
\&    $obj\->add($prop, foo => bar);
\&    $obj\->add($prop, 4 => foo, 5 => bar);
.Ve
.PP
This method is a unified method for storing elements in both hashes and 
arrays.  Hashes elements are simply key/value pairs, while array elements 
are provided as ordinal index/value pairs.
.PP
\fIretrieve\fR
.IX Subsection "retrieve"
.PP
.Vb 2
\&    @values = $obj\->retrieve($hash, qw(foo bar) );
\&    @values = $obj\->retrieve($array, 3 .. 5 );
.Ve
.PP
This method is a unified method for retrieving specific element(s) from both
hashes and arrays.  Hash values are retrieved in the order of the specified
keys, while array elements are retrieved in the order of the specified ordinal
indexes.
.PP
\fIremove\fR
.IX Subsection "remove"
.PP
.Vb 2
\&    $obj\->remove($prop, @keys);
\&    $obj\->remove($prop, 5, 8 .. 10);
.Ve
.PP
This method is a unified method for removing specific elements from both
hashes and arrays.  A list of keys is needed for hash elements, a list of
ordinal indexes is needed for arrays.
.PP
\&\fB\s-1NOTE:\s0\fR In the case of arrays please note that an element removed in the
middle of an array does cause the following elements to be shifted
accordingly.  This method is really only useful for removing a few elements at
a time from an array.  Using it for large swaths of elements will likely prove
it to be poorly performing.  You're better of retrieving the entire array
yourself via the \fBproperty\fR method, splicing what you need, and calling
\&\fBproperty\fR again to set the new array contents.
.PP
\fIpurge\fR
.IX Subsection "purge"
.PP
.Vb 1
\&    $obj\->purge($prop);
.Ve
.PP
This is a unified method for purging the contents of both array and hash
properties.
.SS "\s-1ALIASES\s0"
.IX Subsection "ALIASES"
\fIalias\fR
.IX Subsection "alias"
.PP
.Vb 2
\&    $rv = $obj\->alias($new_alias);
\&    $alias = $obj\->alias;
.Ve
.PP
This method gets/sets the alias for the object.  Gets always return a string,
while sets return a boolean value.  This can be false if the proposed alias is
already in use by another object in its hierarchy.
.PP
\fIrelative\fR
.IX Subsection "relative"
.PP
.Vb 1
\&  $oref = $obj\->relative($name);
.Ve
.PP
This method retrieves the object known under the passed alias.
.PP
\fIrelatives\fR
.IX Subsection "relatives"
.PP
.Vb 1
\&  @orefs = $obj\->relatives($name);
.Ve
.PP
This method retrieves a list of all objects with aliases beginning with the
passed name.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
None.
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
As noted in the \s-1CREDIT\s0 section below portions of the concept and
implementation of opaque objects were taken from Damian Conway's module
\&\fIClass::Std\fR\|(3).  I have chosen to deviate from his implementation in a 
few key areas, and any or all of them might be considered bugs and/or 
limitations.
.PP
Damian relies on an \fIident\fR function in his module to provide each module
with a unique identifier.  Unfortunately, when retrieving internal data
structures he wants you to use them for each and every retrieval.  While
effective, this exercises the stack a bit more and provides a performance
penalty.
.PP
To avoid that penalty I chose to store the \s-1ID\s0 in the anonymous
scalar we referenced as part of object instantiation.  While in theory this
could be overwritten and wreak havoc in the class data structures I think the
performance benefits outweigh it.  I am hedging that most of us won't
accidentally dereference our object reference and overwrite it.
.PP
Another benefit of storing the \s-1ID\s0 directly is that the code you'll write based
on this class looks a lot more like traditional Perl \s-1OO. \s0 If you're a devout
Damian disciple that's probably not a benefit, but his '\fI\f(CI$attr_foo\fI{ident
\&\f(CI$self\fI}\fR' notation really rubs me the wrong way.
.PP
Another performance concern I had with Class::Std was the heavy reliance on
internal hashes.  This penalizes you on both memory and performance
utilization.  So, I changed my internal \fI_ident\fR function to be based purely
on an ordinal index value, which allowed me to use arrays to store all of the
applicable class data.
.PP
End sum, this module gives you the hierarchal qualities I needed along with
some of the opaque object benefits of \fIClass::Std\fR\|(3), but in a manner 
that possibly interferes less with one's natural style of coding while being
generally more efficient and system friendly.
.SH "CREDIT"
.IX Header "CREDIT"
The notion and portions of the implementation of opaque objects were lifted
from Damian Conway's \fIClass::Std\fR\|(3) module.  Conway has a multitude of great
ideas, and I'm grateful that he shares so much with the community.
.SH "AUTHOR"
.IX Header "AUTHOR"
Arthur Corliss (corliss@digitalmages.com)
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
This software is licensed under the same terms as Perl, itself. 
Please see http://dev.perl.org/licenses/ for more information.
.PP
(c) 2009, Arthur Corliss (corliss@digitalmages.com)