Class::MethodMaker - a module for creating generic methods
use Class::MethodMaker new_with_init => 'new', get_set => [ qw /foo bar baz / ];
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.
To override any generated methods, it is sufficient to ensure that the overriding method is defined when Class::MethodMaker is called. Note that the use keyword introduces a BEGIN block, so you may need to define (or at least declare) your overriding method in a BEGIN block.
use
BEGIN
Some new facilities may be marked as EXPERIMENTAL in the documentation. These facilities are being trialled, and whilst it is hoped that they will become mainstream code, no promises are made. They may change or disappear at any time. Caveat Emptor. The maintainer would be delighted to hear any feedback particularly regarding such facilities, be it good or bad, so long as it is constructive.
Some old facilities may be marked as COMPATIBILITY in the documentation. These facilities are being maintained purely for compatibility with old versions of this module, but will ultimately disappear. They are normally replaced by alternatives that are thought preferable for some completely arbitrary raisin. Please avoid using them, and consider amending any existing code that does use them not to. If you believe that their removal will cast an unacceptable pall over your life, please contact the maintainer, or get a new life: whichever is easier.
Creates a basic constructor.
Takes a single string or a reference to an array of strings as its argument. For each string creates a simple method that creates and returns an object of the appropriate class.
This method may be called as a class method, as usual, or as in instance method, in which case a new object of the same class as the instance will be created. Note that new_hash_init works slightly differently with regard to being called on an instance.
new_hash_init
Creates a basic constructor which calls a method named init after instantiating the object. The init method should be defined in the class using MethodMaker.
init
Takes a single string or a reference to an array of strings as its argument. For each string creates a simple method that creates an object of the appropriate class, calls init on that object propagating all arguments, before returning the object.
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 that takes a list of arguments that is treated as a set of key-value pairs, with each such pair causing a call $self->key ($value).
$self->key ($value)
This method may be called as a class method, causing a new instance to be created, or as an instance method, which will operate on the subject instance. This allows it to be combined with new_with_init (see above) to provide some default values. For example, 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.
Note that the operation with regard to action on an instance differs to that of new and new_with_init differently with regard to being called on an instance.
new
new_with_init
You may want to work with this to support default values. The following snippet is one way of doing this (adapted from code supplied by Kevin J. Rice):
package Simple; use Class::MethodMaker get_set => [qw(a b)], new_with_init => 'new'; new_hash_init => 'hash_init'; use constant INSTANCE_DEFAULTS => (a => 7, b => 'default') ; sub init { my $self = shift; my %values = (INSTANCE_DEFAULTS, @_); $self->hash_init(%values); return; }
Now, back at the farm...
use Simple; my $test = Simple->new; # now a==7, b==default my $test = Simple->new(a=>1); # now a==1, b==default. my $test = Simple->new(a=>1, b=>2); # now a==1, b==2.
Combines new_hash_init with new_with_init; arguments passed in are first passed to assignment methods as with new_hash_init, and then the class method 'init' (which must be defined by the client is called, with those arguments. Note that unlike new_with_init, the arguments are pre-munged --- if a single argument is a hashref is passed in, it is expanded out, the the key/value pairs (whether originally as a hash ref or a list) may be reordered as typically occurs with perl hashes.
Creates a basic constructor which only ever returns a single instance of the class: i.e., after the first call, repeated calls to this constructor return the same instance. Note that the instance is instantiated at the time of the first call, not before.
Any arguments are treated as for new_hash_init.
Naturally, init and any initializer methods are called only by the first invocation of this method.
This method should be called only as a class method.
Constructor arguments will be stored as a key, value pairs in the object. No check is done regarding the consistencies of the data passed to the constructor and the accessor methods created.
Takes a single string or a reference to an array of strings as its argument. Each string specifies a slot, for which accessor methods are created. The accessor methods are, by default:
If an argument is provided, sets a new value for x. This is true even if the argument is undef (cf. no argument, which does not set.)
Returns (new) value.
Value defaults to undef.
Sets value to undef. This is exactly equivalent to
$foo->x (undef)
No return.
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.
There are several options available for controlling the names and types of methods created.
The following options affect the type of methods created:
The methods will refer to a class-specific, rather than instance-specific store. I.e., these scalars are shared across all instances of your object in your process.
Please note that the -set_once options are EXPERIMENTAL, as noted above. In particular, they will not be available in initial versions of V2. V1 will continue to be maintained after V2 is released, but you will not be able to upgrade to V2 initially if you use these options.
The methods will allow the value to be set only once. If a caller attempts to set the value a second time, then SUBNAME will be called (default is to die). The subroutine SUBNAME will be called as SUBNAME( $CLASS, $ERRMSG, @ARGS ), where $CLASS is the first parameter passed to the set method, $ERRMSG is a human-readable message, and @ARGS are the remaining parameters passed to the set method.
If SUBNAME is croak, carp, cluck, or confess, then the Carp module is automatically used.
-set_once is shorthand for -set_once_or_die.
-set_once_or_ignore means that any subsequent attempts to set the value will be silently ignored.
Example:
package Person; use Class::MethodMaker new => 'new', get_set => [qw/ -set_once Name /], get_set => [qw/ -set_once_or_report Address /], get_set => [qw/ -set_once_or_ignore ID /]; package main; my $p = new Person; $p->Name('John'); $p->Address('Philadelphia'); $p->ID(43); $p->Name('Martyn'); # die! Attempt to set Person::Name twice. $p->Address('Surrey'); # Calls $p->report("Error...", 'Surrey') $p->ID(44); # returns 43.
The following options affect the methods created as detailed:
Creates getx and setx methods, which return the value, and set the value (no return), respectively.
Note the absence of underscores in the method names. This is to accomodate the java-style StudlyCaps naming scheme.
package Person; use Class::MethodMaker new_hash_init => 'new' , get_set => [qw/ -java Status Size Name /]; package main; my $p = Person->new( Name => 'Homer', Size => '54', Status => 'Comical Moron', );
Creates x and set_x methods, analogous to -java getx and setx respectively.
package Person; use Class::MethodMaker new_hash_init => 'new' , get_set => [qw/ -eiffel status size name /]; package main; my $p = Person->new( name => 'Homer', size => '54', status => 'Comical Moron', );
Creates x (as per the default), and clear_x, which resets the slot value to undef. Use this to ensure backward compatibility.
Creates x (as per the default) only.
Alternatively, an arrayref specifying a template for method names may be supplied. Each name must contain a '*' character, which will be replaced by the slot name, and no two patterns may be the same. undef may be supplied for methods that you do not want created. Currently, the first 4 members of such an arrayref may be used:
Creates a method that if supplied an argument, sets the slot to the value of that argument; the value of the slot (after setting, if relevant) is returned.
Creates a method that takes no arguments, sets the slot value to undefined, and makes no return.
Creates a method that takes no arguments, and returns the value of the slot.
Creates a method that takes one argument, and sets the value of the slot to that value. Given undef as that argument, the value is set to undef. If called with no arguments, the slot value is set to undef.
See the examples.
Creates methods a, b, c which can be used for both getting and setting the named slots:
use Class::MethodMaker get_set => 'a', get_set => [qw/ b c /];
Creates get_d which returns the value in slot d (takes no arguments), and set_d, which sets the value in slot d (no return):
use Class::MethodMaker get_set => [ -java => d ];
Creates e_clear, e_get, e_set, f_clear, f_get, f_set methods:
use Class::MethodMaker get_set => [[undef, '*_clear', '*_get', '*_set'] => qw/e f/ ];
These options may be combined, using order sensitivity. E.g.,
use Class::MethodMaker get_set => [qw/ -java Status -eiffel size name /];
will instantiate the Status component as a java style (with getStatus, setStatus methods), and the size & name components as eiffel style (with size, set_size, name, set_name methods).
Status
getStatus
setStatus
size
name
set_size
set_name
Like get_set, takes a single string or a reference to an array of strings as its argument. For each string, x creates two methods:
If an argument is provided, sets a new value for x. Returns (new) value. Value defaults to undef.
Sets value to undef. No return.
The difference between this and get_set is that these scalars are shared across all instances of your object in your process.
This is now a wrapper around get_set (-static => @args).
Like get_set except sets do not 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.
The argument taken may be a hashref, in which the keys name and join are recognized; name being the slot name, join being a join string t glue any given strings.
join
use Class::MethodMaker get_concat => { name => 'words', join => "\t" };
Will, each time an argument is supplied to the x method, glue this argument onto any existing value with tab separator. Like the join operator, the join field is applied between values, not prior to the first or after the last.
x
Creates get/set methods like get_set but also defines a method which returns a list of the slots in the group.
grouped_fields methods some_group => [ qw / field1 field2 field3 / ];
Its argument list is parsed as a hash of group-name => field-list pairs. Get-set methods are defined for all the fields and a method with the name of the group is defined which returns the list of fields in the group.
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.
object => [ 'Foo' => 'phooey', 'Bar' => [ qw / bar1 bar2 bar3 / ], 'Baz' => { slot => 'foo', comp_mthds => [ qw / bar baz / ] }, 'Fob' => [ { slot => 'dog', comp_mthds => 'bark', }, { slot => 'cat', comp_mthds => 'miaow', }, ]; ];
The main argument should be a reference to an array. The array should contain pairs of class => sub-argument pairs. The sub-arguments parsed thus:
See Baz above. The hash should contain the following keys:
Baz
The name of the instance attribute (slot).
A string or array ref, naming the methods that will be forwarded directly to the object in the slot.
As for String, for each member of the array. Also works if each member is a hash reference (see Fob above).
String
Fob
For each slot x, with forwarding methods y and z, the following methods are created:
y
z
A get/set method.
If supplied with an object of an appropriate type, will set set the slot to that value.
Else, if the slot has no value, then an object is created by calling new on the appropriate class, passing in any supplied arguments.
The stored object is then returned.
Forwarded onto the object in slot x, which is auto-created via new if necessary. The new, if called, is called without arguments.
As for y.
So, using the example above, a method, foo, is created in the class that calls MethodMaker, which can get and set the value of those objects in slot foo, which will generally contain an object of class Baz. Two additional methods are created in the class using MethodMaker, named 'bar' and 'baz' which result in a call to the 'bar' and 'baz' methods on the Baz object stored in slot foo.
foo
Functions like list, but maintains an array of referenced objects in each slot. Forwarded methods return a list of the results returned by maping the method over each object in the array.
list
map
Arguments are like object.
object
Functions like tie_list, but maintains an array of referenced objects in each slot.
tie_list
object_tie_list => [ { slot => xxx, # or [ ... , ... ] tie_array => [ 'ArrayName', args ,...] , class => ['ObjName', constructor_args ] }, ... ]
When xxx is called with one or several arguments, Each argument is:
Stored in the array if the argument is an object of the class 'ObjName'.
Used to create a new object of the class 'ObjName' if the argument is an array ref. The elements of the array ref are passed to the constructor *after* the default constructor arguments.
Discarded if any other case. A new object is created using the default constructor arguments and stored in the array.
Functions like tie_hash, but maintains an array of referenced objects in each slot.
tie_hash
object_tie_hash => [ { slot => xxx, # or [ ... , ... ] tie_hash => [ 'HashName', args ,...] , class => ['ObjName', @constructor_args ] }, ... ]
When xxx is called with more than one argument, xxx is treated as the key. If the second argument is a:
An object of the class 'ObjName' then the object is the new value of the key 'xxx'.
An array ref. A new object of the class 'ObjName' is created and stored in the hash. The elements of the array ref are passed to the constructor *after* the default constructor arguments.
Anything else: A new object is created using the default constructor arguments.
Example, if the default constructor arguments are @c_args :
xxx( # xxx[0] = $obj->isa('ObjName') ? $obj : ObjName->new(@c_args) $obj, # xxx[1] = ObjName->new(@c_args, arg => 'bar') [ arg => 'bar'], # xxx[2 to 8] = ObjName->new(@constructor_arg) 1 .. 6 )
forward => [ comp => 'method1', comp2 => 'method2' ]
Define pass-through methods for certain fields. The above defines that method method1 will be handled by component comp, whilst method method2 will be handled by component comp2.
method1
comp
method2
comp2
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:
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.
Equivalent to x(1).
Equivalent to x(0).
Additionally, boolean defines three class methods:
Returns the vector containing all of the bit fields (remember however that a vector containing all 0 bits is still true).
Returns a list of all the flags by name.
Returns a hash of the flag-name/flag-value pairs.
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 => [ 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 => [ 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.
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:
This method returns the list of values stored in the slot. If any arguments are provided to this method, they replace the current list contents. In an array context it returns the values as an array and in a scalar context as a reference to the array. Note that this reference is currently a direct reference to the storage; changes to the storage will affect the contents of the reference, and vice-versa. This behaviour is not guaranteed; caveat emptor.
Returns the number of elements in x.
Takes a list of indices, returns a list of the corresponding values.
Takes a list, treated as pairs of index => value; each given index is set to the corresponding value. No return.
As for list, but the value of the component is shared across all instances of your object in your process.
Much like list, but can use a tied list instead.
Takes a list of pairs, where the first is the name of the component, the second is an array reference. The array reference takes the usual tie parameters.
For instance if Array_A and ArrayB are tied arrays, you can have:
tie_list => [ foo => [ 'Array_A', foo => 'x', bar => 'B' ], baz => [ 'ArrayB', baz => 0] ],
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:
Called with no arguments returns the hash stored in the slot, as a hash in a list context or as a reference in a scalar context.
Called with one simple scalar argument it treats the argument as a key and returns the value stored under that key.
Called with one array (list) reference argument, the array elements are considered to be be keys of the hash. x returns the list of values stored under those keys (also known as a hash slice.)
Called with one hash reference argument, the keys and values of the hash are added to the hash.
Called with more than one argument, treats them as a series of key/value pairs and adds them to the hash.
Returns the keys of the hash.
Returns the list of values.
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.
Takes a single key, returns whether that key exists in the hash.
Takes a list, deletes each key from the hash.
Resets hash to empty.
Creates a group of methods for dealing with list data stored by key in a slot.
Returns all the values for all the given keys, in order. If no keys are given, returns all the values (in an unspecified key order).
The result is returned as an arrayref in scalar context. This arrayref is not part of the data structure; messing with it will not affect the contents directly (even if a single key was provided as argument.)
If any argument is provided which is an arrayref, then the members of that array are used as keys. Thus, the trivial empty-key case may be utilized with an argument of [].
Returns the keys of the hash. As an arrayref in scalar context.
Takes a list of keys, and returns whether each key exists in the hash (i.e., the and of whether the individual keys exist).
and
Takes a key, and some values. Pushes the values onto the list denoted by the key. If the first argument is an arrayref, then each element of that arrayref is treated as a key and the elements pushed onto each appropriate list.
Takes a list of keys, and pops each one. Returns the list of popped elements. undef is returned in the list for each key that is has an empty list.
Like x_pop, but does not actually change any of the lists.
x_pop
Like push, only the from the other end of the lists.
Like pop, only the from the other end of the lists.
Takes a key, offset, length, and a values list. Splices the list named by the key. Anything from the offset argument (inclusive) may be omitted. See "splice" in perlfunc.
Takes a key, and a set of index->value pairs, and sets each specified index to the corresponding value for the given key.
Takes a list of keys. Resets each named list to empty (but does not delete the keys.)
Takes a list of keys. Returns the sum of the number of elements for each named list.
Takes a key, and a list of indices. Returns a list of each item at the corresponding index in the list of the given key. Uses undef for indices beyond range.
Takes a key, and a list of indices. Removes each corresponding item from the named list. The indices are effectively looked up at the point of call --- thus removing indices 3, 1 from list (a, b, c, d) will remove (d) and (b).
Takes a key, and a set of named arguments, which may be a list or a hash ref. Removes list members based on a grep-like approach.
The filter function used (as a coderef). Is passed two arguments, the value compared against, and the value in the list that is potential for grepping out. If returns true, the value is removed. Default:
sub { $_[0] == $_[1] }
The list keys to sift through (as an arrayref). Unknown keys are ignored. Default: all the known keys.
The values to sift out (as an arrayref). Default: [undef]
[undef]
Options:
Make the corresponding storage class-specific, rather than instance-specific.
Create a get/set method to deal with the tied scalar.
For instance if Enum and Boolean are tied scalar that accept default values, you can have:
tie_scalar => [ foo => [ 'Enum', enum => [qw/A B C/], default => 'B' ], bar => [ 'Enum', enum => [qw/T0 T1/], default => 'T1'], baz => ['Boolean', default => 0] ],
Much like hash, but uses a tied hash instead.
hash
Takes a list of pairs, where the first is the name of the component, the second is a hash reference. The hash reference recognizes the following keys:
Required. The name of the class to tie to. Make sure you have used the required class.
Required. Additional arguments for the tie, as an array ref.
The first argument can also be an arrayref, specifying multiple components to create.
tie_hash => [ hits => { tie => qw/ Tie::RefHash /, args => [], }, ],
Much like hash, but uses a class-based hash instead.
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 => [ qw / foo bar baz / ]
Just like code, except the code is called like a method, with $self as its first argument. Basically, you are creating a method which can be different for each object. Which is sort of weird. But perhaps useful.
abstract => [ qw / foo bar baz / ]
This creates a number of methods will die if called. This is intended to support the use of abstract methods, that must be overidden in a useful subclass.
Create components containing simple counters that may be read, incremented, or reset. For value x, the methods are:
(accepts argument to set),
(accepts argument for increment size),
The counter is implicitly initialized to zero.
Produce a copy of self. The copy is a *shallow* copy; any references will be shared by the instance upon which the method is called and the returned newborn.
Produce a copy of self. The copy is a *deep* copy; any references will be recursively copied value-by-value from the instance upon which the method is called into the returned newborn. Note that this copying does not support the copying of coderefs, ties or XS-based objects.
MethodMaker is a class that can be inherited. A subclass can define new method types by writing a method that generates a hash of method_name/code-reference pairs, and then calls the class method install_methods on them. If the coderef is in fact a string, then that string will be evalled in the hope of getting a coderef to use.
install_methods
eval
For example a simple sub-class that defines a method type upper_case_get_set might look like this:
package Class::MethodMakerSubclass; use strict; use base qw( Class::MethodMaker ); sub upper_case_get_set { my $class = shift; my ($name) = @_; my %methods; $methods{$name} = sub { my ($self, $new) = @_; defined $new and $self->{$name} = uc $new; $self->{$name}; }; $class->install_methods (%methods); } 1;
Alternatively, rather than a coderef, the values of the hash passed to install_methods may be strings, which will be evaled in the hope of returning a coderef to use. If the eval fails, or anything other than a coderef is returned, then C::MM croaks.
Any return value from a method (above) that is used to generate methods will be passed to install_methods --- so in the above, the line
$class->install_methods (%methods);
could be replaced with
return %methods
If intend to publish your meta-methods, consider doing so on CPAN, the Comprehensive Perl Archive Network at http://www.cpan.org . If your meta-methods are generic and potentially useful to a large number of other C::MM users (as distinct from an application-specific subset), please contact the authour of this module at fluffy@cpan.org to discuss integrating those methods with this module.
History: This method was in 0.92, undocumented. Does anybody use this? Would anybody use this subject to some enhancement or other? Let me know.
Purpose: This class generates a wrapper around some builtin function, cacheing the results in the object and providing a by-name interface.
Takes a (core) function name, and a arrayref of return position names (we will call it pos_list). Creates:
Calls the core func with any given arguments, stores the result in the instance.
For each member of pos_list, creates a method of the same name which gets/sets the nth member of the returned list, where n is the position of x in pos_list.
Returns pos_list, in the given order.
Returns a list item name, item value, in order.
Example Usage:
package Stat; use Class::MethodMaker builtin_class => [stat => [qw/ dev ino mode nlink /]], package main; my $file = "$ENV{HOME}/.profile"; my $s = Stat->new ($file); print "File $file has ", $s->nlink, " links\n";
Note that (a) the new method does not check the return value of the function called (in the above example, if $file does not exist, you will silently get an empty object), and (b) if you really want the above example, see the core File::stat module. But you get the idea, I hope.
Email the author.
Current Maintainer: Martyn J. Pearce fluffy@cpan.org
Original Author: Peter Seibel (Organic Online)
Contributions from:
Dominique Dumont (Dominique_Dumont@hp.com) Hewlett-Packard Company. http://www.hp.com Evolution Online Systems, Inc. http://www.evolution.com Matthew Persico Yitzchak Scott-Thoennes
Copyright (c) 2000, 2001, 2002, 2003 Martyn J. Pearce. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Copyright (c) 1998, 1999, 2000 Evolution Online Systems, Inc. You may use this software for free under the terms of the MIT License. More info posted at http://www.evolution.com, or contact info@evolution.com Copyright (c) 1996 Organic Online. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
C<Class::Struct>, C<Class::MakeMethods>, "Object-Oriented Perl" by Damian Conway.
3 POD Errors
The following errors were encountered while parsing the POD:
Expected text after =item, not a number
To install Class::MethodMaker, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Class::MethodMaker
CPAN shell
perl -MCPAN -e shell install Class::MethodMaker
For more information on module installation, please visit the detailed CPAN module installation guide.