NAME
Class::MethodMaker - a module for creating generic methods
SYNOPSIS
use Class::MethodMaker new_with_init => 'new', get_set => [ qw /foo bar
baz / ];
DESCRIPTION
This module solves the problem of having to write a bazillion get/set
methods that are all the same. The argument to 'use' is a hash whose
keys are the names of types of generic methods generated by MethodMaker
and whose values tell method maker what methods to make. (More
precisely, the keys are the names of MethodMaker methods (methods that
write methods) and the values are the arguments to those methods.
SUPPORTED METHOD TYPES
new
Creates a basic constructor.
Takes a single string or a reference to an array of strings as its
argument. For each string creates a method of the form:
sub <string> {
my ($class, @args) = @_;
my $self = {};
bless $self, $class;
}
new_with_init
Creates a basic constructor which calls a method named init after
instatiating the object. The *init*() method should be defined in the
class using MethodMaker.
Takes a single string or a reference to an array of strings as its
argument. For each string creates a method of the form listed below.
sub <string> {
my ($class, @args) = @_;
my $self = {};
bless $self, $class;
$self->init(@args);
$self;
}
new_hash_init
Creates a basic constructor which accepts a hash of slot-name/value
pairs with which to initialize the object. The slot-names are
interpreted as the names of methods that can be called on the object
after it is created and the values are the arguments to be passed to
those methods.
Takes a single string or a reference to an array of strings as its
argument. For each string creates a method of the form listed below.
Note that this method can be called on an existing objec, which allows
it to be combined with new_with_init (see above) to provide some default
values. (Basically, declare a new_with_init method, say 'new' and a
new_hash_init method, for example, 'hash_init' and then in the init
method, you can call modify or add to the %args hash and then call
hash_init.)
sub <string> {
my ($class, %args) = @_;
my $self = {};
bless $self, $class;
foreach (keys %args) {
$self->$_($args{$_});
}
$self;
}
get_set
Takes a single string or a reference to an array of strings as its
argument. For each string, x creates two methods:
sub x {
my ($self, $new) = @_;
defined $new and $self->{$name} = $new;
$self->{$name};
}
sub clear_x
my ($self) = @_;
$self->{$name} = undef;
}
This is your basic get/set method, and can be used for slots containing
any scalar value, including references to non-scalar data. Note,
however, that MethodMaker has meta-methods that define more useful sets
of methods for slots containing references to lists, hashes, and
objects.
get_concat
Like get_set except sets don't clear out the original value, but instead
concatenate the new value to the existing one. Thus these slots are only
good for plain scalars. Also, like get_set, defines clear_foo method.
fields
Creates get/set methods like get_set but also defines a method which
returns a list of the slots in the group.
Takes a single hash-ref or a reference to an array of hash-refs as its
argument. Each hash-ref should have have the keys group and slots. The
group value is the name of the method which returns the list of slots
and the slots value should be an acceptable argument for get_set.
object
Creates methods for accessing a slot that contains an object of a given
class as well as methods to automatically pass method calls onto the
object stored in that slot.
This is a hairy one. The main argument should be a reference to an
array. The array should contain pairs of class => sub-argument pairs.
The sub-argument's are further parsed thusly:
If the sub-argument is a simple string or a reference to an array of
strings (as is the case for Foo and Bar above), for each string a
get/set method is created that can store an object of that class. (The
get/set method, if called with a reference to an object of the given
class as the first argument, stores it in the slot. If the slot isn't
filled yet it creates an object by calling the given class's new method.
Any arguments passed to the get/set method are passed on to new. In all
cases the object now stored in the slot is returned.
If the sub-argument is a ref to a hash (as with Baz, above) then the
hash should have two keys: slot and comp_mthds. The value indexed by
'slot' will be interpreted as the is in (a). The value or values (ref to
an array if plural) indexed by 'comp_mthds' are the names of methods
which should be "inherited" from the object stored in the slot. That is,
using the example above, a method, foo, is created in the class that
calls MethodMaker, which can get and set the value of a slot containing
an object of class Baz. Class Baz in turn defines two methods, 'bar',
and 'baz'. Two more methods are created in the class using MethodMaker,
named 'bar' and 'baz' which result in a call to the 'bar' and 'baz'
methods, through the Baz object stored in slot foo.
boolean
boolean => [ qw / foo bar baz / ]
Creates methods for setting, checking and clearing flags. All flags
created with this meta-method are stored in a single vector for space
efficiency. The argument to boolean should be a string or a reference to
an array of strings. For each string x it defines several methods: x,
set_x, and clear x. x returns the value of the x-flag. If called with an
argument, it first sets the x-flag to the truth-value of the argument.
set_x is equivalent to x(1) and clear_x is equivalent to x(0).
Additionally, boolean defines three class method: *bits*, which returns
the vector containing all of the bit fields (remember however that a
vector containing all 0 bits is still true), *boolean_fields*, which
returns a list of all the flags by name, and *bit_dump*, which returns a
hash of the flag-name/flag-value pairs.
listed_attrib
listed_attrib => [ qw / foo bar baz / ]
Like *boolean*, *listed_attrib* creates x, set_x, and clear_x methods.
However, it also defines a class method x_objects which returns a list
of the objects which presently have the x-flag set to true. N.B.
listed_attrib does not use the same space efficient implementation as
boolean, so boolean should be prefered unless the x_objects method is
actually needed.
key_attrib
key_attrib => [ qw / foo bar baz / ]
Creates get/set methods like get/set but also maintains a hash in which
each object is stored under the value of the field when the slot is set.
If an object has a slot set to a value which another object is already
set to the object currently set to that value has that slot set to undef
and the new object will be put into the hash under that value. (I.e.
only one object can have a given key. The method find_x is defined which
if called with any arguments returns a list of the objects stored under
those values in the hash. Called with no arguments, it returns a
reference to the hash.
key_with_create
key_with_create => [ qw / foo bar baz / ]
Just like key_attrib except the find_x method is defined to call the new
method to create an object if there is no object already stored under
any of the keys you give as arguments.
list
Creates several methods for dealing with slots containing list data.
Takes a string or a reference to an array of strings as its argument and
for each string, x, creates the methods: x, push_x, and pop_x. The
method x returns the list of values stored in the slot. In an array
context it returns them as an array and in a scalar context as a
reference to the array. If called with arguments, x will push them onto
the list. push_x and pop_x do about what you would expect.
hash
Creates a group of methods for dealing with hash data stored in a slot.
Takes a string or a reference to an array of strings and for each
string, x, creates: x, x_keys, x_values, and x_tally. Called with no
arguments x returns the hash stored in the slot, as a hash in an array
context or as a refernce in a scalar context. Called with one argument
it treats the argument as a key and returns the value stored under that
key, or as a list of keys (if it is a reference to a list) and returns
the list of values stored under those keys. Called with more than one
argument, treats them as a series of key/value pairs and adds them to
the hash. x_keys returns the keys of the hash, and x_values returns the
list of values. x_tally takes a list of arguments and for each scalar in
the list increments the value stored in the hash and returns a list of
the current (after the increment) values.
code
code => [ qw / foo bar baz / ]
Creates a slot that holds a code reference. Takes a string or a
reference to a list of string and for each string, x, creates a method x
which if called with one argument which is a CODE reference, it installs
that code in the slot. Otherwise it runs the code stored in the slot
with whatever arguments (including none) were passed in.
method
method => [ qw / foo bar baz / ]
Just like code, except the code is called like a method, with $self as
it's first argument. Basically, you're creating a method which can be
different for each object. Which is sort of weird. But perhaps useful.
interface
interface => [ qw / foo bar baz / ]
ADDDING NEW METHOD TYPES
MethodMaker is a class that can be inherited. A subclass can define new
method types by writing a method that returns a hash of
method_name/code-reference pairs.
For example a simple sub-class that defines a method type
upper_case_get_set might look like this:
sub upper_case_get_set {
shift; # we don't need the class name
my ($name) = @_;
my %results;
$results{$name} =
sub {
my ($self, $new) = @_;
defined $new and $self->{$name} = uc $new;
$self->{$name};
};
%results;
}
