| Class::MakeMethods - Generate common types of methods |
Class::MakeMethods - Generate common types of methods
# Generates methods for your object when you "use" it.
package MyObject;
use Class::MakeMethods::Standard::Hash (
'new' => 'new',
'scalar' => 'foo',
'scalar' => 'bar',
);
# The generated methods can be called just like normal ones
my $obj = MyObject->new( foo => "Foozle", bar => "Bozzle" );
print $obj->foo();
$obj->bar("Barbados");
The Class::MakeMethods framework allows Perl class developers to
quickly define common types of methods. When a module uses
Class::MakeMethods or one of its subclasses, it can select from a
variety of 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.
"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.
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.
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.
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.
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 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 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.
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.
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.
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.
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 ``inside-out'' accessors with external indexes).
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 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.
use Call::MakeMethods ... statements and your function will be
invoked to produce the required closures. See EXTENDING for
more information.
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'':
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 /Included Subclasses.)
*::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.
*: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::Hash:scalar'' you can read it as ``a type of method to access a scalar value stored in a hash-based object, with a standard implementation style'' and know that it's going to call the scalar() function in the Class::MakeMethods::Standard::Hash package to generate the requested method.
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.
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.
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.
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 About Precedence for additional discussion of this issue.)
If you want methods to be declared at run-time when a previously-unknown method is invoked, see the Class::MakeMethods::Autoload manpage.
If you are using Perl version 5.6 or later, see the Class::MakeMethods::Attribute manpage for an additional declaration syntax for generated methods.
sub name :MakeMethod('MethodType' => Arguments);
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 the same method is declared multiple times, 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()
);
Global options 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 ], ... );
Option settings apply to all subsequent method declarations within a single use or make call.
The below options allow you to control generation and installation of the requested methods. (Some subclasses may support additional options; see their documentation for details.)
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();
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 => 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 About Precedence for additional discussion of this issue.)
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'
);
The following types of Simple declarations are supported:
For a list of the supported values of generator_type, see STANDARD CLASSES in the Class::MakeMethods::Docs::Catalog manpage, or the documentation for each subclass.
For each method name you provide, a subroutine of the indicated type will be generated and installed under that name in your module.
Method names should start with a letter, followed by zero or more letters, numbers, or underscores.
The following expansion rules are applied to argument pairs to enable the use of simple strings instead of arrays of arguments.
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.)
The Standard syntax also provides several ways to optionally associate a hash of additional parameters with a given method name.
A hash of parameters to use just for this method name.
(Note: to prevent confusion with self-contained definition hashes,
described below, parameter hashes following a method name must not
contain the key 'name'.)
Each of these method names gets a copy of the same set of parameters.
generator_type => [ { 'name'=>'method_1', param=>value... }, ... ]By including the reserved parameter 'name', you create a self-contained declaration with that name and any associated hash values.
Simple declarations, as shown in the prior section, are treated as if they had an empty parameter hash.
A set of default parameters to be used for several declarations may be specified using any of the following types of arguments to a method generator call:
Set a default value for the specified parameter to be passed to all subsequent declarations.
generator_type => [ '--' => { 'param' => 'value', ... }, 'method_1', 'method_2', ... ]Set default values for one or more parameters to be passed to all subsequent declarations. Equivalent to a series of '-param' => 'value' pairs for each pair in the referenced hash.
generator_type => [ '--special_param', 'method_1', 'method_2', ... ]Appends to the default value for a special parameter named ``--''. This parameter is currently only used by some subclasses; for details see the Class::MakeMethods::Template manpage
Parameters set in these ways are passed to each declaration that follows it until the end of the method-generator argument array, or until overridden by another declaration. Parameters specified in a hash for a specific method name, as discussed above, will override the defaults of the same name for that particular method.
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.
'-template_name'
in a the list of meta-method declaration, but that template is not
available.
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.
The begining of a typical extension might look like the below:
package My::UpperCaseMethods;
use strict;
use Class::MakeMethods '-isasubclass';
sub my_method_type { ... }
You can name your subclass anything you want; it does not need to begin with Class::MakeMethods.
The '-isasubclass' flag is a shortcut that automatically puts
Class::MakeMethods into your package's @ISA array so that it will
inherit the import() and make() class methods. If you omit this
flag, you will need to place the superclass in your @ISA explicitly.
Typically, the subclass should not inherit from Exporter; both Class::MakeMethods and Exporter are based on inheriting an import class method, and getting a subclass to support both would require additional effort.
Each type of method that can be generated is defined in a subroutine of the same name. 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.)
If you plan on distributing your extension, you may wish to follow the ``Naming Convention for Generated Method Types'' described above to facilitate reuse by others.
Each method generation subroutine can be implemented in any one of the following ways:
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-ContainedYour code may do whatever it wishes, and return an empty list.
Global option 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');
...
}
Class into which code should be installed.
MakerClassWhich subclass of Class::MakeMethods will generate the methods?
ForceInstallControls whether generated methods will be installed over pre-existing methods in the target package.
For distribution, installation, support, copyright and license information, see the Class::MakeMethods::Docs::ReadMe manpage.
A collection of sample uses is available in the Class::MakeMethods::Docs::Examples manpage.
See the documentation for each family of subclasses:
A listing of available method types from each of the different subclasses is provided in the Class::MakeMethods::Docs::Catalog manpage.
For a brief survey of the numerous modules on CPAN which offer some type of method generation, see the Class::MakeMethods::Docs::RelatedModules 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.
If you have used Class::MethodMaker, you will note numerous similarities between the two. 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.
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 perltootc (called perltootc in the most recent versions of Perl).
See Making References in the perlref manpage, point 4 for more information on closures. (FWIW, I think there's a big opportunity for a ``perlfunt'' 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 available, but not a good overview of how they all interact in a Perlish way.)
| Class::MakeMethods - Generate common types of methods |