A Contrived Example

  my $obj = MyStruct->new( foo=>"Foozle", bar=>"Bozzle" );
  if ( $obj->foo() =~ /foo/i ) {
    $obj->bar("Barbados!");
  }

Here's a possible implementation for the class whose interface is shown above:

  package MyStruct;
  
  sub new {
    my $callee = shift;
    my $self = bless { @_ }, (ref $callee || $callee);
    return $self;
  }

  sub foo {
    my $self = shift;
    if ( scalar @_ ) {
      $self->{'foo'} = shift();
    } else {
      $self->{'foo'}
    }
  }

  sub bar {
    my $self = shift;
    if ( scalar @_ ) {
      $self->{'bar'} = shift();
    } else {
      $self->{'bar'}
    }
  }

Class::MakeMethods allows you to simply declare those methods to be of a predefined type, and it generates and installs the necessary methods in your package at compile-time.

Here's the equivalent declaration for that same basic class:

  package MyStruct;
  use Class::MakeMethods::Standard::Hash (
    'new'       => 'new',
    'scalar'    => 'foo',
    'scalar'    => 'bar',
  );

A Typical Example

  package MyObject;
  use Class::MakeMethods::Standard::Hash (
    new => 'new',
    scalar => [ 'foo', 'bar' ],
    array => 'my_list',
    hash => 'my_index',
  );

This class now has a constructor named new, two scalar accessors named foo and bar, and a pair of reference accessors named my_list and my_index. Typical usage of the class might include calls like the following:

  my $obj = MyObject->new( foo => 'Foozle' );
  print $obj->foo();
  
  $obj->bar('Barbados'); 
  print $obj->bar();
  
  $obj->my_list(0 => 'Foozle', 1 => 'Bang!');
  print $obj->my_list(1);
  
  $obj->my_index('broccoli' => 'Blah!', 'foo' => 'Fiddle');
  print $obj->my_index('foo');

Lvalue Accessors

  package MyStruct;
  use Class::MakeMethods::Template::Hash (
    'new'                   => 'new',
    'scalar --get --lvalue' => 'foo',
    'array --get --lvalue'  => 'bar',
  );

  $obj->foo = "Foozle";
  print $obj->foo;

  $obj->bar = ( 'baz', 'beep', 'boop' );
  print $obj->bar->[1]; # beep

String and Numeric Accessors

For example, we could declare the following class to hold information about available Perl packages:

  package MyVersionInfo;
  use Class::MakeMethods::Template::Hash (
    'new'     => 'new',
    'string'  => 'package',
    'number'  => 'version',
  );

  sub summary {
    my $self = shift;
    return $self->package() . " is at version " . $self->version()
  }

You could use this class as follows:

  package main;
  use MyVersionInfo;
  
  my $obj = MyVersionInfo->new( package=>"Class::MakeMethods");
  $obj->version( 2.0 );
  print $obj->summary();

These accessors will provide a bit of diagnostic type checking; an attempt to call "$obj->version("foo")" will cause your program to croak.

String Concatenation Interface

  use Class::MakeMethods::Template::Hash
    'string' => [ '--get_concat', 'i', { join => ' - ' } ];

(See Class::MakeMethods::Template::Generic for information about the "string" "get_concat" interface.)

Access Control Example

  use Class::MakeMethods::Composite::Hash
    'scalar' => [ 'secret_password' => { permit => 'pp' } ];

(See Class::MakeMethods::Composite for information about the "permit" modifier.)

For template classes, the same thing is accomplished with '--private':

  use Class::MakeMethods::Template::Hash
    'scalar' => [ '--private', 'secret_password' ];

(See Class::MakeMethods::Template::Universal for information about the "private" modifier.)

Lazy-Init Interface

  package MyWidget;
  use Class::MakeMethods::Template::Hash (
    'new --with_values' => [ 'new' ],
    'scalar --init_and_get' => [ 'foo', 'count', 'result' ],
  );
  
  sub init_foo { 
    return 'foofle';
  }
  
  sub init_count {
    return '3';
  }
  
  sub init_result {
    my $self = shift;
    return $self->foo x $self->count;
  }
  ...
  
  my $widget = MyWidget->new();
  print $widget->result; # output: fooflefooflefoofle
  
  # if values are predefined, the init methods are not used
  my $other_widget = MyWidget->new( foo => 'bar', count => 2 );
  print $widget->result; # output: barbar

(See Class::MakeMethods::Template::Generic for more information about "init_and_get". This interface is also supported by all of Generic's subclasses, so you can add lazy-init methods for global data, class data, array objects, etc. Unfortunately, to date it is only supported for scalar-value accessors...)

Helper Methods

  package MyClass;
  use Class::MakeMethods::Template::Hash('scalar --with_clear' => 'foo');

  my $obj = MyClass->new;
  $obj->foo(23);
  $obj->clear_foo;
  print $obj->foo();

Reference Accessor and Helper Methods

Here's a class whose instances each store a string and an array reference, along with a method to search the directories:

  package MySearchPath;
  use Class::MakeMethods::Template::Hash (
    'new'     => 'new',
    'string'  => 'name',
    'array'   => 'directories',
  );
  
  sub search {
    my $self = shift; 
    my $target = shift;
    foreach my $dir ( $self->directories ) {
      my $candidate = $dir . '/' . $target;
      return $candidate if ( -e $candidate );
    }
    return;
  }

Note that the directories accessor returns the contents of the array when called in a list context, making it easier to loop over.

And here's a sample usage:

  package main;
  use MySearchPath;
  
  my $libs = MySearchPath->new( name=>"libs", directories=>['/usr/lib'] );
  $libs->push_directories( '/usr/local/lib' );
  
  print "Searching in " . $libs->count_directories() . "directories.\n";
  foreach ( 'libtiff', 'libjpeg' ) {
    my $file = $libs->search("$_.so"); 
    print "Checking $_: " . ( $file || 'not found' ) . "\n";
  }

Note the use of the push_* and count_* "helper" accessor methods, which are defined by default for all 'Template::*:array' declarations.

Consult Class::MakeMethods::Template::Generic for more information about the available types of reference accessors, and the various methods they define.

Object Accessors

  package MyStruct;
  use Class::MakeMethods::Template::Hash (
    'new'    => 'new',
    'object' => [ 'widget' => {class=>'MyWidgetClass', delegate=>"twiddle"} ],
  );

(Note that the "class" and "delegate" values specified above are method parameters, which provide additional information about the "widget" declaration; see "Standard Declaration Syntax" for more information.)

The above declaration creates methods equivalent to the following:

  package MyStruct;

  sub widget {
    my $self = shift;
    if ( scalar @_ ) { 
      if (ref $_[0] and UNIVERSAL::isa($_[0], 'MyWidgetClass')) { 
        $self->{widget} = shift;
      } else {
        $self->{widget} = MyWidgetClass->new(@_);
      }
    } else {
      return $self->{widget};
    }
  }
  
  sub clear_widget {
    my $self = shift;
    $self->{widget} = undef;
  }
  
  sub twiddle { 
    my $self = shift;
    my $obj = $self->widget() 
      or Carp::croak("Can't forward twiddle because widget is empty");
    $obj->twiddle(@_) 
  }

Mixing Object and Global Methods

  package MyQueueItem;
  
  use Class::MakeMethods::Standard::Hash (
    new => { name => 'new', defaults=>{ foo => 'Foozle' } },
    scalar => [ 'foo', 'bar' ],
    hash => 'history'
  );
  
  use Class::MakeMethods::Basic::Global (
    scalar => 'Debug',
    array  => 'InQueue',
  );
  
  sub AddQueueItem {
    my $class = shift;
    my $instance = shift;
    $instance->history('AddQueueItem' => time());
    $class->InQueue([0, 0], $instance);    
  }
  
  sub GetQueueItem {
    my $class = shift;
    $class->InQueue([0, 1], []) or $class->new
  }

Adding Custom Initialization to Constructors

Composite::Hash:new { post_rules => [] }

The Composite classes allow you to add pre- and post-operations to any method, so you can pass in a code-ref to be executed after the new() method.

  package MyClass;
  
  sub new_post_init {
    my $self = ${(pop)->{result}}; # get result of original new()
    length($self->foo) or $self->foo('FooBar');   # default value
    warn "Initialized new object '$self'";       
  }
  
  use Class::MakeMethods (
    'Composite::Hash:new' => [
        'new' => { post_rules=>[ \&new_post_init ] } 
    ],
    'Composite::Hash:scalar' => 'foo;,
  );
  ... 
  package main;
  my $self = MyClass->new( foo => 'Foozle' )
    

Template::Hash:new --and_then_init

Use 'Template::Hash:new --and_then_init', which will first create the object and initialize it with the provided values, and then call an init() method on the new object before returning it.

  package MyClass;
  use Class::MakeMethods::Template::Hash (
    'new --and_then_init' => 'new'
    'string'  => 'foo'
  );
  sub init {
    my $self = shift;
    length($self->foo) or $self->foo('FooBar');   # default value
    warn "Initialized new object '$self'";       
  }
  ... 
  package main;
  my $self = MyClass->new( foo => 'Foozle' )
    

Template::Hash:new --with_init

If you don't want your constructor to use the default hash-of-method-names style of initialization, use 'Template::Hash:new --with_init', which will create an empty object, pass its arguments to the init() method on the new object, and then return it.

  package MyClass;
  use Class::MakeMethods::Template::Hash (
    'new --with_init' => 'new'
    'string'  => 'foo'
  );
  sub init {
    my $self = shift;
    $self->foo( shift || 'FooBar' ); # init with arg or default
    warn "Initialized new object '$self'";       
  }
  ... 
  package main;
  my $self = MyClass->new( 'Foozle' )
    

Some additional notes about these constructors:

• The "Template::*:new" methods allow you to specify a name for your method other than "init" by passing the "init_method" parameter:

    use Class::MakeMethods::Template::Hash (
      'new --and_then_init' => [ 
          'new' => { init_method =>  'my_init' } 
      ],
    );
      

• If you know that you're not going to have a complex class hierarchy, you can reduce resource consumption a bit by changing the above declarations from "*::Hash" to "*::Array" so your objects end up as blessed arrays rather than blessed hashes.

Changing Method Names

For example, the accessors declared above use a default, Perl-ish style interface, in which a single method can be called without an argument to retrieve the value, or with an argument to set it. However, you can also select a more Java-like syntax, with separate get* and set* methods, by including the '--java' template specification:

  package MyStruct;
  use Class::MakeMethods::Template::Hash (
    'new'     => 'new',
    'scalar'  => '--java Foo',
  );

(Note that the declaration of Foo could also have been written as 'scalar --java' => 'Foo' or "'scalar' => ['--java', 'Foo']", or "'scalar' => [ 'foo' =" { 'interface'=>'java' } ], all of which are interpreted identically; see the Class::MakeMethods section on "Argument Normalization" for details.)

Usage of this accessor would then be as follows:

  package main;
  use MyStruct;
  
  my $obj = MyStruct->new( setFoo => "Foozle" );
  print $obj->getFoo();
  $obj->setFoo("Bozzle");

Selecting Specific Helper Methods

For example, let's say you wanted to use a Template::Hash:array, but you only wanted two methods to be installed in your class, a foo() accessor and a shift_foo() mutator. Any of the below combinations of syntax should do the trick:

  use Class::MakeMethods::Template::Hash
    'array' => [
      'foo' => { interface=>{'foo'=>'get_set', 'shift_foo'=>'shift'} },
    ];

If you're going to have a lot of methods with the same interface, you could pre-declare a named interface once and use it repeatedly:

  BEGIN {
    require Class::MakeMethods::Template::Hash;
    Class::MakeMethods::Template::Hash->named_method('array')->
        {'interface'}->{'my_get_set_shift'} =
            { '*'=>'get_set', 'shift_*'=>'shift' };
  }

  use Class::MakeMethods::Template::Hash
    'array --my_get_set_shift' => [ 'foo', 'bar' ];

Tree Structure Example

The first class is a single-value data object implemented as a reference to a scalar.

  package MyTreeData;
  use Class::MakeMethods::Template::Scalar (
    'new'     => 'new',
    'string'  => 'value',
  );

The second class defines a node in a tree, with a constructor, an accessor for a data object from the class above, and accessors for a list of child nodes.

  package MyTreeNode;
  use Class::MakeMethods::Template::Hash (
    'new'     => 'new',
    'object -class MyTreeData'  => 'data',
    'array_of_objects -class MyTreeNode' => 'children',
  );
  
  sub depth_first_data {
    my $self = shift;
    return $self->data, map { $_->depth_first_data() } $self->children;
  }

Here's a sample of how the above classes could be used in a program.

  package main;
  use MyTreeData;
  use MyTreeNode;

  my $node = MyTreeNode->new( 
      data => { value=>'data1' }, 
      children => [ { value=>'data3' } ] 
  );
  $node->push_children( MyTreeNode->new( data => { value=>'data2' } ) );
  
  foreach my $data ( $node->depth_first_data ) {
    print $data->value();
  }

Annotated Tutorials

  http://savage.net.au/Perl-tutorials.html
  http://savage.net.au/Perl-tutorials/tut-33.tgz
  http://savage.net.au/Perl-tutorials/tut-34.tgz