NAME

Class::MakeMethods::Guide - Getting Started Guide

SYNOPSIS

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

DESCRIPTION

Object-oriented Perl code is widespread -- you've probably seen code like the below a million times:

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

(If this doesn't look familiar, take a moment to read perltoot and you'll soon learn more than's good for you.)

Typically, this involves creating numerous subroutines that follow a handful of common patterns, like constructor methods and accessor methods. These methods are generally quite simple, requiring only a couple of lines of Perl, but in sufficient bulk, they can cut down on the maintainability of large classes.

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

  sub summary {
    my $self = shift;
    join(', ', map { "\u$_: " . $self->$_() } qw( foo bar ) )
  }

Note in particular that the foo and bar methods are almost identical; this is precisely the type of redundancy Class::MakeMethods addresses.

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',
  );
  
  sub summary {
    my $self = shift;
    join(', ', map { "\u$_: " . $self->$_() } qw( foo bar ) )
  }

This is the basic purpose of Class::MakeMethods: The "boring" pieces of code have been replaced by succinct declarations, placing the focus on the "unique" or "custom" pieces.

The remaining complexity described in this document basically boils down to figuring out which arguments to pass to generate the specific methods you want.

CLASS ARCHITECTURE

Because there are so many common types of methods one might wish to generate, the Class::MakeMethods framework provides an extensible system based on subclasses.

When your class requests a method, the base class performs some standard argument parsing, delegates the construction of the actual method to the appropriate subclass, and then installs whatever method the subclass returns.

What the Base Class Does

The Class::MakeMethods package defines a superclass for method-generating modules, and provides a calling convention and subroutine installation mechanism that will be shared by all subclasses.

The superclass also lets you generate several different types of methods in a single call, and will automatically load named subclasses the first time they're used.

What the Subclass Does

The type of method that gets created is controlled by the specific subclass and generator-method you request. For example, Class::MakeMethods::Standard::Hash has a generator-method scalar(), which is responsible for generating simple scalar-accessor methods for blessed-hash objects.

Because each subclass defines its own set of method types and customization options, a key step is to find your way to the appropriate subclasses, which is the subject of the next section.

CHOOSING A SUBCLASS

Standard

Generally you will want to begin with the Standard::Hash subclass, to create constructor and accessor methods for working with blessed-hash objects (or you might choose the Standard::Array subclass instead). The Standard::Global subclass provides methods for class data shared by all objects in a class.

Each Standard method declaration can optionally include a hash of associated parameters, which allows you to tweak some of the characteristics of the methods. Subroutines are bound as closures to a hash of each method's name and parameters. Standard::Hash and Standard::Array provide object constructor and accessors. The Standard::Global provides for static data shared by all instances and subclasses, while the data for Standard::Inheritable methods trace the inheritance tree to find values, and can be overriden for any subclass or instance.

See Class::MakeMethods::Standard for more. A listing of available method types is provided in "SUBCLASS CATALOG" in Class::MakeMethods::Standard.

Basic

The Basic subclasses provide stripped down method generators with no configurable options, for minimal functionality (and minimum overhead).

Subroutines are bound as closures to the name of each method. Basic::Hash and Basic::Array provide simple object constructors and accessors. Basic::Global provides basic global-data accessors.

See Class::MakeMethods::Basic for more. A listing of available method types is provided in "SUBCLASS CATALOG" in Class::MakeMethods::Basic.

Composite

For additional customization options, check out the Composite subclasses, which allow you to select from a more varied set of implementations and which allow you to adjust any specific method by adding your own code-refs to be run before or after it.

Subroutines are bound as closures to a hash of each method's name and optional additional data, and to one or more subroutine references which make up the composite behavior of the method. Composite::Hash and Composite::Array provide object constructor and accessors. The Composite::Global provides for static data shared by all instances and subclasses, while the data for Composite::Inheritable methods can be overriden for any subclass or instance.

See Class::MakeMethods::Composite for more. A listing of available method types is provided in "SUBCLASS CATALOG" in Class::MakeMethods::Composite.

Template

Finally, the Template subclasses provide an open-ended structure for objects that assemble Perl code on the fly into cachable closure-generating subroutines; if the method you need isn't included, you can extend existing methods by re-defining just the snippet of code that's different.

Class::MakeMethods::Template extends MakeMethods with a text templating system that can assemble Perl code fragments into a desired subroutine. The code for generated methods is eval'd once for each type, and then repeatedly bound as closures to method-specific data for better performance.

Templates for dozens of types of constructor, accessor, and mutator methods are included, ranging from from the mundane (constructors and value accessors for hash and array slots) to the esoteric (inheritable class data and "flyweight" accessors with external indexes).

See Class::MakeMethods::Template for more. A listing is provided in "SUBCLASS CATALOG" in Class::MakeMethods::Template.

Emulation Adaptors

In several cases, Class::MakeMethods provides functionality closely equivalent to that of an existing module, and it is simple to map the existing module's interface to that of Class::MakeMethods.

Emulators are included for Class::MethodMaker, Class::Accessor::Fast, Class::Data::Inheritable, Class::Singleton, and Class::Struct, each of which passes the original module's test suite, usually requiring only a single-line change.

Extensible

Other subclasses may be available separately, or you can define your own for future use. (See "EXTENDING" in Class::MakeMethods.)

USAGE

See "USAGE" in Class::MakeMethods for a guide to the calling conventions that apply to all subclasses.

Naming Convention

When you use Class::MakeMethods, you can refer to the scalar() method provided by the Class::MakeMethods::Standard::Hash class as "Standard::Hash:scalar", and this document will also use that notation.

The names used by the included subclasses and method types reflect three axes of variation, "Group::Subclass:MethodType":

Group

Each group shares a similar style of technical implementation and level of complexity. For example, the Standard::* packages are all simple, while the Composite::* packages all support pre- and post-conditions.

(For a listing of the four main groups of included subclasses, see "SUBCLASS GROUPS", below.)

Subclass

Each subclass generates methods for a similar level of scoping or underlying object type. For example, the *::Hash packages all make methods for objects based on blessed hashes, while the *::Global packages make methods that access class-wide data that will be shared between all objects in a class.

Method Type

Each method type produces a similar type of constructor or accessor. For examples, the *:new methods are all constructors, while the ::scalar methods are all accessors that allow you to get and set a single scalar value.

Bearing that in mind, you should be able to guess the intent of many of the method types based on their names alone; when you see "Standard::Array:list" you can read it as "a type of method to access a list of data stored in an array object, with a standard implementation style" and know that it's going to call Class::MakeMethods::Standard::Array->list().

Mixing Method Types

In general, you can combine method-generators from different MakeMethods subclasses; the only mixing that's problematic is combinations of methods which depend on different underlying object types, like using *::Hash and *::Array methods together.

I frequently mix and match various *::Hash methods, with a scattering of Global or Inheritable methods. The "Subclass:method" syntax is useful here, allowing you to mix and match in a single use statement:

  use Class::MakeMethods
    'Template::Hash:scalar'   => 'foo',
    'Composite::Hash:scalar'  => [ 'bar' => { post_rules => [] } ],
    'Standard::Global:scalar' => 'our_shared_baz';

About Precedence

Rather than passing the method declaration arguments when you use one of these packages, you may instead pass them to a subsequent call to the class method make.

The difference between use and make is primarily one of precedence; the use keyword acts as a BEGIN block, and is thus evaluated before make would be. In particular, a use at the top of a file will be executed before any subroutine declarations later in the file have been seen, whereas a make at the same point in the file will not.

By default, Class::MakeMethods will not install generated methods over any pre-existing methods in the target class. To override this you can pass -ForceInstall => 1 as initial arguments to use or make.

If methods with the same name already exist, earlier calls to use or make() win over later ones, but within each call, later declarations superceed earlier ones.

Here are some examples of the results of these precedence rules:

  # 1
  use Class::MakeMethods::Standard::Hash (
    'scalar'=>['baz'] # baz() not seen yet, so we generate, install
  );
  sub baz { 1 } # Subsequent declaration overwrites it, with warning
  
  # 2
  sub foo { 1 }
  use Class::MakeMethods::Standard::Hash (
    'scalar'=>['foo'] # foo() is already declared, so has no effect
  );
  
  # 3
  sub bar { 1 }
  use Class::MakeMethods::Standard::Hash ( 
      -ForceInstall => 1, # Set flag for following methods...
    'scalar' => ['bar']   # ... now overwrites pre-existing bar()
  );
  
  # 4
  Class::MakeMethods::Standard::Hash->make(
    'scalar'=>['blip'] # blip() is already declared, so has no effect
  );
  sub blip { 1 } # Although lower than make(), this "happens" first
  
  # 5
  sub ping { 1 } 
  Class::MakeMethods::Standard::Hash->make(
      -ForceInstall => 1, # Set flag for following methods...
    'scalar' => ['ping']  # ... now overwrites pre-existing ping()
  );

EXAMPLES

The following examples indicate some of the capabilities of Class::MakeMethods.

Adding Custom Initialization to Constructors

Frequently you'll want to provide some custom code to initialize new objects of your class. Most of the *:new constructor methods provides a way to ensure that this code is consistently called every time a new instance is created.

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'
    'Template::Hash: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'
    'Template::Hash: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' )

Composite::Hash:new ... post_rules=>[...]

The recently added 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' )

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.

Mixing Object and Global Methods

Here's a package declaration using two of the included subclasses, Standard::Hash, for creating and accessing hash-based objects, and Basic::Global, for simple global-value accessors:

  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
  }

Access Control Example

The following defines a secret_password method, which will croak if it is called from outside of the declaring package.

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

Similar functionality is also available as:

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

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

TEMPLATE EXAMPLES

The examples in this section all use Class::MakeMethods::Template subclasses.

String and Numeric Accessors

You can store arbitrary values using the scalar accessors declared above, but the Template subclasses also provide other more specialized accessors that can facilitate the use of specific types of data.

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()
  }

The basic usage of this class is similar to the one we defined above:

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

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

Reference Accessor and Helper Methods

For references to arrays and hashes, the Template subclasses provide accessors with extra "helper methods" to facilitate method-based interaction.

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 $obj = MySearchPath->new( name=>"libs", directories=>['/usr/lib'] );
  $obj->push_directories( '/usr/local/lib' );
  print "Searching in " . $obj->count_directories() . "directories.\n";
  foreach ( 'libtiff', 'libjpeg' ) {
    print "Checking $_: " . ( $obj->search("$_.so") || 'not found' ) . "\n";
  }

Note the use of the push_* and count_* "helper" accessor methods, which are defined by default for all '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

There's also a specialized accessor for object references:

  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(@_) 
  }

Tree Structure Example

In this example we will create a pair of classes with references to other objects.

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

Changing Method Names

The Template subclasses allow you to control the names assigned to the methods you generate by selecting from several naming interfaces.

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");

Lazy-Init Interface

Templapte scalar accessors declared with the "init_and_get" interface can be used for "memoization" or lazy-evaluation for object attributes. If the current accessor value is undefined, they will first call a user-provided init_* method and save its value.

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

String Concatenation Interface

The following defines a get_concat method i, and specifies a string to use when joining additional values when this method is called.

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

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

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

CLASS ARCHITECTURE

What the Base Class Does

What the Subclass Does

CHOOSING A SUBCLASS

Standard

Basic

Composite

Template

Emulation Adaptors

Extensible

USAGE

Naming Convention

Mixing Method Types

About Precedence

EXAMPLES

Adding Custom Initialization to Constructors

Mixing Object and Global Methods

Access Control Example

TEMPLATE EXAMPLES

String and Numeric Accessors

Reference Accessor and Helper Methods

Object Accessors

Tree Structure Example

Changing Method Names

Lazy-Init Interface

String Concatenation Interface

SEE ALSO

Getting-Started Resources

Package Documentation

NAME

SYNOPSIS

DESCRIPTION

CLASS ARCHITECTURE

What the Base Class Does

What the Subclass Does

CHOOSING A SUBCLASS

Standard

Basic

Composite

Template

Emulation Adaptors

Extensible

USAGE

Naming Convention

Mixing Method Types

About Precedence

EXAMPLES

Adding Custom Initialization to Constructors

Mixing Object and Global Methods

Access Control Example

TEMPLATE EXAMPLES

String and Numeric Accessors

Reference Accessor and Helper Methods

Object Accessors

Tree Structure Example

Changing Method Names

Lazy-Init Interface

String Concatenation Interface

SEE ALSO

Getting-Started Resources

Package Documentation

Module Install Instructions