NAME

Class::Modular -- Modular class generation superclass

SYNOPSIS

     package Foo;

     use base qw(Class::Modular);

     use vars (@METHODS);
     BEGIN{@METHODS=qw(blah)};

     sub blah{
         my $self = shift;
         return 1;
     }

     [...]

     package Bar;

     sub method_that_bar_provides{
          print qq(Hello World!\n);
     }

     sub _methods($$){
          return qw(method_that_bar_provides);
     }

     [...]

     use Foo;

     $foo = new Foo;
     $foo->load('Bar');
     $foo->blah && $foo->method_that_bar_provides;

DESCRIPTION

Class::Modular is a superclass for generating modular classes, where methods can be added into the class from the perspective of the object, rather than the perspective of the class.

That is, you can create a class which has a set of generic common functions. Less generic functions can be included or overridden without modifying the base classes. This allows for code to be more modular, and reduces code duplication.

This module attempts to fill the middle ground between Class::Mutator and true classless OOP, like Class::Classless.

FUNCTIONS

load

     $cm->load('Subclass');
     # or
     $cm->load('Subclass',$options);

Loads the named Subclass into this object if the named Subclass has not been loaded.

If debugging is enabled, will warn about loading already loaded subclasses. Use $cm-is_loaded('Subclass')> to avoid these warnings.

Methods

If the subclass has a _methods function (or at least, UNIVERSAL::can thinks it does), _methods is called to return a LIST of methods that the subclass wishes to handle. The Class::Modular object and the options SCALAR are passed to the _methods function.

If the subclass does not have a _methods function, then the array @{"${subclass}::METHODS"} is used to determine the methods that the subclass will handle.

_init and required submodules

If the subclass has a _init function (or at least, UNIVERSAL::can thinks it does), _init is called right after the module is loaded. The Class::Modular object and the options SCALAR are passed to the _methods function. Typical uses for this call are to load other required submodules.

As this is the most common thing to do in _init, if a subclass doesn't have one, then the array @{"${subclass}::SUB_MODULES"} is used to determine the subclass that need to be loaded:

    for my $module (@{"${subclass}::SUB_MODULES"}) {
         $self->is_loaded($module) || $self->load($module);
    }

is_loaded

     if ($cm->is_loaded('Subclass')) {
           # do something
     }

Tests to see if the named subclass is loaded.

Returns 1 if the subclass has been loaded, 0 otherwise.

override

     $obj->override('methodname', $code_ref)

Allows you to override utility functions that are called internally to provide a different default function. It's superficially similar to _addmethods, which is called by load, but it deals with code references, and requires the method name to be known.

Methods overridden here are _NOT_ overrideable in _addmethods. This may need to be changed.

clone

     my $clone  = $obj->clone

Produces a clone of the object with duplicates of all data and/or new connections as appropriate.

Calls _clone on all loaded subclasses.

Warns if debugging is on for classes which don't have a _clone method. Dies on other errors.

clone uses Safe to allow Storable to deparse code references sanely. Set $Class::Modular::USE_SAFE = 0 to disable this. [Doing this may cause errors from Storable about CODE references.]

can

     $obj->can('METHOD');
     Class::Modular->can('METHOD');

Replaces UNIVERSAL's can method so that handled methods are reported correctly. Calls UNIVERSAL::can in the places where we don't know anything it doesn't.

Returns a coderef to the method if the method is supported, undef otherwise.

isa

     $obj->isa('TYPE');
     Class::Modular->isa('TYPE');

Replaces UNIVERSAL's isa method with one that knows which modules have been loaded into this object. Calls is_loaded with the type passed, then calls UNIVERSAL::isa if the type isn't loaded.

handledby

     $obj->handledby('methodname');
     $obj->handledby('Class::Method::methodname');

Returns the subclass that handles the method methodname.

new

     $obj = Foo::Bar->new(qw(baz quux));

Creates a new Foo::Bar object

Aditional arguments can be passed to this creator, and they are stored in $self->{creation_args} (and $self->{$cm}{creation_args} by _init.

This new function creates an object of Class::Modular, and calls the $self-load(Foo::Bar)>, which will typically do what you want.

If you override this method in your subclasses, you will not be able to use override to override methods defined within those subclasses. This may or may not be a feature. You must also call $self-SUPER::_init(@_)> if you override new.

FUNCTIONS YOU PROBABLY DON'T CARE ABOUT

DESTROY

     undef $foo;

Calls all subclass _destroy methods.

Subclasses need only implement a _destroy method if they have references that need to be uncircularized, or things that should be disconnected or closed.

AUTOLOAD

The AUTOLOAD function is responsible for calling child methods which have been installed into the current Class::Modular handle.

Subclasses that have a new function as well as an AUTOLOAD function must call Class::Modular::AUTOLOAD and set $Class::Modular::AUTOLOAD

     $Class::Modular::AUTOLOAD = $AUTOLOAD;
     goto &Class::Modular::AUTOLOAD;

Failure to do the above will break Class::Modular utterly.

_init

     $self->_init(@args);

Stores the arguments used at new so modules that are loaded later can read them from creation_args

You can also override this method, but if you do so, you should call Class::Modular::_init($self,@_) if you don't set creation_args.

_addmethods

     $self->_addmethods()

Given an array of methods, adds the methods into the _methodhash calling table.

Methods that have previously been overridden by override are _NOT_ overridden again. This may need to be adjusted in load.

BUGS

Because this module works through AUTOLOAD, utilities that use can($object) instead of $object->can() will fail to see routines that are actually there. Params::Validate, an excellent module, is currently one of these offenders.

COPYRIGHT

This module is part of DA, Don Armstrong's Modules, and is released under the terms of the GPL version 2, or any later version. See the file README and COPYING for more information.

Copyright 2003, 2005 by Don Armstrong <don@donarmstrong.com>

cpanm Class::Modular

perl -MCPAN -e shell
install Class::Modular