NAME
Class::MakeMethods - Generate common types of methods
SYNOPSIS
# Generates methods for your object when you "use" it.
package MyObject;
use Class::MakeMethods::Standard::Hash (
'new' => 'new',
'scalar' => 'foo',
'scalar' => 'bar',
);
# The resulting methods can be called exactly as normal ones
my $obj = MyObject->new( foo => "Foozle", bar => "Bozzle" );
print $obj->foo();
$obj->bar("Barbados");
DESCRIPTION
The Class::MakeMethods framework allows Perl class developers to quickly
define common types of methods. When a module "use"s a subclass of
Class::MakeMethods, it can select from the supported method types, and
specify a name for each method desired. The methods are dynamically
generated and installed in the calling package.
Construction of the individual methods is handled by subclasses. This
delegation approach allows for a wide variety of method-generation
techniques to be supported, each by a different subclass. Subclasses can
also be added to provide support for new types of methods.
Over a dozen subclasses are available, including implementations of a
variety of different method-generation techniques. Each subclass
generates several types of methods, with some supporting their own
open-eneded extension syntax, for hundreds of possible combinations of
method types.
MOTIVATION
"Make easy things easier."
This module addresses a problem encountered in object-oriented
development wherein numerous methods are defined which differ only
slightly from each other.
A common example is accessor methods for hash-based object attributes,
which allow you to get and set the value $self->{'foo'} by calling a
method $self->foo().
These methods are generally quite simple, requiring only a couple of
lines of Perl, but in sufficient bulk, they can cut down on the
maintainability of large classes.
Class::MakeMethods allows you to simply declare those methods to be of a
predefined type, and it generates and installs the necessary methods in
your package at compile-time.
A Contrived Example
Object-oriented Perl code is widespread -- you've probably seen code
like the below a million times:
my $obj = MyStruct->new( foo=>"Foozle", bar=>"Bozzle" );
if ( $obj->foo() =~ /foo/i ) {
$obj->bar("Barbados!");
}
print $obj->summary();
(If this doesn't look familiar, take a moment to read the perlboot
manpage and you'll soon learn more than's good for you.)
Typically, this involves creating numerous subroutines that follow a
handful of common patterns, like constructor methods and accessor
methods. The classic example is accessor methods for hash-based object
attributes, which allow you to get and set the value *self*->{*foo*} by
calling a method *self*->*foo*(). These methods are generally quite
simple, requiring only a couple of lines of Perl, but in sufficient
bulk, they can cut down on the maintainability of large classes.
Here's a possible implementation for the class whose interface is shown
above:
package MyStruct;
sub new {
my $callee = shift;
my $self = bless { @_ }, (ref $callee || $callee);
return $self;
}
sub foo {
my $self = shift;
if ( scalar @_ ) {
$self->{'foo'} = shift();
} else {
$self->{'foo'}
}
}
sub bar {
my $self = shift;
if ( scalar @_ ) {
$self->{'bar'} = shift();
} else {
$self->{'bar'}
}
}
sub summary {
my $self = shift;
join(', ', map { "\u$_: " . $self->$_() } qw( foo bar ) )
}
Note in particular that the foo and bar methods are almost identical,
and that the new method could be used for almost any class; this is
precisely the type of redundancy Class::MakeMethods addresses.
Class::MakeMethods allows you to simply declare those methods to be of a
predefined type, and it generates and installs the necessary methods in
your package at compile-time.
Here's the equivalent declaration for that same basic class:
package MyStruct;
use Class::MakeMethods::Standard::Hash (
'new' => 'new',
'scalar' => 'foo',
'scalar' => 'bar',
);
sub summary {
my $self = shift;
join(', ', map { "\u$_: " . $self->$_() } qw( foo bar ) )
}
This is the basic purpose of Class::MakeMethods: The "boring" pieces of
code have been replaced by succinct declarations, placing the focus on
the "unique" or "custom" pieces.
GETTING STARTED
Once you've grasped the basic idea -- simplifying repetitive code by
generating and installing methods on demand -- the remaining complexity
basically boils down to figuring out which arguments to pass to generate
the specific methods you want.
Unfortunately, this is not a trivial task, as there are dozens of
different types of methods that can be generated, each with a variety of
options, and several alternative ways to write each method declaration.
You may prefer to start by just finding a few examples that you can
modify to accomplish your immediate needs, and defer investigating all
of the extras until you're ready to take a closer look.
Other Documentation
The remainder of this document focuses on points of usage that are
common across all subclasses, and describes how to create your own
subclasses.
If this is your first exposure to Class::MakeMethods, you may want to
skim over the rest of this document, then take a look at the examples
and one or two of the method-generating subclasses to get a more
concrete sense of typical usage, before returning to the details
presented below.
* A collection of sample uses is available in the
Class::MakeMethods::Docs::Examples manpage.
* Some of the most common object and class methods are available from
the Class::MakeMethods::Standard::Hash manpage, the
Class::MakeMethods::Standard::Global manpage and the
Class::MakeMethods::Standard::Universal manpage.
* If you need a bit more flexibility, see the
Class::MakeMethods::Composite manpage for method generators which
offer more customization options, including pre- and post-method
callback hooks.
* For the largest collection of methods and options, see the
Class::MakeMethods::Template manpage, which uses a system of dynamic
code generation to allow endless variation.
* A listing of available method types from each of the different
subclasses is provided in the Class::MakeMethods::Docs::Catalog
manpage.
CLASS ARCHITECTURE
Because there are so many common types of methods one might wish to
generate, the Class::MakeMethods framework provides an extensible system
based on subclasses.
When your code requests a method, the MakeMethods base class performs
some standard argument parsing, delegates the construction of the actual
method to the appropriate subclass, and then installs whatever method
the subclass returns.
The MakeMethods Base Class
The Class::MakeMethods package defines a superclass for
method-generating modules, and provides a calling convention, on-the-fly
subclass loading, and subroutine installation that will be shared by all
subclasses.
The superclass also lets you generate several different types of methods
in a single call, and will automatically load named subclasses the first
time they're used.
The MakeMethods Subclasses
The type of method that gets created is controlled by the specific
subclass and generator function you request. For example,
"Class::MakeMethods::Standard::Hash" has a generator function
"scalar()", which is responsible for generating simple scalar-accessor
methods for blessed-hash objects.
Each generator function specified is passed the arguments specifying the
method the caller wants, and produces a closure or eval-able sequence of
Perl statements representing the ready-to-install function.
Included Subclasses
Because each subclass defines its own set of method types and
customization options, a key step is to find your way to the appropriate
subclasses.
Standard (See the Class::MakeMethods::Standard manpage.)
Generally you will want to begin with the Standard::Hash subclass,
to create constructor and accessor methods for working with
blessed-hash objects (or you might choose the Standard::Array
subclass instead). The Standard::Global subclass provides methods
for class data shared by all objects in a class.
Each Standard method declaration can optionally include a hash of
associated parameters, which allows you to tweak some of the
characteristics of the methods. Subroutines are bound as closures to
a hash of each method's name and parameters. Standard::Hash and
Standard::Array provide object constructor and accessors. The
Standard::Global provides for static data shared by all instances
and subclasses, while the data for Standard::Inheritable methods
trace the inheritance tree to find values, and can be overriden for
any subclass or instance.
Composite (See the Class::MakeMethods::Composite manpage.)
For additional customization options, check out the Composite
subclasses, which allow you to select from a more varied set of
implementations and which allow you to adjust any specific method by
adding your own code-refs to be run before or after it.
Subroutines are bound as closures to a hash of each method's name
and optional additional data, and to one or more subroutine
references which make up the composite behavior of the method.
Composite::Hash and Composite::Array provide object constructor and
accessors. The Composite::Global provides for static data shared by
all instances and subclasses, while the data for
Composite::Inheritable methods can be overriden for any subclass or
instance.
Template (See the Class::MakeMethods::Template manpage.)
The Template subclasses provide an open-ended structure for objects
that assemble Perl code on the fly into cachable closure-generating
subroutines; if the method you need isn't included, you can extend
existing methods by re-defining just the snippet of code that's
different.
Class::MakeMethods::Template extends MakeMethods with a text
templating system that can assemble Perl code fragments into a
desired subroutine. The code for generated methods is eval'd once
for each type, and then repeatedly bound as closures to
method-specific data for better performance.
Templates for dozens of types of constructor, accessor, and mutator
methods are included, ranging from from the mundane (constructors
and value accessors for hash and array slots) to the esoteric
(inheritable class data and "flyweight" accessors with external
indexes).
Basic (See the Class::MakeMethods::Basic manpage.)
The Basic subclasses provide stripped down method generators with no
configurable options, for minimal functionality (and minimum
overhead).
Subroutines are bound as closures to the name of each method.
Basic::Hash and Basic::Array provide simple object constructors and
accessors. Basic::Global provides basic global-data accessors.
Emulators (See the Class::MakeMethods::Emulator manpage.)
In several cases, Class::MakeMethods provides functionality closely
equivalent to that of an existing module, and it is simple to map
the existing module's interface to that of Class::MakeMethods.
Emulators are included for Class::MethodMaker,
Class::Accessor::Fast, Class::Data::Inheritable, Class::Singleton,
and Class::Struct, each of which passes the original module's test
suite, usually requiring only that the name of the module be
changed.
Extending
Class::MakeMethods can be extended by creating subclasses that
define additional method-generation functions. Callers can then
specify the name of your subclass and generator function in their
"use Call::MakeMethods ..." statements and your function will be
invoked to produce the required closures. See the EXTENDING entry
elsewhere in this document for more information.
Naming Convention for Generated Method Types
Method generation functions in this document are often referred to using
the '*MakerClass*:*MethodType*' or
'*MakerGroup*::*MakerSubclass*:*MethodType*' naming conventions. As you
will see, these are simply the names of Perl packages and the names of
functions that are contained in those packages.
The included subclasses are grouped into several major groups, so the
names used by the included subclasses and method types reflect three
axes of variation, "*Group*::*Subclass*:*Type*":
MakerGroup
Each group shares a similar style of technical implementation and
level of complexity. For example, the "Standard::*" packages are all
simple, while the "Composite::*" packages all support pre- and
post-conditions.
(For a listing of the four main groups of included subclasses, see
the section on "/Included Subclasses".)
MakerSubclass
Each subclass generates methods for a similar level of scoping or
underlying object type. For example, the "*::Hash" packages all make
methods for objects based on blessed hashes, while the "*::Global"
packages make methods that access class-wide data that will be
shared between all objects in a class.
Method Type
Each method type produces a similar type of constructor or accessor.
For examples, the "*:new" methods are all constructors, while the
"::scalar" methods are all accessors that allow you to get and set a
single scalar value.
Bearing that in mind, you should be able to guess the intent of many of
the method types based on their names alone; when you see
"Standard::Array:list" you can read it as "a type of method to access a
*list* of data stored in an *array* object, with a *"standard"*
implementation style" and know that it's going to call the list()
function in the Class::MakeMethods::Standard::Array package to generate
the requested method.
USAGE
The supported method types, and the kinds of arguments they expect, vary
from subclass to subclass; see the documentation of each subclass for
details.
However, the features described below are applicable to all subclasses.
Invocation
Methods are dynamically generated and installed into the calling package
when you "use Class::MakeMethods (...)" or one of its subclasses, or if
you later call "Class::MakeMethods->make(...)".
The arguments to "use" or "make" should be pairs of a generator type
name and an associated array of method-name arguments to pass to the
generator.
* use Class::MakeMethods::*MakerClass* ( '*MethodType*' => [
*Arguments* ], *...* );
* Class::MakeMethods::*MakerClass*->make ( '*MethodType*' => [
*Arguments* ], *...* );
You may select a specific subclass of Class::MakeMethods for a single
generator-type/argument pair by prefixing the type name with a subclass
name and a colon.
* use Class::MakeMethods ( '*MakerClass*:*MethodType*' => [
*Arguments* ], *...* );
* Class::MakeMethods->make ( '*MakerClass*:*MethodType*' => [
*Arguments* ], *...* );
The difference between "use" and "make" is primarily one of precedence;
the "use" keyword acts as a BEGIN block, and is thus evaluated before
"make" would be. (See the section on "About Precedence" for additional
discussion of this issue.)
Alternative Invocation
If you want methods to be declared at run-time when a previously-unknown
method is invoked, see the Class::MakeMethods::Autoload manpage.
* use Class::MakeMethods::Autoload '*MakerClass*:*MethodType*';
If you are using Perl version 5.6 or later, see the
Class::MakeMethods::Attribute manpage for an additional declaration
syntax for generated methods.
* use Class::MakeMethods::Attribute '*MakerClass*';
sub *name* :MakeMethod('*MethodType*' => *Arguments*);
Mixing Method Types
A single calling class can combine generated methods from different
MakeMethods subclasses. In general, the only mixing that's problematic
is combinations of methods which depend on different underlying object
types, like using *::Hash and *::Array methods together -- the methods
will be generated, but some of them are guaranteed to fail when called,
depending on whether your object happens to be a blessed hashref or
arrayref.
For example, it's common to mix and match various *::Hash methods, with
a scattering of Global or Inheritable methods:
use Class::MakeMethods (
'Basic::Hash:scalar' => 'foo',
'Composite::Hash:scalar' => [ 'bar' => { post_rules => [] } ],
'Standard::Global:scalar' => 'our_shared_baz'
);
Argument Normalization
The following expansion rules are applied to argument pairs to enable
the use of simple strings instead of arrays of arguments.
* Each type can be followed by a single meta-method definition, or by
a reference to an array of them.
* If the argument is provided as a string containing spaces, it is
split and each word is treated as a separate argument.
* It the meta-method type string contains spaces, it is split and only
the first word is used as the type, while the remaining words are
placed at the front of the argument list.
For example, the following statements are equivalent ways of declaring a
pair of Basic::Hash scalar methods named 'foo' and 'bar':
use Class::MakeMethods::Basic::Hash (
'scalar' => [ 'foo', 'bar' ],
);
use Class::MakeMethods::Basic::Hash (
'scalar' => 'foo',
'scalar' => 'bar',
);
use Class::MakeMethods::Basic::Hash (
'scalar' => 'foo bar',
);
use Class::MakeMethods::Basic::Hash (
'scalar foo' => 'bar',
);
(The last of these is clearly a bit peculiar and potentially misleading
if used as shown, but it enables advanced subclasses to provide
convenient formatting for declarations with defaults or modifiers, such
as "'Template::Hash:scalar --private' => 'foo'", discussed elsewhere.)
Global Parameters
Global parameters may be specified as an argument pair with a leading
hyphen. (This distinguishes them from type names, which must be valid
Perl subroutine names, and thus will never begin with a hyphen.)
use Class::MakeMethods::*MakerClass* ( '-*Param*' => *ParamValue*,
'*MethodType*' => [ *Arguments* ], *...* );
Parameter settings apply to all subsequent method declarations within a
single "use" or "make" call.
The below parameters allow you to control generation and installation of
the requested methods. (Some subclasses may support additional
parameters; see their documentation for details.)
-TargetClass
By default, the methods are installed in the first package in the
caller() stack that is not a Class::MakeMethods subclass; this is
generally the package in which your use or make statement was
issued. To override this you can pass "-TargetClass => *package*" as
initial arguments to "use" or "make".
This allows you to construct or modify classes "from the outside":
package main;
use Class::MakeMethods::Basic::Hash(
-TargetClass => 'MyWidget',
'new' => ['create'],
'scalar' => ['foo', 'bar'],
);
$o = MyWidget->new( foo => 'Foozle' );
print $o->foo();
-MakerClass
By default, meta-methods are looked up in the package you called use
or make on.
You can override this by passing the "-MakerClass" flag, which
allows you to switch packages for the remainder of the meta-method
types and arguments.
use Class::MakeMethods ( '-MakerClass'=>'*MakerClass*',
'*MethodType*' => [ *Arguments* ] );
When specifying the MakerClass, you may provide either the trailing
part name of a subclass inside of the "Class::MakeMethods::"
namespace, or a full package name prefixed by "::".
For example, the following four statements are equivalent ways of
declaring a Basic::Hash scalar method named 'foo':
use Class::MakeMethods::Basic::Hash (
'scalar' => [ 'foo' ]
);
use Class::MakeMethods (
'Basic::Hash:scalar' => [ 'foo' ]
);
use Class::MakeMethods (
'-MakerClass'=>'Basic::Hash',
'scalar' => [ 'foo' ]
);
use Class::MakeMethods (
'-MakerClass'=>'::Class::MakeMethods::Basic::Hash',
'scalar' => [ 'foo' ]
);
-ForceInstall
By default, Class::MakeMethods will not install generated methods
over any pre-existing methods in the target class. To override this
you can pass "-ForceInstall => 1" as initial arguments to "use" or
"make".
Note that the "use" keyword acts as a BEGIN block, so a "use" at the
top of a file will be executed before any subroutine declarations
later in the file have been seen. (See the section on "About
Precedence" for additional discussion of this issue.)
About Precedence
Rather than passing the method declaration arguments when you "use" one
of these packages, you may instead pass them to a subsequent call to the
class method "make".
The difference between "use" and "make" is primarily one of precedence;
the "use" keyword acts as a BEGIN block, and is thus evaluated before
"make" would be. In particular, a "use" at the top of a file will be
executed before any subroutine declarations later in the file have been
seen, whereas a "make" at the same point in the file will not.
By default, Class::MakeMethods will not install generated methods over
any pre-existing methods in the target class. To override this you can
pass "-ForceInstall => 1" as initial arguments to "use" or "make".
If methods with the same name already exist, earlier calls to "use" or
"make()" win over later ones, but within each call, later declarations
superceed earlier ones.
Here are some examples of the results of these precedence rules:
# 1 - use, before use Class::MakeMethods::Standard::Hash (
'scalar'=>['baz'] # baz() not seen yet, so we generate, install ); sub
baz { 1 } # Subsequent declaration overwrites it, with warning
# 2 - use, after
sub foo { 1 }
use Class::MakeMethods::Standard::Hash (
'scalar'=>['foo'] # foo() is already declared, so has no effect
);
# 3 - use, after, Force
sub bar { 1 }
use Class::MakeMethods::Standard::Hash (
-ForceInstall => 1, # Set flag for following methods...
'scalar' => ['bar'] # ... now overwrites pre-existing bar()
);
# 4 - make, before
Class::MakeMethods::Standard::Hash->make(
'scalar'=>['blip'] # blip() is already declared, so has no effect
);
sub blip { 1 } # Although lower than make(), this "happens" first
# 5 - make, after, Force
sub ping { 1 }
Class::MakeMethods::Standard::Hash->make(
-ForceInstall => 1, # Set flag for following methods...
'scalar' => ['ping'] # ... now overwrites pre-existing ping()
);
EXTENDING
Class::MakeMethods can be extended by creating subclasses that define
additional meta-method types. Callers then select your subclass using
any of the several techniques described above.
You can give your meta-method type any name that is a legal subroutine
identifier. Names begining with an underscore, and the names "import"
and "make", are reserved for internal use by Class::MakeMethods.
Implementation Options
Your meta-method subroutine should provide one of the following types of
functionality:
* Subroutine Generation
Returns a list of subroutine name/code pairs.
The code returned may either be a coderef, or a string containing
Perl code that can be evaled and will return a coderef. If the eval
fails, or anything other than a coderef is returned, then
Class::MakeMethods croaks.
For example a simple sub-class with a method type upper_case_get_set
that generates an accessor method for each argument provided might
look like this:
package My::UpperCaseMethods;
use Class::MakeMethods '-isasubclass';
sub uc_scalar {
my $class = shift;
map {
my $name = $_;
$name => sub {
my $self = shift;
if ( scalar @_ ) {
$self->{ $name } = uc( shift )
} else {
$self->{ $name };
}
}
} @_;
}
Callers could then generate these methods as follows:
use My::UpperCaseMethods ( 'uc_scalar' => 'foo' );
* Aliasing
Returns a string containing a different meta-method type to use for
those same arguments.
For example a simple sub-class that defines a method type
stored_value might look like this:
package My::UpperCaseMethods;
use Class::MakeMethods '-isasubclass';
sub regular_scalar { return 'Basic::Hash:scalar' }
And here's an example usage:
use My::UpperCaseMethods ( 'regular_scalar' => [ 'foo' ] );
* Rewriting
Returns one or more array references with different meta-method
types and arguments to use.
For example, the below meta-method definition reviews the name of
each method it's passed and creates different types of meta-methods
based on whether the declared name is in all upper case:
package My::UpperCaseMethods;
use Class::MakeMethods '-isasubclass';
sub auto_detect {
my $class = shift;
my @rewrite = ( [ 'Basic::Hash:scalar' ],
[ '::My::UpperCaseMethods:uc_scalar' ] );
foreach ( @_ ) {
my $name_is_uppercase = ( $_ eq uc($_) ) ? 1 : 0;
push @{ $rewrite[ $name_is_uppercase ] }, $_
}
return @rewrite;
}
The following invocation would then generate a regular scalar
accessor method foo, and a uc_scalar method BAR:
use My::UpperCaseMethods ( 'auto_detect' => [ 'foo', 'BAR' ] );
* Generator Object
Returns an object with a method named make_methods which will be
responsible for returning subroutine name/code pairs.
See the Class::MakeMethods::Template manpage for an example.
* Self-Contained
Your code may do whatever it wishes, and return an empty list.
Access to Parameters
Global parameter values are available through the _context() class
method at the time that method generation is being performed.
package My::Maker;
sub my_methodtype {
my $class = shift;
warn "Installing in " . $class->_context('TargetClass');
...
}
* TargetClass
Class into which code should be installed.
* MakerClass
Which subclass of Class::MakeMethods will generate the methods?
* ForceInstall
Controls whether generated methods will be installed over
pre-existing methods in the target package.
DIAGNOSTICS
The following warnings and errors may be produced when using
Class::MakeMethods to generate methods. (Note that this list does not
include run-time messages produced by calling the generated methods.)
These messages are classified as follows (listed in increasing order of
desperation):
(Q) A debugging message, only shown if $CONTEXT{Debug} is true
(W) A warning.
(D) A deprecation.
(F) A fatal error in caller's use of the module.
(I) An internal problem with the module or subclasses.
Portions of the message which may vary are denoted with a %s.
Can't interpret meta-method template: argument is empty or undefined
(F)
Can't interpret meta-method template: unknown template name '%s'
(F)
Can't interpret meta-method template: unsupported template type '%s'
(F)
Can't make method %s(): template specifies unknown behavior '%s'
(F)
Can't parse meta-method declaration: argument is empty or undefined
(F) You passed an undefined value or an empty string in the list of
meta-method declarations to use or make.
Can't parse meta-method declaration: missing name attribute.
(F) You included an hash-ref-style meta-method declaration that did
not include the required name attribute. You may have meant this to
be an attributes hash for a previously specified name, but if so we
were unable to locate it.
Can't parse meta-method declaration: unknown template name '%s'
(F) You included a template specifier of the form
"'-*template_name*'" in a the list of meta-method declaration, but
that template is not available.
Can't parse meta-method declaration: unsupported declaration type '%s'
(F) You included an unsupported type of value in a list of
meta-method declarations.
Compilation error: %s
(I)
Not an interpretable meta-method: '%s'
(I)
Odd number of arguments passed to %s make
(F) You specified an odd number of arguments in a call to use or
make. The arguments should be key => value pairs.
Unable to compile generated method %s(): %s
(I) The install_methods subroutine attempted to compile a subroutine
by calling eval on a provided string, which failed for the indicated
reason, usually some type of Perl syntax error.
Unable to dynamically load $package: $%s
(F)
Unable to install code for %s() method: '%s'
(I) The install_methods subroutine was passed an unsupported value
as the code to install for the named method.
Unexpected return value from compilation of %s(): '%s'
(I) The install_methods subroutine attempted to compile a subroutine
by calling eval on a provided string, but the eval returned
something other than than the code ref we expect.
Unexpected return value from meta-method constructor %s: %s
(I) The requested method-generator was invoked, but it returned an
unacceptable value.
BUGS
It does not appear to be possible to assign subroutine names to closures
within Perl. As a result, debugging output from Carp and similar sources
will show all generated methods as "ANON()" rather than
"YourClass::methodname()".
See the Class::MakeMethods::Docs::ToDo manpage for other outstanding
issues.
VERSION
This is Class::MakeMethods v1.006.
Distribution Summary
This module's summary in the CPAN DSLIP is intended to read:
Name DSLIP Description
-------------- ----- ---------------------------------------------
Class::
::MakeMethods RdpOp Generate common types of methods
Release Status
This module has been used in a variety of production contexts, has been
available on CPAN for over a year, and several other CPAN modules depend
on it for their own operation, so it would be fair to say that it is no
longer in "beta test" but rather fully released.
However, while some portions are well tested, others are not, and new
bug reports do trickle in occasionally. If you do encounter any
problems, please inform the author and I'll endeavor to patch them
promptly.
While numerous additional features have been outlined for future
development, the intent is support these by adding more options to the
declaration interface, while maintaining backward compatibility.
Discussion and Support
There is not currently any offical discussion and support forum for this
pacakage.
If you have questions or feedback about this module, please feel free to
contact the author at the below address.
I would be particularly interested in any suggestions towards improving
the documentation, correcting any Perl-version or platform dependencies,
as well as general feedback and suggested additions.
INSTALLATION
You should be able to install this module using the CPAN shell
interface:
perl -MCPAN -e 'install Class::MakeMethods'
If this module has not yet been posted to your local CPAN mirror, you
may also retrieve the current distribution from the below address and
follow the normal "gunzip", "tar xf", "cd", "perl Makefile.PL && make
test && sudo make install" procedure or your local equivalent:
http://www.evoscript.org/Class-MakeMethods/
Prerequisites
In general, this module should work with Perl 5.003 or later, without
requring any modules beyond the core Perl distribution.
Certain features may be available only on some platforms, as noted
below:
* Class::MakeMethods::Attribute
The ":MakeMethod" subroutine attribute requires Perl version 5.6 and
the Attribute::Handlers module (from CPAN).
Tested Platforms
This release has been tested succesfully on the following platforms:
5.6.1 on darwin
Earlier releases have also tested on the following platforms:
5.005_02 on Rhapsody
5.005_03 on sun4-solaris: PASS as of 1.0.13
v5.6.0 on sun4-solaris: PASS as of 1.0.13
v5.6.1 on WinNT: PASS as of 1.0.14.a (was TEST FAILURE as of 1.0.13)
v5.6.? on RedHat 7.1 i386: TEST FAILURE as of 1.0.13
v5.6.1 on ppc-linux-64all: FAIL as of 1.0.12
5.004 on MacOS (MacPerl 520r4): PASS as of 1.0.6
5.005 on WinNT (ActivePerl 618): PASS as of 1.0.6
You may also review the current test results from CPAN-Testers:
http://testers.cpan.org/search?request=dist&dist=Class-MakeMethods
SEE ALSO
Package Documentation
A collection of sample uses is available in the
Class::MakeMethods::Docs::Examples manpage.
See the documentation for each family of subclasses:
* the Class::MakeMethods::Basic manpage
* the Class::MakeMethods::Standard manpage
* the Class::MakeMethods::Composite manpage
* the Class::MakeMethods::Template manpage
A listing of available method types from each of the different
subclasses is provided in the Class::MakeMethods::Docs::Catalog manpage.
Related Modules
For a brief survey of the numerous modules on CPAN which offer some type
of method generation, see the Class::MakeMethods::Docs::RelatedModules
manpage.
If you have used Class::MethodMaker, you will note numerous
similarities. Class::MakeMethods is based on Class::MethodMaker, but has
been substantially revised in order to provide a range of new features.
Backward compatibility and conversion documentation is provded in the
Class::MakeMethods::Emulator::MethodMaker manpage.
In several cases, Class::MakeMethods provides functionality closely
equivalent to that of an existing module, and emulator modules are
provided to map the existing module's interface to that of
Class::MakeMethods. See the Class::MakeMethods::Emulator manpage for
more information.
Perl Docs
See the perlboot manpage for a quick introduction to objects for
beginners. For an extensive discussion of various approaches to class
construction, see the perltoot manpage and the perltootc manpage (called
the perltootc manpage in the most recent versions of Perl).
See the section on "Making References" in the perlref manpage, point 4
for more information on closures. (FWIW, I think there's a big
opportunity for a "perltfun" podfile bundled with Perl in the tradition
of "perlboot" and "perltoot", exploring the utility of function
references, callbacks, closures, and continuations... There are a bunch
of useful references out there, but not a good overview of how they all
interact in a Perlish way.)
CREDITS AND COPYRIGHT
Author
M. Simon Cavalletto, simonm@cavalletto.org
Evolution Softworks, www.evoscript.org
Feedback and Suggestions
Thanks to:
Martyn J. Pearce
Scott R. Godin
Ron Savage
Jay Lawrence
Adam Spiers
Malcolm Cook
Terrence Brannon
Jared Rhine
Source Material
This package was inspired by the ground-breaking original
closure-generating method maker module:
Class::MethodMaker, by Peter Seibel.
Additional inspiration, cool tricks, and blocks of useful code for this
module were extracted from the following CPAN modules:
Class::Accessor, by Michael G Schwern
Class::Contract, by Damian Conway
Class::SelfMethods, by Toby Everett
Copyright
Copyright 2002 Matthew Simon Cavalletto.
Portions copyright 1998, 1999, 2000, 2001 Evolution Online Systems, Inc.
Based in part on Class::MethodMaker, originally developed by Peter
Seibel. Portions Copyright 1996 Organic Online. Portions Copyright 2000
Martyn J. Pearce.
Emulator::AccessorFast is based on Class::Accessor::Fast. Portions
Copyright 2000 Michael G Schwern.
Emulator::Inheritable is based on Class::Data::Inheritable. Portions
Copyright 2000 Damian Conway and Michael G Schwern.
Emulator::Singleton is based on Class::Singleton, by Andy Wardley.
Portions Copyright 1998 Canon Research Centre Europe Ltd.
Utility::Ref is based on Ref.pm. Portions Copyright 1994 David Muir
Sharnoff.
License
You may use, modify, and distribute this software under the same terms
as Perl.