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.

  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
    `map'ing 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 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.

    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.

  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
        `use'd 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
    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.

  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;
