|
B |
Class::MakeMethods::Emulator::MethodMaker - Emulate Class::MethodMaker
package MyObject;
use Class::MakeMethods::Emulator::MethodMaker(
new_with_init => 'new',
get_set => [ qw / foo bar baz / ];
);
... OR ...
package MyObject;
use Class::MakeMethods::Emulator::MethodMaker '-take_namespace';
use Class::MethodMaker (
new_with_init => 'new',
get_set => [ qw / foo bar baz / ];
);
This module provides emulation of Class::MethodMaker, using the Class::MakeMethods framework.
Although originally based on Class::MethodMaker, the calling convention for Class::MakeMethods differs in a variety of ways; most notably, the names given to various types of methods have been changed, and the format for specifying method attributes has been standardized. This package uses the aliasing capability provided by Class::MakeMethods, defining methods that modify the declaration arguments as necessary and pass them off to various subclasses of Class::MakeMethods.
There are several ways to call this emulation module:
Replace occurances in your code of Class::MethodMaker with Class::MakeMethods::Emulator::MethodMaker.
If you use Class::MakeMethods::Emulator::MethodMaker '-take_namespace', the Class::MethodMaker namespace will be aliased to this package, and calls to the original package will be transparently handled by this emulator.
To remove the emulation aliasing, call use Class::MakeMethods::Emulator::MethodMaker '-release_namespace'.
Note: This affects all subsequent uses of Class::MethodMaker in your program, including those in other modules, and might cause unexpected effects.
Passing '-sugar' as the first argument in a use or import call will cause the 'methods' package to be declared as an alias to this one.
This allows you to write declarations in the following manner.
use Class::MakeMethods::Emulator::MethodMaker '-sugar';
make methods
get_set => [ qw / foo bar baz / ],
list => [ qw / a b c / ];
Note: This feature is deprecated in Class::MethodMaker version 0.96 and later.
NOTE: The documentation below is derived from version 1.02 of Class::MethodMaker, and has been reused with only minor revisions and annotations. Class::MakeMethods::Emulator::MethodMaker provides support for all of the features and examples shown below, with no changes required.
The argument to 'use' is a hash whose keys are the names of types of generic methods defined by MethodMaker and whose values tell MethodMaker what methods to make. More precisely, the keys are the names of MethodMaker 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 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.
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.
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.
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.
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.
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).
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.
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.
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:
Returns (new) value.
Value defaults to undef.
$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 following options affect the methods created as detailed:
Alternatively, an arrayref specifying an interface 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:
See the examples.
Creates methods a, b, c which can be used for both getting and setting the named slots:
use Class::MakeMethods::Emulator::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::MakeMethods::Emulator::MethodMaker
get_set => [ -java => d ];
Creates e_clear, e_get, e_set, f_clear, f_get, f_set methods:
use Class::MakeMethods::Emulator::MethodMaker
get_set => [[undef, '*_clear', '*_get', '*_set'] => qw/e f/ ];
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.
Example:
use Class::MakeMethods::Emulator::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.
Create components containing simple counters that may be read, incremented, or reset. For value x, the methods are:
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:
Baz above. The hash should contain the following keys:
String, for each member of the array. Also works if each
member is a hash reference (see Fob above).
For each slot x, with forwarding methods y and z, the following
methods are created:
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.
x, which is auto-created via new
if necessary. The new, if called, is called without arguments.
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.
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.
Arguments are like object.
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.
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:
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 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.
Much like hash, but uses a tied hash instead.
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:
used the required class.
The first argument can also be an arrayref, specifying multiple components to create.
Example:
tie_hash => [
hits => {
tie => qw/ Tie::RefHash /,
args => [],
},
],
Creates a group of methods for dealing with list data stored by key in a slot.
Takes a string or a reference to an array of strings and for each string, x, creates:
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 [].
and of whether the individual keys exist).
x_pop, but does not actually change any of the lists.
sub { $_[0] == $_[1] }
[undef]
Options:
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:
The difference between this and the get_set manpage is that these scalars are shared across all instances of your object in your process.
Much like hash, but uses a class-based hash instead.
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:
Additionally, boolean defines three class methods:
Creates get/set methods like get_set but also defines a method which returns a list of the slots in the group.
use Class::MakeMethods::Emulator::MethodMaker
grouped_fields => [
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.
struct => [ qw / foo bar baz / ];
Creates methods for setting, checking and clearing values which are stored by position in an array. All the slots created with this meta-method are stored in a single array.
The argument to struct should be a string or a reference to an array of strings. For each string meta-method x, it defines two methods: x and clear_x. x returns the value of the x-slot. If called with an argument, it first sets the x-slot to the argument. clear_x sets the slot to undef.
Additionally, struct defines three class method: struct, which returns a list of all of the struct values, struct_fields, which returns a list of all the slots by name, and struct_dump, which returns a hash of the slot-name/slot-value pairs.
Note: This feature is included but not documented in Class::MethodMaker version 1.
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.
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.
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:
Example Usage:
package Stat;
use Class::MakeMethods::Emulator::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.
If you wish to convert your code from use of the Class::MethodMaker emulator to direct use of Class::MakeMethods, you will need to adjust the arguments specified in your use or make calls.
Often this is simply a matter of replacing the names of aliased method-types listed below with the new equivalents.
For example, suppose that you code contained the following declaration:
use Class::MethodMaker (
counter => [ 'foo' ]
);
Consulting the listings below you can find that counter is an alias for Hash:number --counter and you could thus revise your declaration to read:
use Class::MakeMethods (
'Hash:number --counter' => [ 'foo' ]
);
However, note that those methods marked ``(with custom interface)'' below have a different default naming convention for helper methods in Class::MakeMethods, and you will need to either supply a similar interface or alter your module's calling interface.
Also note that the forward, object, and object_list method types, marked ``(with modified arguments)'' below, require their arguments to be specified differently.
See the Class::MakeMethods::Template::Generic manpage for more information about the default interfaces of these method types.
The following equivalencies are declared for old meta-method names that are now handled by the Hash implementation:
new 'Template::Hash:new --with_values' new_with_init 'Template::Hash:new --with_init' new_hash_init 'Template::Hash:new --instance_with_methods' copy 'Template::Hash:copy' get_set 'Template::Hash:scalar' (with custom interfaces) counter 'Template::Hash:number --counter' get_concat 'Template::Hash:string --get_concat' (with custom interface) boolean 'Template::Hash:bits' (with custom interface) list 'Template::Hash:array' (with custom interface) struct 'Template::Hash:struct' hash 'Template::Hash:hash' (with custom interface) tie_hash 'Template::Hash:tiedhash' (with custom interface) hash_of_lists 'Template::Hash:hash_of_arrays' code 'Template::Hash:code' method 'Template::Hash:code --method' object 'Template::Hash:object' (with custom interface and modified arguments) object_list 'Template::Hash:array_of_objects' (with custom interface and modified arguments) key_attrib 'Template::Hash:string_index' key_with_create 'Template::Hash:string_index --find_or_new'
The following equivalencies are declared for old meta-method names that are now handled by the Static implementation:
static_get_set 'Template::Static:scalar' (with custom interface) static_hash 'Template::Static:hash' (with custom interface)
The following equivalency is declared for the one old meta-method name that us now handled by the Flyweight implementation:
listed_attrib 'Template::Flyweight:boolean_index'
The following equivalencies are declared for old meta-method names that are now handled by the Struct implementation:
builtin_class 'Template::Struct:builtin_isa'
The following equivalencies are declared for old meta-method names that are now handled by the Universal implementation:
abstract 'Template::Universal:croak --abstract' forward 'Template::Universal:forward_methods' (with modified arguments)
In order to enable third-party subclasses of MethodMaker to run under this emulator, several aliases or stub replacements are provided for internal Class::MethodMaker methods which have been eliminated or renamed.
This module aims to provide a 100% compatible drop-in replacement for Class::MethodMaker; if you detect a difference when using this emulation, please inform the author.
There are no known incompatibilities at this time.
The test suite from Class::MethodMaker version 1.02 is included with this package, with all file names prepended with ``7_MethodMaker_''. The tests are unchanged except for the a direct substitution of Class::MakeMethods::Emulator::MethodMaker in the place of Class::MethodMaker.
Note that there was a subtle test error in hash_of_lists.t that only affected some platforms where a hash's keys are returned in an unusual order (ex. Perl 5.7 on Mac OS X); this has been corrected in the included tests and reported to the maintainer of Class::MethodMaker.
In cases where Class::MethodMaker version 0.92's test suite contained
a different version of a test, it is also included. (Note that
version 0.92's get_concat returned '' for empty values, but in
version 0.96 this was changed to undef; this emulator follows the
later behavior. To avoid ``use of undefined value'' warnings from
the 0.92 version of get_concat.t, that test has been modified by
appending a new flag after the name, 'get_concat --noundef',
which restores the earlier behavior.)
See the Class::MethodMaker manpage for more information about the original module.
A good introduction to Class::MethodMaker is provided by pages 222-234 of Object Oriented Perl, by Damian Conway (Manning, 1999).
http://www.browsebooks.com/Conway/
See the Class::MakeMethods manpage for an overview of the method-generation framework this is based on.
See the Class::MakeMethods::Emulator::ReadMe manpage for distribution, installation, version and support information.
|
B |