Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MakeMethods(3)	      User Contributed Perl Documentation	MakeMethods(3)

NAME
       Class::MakeMethods - Generate common types of methods

SYNOPSIS
	 # Generates methods for your object when you "use" it.
	 package MyObject;
	 use Class::MakeMethods::Standard::Hash	(
	   'new'       => 'new',
	   'scalar'    => 'foo',
	   'scalar'    => 'bar',
	 );

	 # The generated methods can be	called just like normal	ones
	 my $obj = MyObject->new( foo => "Foozle", bar => "Bozzle" );
	 print $obj->foo();
	 $obj->bar("Barbados");

DESCRIPTION
       The Class::MakeMethods framework	allows Perl class developers to
       quickly define common types of methods. When a module "use"s
       Class::MakeMethods or one of its	subclasses, it can select from a
       variety of supported method types, and specify a	name for each method
       desired.	The methods are	dynamically generated and installed in the
       calling package.

       Construction of the individual methods is handled by subclasses.	 This
       delegation approach allows for a	wide variety of	method-generation
       techniques to be	supported, each	by a different subclass. Subclasses
       can also	be added to provide support for	new types of methods.

       Over a dozen subclasses are available, including	implementations	of a
       variety of different method-generation techniques. Each subclass
       generates several types of methods, with	some supporting	their own
       open-eneded extension syntax, for hundreds of possible combinations of
       method types.

GETTING	STARTED
   Motivation
	 "Make easy things easier."

       This module addresses a problem encountered in object-oriented
       development wherein numerous methods are	defined	which differ only
       slightly	from each other.

       A common	example	is accessor methods for	hash-based object attributes,
       which allow you to get and set the value	$self->{'foo'} by calling a
       method $self->foo().

       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.

       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.

   A Contrived Example
       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 perlboot 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.	The classic example is accessor	methods	for hash-based object
       attributes, which allow you to get and set the value self->{foo}	by
       calling a method	self->foo().  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,
       and that	the new	method could be	used for almost	any class; 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.

   Finding the Method Types You	Need
       Once you've grasped the basic idea -- simplifying repetitive code by
       generating and installing methods on demand -- the remaining complexity
       basically boils down to figuring	out which arguments to pass to
       generate	the specific methods you want.

       Unfortunately, this is not a trivial task, as there are dozens of
       different types of methods that can be generated, each with a variety
       of options, and several alternative ways	to write each method
       declaration. You	may prefer to start by just finding a few examples
       that you	can modify to accomplish your immediate	needs, and defer
       investigating all of the	extras until you're ready to take a closer
       look.

   Other Documentation
       The remainder of	this document focuses on points	of usage that are
       common across all subclasses, and describes how to create your own
       subclasses.

       If this is your first exposure to Class::MakeMethods, you may want to
       skim over the rest of this document, then take a	look at	the examples
       and one or two of the method-generating subclasses to get a more
       concrete	sense of typical usage,	before returning to the	details
       presented below.

       o   A collection	of sample uses is available in
	   Class::MakeMethods::Docs::Examples.

       o   Some	of the most common object and class methods are	available from
	   Class::MakeMethods::Standard::Hash,
	   Class::MakeMethods::Standard::Global	and
	   Class::MakeMethods::Standard::Universal.

       o   If you need a bit more flexibility, see
	   Class::MakeMethods::Composite for method generators which offer
	   more	customization options, including pre- and post-method callback
	   hooks.

       o   For the largest collection of methods and options, see
	   Class::MakeMethods::Template, which uses a system of	dynamic	code
	   generation to allow endless variation.

       o   A listing of	available method types from each of the	different
	   subclasses is provided in Class::MakeMethods::Docs::Catalog.

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 code requests a method, the MakeMethods 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.

   The MakeMethods Base	Class
       The Class::MakeMethods package defines a	superclass for method-
       generating modules, and provides	a calling convention, on-the-fly
       subclass	loading, and subroutine	installation 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.

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

       Each generator function specified is passed the arguments specifying
       the method the caller wants, and	produces a closure or eval-able
       sequence	of Perl	statements representing	the ready-to-install function.

   Included Subclasses
       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.

       Standard	(See Class::MakeMethods::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.

       Composite (See Class::MakeMethods::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.

       Template	(See Class::MakeMethods::Template.)
	   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 "inside-out" accessors with external
	   indexes).

       Basic (See Class::MakeMethods::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.

       Emulators (See Class::MakeMethods::Emulator.)
	   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 that the name of the module be
	   changed.

       Extending
	   Class::MakeMethods can be extended by creating subclasses that
	   define additional method-generation functions. Callers can then
	   specify the name of your subclass and generator function in their
	   "use	Call::MakeMethods ..." statements and your function will be
	   invoked to produce the required closures. See "EXTENDING" for more
	   information.

   Naming Convention for Generated Method Types
       Method generation functions in this document are	often referred to
       using the 'MakerClass:MethodType' or
       'MakerGroup::MakerSubclass:MethodType' naming conventions. As you will
       see, these are simply the names of Perl packages	and the	names of
       functions that are contained in those packages.

       The included subclasses are grouped into	several	major groups, so the
       names used by the included subclasses and method	types reflect three
       axes of variation, "Group::Subclass:Type":

       Maker 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
	   "Included Subclasses"" in ".)

       Maker 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::Hash:scalar" you can read it as "a type of method to access
       a scalar	value stored in	a hash-based object, with a standard
       implementation style" and know that it's	going to call the scalar()
       function	in the Class::MakeMethods::Standard::Hash package to generate
       the requested method.

USAGE
       The supported method types, and the kinds of arguments they expect,
       vary from subclass to subclass; see the documentation of	each subclass
       for details.

       However,	the features described below are applicable to all subclasses.

   Invocation
       Methods are dynamically generated and installed into the	calling
       package when you	"use Class::MakeMethods	(...)" or one of its
       subclasses, or if you later call	"Class::MakeMethods->make(...)".

       The arguments to	"use" or "make"	should be pairs	of a generator type
       name and	an associated array of method-name arguments to	pass to	the
       generator.

       o   use Class::MakeMethods::MakerClass (
	       'MethodType' => [ Arguments ], ...
	     );

       o   Class::MakeMethods::MakerClass->make	(
	       'MethodType' => [ Arguments ], ...
	     );

       You may select a	specific subclass of Class::MakeMethods	for a single
       generator-type/argument pair by prefixing the type name with a subclass
       name and	a colon.

       o   use Class::MakeMethods (
	       'MakerClass:MethodType' => [ Arguments ], ...
	     );

       o   Class::MakeMethods->make (
	       'MakerClass:MethodType' => [ Arguments ], ...
	     );

       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.	(See "About Precedence"	for additional discussion of
       this issue.)

   Alternative Invocation
       If you want methods to be declared at run-time when a previously-
       unknown method is invoked, see Class::MakeMethods::Autoload.

       o   use Class::MakeMethods::Autoload 'MakerClass:MethodType';

       If you are using	Perl version 5.6 or later, see
       Class::MakeMethods::Attribute for an additional declaration syntax for
       generated methods.

       o   use Class::MakeMethods::Attribute 'MakerClass';

	   sub name :MakeMethod('MethodType' =>	Arguments);

   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 the same method is declared multiple times, 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, before
	 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 - use, after
	 sub foo { 1 }
	 use Class::MakeMethods::Standard::Hash	(
	   'scalar'=>['foo'] # foo() is	already	declared, so has no effect
	 );

	 # 3 - use, after, Force
	 sub bar { 1 }
	 use Class::MakeMethods::Standard::Hash	(
	     -ForceInstall => 1, # Set flag for	following methods...
	   'scalar' => ['bar']	 # ... now overwrites pre-existing bar()
	 );

	 # 4 - make, before
	 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 - make, after, Force
	 sub ping { 1 }
	 Class::MakeMethods::Standard::Hash->make(
	     -ForceInstall => 1, # Set flag for	following methods...
	   'scalar' => ['ping']	 # ... now overwrites pre-existing ping()
	 );

   Global Options
       Global options may be specified as an argument pair with	a leading
       hyphen. (This distinguishes them	from type names, which must be valid
       Perl subroutine names, and thus will never begin	with a hyphen.)

       use Class::MakeMethods::MakerClass (
	   '-Param' => ParamValue,
	   'MethodType'	=> [ Arguments ], ...
	 );

       Option settings apply to	all subsequent method declarations within a
       single "use" or "make" call.

       The below options allow you to control generation and installation of
       the requested methods. (Some subclasses may support additional options;
       see their documentation for details.)

       -TargetClass
	   By default, the methods are installed in the	first package in the
	   caller() stack that is not a	Class::MakeMethods subclass; this is
	   generally the package in which your use or make statement was
	   issued. To override this you	can pass "-TargetClass => package" as
	   initial arguments to	"use" or "make".

	   This	allows you to construct	or modify classes "from	the outside":

	     package main;

	     use Class::MakeMethods::Basic::Hash(
	       -TargetClass => 'MyWidget',
	       'new' =>	['create'],
	       'scalar'	=> ['foo', 'bar'],
	     );

	     $o	= MyWidget->new( foo =>	'Foozle' );
	     print $o->foo();

       -MakerClass
	   By default, meta-methods are	looked up in the package you called
	   use or make on.

	   You can override this by passing the	"-MakerClass" flag, which
	   allows you to switch	packages for the remainder of the meta-method
	   types and arguments.

	   use Class::MakeMethods (
	       '-MakerClass'=>'MakerClass',
	       'MethodType' => [ Arguments ]
	     );

	   When	specifying the MakerClass, you may provide either the trailing
	   part	name of	a subclass inside of the "Class::MakeMethods::"
	   namespace, or a full	package	name prefixed by "::".

	   For example,	the following four statements are equivalent ways of
	   declaring a Basic::Hash scalar method named 'foo':

	     use Class::MakeMethods::Basic::Hash (
	       'scalar'	=> [ 'foo' ]
	     );

	     use Class::MakeMethods (
	       'Basic::Hash:scalar' => [ 'foo' ]
	     );

	     use Class::MakeMethods (
	       '-MakerClass'=>'Basic::Hash',
	       'scalar'	=>  [ 'foo' ]
	     );

	     use Class::MakeMethods (
	       '-MakerClass'=>'::Class::MakeMethods::Basic::Hash',
	       'scalar'	=>  [ 'foo' ]
	     );

       -ForceInstall
	   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".

	   Note	that the "use" keyword acts as a BEGIN block, so a "use" at
	   the top of a	file will be executed before any subroutine
	   declarations	later in the file have been seen. (See "About
	   Precedence" for additional discussion of this issue.)

   Mixing Method Types
       A single	calling	class can combine generated methods from different
       MakeMethods subclasses. In general, the only mixing that's problematic
       is combinations of methods which	depend on different underlying object
       types, like using *::Hash and *::Array methods together -- the methods
       will be generated, but some of them  are	guaranteed to fail when
       called, depending on whether your object	happens	to be a	blessed
       hashref or arrayref.

       For example, it's common	to mix and match various *::Hash methods, with
       a scattering of Global or Inheritable methods:

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

   Declaration Syntax
       The following types of Simple declarations are supported:

       o   generator_type => 'method_name'

       o   generator_type => 'method_1 method_2...'

       o   generator_type => [ 'method_1', 'method_2', ...]

       For a list of the supported values of generator_type, see "STANDARD
       CLASSES"	in Class::MakeMethods::Docs::Catalog, or the documentation for
       each subclass.

       For each	method name you	provide, a subroutine of the indicated type
       will be generated and installed under that name in your module.

       Method names should start with a	letter,	followed by zero or more
       letters,	numbers, or underscores.

   Argument Normalization
       The following expansion rules are applied to argument pairs to enable
       the use of simple strings instead of arrays of arguments.

       o   Each	type can be followed by	a single meta-method definition, or by
	   a reference to an array of them.

       o   If the argument is provided as a string containing spaces, it is
	   split and each word is treated as a separate	argument.

       o   It the meta-method type string contains spaces, it is split and
	   only	the first word is used as the type, while the remaining	words
	   are placed at the front of the argument list.

       For example, the	following statements are equivalent ways of declaring
       a pair of Basic::Hash scalar methods named 'foo'	and 'bar':

	 use Class::MakeMethods::Basic::Hash (
	   'scalar' => [ 'foo',	'bar' ],
	 );

	 use Class::MakeMethods::Basic::Hash (
	   'scalar' => 'foo',
	   'scalar' => 'bar',
	 );

	 use Class::MakeMethods::Basic::Hash (
	   'scalar' => 'foo bar',
	 );

	 use Class::MakeMethods::Basic::Hash (
	   'scalar foo'	=> 'bar',
	 );

       (The last of these is clearly a bit peculiar and	potentially misleading
       if used as shown, but it	enables	advanced subclasses to provide
       convenient formatting for declarations with  defaults or	modifiers,
       such as 'Template::Hash:scalar --private' => 'foo', discussed
       elsewhere.)

   Parameter Syntax
       The Standard syntax also	provides several ways to optionally associate
       a hash of additional parameters with a given method name.

       o   generator_type => [
	       'method_1' => { param=>value... }, ...
	     ]

	   A hash of parameters	to use just for	this method name.

	   (Note: to prevent confusion with self-contained definition hashes,
	   described below, parameter hashes following a method	name must not
	   contain the key 'name'.)

       o   generator_type => [
	       [ 'method_1', 'method_2', ... ] => { param=>value... }
	     ]

	   Each	of these method	names gets a copy of the same set of
	   parameters.

       o   generator_type => [
	       { 'name'=>'method_1', param=>value... },	...
	     ]

	   By including	the reserved parameter 'name', you create a self-
	   contained declaration with that name	and any	associated hash
	   values.

       Simple declarations, as shown in	the prior section, are treated as if
       they had	an empty parameter hash.

   Default Parameters
       A set of	default	parameters to be used for several declarations may be
       specified using any of the following types of arguments to a method
       generator call:

       o   generator_type => [
	       '-param'	=> 'value', 'method_1',	'method_2', ...
	     ]

	   Set a default value for the specified parameter to be passed	to all
	   subsequent declarations.

       o   generator_type => [
	       '--' => { 'param' => 'value', ... }, 'method_1',	'method_2',
	   ...
	     ]

	   Set default values for one or more parameters to be passed to all
	   subsequent declarations. Equivalent to a series of '-param' =>
	   'value' pairs for each pair in the referenced hash.

       o   generator_type => [
	       '--special_param', 'method_1', 'method_2', ...
	     ]

	   Appends to the default value	for a special parameter	named "--".
	   This	parameter is currently only used by some subclasses; for
	   details see Class::MakeMethods::Template

       Parameters set in these ways are	passed to each declaration that
       follows it until	the end	of the method-generator	argument array,	or
       until overridden	by another declaration.	Parameters specified in	a hash
       for a specific method name, as discussed	above, will override the
       defaults	of the same name for that particular method.

DIAGNOSTICS
       The following warnings and errors may be	produced when using
       Class::MakeMethods to generate methods. (Note that this list does not
       include run-time	messages produced by calling the generated methods.)

       These messages are classified as	follows	(listed	in increasing order of
       desperation):

	   (Q) A debugging message, only shown if $CONTEXT{Debug} is true
	   (W) A warning.
	   (D) A deprecation.
	   (F) A fatal error in	caller's use of	the module.
	   (I) An internal problem with	the module or subclasses.

       Portions	of the message which may vary are denoted with a %s.

       Can't interpret meta-method template: argument is empty or undefined
	   (F)

       Can't interpret meta-method template: unknown template name '%s'
	   (F)

       Can't interpret meta-method template: unsupported template type '%s'
	   (F)

       Can't make method %s(): template	specifies unknown behavior '%s'
	   (F)

       Can't parse meta-method declaration: argument is	empty or undefined
	   (F) You passed an undefined value or	an empty string	in the list of
	   meta-method declarations to use or make.

       Can't parse meta-method declaration: missing name attribute.
	   (F) You included an hash-ref-style meta-method declaration that did
	   not include the required name attribute. You	may have meant this to
	   be an attributes hash for a previously specified name, but if so we
	   were	unable to locate it.

       Can't parse meta-method declaration: unknown template name '%s'
	   (F) You included a template specifier of the	form '-template_name'
	   in a	the list of meta-method	declaration, but that template is not
	   available.

       Can't parse meta-method declaration: unsupported	declaration type '%s'
	   (F) You included an unsupported type	of value in a list of meta-
	   method declarations.

       Compilation error: %s
	   (I)

       Not an interpretable meta-method: '%s'
	   (I)

       Odd number of arguments passed to %s make
	   (F) You specified an	odd number of arguments	in a call to use or
	   make.  The arguments	should be key => value pairs.

       Unable to compile generated method %s():	%s
	   (I) The install_methods subroutine attempted	to compile a
	   subroutine by calling eval on a provided string, which failed for
	   the indicated reason, usually some type of Perl syntax error.

       Unable to dynamically load $package: $%s
	   (F)

       Unable to install code for %s() method: '%s'
	   (I) The install_methods subroutine was passed an unsupported	value
	   as the code to install for the named	method.

       Unexpected return value from compilation	of %s(): '%s'
	   (I) The install_methods subroutine attempted	to compile a
	   subroutine by calling eval on a provided string, but	the eval
	   returned something other than than the code ref we expect.

       Unexpected return value from meta-method	constructor %s:	%s
	   (I) The requested method-generator was invoked, but it returned an
	   unacceptable	value.

EXTENDING
       Class::MakeMethods can be extended by creating subclasses that define
       additional meta-method types. Callers then select your subclass using
       any of the several techniques described above.

   Creating A Subclass
       The begining of a typical extension might look like the below:

	 package My::UpperCaseMethods;
	 use strict;
	 use Class::MakeMethods	'-isasubclass';

	 sub my_method_type { ... }

       You can name your subclass anything you want; it	does not need to begin
       with Class::MakeMethods.

       The '-isasubclass' flag is a shortcut that automatically	puts
       Class::MakeMethods into your package's @ISA array so that it will
       inherit the import() and	make() class methods. If you omit this flag,
       you will	need to	place the superclass in	your @ISA explicitly.

       Typically, the subclass should not inherit from Exporter; both
       Class::MakeMethods and Exporter are based on inheriting an import class
       method, and getting a subclass to support both would require additional
       effort.

   Naming Method Types
       Each type of method that	can be generated is defined in a subroutine of
       the same	name. You can give your	meta-method type any name that is a
       legal subroutine	identifier.

       (Names begining with an underscore, and the names "import" and "make",
       are reserved for	internal use by	Class::MakeMethods.)

       If you plan on distributing your	extension, you may wish	to follow the
       "Naming Convention for Generated	Method Types" described	above to
       facilitate reuse	by others.

   Implementation Options
       Each method generation subroutine can be	implemented in any one of the
       following ways:

       o   Subroutine Generation

	   Returns a list of subroutine	name/code pairs.

	   The code returned may either	be a coderef, or a string containing
	   Perl	code that can be evaled	and will return	a coderef. If the eval
	   fails, or anything other than a coderef is returned,	then
	   Class::MakeMethods croaks.

	   For example a simple	sub-class with a method	type
	   upper_case_get_set that generates an	accessor method	for each
	   argument provided might look	like this:

	     package My::UpperCaseMethods;
	     use Class::MakeMethods '-isasubclass';

	     sub uc_scalar {
	       my $class = shift;
	       map {
		 my $name = $_;
		 $name => sub {
		   my $self = shift;
		   if (	scalar @_ ) {
		     $self->{ $name } =	uc( shift )
		   } else {
		     $self->{ $name };
		   }
		 }
	       } @_;
	     }

	   Callers could then generate these methods as	follows:

	     use My::UpperCaseMethods (	'uc_scalar' => 'foo' );

       o   Aliasing

	   Returns a string containing a different meta-method type to use for
	   those same arguments.

	   For example a simple	sub-class that defines a method	type
	   stored_value	might look like	this:

	     package My::UpperCaseMethods;
	     use Class::MakeMethods '-isasubclass';

	     sub regular_scalar	{ return 'Basic::Hash:scalar' }

	   And here's an example usage:

	     use My::UpperCaseMethods (	'regular_scalar' => [ 'foo' ] );

       o   Rewriting

	   Returns one or more array references	with different meta-method
	   types and arguments to use.

	   For example,	the below meta-method definition reviews the name of
	   each	method it's passed and creates different types of meta-methods
	   based on whether the	declared name is in all	upper case:

	     package My::UpperCaseMethods;
	     use Class::MakeMethods '-isasubclass';

	     sub auto_detect {
	       my $class = shift;
	       my @rewrite = ( [ 'Basic::Hash:scalar' ],
			       [ '::My::UpperCaseMethods:uc_scalar' ] );
	       foreach ( @_ ) {
		 my $name_is_uppercase = ( $_ eq uc($_)	) ? 1 :	0;
		 push @{ $rewrite[ $name_is_uppercase ]	}, $_
	       }
	       return @rewrite;
	     }

	   The following invocation would then generate	a regular scalar
	   accessor method foo,	and a uc_scalar	method BAR:

	     use My::UpperCaseMethods (	'auto_detect' => [ 'foo', 'BAR'	] );

       o   Generator Object

	   Returns an object with a method named make_methods which will be
	   responsible for returning subroutine	name/code pairs.

	   See Class::MakeMethods::Template for	an example.

       o   Self-Contained

	   Your	code may do whatever it	wishes,	and return an empty list.

   Access to Options
       Global option values are	available through the _context() class method
       at the time that	method generation is being performed.

	 package My::Maker;
	 sub my_methodtype {
	   my $class = shift;
	   warn	"Installing in " . $class->_context('TargetClass');
	   ...
	 }

       o   TargetClass

	   Class into which code should	be installed.

       o   MakerClass

	   Which subclass of Class::MakeMethods	will generate the methods?

       o   ForceInstall

	   Controls whether generated methods will be installed	over pre-
	   existing methods in the target package.

SEE ALSO
   License and Support
       For distribution, installation, support,	copyright and license
       information, see	Class::MakeMethods::Docs::ReadMe.

   Package Documentation
       A collection of sample uses is available	in
       Class::MakeMethods::Docs::Examples.

       See the documentation for each family of	subclasses:

       o   Class::MakeMethods::Basic

       o   Class::MakeMethods::Standard

       o   Class::MakeMethods::Composite

       o   Class::MakeMethods::Template

       A listing of available method types from	each of	the different
       subclasses is provided in Class::MakeMethods::Docs::Catalog.

   Related Modules
       For a brief survey of the numerous modules on CPAN which	offer some
       type of method generation, see
       Class::MakeMethods::Docs::RelatedModules.

       In several cases, Class::MakeMethods provides functionality closely
       equivalent to that of an	existing module, and emulator modules are
       provided	to map the existing module's interface to that of
       Class::MakeMethods.  See	Class::MakeMethods::Emulator for more
       information.

       If you have used	Class::MethodMaker, you	will note numerous
       similarities between the	two.  Class::MakeMethods is based on
       Class::MethodMaker, but has been	substantially revised in order to
       provide a range of new features.	 Backward compatibility	and conversion
       documentation is	provded	in Class::MakeMethods::Emulator::MethodMaker.

   Perl	Docs
       See perlboot for	a quick	introduction to	objects	for beginners.	For an
       extensive discussion of various approaches to class construction, see
       perltoot	and perltootc (called perltootc	in the most recent versions of
       Perl).

       See "Making References" in perlref, point 4 for more information	on
       closures. (FWIW,	I think	there's	a big opportunity for a	"perlfunt"
       podfile bundled with Perl in the	tradition of "perlboot"	and
       "perltoot", exploring the utility of function references, callbacks,
       closures, and continuations... There are	a bunch	of useful references
       available, but not a good overview of how they all interact in a
       Perlish way.)

perl v5.24.1			  2004-09-06			MakeMethods(3)

NAME | SYNOPSIS | DESCRIPTION | GETTING STARTED | CLASS ARCHITECTURE | USAGE | DIAGNOSTICS | EXTENDING | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Class::MakeMethods&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help