Object(3) User Contributed Perl Documentation Object(3)DIAGNOSTICS
none
AUTHOR
David A. Parker, dparker@nocpulse.com
SEE ALSO
FreezeThaw, Config::IniFiles, perlobj, perltoot
NAME
NOCpulse:: Object - an abstract PERL class that tries and fails to
cover up the ugliness that is OO in Perl, amongst other things.
SYNOPSIS
package MyClass;
use NOCpulse::Object;
@ISA qw(NOCpulse::Object);
...
DESCRIPTIONNOCpulse::Object is an attempt to simplify the task of building class
hierarchies under Perl. It has a few "extras" that make writing
applications a bit easier as well. Specifically, NOCpulse::Object...
...defines a protocol for instance creation
...defines a protocol for instance variable creation
...defines a protocol for accessing instance variables
...defines a protocol for "dumping" the contents of an object
...defines a protocol for "Class Instance" variables
...wraps the FreezeThaw mechanism to help facilitate very primitive persistence
...provides global class-side access to a user-specified .INI file a la Config::IniFiles
REQUIRES
Perl 5.004, Carp, Config::IniFiles, FreezeThaw
EXPORTS
nothing
MODULE VARIABLES
$config - holds an Config::IniFiles instance if one was created with
SystemIni() $DEBUGOBJECT - holds the default debug instance
CLASS VARIABLES
$classvars - holds hashes of "class instance" variables
MODULE METHODS
SystemIni($inifile)
This method accepts the name of an .ini file (a la
Config::IniFiles) and initializes the module $config variable with
an instance of Config::IniFiles based on that file. Note that this
is a global change - it applies to all subclasses and their
instances for the execution of the current program.
CLASS METHODSClassBasename()
Class or object method to return just the last part of a
PERL class name (i.e. gets rid of leading path parts (e.g. Something::Basename)
Config()
Returns a pointer to the Config::IniFiles instance that was created
when SystemIni() was called.
ConfigValue($name[,$item])
Retrieves the value of the item $name in the section ref($class) of
the .ini file specified when SystemIni() was called. This is
analogous to putting your class variables in an .ini file (and is
very handy).
This method includes a mechanism for dealing with individual per-
class .ini files as well as follows:
* you must include an entry in the SystemIni (above) within the
section
for this class called "ini" (e.g. ini=MyOther.ini).
* when you call ConfigValue, you must pass both a section name and
an item
name ($item) as opposed to just an item name.
If you do these things, an Config::IniFiles instance will be
created and stored as a class instance variable for the class in
question whose name is "config", and this method will defer any
section,item requests to that instance rather than to the instance
created for the file specified with SystemIni.
getClassInstVar($name)
Returns the value of the "class instance" variable whose name is
$name (if any). Walks up the inheritance tree to find the value in
question.
getClassVar($name)
Returns the value of the class variable whose name is $name (if
any).
setClassVar($name,$value)
Sets the value of the class variable whose name is $name to the
value $value. You can retrieve the value of $name via either
getClassVar or getClassInstVar (see above).
setDebugObject(<NOCpulse::Debug instance>)
Set the debug object for the entity in question. NOTE that how
this is called has tremendous bearing on what it does. If you call
it from the perspective of an instance, a private debug instance
will be stored for the instance in question. If you call it from
the perspective of a class, a class variable will be stored which
will be retrieved via the class instance variable mechanism
(meaning that 'inheritance' will occur).
defaultDebugObject()
Returns the default debug object. You can override this. By
default it returns an instance that was built when the
NOCpulse::Object module was loaded. The module in question will
have a single level 1 literal stream in it.
debugObject()
Returns the debug object (if any) for the entity in question. This
can be called from either a class or an instance perspective. If
called in an instance perspective, a check is performed to see if
the instance in question has its own debug object (and returns it
if true). Otherwise or if the calling context is from that of a
class, attempts to retrieve a class instance version of a debug
object (see setDebugObject and getClassInstVar). Failing all of
that it returns defaultDebugObject().
dprint(<$level>,<@msgs>);
Prints @msgs via $self->debugObject (regardless of whether $self is
an instance or a class) at level $level.
new()
Creates a new instance of the class, ensuring that all instance
variables are built via the instVarDefinitions() method (below).
newInitialized(@parameters)
Creates a new instance of the class via a call to new(), then calls
its initialize() method, passing anything that you passed as a
parameter on to it.
Your override must return whatever you want the result of the call
to the constructor to be - THIS IS VERY IMPORTANT!! Default
behavior is to return the instance, and usually that is what you
will want to do as well
fromStoreString()
Re-creates an instance of an arbitrary class from a string created
by the storeString() method. Uses the FreezeThaw thaw() method.
INSTANCE METHODSinstVarDefinitions()
Subclasses that wish to define instance variables should override
this method. The override implementation should contain a call to
$self->SUPER::instVarDefinitions followed by one or more calls to
$self->addInstVar().
NOTE: it is possible to bypass this step and make calls to
addInstVar() or even just make calls to set_xxx or set() methods
(described below) in an ad-hoc fashion. The reasoning behind the
instVarDefinitions() mechanism is that explicit definitions of
instance variables adds substantially to code clarity.
addInstVar($name[,$value])
Defines an instance variable for the instance whose name is $name
and whose (optional) value is $value. Variables defined in this
manner can be accessed via the get_ and set_ methods that get
"AUTOLOADed" as described below.
initialize(@parameters)
Subclasses who wish to have an initialization sequence beyond what
happens in instVarDefinitions() should override this. This method
will recieve any parameters that might have been passed to
ref($self)->newInitialized(), so your override can use that
information as necessary. Your override should return whatever you
want the result of the constructor call to be if you're calling
this via newInitialized()!! Usually you'll want this to be the
instance, which is what the default behavior is here
printString()
Returns a string that expresses the contents of the object. This
method does a dump of every instance variable in a given instance,
and and in addition will descend into any other classes that it
finds along the way. The abstract implementation is useful as a
diagnostic. Smalltalk fans may wish to override this in class-
specific ways.
asString()
Calls printString() (above)
storeString()
Returns a "frozen" version of the current instance in the form of a
string via the FreezeThaw freeze() method. The string can be
stored in a file for later "thawing" via a call to
NOCpulse::Object->fromStoreString() (above).
NOTE: No clamping is performed - if you have self-referential
instances you will get EVERYTHING when you call this. If you are
planning on doing object persistence with this mechanism, do some
sort of hash table lookup reference instead.
configValue($name[,$item])
Calls the class side ConfigValue() method (above) and returns its
result.
has($name)
Returns true if an instance variable called $name exists for the
instance in question. Calls to this method can be constructed as
"$self->has_name()"; see AUTOLOAD below
get($name)
Returns the value of the instance variable called $name. Calls to
this method can be constructed as "$self->get_name()" see AUTOLOAD
below
set($name,$value)
Sets the value of the instance variable called $name to $value.
Calls to this method can be constructed as
"$self->set_name($value)" see AUTOLOAD below
delete($name)
Removes the the instance variable called $name from the instance in
question. Calls to this method can be constructed as
"$self->delete_name()" see AUTOLOAD below
doesNotUnderstand($class,$message,@params)
Called by AUTOLOAD (see below) if the message sent to the object
cannot be resolved. This method gives you a chance to catch these
things and provide AUTOLOAD like behavior, but with inheritance.
The fallthrough behavior is to croak with an informative message.
One of the really nice things about NOCpulse::Object is that you
will not have to worry about goofy hash dereferencing to get at
your variables. NOCpulse::Object uses the doesNotUnderstand
mechanism to generate has_, get_, set_, and delete_ methods for
you.
As an example, if you defined instance variables thusly...
sub instVarDefinitions
{
my $self = shift();
$self->addInstVar('foo');
$self->addInstVar('bar');
}
..., your instance will (from that point on) behave as if a number
of accessor methods had been defined for it as well, so...
my $object = MyClass->newInitialized;
$object->set_foo('a value');
$object->set_bar('another value');
print $object->get_foo." ".$object->get_bar."\n";
...will work nicely.
POD ERRORS
Hey! The above document had some coding errors, which are explained
below:
Around line 545:
You forgot a '=back' before '=head1'
Around line 686:
You forgot a '=back' before '=head1'
perl v5.14.1 2010-08-26 Object(3)
