1MakeMethods(3)        User Contributed Perl Documentation       MakeMethods(3)
2
3
4

NAME

6       Class::MakeMethods - Generate common types of methods
7

SYNOPSIS

9         # Generates methods for your object when you "use" it.
10         package MyObject;
11         use Class::MakeMethods::Standard::Hash (
12           'new'       => 'new',
13           'scalar'    => 'foo',
14           'scalar'    => 'bar',
15         );
16
17         # The generated methods can be called just like normal ones
18         my $obj = MyObject->new( foo => "Foozle", bar => "Bozzle" );
19         print $obj->foo();
20         $obj->bar("Barbados");
21

DESCRIPTION

23       The Class::MakeMethods framework allows Perl class developers to
24       quickly define common types of methods. When a module "use"s
25       Class::MakeMethods or one of its subclasses, it can select from a
26       variety of supported method types, and specify a name for each method
27       desired. The methods are dynamically generated and installed in the
28       calling package.
29
30       Construction of the individual methods is handled by subclasses.  This
31       delegation approach allows for a wide variety of method-generation
32       techniques to be supported, each by a different subclass. Subclasses
33       can also be added to provide support for new types of methods.
34
35       Over a dozen subclasses are available, including implementations of a
36       variety of different method-generation techniques. Each subclass
37       generates several types of methods, with some supporting their own
38       open-eneded extension syntax, for hundreds of possible combinations of
39       method types.
40

GETTING STARTED

42   Motivation
43         "Make easy things easier."
44
45       This module addresses a problem encountered in object-oriented
46       development wherein numerous methods are defined which differ only
47       slightly from each other.
48
49       A common example is accessor methods for hash-based object attributes,
50       which allow you to get and set the value $self->{'foo'} by calling a
51       method $self->foo().
52
53       These methods are generally quite simple, requiring only a couple of
54       lines of Perl, but in sufficient bulk, they can cut down on the
55       maintainability of large classes.
56
57       Class::MakeMethods allows you to simply declare those methods to be of
58       a predefined type, and it generates and installs the necessary methods
59       in your package at compile-time.
60
61   A Contrived Example
62       Object-oriented Perl code is widespread -- you've probably seen code
63       like the below a million times:
64
65         my $obj = MyStruct->new( foo=>"Foozle", bar=>"Bozzle" );
66         if ( $obj->foo() =~ /foo/i ) {
67           $obj->bar("Barbados!");
68         }
69         print $obj->summary();
70
71       (If this doesn't look familiar, take a moment to read perlboot and
72       you'll soon learn more than's good for you.)
73
74       Typically, this involves creating numerous subroutines that follow a
75       handful of common patterns, like constructor methods and accessor
76       methods. The classic example is accessor methods for hash-based object
77       attributes, which allow you to get and set the value self->{foo} by
78       calling a method self->foo().  These methods are generally quite
79       simple, requiring only a couple of lines of Perl, but in sufficient
80       bulk, they can cut down on the maintainability of large classes.
81
82       Here's a possible implementation for the class whose interface is shown
83       above:
84
85         package MyStruct;
86
87         sub new {
88           my $callee = shift;
89           my $self = bless { @_ }, (ref $callee || $callee);
90           return $self;
91         }
92
93         sub foo {
94           my $self = shift;
95           if ( scalar @_ ) {
96             $self->{'foo'} = shift();
97           } else {
98             $self->{'foo'}
99           }
100         }
101
102         sub bar {
103           my $self = shift;
104           if ( scalar @_ ) {
105             $self->{'bar'} = shift();
106           } else {
107             $self->{'bar'}
108           }
109         }
110
111         sub summary {
112           my $self = shift;
113           join(', ', map { "\u$_: " . $self->$_() } qw( foo bar ) )
114         }
115
116       Note in particular that the foo and bar methods are almost identical,
117       and that the new method could be used for almost any class; this is
118       precisely the type of redundancy Class::MakeMethods addresses.
119
120       Class::MakeMethods allows you to simply declare those methods to be of
121       a predefined type, and it generates and installs the necessary methods
122       in your package at compile-time.
123
124       Here's the equivalent declaration for that same basic class:
125
126         package MyStruct;
127         use Class::MakeMethods::Standard::Hash (
128           'new'       => 'new',
129           'scalar'    => 'foo',
130           'scalar'    => 'bar',
131         );
132
133         sub summary {
134           my $self = shift;
135           join(', ', map { "\u$_: " . $self->$_() } qw( foo bar ) )
136         }
137
138       This is the basic purpose of Class::MakeMethods: The "boring" pieces of
139       code have been replaced by succinct declarations, placing the focus on
140       the "unique" or "custom" pieces.
141
142   Finding the Method Types You Need
143       Once you've grasped the basic idea -- simplifying repetitive code by
144       generating and installing methods on demand -- the remaining complexity
145       basically boils down to figuring out which arguments to pass to
146       generate the specific methods you want.
147
148       Unfortunately, this is not a trivial task, as there are dozens of
149       different types of methods that can be generated, each with a variety
150       of options, and several alternative ways to write each method
151       declaration. You may prefer to start by just finding a few examples
152       that you can modify to accomplish your immediate needs, and defer
153       investigating all of the extras until you're ready to take a closer
154       look.
155
156   Other Documentation
157       The remainder of this document focuses on points of usage that are
158       common across all subclasses, and describes how to create your own
159       subclasses.
160
161       If this is your first exposure to Class::MakeMethods, you may want to
162       skim over the rest of this document, then take a look at the examples
163       and one or two of the method-generating subclasses to get a more
164       concrete sense of typical usage, before returning to the details
165       presented below.
166
167       ·   A collection of sample uses is available in
168           Class::MakeMethods::Docs::Examples.
169
170       ·   Some of the most common object and class methods are available from
171           Class::MakeMethods::Standard::Hash,
172           Class::MakeMethods::Standard::Global and
173           Class::MakeMethods::Standard::Universal.
174
175       ·   If you need a bit more flexibility, see
176           Class::MakeMethods::Composite for method generators which offer
177           more customization options, including pre- and post-method callback
178           hooks.
179
180       ·   For the largest collection of methods and options, see
181           Class::MakeMethods::Template, which uses a system of dynamic code
182           generation to allow endless variation.
183
184       ·   A listing of available method types from each of the different
185           subclasses is provided in Class::MakeMethods::Docs::Catalog.
186

CLASS ARCHITECTURE

188       Because there are so many common types of methods one might wish to
189       generate, the Class::MakeMethods framework provides an extensible
190       system based on subclasses.
191
192       When your code requests a method, the MakeMethods base class performs
193       some standard argument parsing, delegates the construction of the
194       actual method to the appropriate subclass, and then installs whatever
195       method the subclass returns.
196
197   The MakeMethods Base Class
198       The Class::MakeMethods package defines a superclass for method-
199       generating modules, and provides a calling convention, on-the-fly
200       subclass loading, and subroutine installation that will be shared by
201       all subclasses.
202
203       The superclass also lets you generate several different types of
204       methods in a single call, and will automatically load named subclasses
205       the first time they're used.
206
207   The Method Generator Subclasses
208       The type of method that gets created is controlled by the specific
209       subclass and generator function you request. For example,
210       "Class::MakeMethods::Standard::Hash" has a generator function
211       "scalar()", which is responsible for generating simple scalar-accessor
212       methods for blessed-hash objects.
213
214       Each generator function specified is passed the arguments specifying
215       the method the caller wants, and produces a closure or eval-able
216       sequence of Perl statements representing the ready-to-install function.
217
218   Included Subclasses
219       Because each subclass defines its own set of method types and
220       customization options, a key step is to find your way to the
221       appropriate subclasses.
222
223       Standard (See Class::MakeMethods::Standard.)
224           Generally you will want to begin with the Standard::Hash subclass,
225           to create constructor and accessor methods for working with
226           blessed-hash objects (or you might choose the Standard::Array
227           subclass instead).  The Standard::Global subclass provides methods
228           for class data shared by all objects in a class.
229
230           Each Standard method declaration can optionally include a hash of
231           associated parameters, which allows you to tweak some of the
232           characteristics of the methods. Subroutines are bound as closures
233           to a hash of each method's name and parameters. Standard::Hash and
234           Standard::Array provide object constructor and accessors. The
235           Standard::Global provides for static data shared by all instances
236           and subclasses, while the data for Standard::Inheritable methods
237           trace the inheritance tree to find values, and can be overriden for
238           any subclass or instance.
239
240       Composite (See Class::MakeMethods::Composite.)
241           For additional customization options, check out the Composite
242           subclasses, which allow you to select from a more varied set of
243           implementations and which allow you to adjust any specific method
244           by adding your own code-refs to be run before or after it.
245
246           Subroutines are bound as closures to a hash of each method's name
247           and optional additional data, and to one or more subroutine
248           references which make up the composite behavior of the method.
249           Composite::Hash and Composite::Array provide object constructor and
250           accessors. The Composite::Global provides for static data shared by
251           all instances and subclasses, while the data for
252           Composite::Inheritable methods can be overriden for any subclass or
253           instance.
254
255       Template (See Class::MakeMethods::Template.)
256           The Template subclasses provide an open-ended structure for objects
257           that assemble Perl code on the fly into cachable closure-generating
258           subroutines; if the method you need isn't included, you can extend
259           existing methods by re-defining just the snippet of code that's
260           different.
261
262           Class::MakeMethods::Template extends MakeMethods with a text
263           templating system that can assemble Perl code fragments into a
264           desired subroutine. The code for generated methods is eval'd once
265           for each type, and then repeatedly bound as closures to method-
266           specific data for better performance.
267
268           Templates for dozens of types of constructor, accessor, and mutator
269           methods are included, ranging from from the mundane (constructors
270           and value accessors for hash and array slots) to the esoteric
271           (inheritable class data and "inside-out" accessors with external
272           indexes).
273
274       Basic (See Class::MakeMethods::Basic.)
275           The Basic subclasses provide stripped down method generators with
276           no configurable options, for minimal functionality (and minimum
277           overhead).
278
279           Subroutines are bound as closures to the name of each method.
280           Basic::Hash and Basic::Array provide simple object constructors and
281           accessors. Basic::Global provides basic global-data accessors.
282
283       Emulators (See Class::MakeMethods::Emulator.)
284           In several cases, Class::MakeMethods provides functionality closely
285           equivalent to that of an existing module, and it is simple to map
286           the existing module's interface to that of Class::MakeMethods.
287
288           Emulators are included for Class::MethodMaker,
289           Class::Accessor::Fast, Class::Data::Inheritable, Class::Singleton,
290           and Class::Struct, each of which passes the original module's test
291           suite, usually requiring only that the name of the module be
292           changed.
293
294       Extending
295           Class::MakeMethods can be extended by creating subclasses that
296           define additional method-generation functions. Callers can then
297           specify the name of your subclass and generator function in their
298           "use Call::MakeMethods ..." statements and your function will be
299           invoked to produce the required closures. See "EXTENDING" for more
300           information.
301
302   Naming Convention for Generated Method Types
303       Method generation functions in this document are often referred to
304       using the 'MakerClass:MethodType' or
305       'MakerGroup::MakerSubclass:MethodType' naming conventions. As you will
306       see, these are simply the names of Perl packages and the names of
307       functions that are contained in those packages.
308
309       The included subclasses are grouped into several major groups, so the
310       names used by the included subclasses and method types reflect three
311       axes of variation, "Group::Subclass:Type":
312
313       Maker Group
314           Each group shares a similar style of technical implementation and
315           level of complexity. For example, the "Standard::*" packages are
316           all simple, while the "Composite::*" packages all support pre- and
317           post-conditions.
318
319           (For a listing of the four main groups of included subclasses, see
320           "Included Subclasses"" in ".)
321
322       Maker Subclass
323           Each subclass generates methods for a similar level of scoping or
324           underlying object type. For example, the *::Hash packages all make
325           methods for objects based on blessed hashes, while the *::Global
326           packages make methods that access class-wide data that will be
327           shared between all objects in a class.
328
329       Method Type
330           Each method type produces a similar type of constructor or
331           accessor. For examples, the *:new methods are all constructors,
332           while the "::scalar" methods are all accessors that allow you to
333           get and set a single scalar value.
334
335       Bearing that in mind, you should be able to guess the intent of many of
336       the method types based on their names alone; when you see
337       "Standard::Hash:scalar" you can read it as "a type of method to access
338       a scalar value stored in a hash-based object, with a standard
339       implementation style" and know that it's going to call the scalar()
340       function in the Class::MakeMethods::Standard::Hash package to generate
341       the requested method.
342

USAGE

344       The supported method types, and the kinds of arguments they expect,
345       vary from subclass to subclass; see the documentation of each subclass
346       for details.
347
348       However, the features described below are applicable to all subclasses.
349
350   Invocation
351       Methods are dynamically generated and installed into the calling
352       package when you "use Class::MakeMethods (...)" or one of its
353       subclasses, or if you later call "Class::MakeMethods->make(...)".
354
355       The arguments to "use" or "make" should be pairs of a generator type
356       name and an associated array of method-name arguments to pass to the
357       generator.
358
359       ·   use Class::MakeMethods::MakerClass (
360               'MethodType' => [ Arguments ], ...
361             );
362
363       ·   Class::MakeMethods::MakerClass->make (
364               'MethodType' => [ Arguments ], ...
365             );
366
367       You may select a specific subclass of Class::MakeMethods for a single
368       generator-type/argument pair by prefixing the type name with a subclass
369       name and a colon.
370
371       ·   use Class::MakeMethods (
372               'MakerClass:MethodType' => [ Arguments ], ...
373             );
374
375       ·   Class::MakeMethods->make (
376               'MakerClass:MethodType' => [ Arguments ], ...
377             );
378
379       The difference between "use" and "make" is primarily one of precedence;
380       the "use" keyword acts as a BEGIN block, and is thus evaluated before
381       "make" would be. (See "About Precedence" for additional discussion of
382       this issue.)
383
384   Alternative Invocation
385       If you want methods to be declared at run-time when a previously-
386       unknown method is invoked, see Class::MakeMethods::Autoload.
387
388       ·   use Class::MakeMethods::Autoload 'MakerClass:MethodType';
389
390       If you are using Perl version 5.6 or later, see
391       Class::MakeMethods::Attribute for an additional declaration syntax for
392       generated methods.
393
394       ·   use Class::MakeMethods::Attribute 'MakerClass';
395
396           sub name :MakeMethod('MethodType' => Arguments);
397
398   About Precedence
399       Rather than passing the method declaration arguments when you "use" one
400       of these packages, you may instead pass them to a subsequent call to
401       the class method "make".
402
403       The difference between "use" and "make" is primarily one of precedence;
404       the "use" keyword acts as a BEGIN block, and is thus evaluated before
405       "make" would be. In particular, a "use" at the top of a file will be
406       executed before any subroutine declarations later in the file have been
407       seen, whereas a "make" at the same point in the file will not.
408
409       By default, Class::MakeMethods will not install generated methods over
410       any pre-existing methods in the target class. To override this you can
411       pass "-ForceInstall => 1" as initial arguments to "use" or "make".
412
413       If the same method is declared multiple times, earlier calls to "use"
414       or "make()" win over later ones, but within each call, later
415       declarations superceed earlier ones.
416
417       Here are some examples of the results of these precedence rules:
418
419         # 1 - use, before
420         use Class::MakeMethods::Standard::Hash (
421           'scalar'=>['baz'] # baz() not seen yet, so we generate, install
422         );
423         sub baz { 1 } # Subsequent declaration overwrites it, with warning
424
425         # 2 - use, after
426         sub foo { 1 }
427         use Class::MakeMethods::Standard::Hash (
428           'scalar'=>['foo'] # foo() is already declared, so has no effect
429         );
430
431         # 3 - use, after, Force
432         sub bar { 1 }
433         use Class::MakeMethods::Standard::Hash (
434             -ForceInstall => 1, # Set flag for following methods...
435           'scalar' => ['bar']   # ... now overwrites pre-existing bar()
436         );
437
438         # 4 - make, before
439         Class::MakeMethods::Standard::Hash->make(
440           'scalar'=>['blip'] # blip() is already declared, so has no effect
441         );
442         sub blip { 1 } # Although lower than make(), this "happens" first
443
444         # 5 - make, after, Force
445         sub ping { 1 }
446         Class::MakeMethods::Standard::Hash->make(
447             -ForceInstall => 1, # Set flag for following methods...
448           'scalar' => ['ping']  # ... now overwrites pre-existing ping()
449         );
450
451   Global Options
452       Global options may be specified as an argument pair with a leading
453       hyphen. (This distinguishes them from type names, which must be valid
454       Perl subroutine names, and thus will never begin with a hyphen.)
455
456       use Class::MakeMethods::MakerClass (
457           '-Param' => ParamValue,
458           'MethodType' => [ Arguments ], ...
459         );
460
461       Option settings apply to all subsequent method declarations within a
462       single "use" or "make" call.
463
464       The below options allow you to control generation and installation of
465       the requested methods. (Some subclasses may support additional options;
466       see their documentation for details.)
467
468       -TargetClass
469           By default, the methods are installed in the first package in the
470           caller() stack that is not a Class::MakeMethods subclass; this is
471           generally the package in which your use or make statement was
472           issued. To override this you can pass "-TargetClass => package" as
473           initial arguments to "use" or "make".
474
475           This allows you to construct or modify classes "from the outside":
476
477             package main;
478
479             use Class::MakeMethods::Basic::Hash(
480               -TargetClass => 'MyWidget',
481               'new' => ['create'],
482               'scalar' => ['foo', 'bar'],
483             );
484
485             $o = MyWidget->new( foo => 'Foozle' );
486             print $o->foo();
487
488       -MakerClass
489           By default, meta-methods are looked up in the package you called
490           use or make on.
491
492           You can override this by passing the "-MakerClass" flag, which
493           allows you to switch packages for the remainder of the meta-method
494           types and arguments.
495
496           use Class::MakeMethods (
497               '-MakerClass'=>'MakerClass',
498               'MethodType' => [ Arguments ]
499             );
500
501           When specifying the MakerClass, you may provide either the trailing
502           part name of a subclass inside of the "Class::MakeMethods::"
503           namespace, or a full package name prefixed by "::".
504
505           For example, the following four statements are equivalent ways of
506           declaring a Basic::Hash scalar method named 'foo':
507
508             use Class::MakeMethods::Basic::Hash (
509               'scalar' => [ 'foo' ]
510             );
511
512             use Class::MakeMethods (
513               'Basic::Hash:scalar' => [ 'foo' ]
514             );
515
516             use Class::MakeMethods (
517               '-MakerClass'=>'Basic::Hash',
518               'scalar' =>  [ 'foo' ]
519             );
520
521             use Class::MakeMethods (
522               '-MakerClass'=>'::Class::MakeMethods::Basic::Hash',
523               'scalar' =>  [ 'foo' ]
524             );
525
526       -ForceInstall
527           By default, Class::MakeMethods will not install generated methods
528           over any pre-existing methods in the target class. To override this
529           you can pass "-ForceInstall => 1" as initial arguments to "use" or
530           "make".
531
532           Note that the "use" keyword acts as a BEGIN block, so a "use" at
533           the top of a file will be executed before any subroutine
534           declarations later in the file have been seen. (See "About
535           Precedence" for additional discussion of this issue.)
536
537   Mixing Method Types
538       A single calling class can combine generated methods from different
539       MakeMethods subclasses. In general, the only mixing that's problematic
540       is combinations of methods which depend on different underlying object
541       types, like using *::Hash and *::Array methods together -- the methods
542       will be generated, but some of them  are guaranteed to fail when
543       called, depending on whether your object happens to be a blessed
544       hashref or arrayref.
545
546       For example, it's common to mix and match various *::Hash methods, with
547       a scattering of Global or Inheritable methods:
548
549         use Class::MakeMethods (
550           'Basic::Hash:scalar'      => 'foo',
551           'Composite::Hash:scalar'  => [ 'bar' => { post_rules => [] } ],
552           'Standard::Global:scalar' => 'our_shared_baz'
553         );
554
555   Declaration Syntax
556       The following types of Simple declarations are supported:
557
558       ·   generator_type => 'method_name'
559
560       ·   generator_type => 'method_1 method_2...'
561
562       ·   generator_type => [ 'method_1', 'method_2', ...]
563
564       For a list of the supported values of generator_type, see "STANDARD
565       CLASSES" in Class::MakeMethods::Docs::Catalog, or the documentation for
566       each subclass.
567
568       For each method name you provide, a subroutine of the indicated type
569       will be generated and installed under that name in your module.
570
571       Method names should start with a letter, followed by zero or more
572       letters, numbers, or underscores.
573
574   Argument Normalization
575       The following expansion rules are applied to argument pairs to enable
576       the use of simple strings instead of arrays of arguments.
577
578       ·   Each type can be followed by a single meta-method definition, or by
579           a reference to an array of them.
580
581       ·   If the argument is provided as a string containing spaces, it is
582           split and each word is treated as a separate argument.
583
584       ·   It the meta-method type string contains spaces, it is split and
585           only the first word is used as the type, while the remaining words
586           are placed at the front of the argument list.
587
588       For example, the following statements are equivalent ways of declaring
589       a pair of Basic::Hash scalar methods named 'foo' and 'bar':
590
591         use Class::MakeMethods::Basic::Hash (
592           'scalar' => [ 'foo', 'bar' ],
593         );
594
595         use Class::MakeMethods::Basic::Hash (
596           'scalar' => 'foo',
597           'scalar' => 'bar',
598         );
599
600         use Class::MakeMethods::Basic::Hash (
601           'scalar' => 'foo bar',
602         );
603
604         use Class::MakeMethods::Basic::Hash (
605           'scalar foo' => 'bar',
606         );
607
608       (The last of these is clearly a bit peculiar and potentially misleading
609       if used as shown, but it enables advanced subclasses to provide
610       convenient formatting for declarations with  defaults or modifiers,
611       such as 'Template::Hash:scalar --private' => 'foo', discussed
612       elsewhere.)
613
614   Parameter Syntax
615       The Standard syntax also provides several ways to optionally associate
616       a hash of additional parameters with a given method name.
617
618       ·   generator_type => [
619               'method_1' => { param=>value... }, ...
620             ]
621
622           A hash of parameters to use just for this method name.
623
624           (Note: to prevent confusion with self-contained definition hashes,
625           described below, parameter hashes following a method name must not
626           contain the key 'name'.)
627
628       ·   generator_type => [
629               [ 'method_1', 'method_2', ... ] => { param=>value... }
630             ]
631
632           Each of these method names gets a copy of the same set of
633           parameters.
634
635       ·   generator_type => [
636               { 'name'=>'method_1', param=>value... }, ...
637             ]
638
639           By including the reserved parameter 'name', you create a self-
640           contained declaration with that name and any associated hash
641           values.
642
643       Simple declarations, as shown in the prior section, are treated as if
644       they had an empty parameter hash.
645
646   Default Parameters
647       A set of default parameters to be used for several declarations may be
648       specified using any of the following types of arguments to a method
649       generator call:
650
651       ·   generator_type => [
652               '-param' => 'value', 'method_1', 'method_2', ...
653             ]
654
655           Set a default value for the specified parameter to be passed to all
656           subsequent declarations.
657
658       ·   generator_type => [
659               '--' => { 'param' => 'value', ... }, 'method_1', 'method_2',
660           ...
661             ]
662
663           Set default values for one or more parameters to be passed to all
664           subsequent declarations. Equivalent to a series of '-param' =>
665           'value' pairs for each pair in the referenced hash.
666
667       ·   generator_type => [
668               '--special_param', 'method_1', 'method_2', ...
669             ]
670
671           Appends to the default value for a special parameter named "--".
672           This parameter is currently only used by some subclasses; for
673           details see Class::MakeMethods::Template
674
675       Parameters set in these ways are passed to each declaration that
676       follows it until the end of the method-generator argument array, or
677       until overridden by another declaration. Parameters specified in a hash
678       for a specific method name, as discussed above, will override the
679       defaults of the same name for that particular method.
680

DIAGNOSTICS

682       The following warnings and errors may be produced when using
683       Class::MakeMethods to generate methods. (Note that this list does not
684       include run-time messages produced by calling the generated methods.)
685
686       These messages are classified as follows (listed in increasing order of
687       desperation):
688
689           (Q) A debugging message, only shown if $CONTEXT{Debug} is true
690           (W) A warning.
691           (D) A deprecation.
692           (F) A fatal error in caller's use of the module.
693           (I) An internal problem with the module or subclasses.
694
695       Portions of the message which may vary are denoted with a %s.
696
697       Can't interpret meta-method template: argument is empty or undefined
698           (F)
699
700       Can't interpret meta-method template: unknown template name '%s'
701           (F)
702
703       Can't interpret meta-method template: unsupported template type '%s'
704           (F)
705
706       Can't make method %s(): template specifies unknown behavior '%s'
707           (F)
708
709       Can't parse meta-method declaration: argument is empty or undefined
710           (F) You passed an undefined value or an empty string in the list of
711           meta-method declarations to use or make.
712
713       Can't parse meta-method declaration: missing name attribute.
714           (F) You included an hash-ref-style meta-method declaration that did
715           not include the required name attribute. You may have meant this to
716           be an attributes hash for a previously specified name, but if so we
717           were unable to locate it.
718
719       Can't parse meta-method declaration: unknown template name '%s'
720           (F) You included a template specifier of the form '-template_name'
721           in a the list of meta-method declaration, but that template is not
722           available.
723
724       Can't parse meta-method declaration: unsupported declaration type '%s'
725           (F) You included an unsupported type of value in a list of meta-
726           method declarations.
727
728       Compilation error: %s
729           (I)
730
731       Not an interpretable meta-method: '%s'
732           (I)
733
734       Odd number of arguments passed to %s make
735           (F) You specified an odd number of arguments in a call to use or
736           make.  The arguments should be key => value pairs.
737
738       Unable to compile generated method %s(): %s
739           (I) The install_methods subroutine attempted to compile a
740           subroutine by calling eval on a provided string, which failed for
741           the indicated reason, usually some type of Perl syntax error.
742
743       Unable to dynamically load $package: $%s
744           (F)
745
746       Unable to install code for %s() method: '%s'
747           (I) The install_methods subroutine was passed an unsupported value
748           as the code to install for the named method.
749
750       Unexpected return value from compilation of %s(): '%s'
751           (I) The install_methods subroutine attempted to compile a
752           subroutine by calling eval on a provided string, but the eval
753           returned something other than than the code ref we expect.
754
755       Unexpected return value from meta-method constructor %s: %s
756           (I) The requested method-generator was invoked, but it returned an
757           unacceptable value.
758

EXTENDING

760       Class::MakeMethods can be extended by creating subclasses that define
761       additional meta-method types. Callers then select your subclass using
762       any of the several techniques described above.
763
764   Creating A Subclass
765       The begining of a typical extension might look like the below:
766
767         package My::UpperCaseMethods;
768         use strict;
769         use Class::MakeMethods '-isasubclass';
770
771         sub my_method_type { ... }
772
773       You can name your subclass anything you want; it does not need to begin
774       with Class::MakeMethods.
775
776       The '-isasubclass' flag is a shortcut that automatically puts
777       Class::MakeMethods into your package's @ISA array so that it will
778       inherit the import() and make() class methods. If you omit this flag,
779       you will need to place the superclass in your @ISA explicitly.
780
781       Typically, the subclass should not inherit from Exporter; both
782       Class::MakeMethods and Exporter are based on inheriting an import class
783       method, and getting a subclass to support both would require additional
784       effort.
785
786   Naming Method Types
787       Each type of method that can be generated is defined in a subroutine of
788       the same name. You can give your meta-method type any name that is a
789       legal subroutine identifier.
790
791       (Names begining with an underscore, and the names "import" and "make",
792       are reserved for internal use by Class::MakeMethods.)
793
794       If you plan on distributing your extension, you may wish to follow the
795       "Naming Convention for Generated Method Types" described above to
796       facilitate reuse by others.
797
798   Implementation Options
799       Each method generation subroutine can be implemented in any one of the
800       following ways:
801
802       ·   Subroutine Generation
803
804           Returns a list of subroutine name/code pairs.
805
806           The code returned may either be a coderef, or a string containing
807           Perl code that can be evaled and will return a coderef. If the eval
808           fails, or anything other than a coderef is returned, then
809           Class::MakeMethods croaks.
810
811           For example a simple sub-class with a method type
812           upper_case_get_set that generates an accessor method for each
813           argument provided might look like this:
814
815             package My::UpperCaseMethods;
816             use Class::MakeMethods '-isasubclass';
817
818             sub uc_scalar {
819               my $class = shift;
820               map {
821                 my $name = $_;
822                 $name => sub {
823                   my $self = shift;
824                   if ( scalar @_ ) {
825                     $self->{ $name } = uc( shift )
826                   } else {
827                     $self->{ $name };
828                   }
829                 }
830               } @_;
831             }
832
833           Callers could then generate these methods as follows:
834
835             use My::UpperCaseMethods ( 'uc_scalar' => 'foo' );
836
837       ·   Aliasing
838
839           Returns a string containing a different meta-method type to use for
840           those same arguments.
841
842           For example a simple sub-class that defines a method type
843           stored_value might look like this:
844
845             package My::UpperCaseMethods;
846             use Class::MakeMethods '-isasubclass';
847
848             sub regular_scalar { return 'Basic::Hash:scalar' }
849
850           And here's an example usage:
851
852             use My::UpperCaseMethods ( 'regular_scalar' => [ 'foo' ] );
853
854       ·   Rewriting
855
856           Returns one or more array references with different meta-method
857           types and arguments to use.
858
859           For example, the below meta-method definition reviews the name of
860           each method it's passed and creates different types of meta-methods
861           based on whether the declared name is in all upper case:
862
863             package My::UpperCaseMethods;
864             use Class::MakeMethods '-isasubclass';
865
866             sub auto_detect {
867               my $class = shift;
868               my @rewrite = ( [ 'Basic::Hash:scalar' ],
869                               [ '::My::UpperCaseMethods:uc_scalar' ] );
870               foreach ( @_ ) {
871                 my $name_is_uppercase = ( $_ eq uc($_) ) ? 1 : 0;
872                 push @{ $rewrite[ $name_is_uppercase ] }, $_
873               }
874               return @rewrite;
875             }
876
877           The following invocation would then generate a regular scalar
878           accessor method foo, and a uc_scalar method BAR:
879
880             use My::UpperCaseMethods ( 'auto_detect' => [ 'foo', 'BAR' ] );
881
882       ·   Generator Object
883
884           Returns an object with a method named make_methods which will be
885           responsible for returning subroutine name/code pairs.
886
887           See Class::MakeMethods::Template for an example.
888
889       ·   Self-Contained
890
891           Your code may do whatever it wishes, and return an empty list.
892
893   Access to Options
894       Global option values are available through the _context() class method
895       at the time that method generation is being performed.
896
897         package My::Maker;
898         sub my_methodtype {
899           my $class = shift;
900           warn "Installing in " . $class->_context('TargetClass');
901           ...
902         }
903
904       ·   TargetClass
905
906           Class into which code should be installed.
907
908       ·   MakerClass
909
910           Which subclass of Class::MakeMethods will generate the methods?
911
912       ·   ForceInstall
913
914           Controls whether generated methods will be installed over pre-
915           existing methods in the target package.
916

SEE ALSO

918   License and Support
919       For distribution, installation, support, copyright and license
920       information, see Class::MakeMethods::Docs::ReadMe.
921
922   Package Documentation
923       A collection of sample uses is available in
924       Class::MakeMethods::Docs::Examples.
925
926       See the documentation for each family of subclasses:
927
928       ·   Class::MakeMethods::Basic
929
930       ·   Class::MakeMethods::Standard
931
932       ·   Class::MakeMethods::Composite
933
934       ·   Class::MakeMethods::Template
935
936       A listing of available method types from each of the different
937       subclasses is provided in Class::MakeMethods::Docs::Catalog.
938
939   Related Modules
940       For a brief survey of the numerous modules on CPAN which offer some
941       type of method generation, see
942       Class::MakeMethods::Docs::RelatedModules.
943
944       In several cases, Class::MakeMethods provides functionality closely
945       equivalent to that of an existing module, and emulator modules are
946       provided to map the existing module's interface to that of
947       Class::MakeMethods.  See Class::MakeMethods::Emulator for more
948       information.
949
950       If you have used Class::MethodMaker, you will note numerous
951       similarities between the two.  Class::MakeMethods is based on
952       Class::MethodMaker, but has been substantially revised in order to
953       provide a range of new features.  Backward compatibility and conversion
954       documentation is provded in Class::MakeMethods::Emulator::MethodMaker.
955
956   Perl Docs
957       See perlboot for a quick introduction to objects for beginners.  For an
958       extensive discussion of various approaches to class construction, see
959       perltoot and perltootc (called perltootc in the most recent versions of
960       Perl).
961
962       See "Making References" in perlref, point 4 for more information on
963       closures. (FWIW, I think there's a big opportunity for a "perlfunt"
964       podfile bundled with Perl in the tradition of "perlboot" and
965       "perltoot", exploring the utility of function references, callbacks,
966       closures, and continuations... There are a bunch of useful references
967       available, but not a good overview of how they all interact in a
968       Perlish way.)
969
970
971
972perl v5.12.0                      2004-09-06                    MakeMethods(3)
Impressum