NAME

SYNOPSIS

  package MyMethodMaker;

  use Rose::Object::MakeMethods;
  our @ISA = qw(Rose::Object::MakeMethods);

  sub widget
  {
    my($class, $name, $args) = @_;

    my $key = $args->{'hash_key'} || $name;
    my $interface = $args->{'interface'} || 'get_set';

    my %methods;

    if($interface =~ /^get_set/)
    {
      $methods{$name} = sub
      {
        my($self) = shift;
        if(@_) { ... }
        ...
        return $self->{$key};
      };
    }

    if($interface eq 'get_set_delete')
    {
      $methods{"delete_$name"} = sub { ... };
    )

    return \%methods;
  }
  ...

  package MyObject;

  sub new { ... }

  use MyMethodMaker
  (
    'widget --get_set_delete' => 'foo',

    'widget' => 
    [
      'bar',
      'baz',
    ]
  );
  ...

  $o = MyObject->new;

  $o->foo($bar);
  $o->delete_foo();

  print $o->bar . $o->baz;
  ...

DESCRIPTION

There are method makers that make both object methods and class methods. The object method makers are in the "Rose::Object::MakeMethods::*" namespace. The class method makers are in the "Rose::Class::MakeMethods::*" namespace for the sake of clarity, but still inherit from Class::MethodMaker and therefore share the same method making interface.

Several useful method makers are included under the "Rose::Object::MakeMethods::*" and "Rose::Class::MakeMethods::*" namespaces, mostly for use by other "Rose::*" objects and classes.

This family of modules is not as powerful or flexible as the one that inspired it: Class::MethodMaker. I found that I was only using a tiny corner of the functionality provided by Class::MethodMaker, so I wrote this as a simple, smaller replacement.

The fact that many "Rose::*" modules use Rose::Object::MakeMethods subclasses to make their methods should be considered an implementation detail that can change at any time.

CLASS METHODS

allow_apparent_reload [BOOL]

Get or set an attribute that determines whether or not to allow an attempt to re-make the same method using the same class that made it earlier. The default is true.

This issue comes up when a module is forcibly reloaded, e.g., by Apache::Reload or Apache::StatINC. When this happens, all the "make methods" actions will be attempted again. In the absence of the "preserve_existing" or "override_existing" options, the allow_apparent_reload attribute will be consulted. If it's true, and if it appears that the method in question was made by this method-maker class, then it behaves as if the "preserve_existing" option had been passed. If it is false, then a fatal "method redefined" error will occur.

import SPEC

The "import" class method is mean to be called implicitly as a result of a "use" statement. For example:

    use Rose::Object::MakeMethods::Generic
    (
      SPEC
    );
    

is roughly equivalent to:

    require Rose::Object::MakeMethods::Generic;
    Rose::Object::MakeMethods::Generic->import(SPEC);
    

where SPEC is a series of specifications for the methods to be created. (But don't call import explicitly; use make_methods instead.)

In response to each method specification, one or more methods are created.

The first part of the SPEC argument is an optional hash reference whose contents are intended to modify the behavior of the method maker class itself, rather than the individual methods being made. There are currently only two valid arguments for this hash:

   bitfield => 'my_bits'

   bitfield => [ 'my_bits' ],

   bitfield => [ 'my_bits' => {} ],

   'bitfield --opt1=2' => 'my_bits'

   'bitfield --opt1=2' => [ 'my_bits' ]

   bitfield => [ 'my_bits' => { opt1 => 2 } ]

   'bitfield --opt1=2 --opt2=7' => 'my_bits'

   'bitfield --opt1=2 --opt2=7' => [ 'my_bits' ]

   bitfield => [ 'my_bits' => { opt1 => 2, opt2 => 7 } ]

   'bitfield --opt2=7' => [ 'my_bits' => { opt1 => 2 } ]

   'bitfield --opt1=99' => 'my_bits'

   'bitfield --opt1=5' => [ 'my_bits' => { opt1 => 99 } ]

    'bitfield --foobar' => 'my_bits'

    'bitfield --interface=foobar' => 'my_bits'

    bitfield => [ my_bits => { interface => 'foobar' } ]

    'bitfield --foobar --baz' => 'my_bits'

    'bitfield --interface=foobar --baz=1' => 'my_bits'

    bitfield => 
    [
      my_bits => { interface => 'foobar', baz => 1 }
    ]

     'bitfield --opt1=2' => 
     [
       'my_bits1',
       'my_bits2',
       'my_bits3',
     ]

     bitfield => 
     [
       'my_bits1' => { opt1 => 2 },
       'my_bits2' => { opt1 => 2 },
       'my_bits3' => { opt1 => 2 },
     ]

     'bitfield --opt1=2' => 
     [
       'my_bits1',
       'my_bits2',
       'my_bits3' => { opt1 => 999 },
     ]

    use Rose::Object::MakeMethods::Generic
    (
      { override_existing => 1 },

      'bitfield' => [ qw(my_bits other_bits) ],

      'bitfield --opt1=5' => 
      [
        'a',
        'b',
      ],

      'bitfield' =>
      [
        'c',
        'd' => { opt2 => 7 },
        'e' => { opt1 => 1 },
        'f' => { }, # empty is okay too
      ]
    );

make_methods SPEC

This method is equivalent to the "import" method, but makes the intent of the code clearer when it is called explicitly. (The "import" method is only meant to be called implicitly by "use".)

SUBCLASSING

The subroutine will be passed three arguments when it is called:

• The class of the method maker as a string. This argument is usually ignored unless you are going to call some other class method.
• The method name. In the common case, a single method with this name is defined, but you are free to do whatever you want with it, including ignoring it.
• A reference to a hash containing the options for the method.

The subroutine is expected to return a reference to a hash containing name/code reference pairs. Note that the subroutine does not actually install the methods. It simple returns the name of each method that is to be installed, along with references to the closures that contain the code for those methods.

This subroutine is called for each name in the method specifier. For example, this would result in three separate calls to the "bitfield" subroutine of the "MyMethodMaker" class:

    use MyMethodMaker
    (
      bitfield => 
      [
        'my_bits',
        'your_bits'  => { size => 32 },
        'other_bits' => { size => 128 },
      ]
    );

So why not have the subroutine return a single code reference rather than a reference to a hash of name.code reference pairs? There are two reasons.

First, remember that the name argument ("my_bits", "your_bits", "other_bits") may be modified or ignored by the method maker. The actual names of the methods created are determined by the keys of the hash reference returned by the subroutine.

Second, a single call with a single method name argument may result in the creation more than one method--usually a "family" of methods. For example:

    package MyObject;

    use MyMethodMaker
    (
      # creates add_book(), delete_book(), and books() methods
      'hash --manip' => 'book',
    );
    ...

    $o = MyObject->new(...);

    $o->add_book($book);

    print join("\n", map { $_->title } $o->books);

    $o->delete_book($book);

Here, the "hash" method type elected to create three methods by prepending "add_" and "delete_" and appending "s" to the supplied method name argument, "book".

Anything not specified in this documentation is simply a matter of convention. For example, the Rose::Object::MakeMethods subclasses all use a common set of method options: "hash_key", "interface", etc. As you read their documentation, this will become apparent.

Finally, here's an example of a subclass that makes scalar accessors:

    package Rose::Object::MakeMethods::Generic;

    use strict;
    use Carp();

    use Rose::Object::MakeMethods;
    our @ISA = qw(Rose::Object::MakeMethods);

    sub scalar
    {
      my($class, $name, $args) = @_;

      my %methods;

      my $key = $args->{'hash_key'} || $name;
      my $interface = $args->{'interface'} || 'get_set';

      if($interface eq 'get_set_init')
      {
        my $init_method = $args->{'init_method'} || "init_$name";

        $methods{$name} = sub
        {
          return $_[0]->{$key} = $_[1]  if(@_ > 1);

          return defined $_[0]->{$key} ? $_[0]->{$key} :
            ($_[0]->{$key} = $_[0]->$init_method());
        }
      }
      elsif($interface eq 'get_set')
      {
        $methods{$name} = sub
        {
          return $_[0]->{$key} = $_[1]  if(@_ > 1);
          return $_[0]->{$key};
        }
      }
      else { Carp::croak "Unknown interface: $interface" }

      return \%methods;
    }

It can be used like this:

    package MyObject;

    use Rose::Object::MakeMethods::Generic
    (
      scalar => 
      [
        'power',
        'error',
      ],

      'scalar --get_set_init' => 'name',
    );

    sub init_name { 'Fred' }
    ...

    $o = MyObject->new(power => 5);

    print $o->name; # Fred

    $o->power(99) or die $o->error;

This is actually a subset of the code in the actual Rose::Object::MakeMethods::Generic module. See the rest of the "Rose::Object::MakeMethods::*" and "Rose::Class::MakeMethods::*" modules for more examples.

AUTHOR

LICENSE