Linux Certif

Toute la documentation sur la certification Linux LPI

NOCpulse::Object.3pm

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);
         ...
 
 

DESCRIPTION

NOCpulse::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 METHODS

ClassBasename()

         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 METHODS

instVarDefinitions()

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'