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.

    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.

    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.

AUTHOR
    (Original) Peter Seibel (Organic Online).

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

    Contributions from:

      Evolution Online Systems, Inc. http://www.evolution.com
      Matthew Persico
      Yitzchak Scott-Thoennes

SEE ALSO


VERSION
    Class::MethodMaker v0.95

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.

  get_set

    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:

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

    COMPATIBILITY: clear_x
        Sets value to undef.  This method is present purely for backward
        compatibility.  Please use  $foo->x (undef)

        instead.  *This method will disappear from the default in time*.

        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.

  EXPERIMENTAL: Options

    There are several options available for controlling the names and
    types of methods created.

    The following options affect the methods created as detailed:

    -java
        Creates get_x and set_x methods, which return the value, and set
        the value (no return), respectively.

    -eiffel
        Creates x and set_x methods, analogous to -java get_x and set_x
        respectively.

    -compatibility
        Creates x (as per the default), and clear_x, which resets the
        slot value to undef.  Use this to ensure backward compatibility.

    -noclear
        Creates x (as per the default) only.  *This will become the
        default in time*.

    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:

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

    1   Creates a method that takes no arguments, sets the slot value to
        undefined, and makes no return.

    2   Creates a method that takes no arguments, and returns the value
        of the slot.

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

  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/ ];

  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  the get_set manpage 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.

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

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

    x_clear
        Resets hash to empty.

  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 the splice entry in the
        perlfunc manpage.

    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 `use'd the required class*.

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

    The first argument can also be an arrayref, specifying multiple
    components to create.

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

  counter

    Create components containing simple counters that may be read,
    incremented, or reset.  For value x, the methods are:

    x   (accepts argument to set),

    incr_x
        (accepts argument for increment size),

    reset_x.
        The counter is implicitly initialized to zero.

ADDDING NEW METHOD TYPES
    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.

    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;

  EXPERIMENTAL: builtin_class

    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:

    new Calls the core func with any given arguments, stores the result
        in the instance.

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

    fields
        Returns pos_list, in the given order.

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

