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.

AUTHOR

(Original) Peter Seibel (Organic Online).

Evolution Online Systems, Inc. http://www.evolution.com

Current Maintainer: Martyn J. Pearce fluffy@engineer.com

SEE ALSO

VERSION

Class::MethodMaker v0.93

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 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.

    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:

x

If an argument is provided, sets a new value for x. Returns (new) value. Value defaults to undef.

clear_x

Sets value to 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.

static_get_set

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:

x

If an argument is provided, sets a new value for x. Returns (new) value. Value defaults to undef.

clear_x

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.

get_concat

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.

grouped_fields

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.

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.

    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:

Hash Reference

See Baz above. The hash should contain the following keys:

slot

The name of the instance attribute (slot).

comp_mthds

A stringor array ref, naming the methods that will be forwarded directly to the object in the slot.

Array Reference

As for String, for each member of the array. Also works if each member is a hash reference (see Fob above).

String

The name of the instance attribute (slot).

For each method definition 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 is not filled yet it creates an object by calling the given new method of the given class. 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.

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 hash 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.

object_list

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

  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.

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

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

Equivalent to x(1).

clear_x

Equivalent to x(0).

Additionally, boolean defines three class methods:

bits

Returns the vector containing all of the bit fields (remember however that a vector containing all 0 bits is still true).

boolean_fields

Returns a list of all the flags by name.

bit_dump

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

This method 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.

push_x
pop_x
shift_x
unshift_x
splice_x
clear_x
count_x

Returns the number of elements in x.

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

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.

x_keys

Returns the keys of the hash.

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.

x_exists

Takes a single key, returns whether that key exists in the hash.

x_delete

Takes a list, deletes each key from the hash.

hash_of_lists

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:

x

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 [].

x_keys

Returns the keys of the hash. As an arrayref in scalar context.

x_exists

Takes a list of keys, and returns whether each key exists in the hash (i.e., the and of whether the individual keys exist).

x_delete

Takes a list, deletes each key from the hash.

x_push

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.

x_pop

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.

x_unshift

Like push, only the from the other end of the lists.

x_shift

Like pop, only the from the other end of the lists.

x_splice

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.

x_clear

Takes a list of keys. Resets each named list to empty (but does not delete the keys.)

x_count

Takes a list of keys. Returns the sum of the number of elements for each named list.

x_index

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.

x_remove

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).

x_sift

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.

filter

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] }
keys

The list keys to sift through (as an arrayref). Unknown keys are ignored. Default: all the known keys.

values

The values to sift out (as an arrayref). Default: [undef]

tie_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:

tie

Required. The name of the class to tie to. Make sure you have used the required class.

args

Required. Additional arguments for the tie, as an array ref.

Example:

   tie_hash     => [
                    hits        => {
                                    tie => qw/ Tie::RefHash /,
                                    args => [],
                                   },
                   ],

static_hash

Much like hash, but uses a class-based hash instead.

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 its first argument. Basically, you're creating a method which can be different for each object. Which is sort of weird. But perhaps useful.

abstract

  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.

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:

  package Class::MethodMakerSubclass;

  use strict;
  use Class::MethodMaker;

  @Class::MethodMakerSubclass::ISA = qw ( Class::MethodMaker );

  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;
  }

  1;