1MakeMethods(3) User Contributed Perl Documentation MakeMethods(3)
2
6 Class::MakeMethods - Generate common types of methods
7
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 # 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
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 vari‐
26 ety 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 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 Over a dozen subclasses are available, including implementations of a
36 variety of different method-generation techniques. Each subclass gener‐
37 ates several types of methods, with some supporting their own open-
38 eneded extension syntax, for hundreds of possible combinations of
39 method types.
40
42 Motivation
43 "Make easy things easier."
45 This module addresses a problem encountered in object-oriented develop‐
47 ment wherein numerous methods are defined which differ only slightly
48 from each other.
49 A common example is accessor methods for hash-based object attributes,
51 which allow you to get and set the value $self->{'foo'} by calling a
52 method $self->foo().
53 These methods are generally quite simple, requiring only a couple of
55 lines of Perl, but in sufficient bulk, they can cut down on the main‐
56 tainability of large classes.
57 Class::MakeMethods allows you to simply declare those methods to be of
59 a predefined type, and it generates and installs the necessary methods
60 in your package at compile-time.
61 A Contrived Example
63 Object-oriented Perl code is widespread -- you've probably seen code
65 like the below a million times:
66 my $obj = MyStruct->new( foo=>"Foozle", bar=>"Bozzle" );
68 if ( $obj->foo() =~ /foo/i ) {
69 $obj->bar("Barbados!");
70 }
71 print $obj->summary();
72 (If this doesn't look familiar, take a moment to read perlboot and
74 you'll soon learn more than's good for you.)
75 Typically, this involves creating numerous subroutines that follow a
77 handful of common patterns, like constructor methods and accessor meth‐
78 ods. The classic example is accessor methods for hash-based object
79 attributes, which allow you to get and set the value self->{foo} by
80 calling a method self->foo(). These methods are generally quite sim‐
81 ple, requiring only a couple of lines of Perl, but in sufficient bulk,
82 they can cut down on the maintainability of large classes.
83 Here's a possible implementation for the class whose interface is shown
85 above:
86 package MyStruct;
88 sub new {
90 my $callee = shift;
91 my $self = bless { @_ }, (ref $callee ⎪⎪ $callee);
92 return $self;
93 }
94 sub foo {
96 my $self = shift;
97 if ( scalar @_ ) {
98 $self->{'foo'} = shift();
99 } else {
100 $self->{'foo'}
101 }
102 }
103 sub bar {
105 my $self = shift;
106 if ( scalar @_ ) {
107 $self->{'bar'} = shift();
108 } else {
109 $self->{'bar'}
110 }
111 }
112 sub summary {
114 my $self = shift;
115 join(', ', map { "\u$_: " . $self->$_() } qw( foo bar ) )
116 }
117 Note in particular that the foo and bar methods are almost identical,
119 and that the new method could be used for almost any class; this is
120 precisely the type of redundancy Class::MakeMethods addresses.
121 Class::MakeMethods allows you to simply declare those methods to be of
123 a predefined type, and it generates and installs the necessary methods
124 in your package at compile-time.
125 Here's the equivalent declaration for that same basic class:
127 package MyStruct;
129 use Class::MakeMethods::Standard::Hash (
130 'new' => 'new',
131 'scalar' => 'foo',
132 'scalar' => 'bar',
133 );
134 sub summary {
136 my $self = shift;
137 join(', ', map { "\u$_: " . $self->$_() } qw( foo bar ) )
138 }
139 This is the basic purpose of Class::MakeMethods: The "boring" pieces of
141 code have been replaced by succinct declarations, placing the focus on
142 the "unique" or "custom" pieces.
143 Finding the Method Types You Need
145 Once you've grasped the basic idea -- simplifying repetitive code by
147 generating and installing methods on demand -- the remaining complexity
148 basically boils down to figuring out which arguments to pass to gener‐
149 ate the specific methods you want.
150 Unfortunately, this is not a trivial task, as there are dozens of dif‐
152 ferent types of methods that can be generated, each with a variety of
153 options, and several alternative ways to write each method declaration.
154 You may prefer to start by just finding a few examples that you can
155 modify to accomplish your immediate needs, and defer investigating all
156 of the extras until you're ready to take a closer look.
157 Other Documentation
159 The remainder of this document focuses on points of usage that are com‐
161 mon across all subclasses, and describes how to create your own sub‐
162 classes.
163 If this is your first exposure to Class::MakeMethods, you may want to
165 skim over the rest of this document, then take a look at the examples
166 and one or two of the method-generating subclasses to get a more con‐
167 crete sense of typical usage, before returning to the details presented
168 below.
169 · A collection of sample uses is available in Class::MakeMeth‐
171 ods::Docs::Examples.
172 · Some of the most common object and class methods are available from
174 Class::MakeMethods::Standard::Hash, Class::MakeMethods::Stan‐
175 dard::Global and Class::MakeMethods::Standard::Universal.
176 · If you need a bit more flexibility, see Class::MakeMethods::Compos‐
178 ite for method generators which offer more customization options,
179 including pre- and post-method callback hooks.
180 · For the largest collection of methods and options, see
182 Class::MakeMethods::Template, which uses a system of dynamic code
183 generation to allow endless variation.
184 · A listing of available method types from each of the different sub‐
186 classes is provided in Class::MakeMethods::Docs::Catalog.
187
189 Because there are so many common types of methods one might wish to
190 generate, the Class::MakeMethods framework provides an extensible sys‐
191 tem based on subclasses.
192 When your code requests a method, the MakeMethods base class performs
194 some standard argument parsing, delegates the construction of the
195 actual method to the appropriate subclass, and then installs whatever
196 method the subclass returns.
197 The MakeMethods Base Class
199 The Class::MakeMethods package defines a superclass for method-generat‐
201 ing modules, and provides a calling convention, on-the-fly subclass
202 loading, and subroutine installation that will be shared by all sub‐
203 classes.
204 The superclass also lets you generate several different types of meth‐
206 ods in a single call, and will automatically load named subclasses the
207 first time they're used.
208 The Method Generator Subclasses
210 The type of method that gets created is controlled by the specific sub‐
212 class and generator function you request. For example,
213 "Class::MakeMethods::Standard::Hash" has a generator function
214 "scalar()", which is responsible for generating simple scalar-accessor
215 methods for blessed-hash objects.
216 Each generator function specified is passed the arguments specifying
218 the method the caller wants, and produces a closure or eval-able
219 sequence of Perl statements representing the ready-to-install function.
220 Included Subclasses
222 Because each subclass defines its own set of method types and cus‐
224 tomization options, a key step is to find your way to the appropriate
225 subclasses.
226 Standard (See Class::MakeMethods::Standard.)
228 Generally you will want to begin with the Standard::Hash subclass,
229 to create constructor and accessor methods for working with
230 blessed-hash objects (or you might choose the Standard::Array sub‐
231 class instead). The Standard::Global subclass provides methods for
232 class data shared by all objects in a class.
233 Each Standard method declaration can optionally include a hash of
235 associated parameters, which allows you to tweak some of the char‐
236 acteristics of the methods. Subroutines are bound as closures to a
237 hash of each method's name and parameters. Standard::Hash and Stan‐
238 dard::Array provide object constructor and accessors. The Stan‐
239 dard::Global provides for static data shared by all instances and
240 subclasses, while the data for Standard::Inheritable methods trace
241 the inheritance tree to find values, and can be overriden for any
242 subclass or instance.
243 Composite (See Class::MakeMethods::Composite.)
245 For additional customization options, check out the Composite sub‐
246 classes, which allow you to select from a more varied set of imple‐
247 mentations and which allow you to adjust any specific method by
248 adding your own code-refs to be run before or after it.
249 Subroutines are bound as closures to a hash of each method's name
251 and optional additional data, and to one or more subroutine refer‐
252 ences which make up the composite behavior of the method. Compos‐
253 ite::Hash and Composite::Array provide object constructor and
254 accessors. The Composite::Global provides for static data shared by
255 all instances and subclasses, while the data for Composite::Inheri‐
256 table methods can be overriden for any subclass or instance.
257 Template (See Class::MakeMethods::Template.)
259 The Template subclasses provide an open-ended structure for objects
260 that assemble Perl code on the fly into cachable closure-generating
261 subroutines; if the method you need isn't included, you can extend
262 existing methods by re-defining just the snippet of code that's
263 different.
264 Class::MakeMethods::Template extends MakeMethods with a text tem‐
266 plating system that can assemble Perl code fragments into a desired
267 subroutine. The code for generated methods is eval'd once for each
268 type, and then repeatedly bound as closures to method-specific data
269 for better performance.
270 Templates for dozens of types of constructor, accessor, and mutator
272 methods are included, ranging from from the mundane (constructors
273 and value accessors for hash and array slots) to the esoteric
274 (inheritable class data and "inside-out" accessors with external
275 indexes).
276 Basic (See Class::MakeMethods::Basic.)
278 The Basic subclasses provide stripped down method generators with
279 no configurable options, for minimal functionality (and minimum
280 overhead).
281 Subroutines are bound as closures to the name of each method.
283 Basic::Hash and Basic::Array provide simple object constructors and
284 accessors. Basic::Global provides basic global-data accessors.
285 Emulators (See Class::MakeMethods::Emulator.)
287 In several cases, Class::MakeMethods provides functionality closely
288 equivalent to that of an existing module, and it is simple to map
289 the existing module's interface to that of Class::MakeMethods.
290 Emulators are included for Class::MethodMaker, Class::Acces‐
292 sor::Fast, Class::Data::Inheritable, Class::Singleton, and
293 Class::Struct, each of which passes the original module's test
294 suite, usually requiring only that the name of the module be
295 changed.
296 Extending
298 Class::MakeMethods can be extended by creating subclasses that
299 define additional method-generation functions. Callers can then
300 specify the name of your subclass and generator function in their
301 "use Call::MakeMethods ..." statements and your function will be
302 invoked to produce the required closures. See "EXTENDING" for more
303 information.
304 Naming Convention for Generated Method Types
306 Method generation functions in this document are often referred to
308 using the 'MakerClass:MethodType' or 'MakerGroup::MakerSubclass:Method‐
309 Type' naming conventions. As you will see, these are simply the names
310 of Perl packages and the names of functions that are contained in those
311 packages.
312 The included subclasses are grouped into several major groups, so the
314 names used by the included subclasses and method types reflect three
315 axes of variation, "Group::Subclass:Type":
316 Maker Group
318 Each group shares a similar style of technical implementation and
319 level of complexity. For example, the "Standard::*" packages are
320 all simple, while the "Composite::*" packages all support pre- and
321 post-conditions.
322 (For a listing of the four main groups of included subclasses, see
324 "/Included Subclasses".)
325 Maker Subclass
327 Each subclass generates methods for a similar level of scoping or
328 underlying object type. For example, the *::Hash packages all make
329 methods for objects based on blessed hashes, while the *::Global
330 packages make methods that access class-wide data that will be
331 shared between all objects in a class.
332 Method Type
334 Each method type produces a similar type of constructor or acces‐
335 sor. For examples, the *:new methods are all constructors, while
336 the "::scalar" methods are all accessors that allow you to get and
337 set a single scalar value.
338 Bearing that in mind, you should be able to guess the intent of many of
340 the method types based on their names alone; when you see "Stan‐
341 dard::Hash:scalar" you can read it as "a type of method to access a
342 scalar value stored in a hash-based object, with a standard implementa‐
343 tion style" and know that it's going to call the scalar() function in
344 the Class::MakeMethods::Standard::Hash package to generate the
345 requested method.
346
348 The supported method types, and the kinds of arguments they expect,
349 vary from subclass to subclass; see the documentation of each subclass
350 for details.
351 However, the features described below are applicable to all subclasses.
353 Invocation
355 Methods are dynamically generated and installed into the calling pack‐
357 age when you "use Class::MakeMethods (...)" or one of its subclasses,
358 or if you later call "Class::MakeMethods->make(...)".
359 The arguments to "use" or "make" should be pairs of a generator type
361 name and an associated array of method-name arguments to pass to the
362 generator.
363 · use Class::MakeMethods::MakerClass (
365 'MethodType' => [ Arguments ], ...
366 );
367 · Class::MakeMethods::MakerClass->make (
369 'MethodType' => [ Arguments ], ...
370 );
371 You may select a specific subclass of Class::MakeMethods for a single
373 generator-type/argument pair by prefixing the type name with a subclass
374 name and a colon.
375 · use Class::MakeMethods (
377 'MakerClass:MethodType' => [ Arguments ], ...
378 );
379 · Class::MakeMethods->make (
381 'MakerClass:MethodType' => [ Arguments ], ...
382 );
383 The difference between "use" and "make" is primarily one of precedence;
385 the "use" keyword acts as a BEGIN block, and is thus evaluated before
386 "make" would be. (See "About Precedence" for additional discussion of
387 this issue.)
388 Alternative Invocation
390 If you want methods to be declared at run-time when a previously-
392 unknown method is invoked, see Class::MakeMethods::Autoload.
393 · use Class::MakeMethods::Autoload 'MakerClass:MethodType';
395 If you are using Perl version 5.6 or later, see Class::MakeMeth‐
397 ods::Attribute for an additional declaration syntax for generated meth‐
398 ods.
399 · use Class::MakeMethods::Attribute 'MakerClass';
401 sub name :MakeMethod('MethodType' => Arguments);
403 About Precedence
405 Rather than passing the method declaration arguments when you "use" one
407 of these packages, you may instead pass them to a subsequent call to
408 the class method "make".
409 The difference between "use" and "make" is primarily one of precedence;
411 the "use" keyword acts as a BEGIN block, and is thus evaluated before
412 "make" would be. In particular, a "use" at the top of a file will be
413 executed before any subroutine declarations later in the file have been
414 seen, whereas a "make" at the same point in the file will not.
415 By default, Class::MakeMethods will not install generated methods over
417 any pre-existing methods in the target class. To override this you can
418 pass "-ForceInstall => 1" as initial arguments to "use" or "make".
419 If the same method is declared multiple times, earlier calls to "use"
421 or "make()" win over later ones, but within each call, later declara‐
422 tions superceed earlier ones.
423 Here are some examples of the results of these precedence rules:
425 # 1 - use, before
427 use Class::MakeMethods::Standard::Hash (
428 'scalar'=>['baz'] # baz() not seen yet, so we generate, install
429 );
430 sub baz { 1 } # Subsequent declaration overwrites it, with warning
431 # 2 - use, after
433 sub foo { 1 }
434 use Class::MakeMethods::Standard::Hash (
435 'scalar'=>['foo'] # foo() is already declared, so has no effect
436 );
437 # 3 - use, after, Force
439 sub bar { 1 }
440 use Class::MakeMethods::Standard::Hash (
441 -ForceInstall => 1, # Set flag for following methods...
442 'scalar' => ['bar'] # ... now overwrites pre-existing bar()
443 );
444 # 4 - make, before
446 Class::MakeMethods::Standard::Hash->make(
447 'scalar'=>['blip'] # blip() is already declared, so has no effect
448 );
449 sub blip { 1 } # Although lower than make(), this "happens" first
450 # 5 - make, after, Force
452 sub ping { 1 }
453 Class::MakeMethods::Standard::Hash->make(
454 -ForceInstall => 1, # Set flag for following methods...
455 'scalar' => ['ping'] # ... now overwrites pre-existing ping()
456 );
457 Global Options
459 Global options may be specified as an argument pair with a leading
461 hyphen. (This distinguishes them from type names, which must be valid
462 Perl subroutine names, and thus will never begin with a hyphen.)
463 use Class::MakeMethods::MakerClass (
465 '-Param' => ParamValue,
466 'MethodType' => [ Arguments ], ...
467 );
468 Option settings apply to all subsequent method declarations within a
470 single "use" or "make" call.
471 The below options allow you to control generation and installation of
473 the requested methods. (Some subclasses may support additional options;
474 see their documentation for details.)
475 -TargetClass
477 By default, the methods are installed in the first package in the
478 caller() stack that is not a Class::MakeMethods subclass; this is
479 generally the package in which your use or make statement was
480 issued. To override this you can pass "-TargetClass => package" as
481 initial arguments to "use" or "make".
482 This allows you to construct or modify classes "from the outside":
484 package main;
486 use Class::MakeMethods::Basic::Hash(
488 -TargetClass => 'MyWidget',
489 'new' => ['create'],
490 'scalar' => ['foo', 'bar'],
491 );
492 $o = MyWidget->new( foo => 'Foozle' );
494 print $o->foo();
495 -MakerClass
497 By default, meta-methods are looked up in the package you called
498 use or make on.
499 You can override this by passing the "-MakerClass" flag, which
501 allows you to switch packages for the remainder of the meta-method
502 types and arguments.
503 use Class::MakeMethods (
505 '-MakerClass'=>'MakerClass',
506 'MethodType' => [ Arguments ]
507 );
508 When specifying the MakerClass, you may provide either the trailing
510 part name of a subclass inside of the "Class::MakeMethods::" names‐
511 pace, or a full package name prefixed by "::".
512 For example, the following four statements are equivalent ways of
514 declaring a Basic::Hash scalar method named 'foo':
515 use Class::MakeMethods::Basic::Hash (
517 'scalar' => [ 'foo' ]
518 );
519 use Class::MakeMethods (
521 'Basic::Hash:scalar' => [ 'foo' ]
522 );
523 use Class::MakeMethods (
525 '-MakerClass'=>'Basic::Hash',
526 'scalar' => [ 'foo' ]
527 );
528 use Class::MakeMethods (
530 '-MakerClass'=>'::Class::MakeMethods::Basic::Hash',
531 'scalar' => [ 'foo' ]
532 );
533 -ForceInstall
535 By default, Class::MakeMethods will not install generated methods
536 over any pre-existing methods in the target class. To override this
537 you can pass "-ForceInstall => 1" as initial arguments to "use" or
538 "make".
539 Note that the "use" keyword acts as a BEGIN block, so a "use" at
541 the top of a file will be executed before any subroutine declara‐
542 tions later in the file have been seen. (See "About Precedence" for
543 additional discussion of this issue.)
544 Mixing Method Types
546 A single calling class can combine generated methods from different
548 MakeMethods subclasses. In general, the only mixing that's problematic
549 is combinations of methods which depend on different underlying object
550 types, like using *::Hash and *::Array methods together -- the methods
551 will be generated, but some of them are guaranteed to fail when
552 called, depending on whether your object happens to be a blessed
553 hashref or arrayref.
554 For example, it's common to mix and match various *::Hash methods, with
556 a scattering of Global or Inheritable methods:
557 use Class::MakeMethods (
559 'Basic::Hash:scalar' => 'foo',
560 'Composite::Hash:scalar' => [ 'bar' => { post_rules => [] } ],
561 'Standard::Global:scalar' => 'our_shared_baz'
562 );
563 Declaration Syntax
565 The following types of Simple declarations are supported:
567 · generator_type => 'method_name'
569 · generator_type => 'method_1 method_2...'
571 · generator_type => [ 'method_1', 'method_2', ...]
573 For a list of the supported values of generator_type, see "STANDARD
575 CLASSES" in Class::MakeMethods::Docs::Catalog, or the documentation for
576 each subclass.
577 For each method name you provide, a subroutine of the indicated type
579 will be generated and installed under that name in your module.
580 Method names should start with a letter, followed by zero or more let‐
582 ters, numbers, or underscores.
583 Argument Normalization
585 The following expansion rules are applied to argument pairs to enable
587 the use of simple strings instead of arrays of arguments.
588 · Each type can be followed by a single meta-method definition, or by
590 a reference to an array of them.
591 · If the argument is provided as a string containing spaces, it is
593 split and each word is treated as a separate argument.
594 · It the meta-method type string contains spaces, it is split and
596 only the first word is used as the type, while the remaining words
597 are placed at the front of the argument list.
598 For example, the following statements are equivalent ways of declaring
600 a pair of Basic::Hash scalar methods named 'foo' and 'bar':
601 use Class::MakeMethods::Basic::Hash (
603 'scalar' => [ 'foo', 'bar' ],
604 );
605 use Class::MakeMethods::Basic::Hash (
607 'scalar' => 'foo',
608 'scalar' => 'bar',
609 );
610 use Class::MakeMethods::Basic::Hash (
612 'scalar' => 'foo bar',
613 );
614 use Class::MakeMethods::Basic::Hash (
616 'scalar foo' => 'bar',
617 );
618 (The last of these is clearly a bit peculiar and potentially misleading
620 if used as shown, but it enables advanced subclasses to provide conve‐
621 nient formatting for declarations with defaults or modifiers, such as
622 'Template::Hash:scalar --private' => 'foo', discussed elsewhere.)
623 Parameter Syntax
625 The Standard syntax also provides several ways to optionally associate
627 a hash of additional parameters with a given method name.
628 · generator_type => [
630 'method_1' => { param=>value... }, ...
631 ]
632 A hash of parameters to use just for this method name.
634 (Note: to prevent confusion with self-contained definition hashes,
636 described below, parameter hashes following a method name must not
637 contain the key 'name'.)
638 · generator_type => [
640 [ 'method_1', 'method_2', ... ] => { param=>value... }
641 ]
642 Each of these method names gets a copy of the same set of parame‐
644 ters.
645 · generator_type => [
647 { 'name'=>'method_1', param=>value... }, ...
648 ]
649 By including the reserved parameter 'name', you create a self-con‐
651 tained declaration with that name and any associated hash values.
652 Simple declarations, as shown in the prior section, are treated as if
654 they had an empty parameter hash.
655 Default Parameters
657 A set of default parameters to be used for several declarations may be
659 specified using any of the following types of arguments to a method
660 generator call:
661 · generator_type => [
663 '-param' => 'value', 'method_1', 'method_2', ...
664 ]
665 Set a default value for the specified parameter to be passed to all
667 subsequent declarations.
668 · generator_type => [
670 '--' => { 'param' => 'value', ... }, 'method_1', 'method_2',
671 ...
672 ]
673 Set default values for one or more parameters to be passed to all
675 subsequent declarations. Equivalent to a series of '-param' =>
676 'value' pairs for each pair in the referenced hash.
677 · generator_type => [
679 '--special_param', 'method_1', 'method_2', ...
680 ]
681 Appends to the default value for a special parameter named "--".
683 This parameter is currently only used by some subclasses; for
684 details see Class::MakeMethods::Template
685 Parameters set in these ways are passed to each declaration that fol‐
687 lows it until the end of the method-generator argument array, or until
688 overridden by another declaration. Parameters specified in a hash for a
689 specific method name, as discussed above, will override the defaults of
690 the same name for that particular method.
691
693 The following warnings and errors may be produced when using
694 Class::MakeMethods to generate methods. (Note that this list does not
695 include run-time messages produced by calling the generated methods.)
696 These messages are classified as follows (listed in increasing order of
698 desperation):
699 (Q) A debugging message, only shown if $CONTEXT{Debug} is true
701 (W) A warning.
702 (D) A deprecation.
703 (F) A fatal error in caller's use of the module.
704 (I) An internal problem with the module or subclasses.
705 Portions of the message which may vary are denoted with a %s.
707 Can't interpret meta-method template: argument is empty or undefined
709 (F)
710 Can't interpret meta-method template: unknown template name '%s'
712 (F)
713 Can't interpret meta-method template: unsupported template type '%s'
715 (F)
716 Can't make method %s(): template specifies unknown behavior '%s'
718 (F)
719 Can't parse meta-method declaration: argument is empty or undefined
721 (F) You passed an undefined value or an empty string in the list of
722 meta-method declarations to use or make.
723 Can't parse meta-method declaration: missing name attribute.
725 (F) You included an hash-ref-style meta-method declaration that did
726 not include the required name attribute. You may have meant this to
727 be an attributes hash for a previously specified name, but if so we
728 were unable to locate it.
729 Can't parse meta-method declaration: unknown template name '%s'
731 (F) You included a template specifier of the form '-template_name'
732 in a the list of meta-method declaration, but that template is not
733 available.
734 Can't parse meta-method declaration: unsupported declaration type '%s'
736 (F) You included an unsupported type of value in a list of meta-
737 method declarations.
738 Compilation error: %s
740 (I)
741 Not an interpretable meta-method: '%s'
743 (I)
744 Odd number of arguments passed to %s make
746 (F) You specified an odd number of arguments in a call to use or
747 make. The arguments should be key => value pairs.
748 Unable to compile generated method %s(): %s
750 (I) The install_methods subroutine attempted to compile a subrou‐
751 tine by calling eval on a provided string, which failed for the
752 indicated reason, usually some type of Perl syntax error.
753 Unable to dynamically load $package: $%s
755 (F)
756 Unable to install code for %s() method: '%s'
758 (I) The install_methods subroutine was passed an unsupported value
759 as the code to install for the named method.
760 Unexpected return value from compilation of %s(): '%s'
762 (I) The install_methods subroutine attempted to compile a subrou‐
763 tine by calling eval on a provided string, but the eval returned
764 something other than than the code ref we expect.
765 Unexpected return value from meta-method constructor %s: %s
767 (I) The requested method-generator was invoked, but it returned an
768 unacceptable value.
769
771 Class::MakeMethods can be extended by creating subclasses that define
772 additional meta-method types. Callers then select your subclass using
773 any of the several techniques described above.
774 Creating A Subclass
776 The begining of a typical extension might look like the below:
778 package My::UpperCaseMethods;
780 use strict;
781 use Class::MakeMethods '-isasubclass';
782 sub my_method_type { ... }
784 You can name your subclass anything you want; it does not need to begin
786 with Class::MakeMethods.
787 The '-isasubclass' flag is a shortcut that automatically puts
789 Class::MakeMethods into your package's @ISA array so that it will
790 inherit the import() and make() class methods. If you omit this flag,
791 you will need to place the superclass in your @ISA explicitly.
792 Typically, the subclass should not inherit from Exporter; both
794 Class::MakeMethods and Exporter are based on inheriting an import class
795 method, and getting a subclass to support both would require additional
796 effort.
797 Naming Method Types
799 Each type of method that can be generated is defined in a subroutine of
801 the same name. You can give your meta-method type any name that is a
802 legal subroutine identifier.
803 (Names begining with an underscore, and the names "import" and "make",
805 are reserved for internal use by Class::MakeMethods.)
806 If you plan on distributing your extension, you may wish to follow the
808 "Naming Convention for Generated Method Types" described above to
809 facilitate reuse by others.
810 Implementation Options
812 Each method generation subroutine can be implemented in any one of the
814 following ways:
815 · Subroutine Generation
817 Returns a list of subroutine name/code pairs.
819 The code returned may either be a coderef, or a string containing
821 Perl code that can be evaled and will return a coderef. If the eval
822 fails, or anything other than a coderef is returned, then
823 Class::MakeMethods croaks.
824 For example a simple sub-class with a method type
826 upper_case_get_set that generates an accessor method for each argu‐
827 ment provided might look like this:
828 package My::UpperCaseMethods;
830 use Class::MakeMethods '-isasubclass';
831 sub uc_scalar {
833 my $class = shift;
834 map {
835 my $name = $_;
836 $name => sub {
837 my $self = shift;
838 if ( scalar @_ ) {
839 $self->{ $name } = uc( shift )
840 } else {
841 $self->{ $name };
842 }
843 }
844 } @_;
845 }
846 Callers could then generate these methods as follows:
848 use My::UpperCaseMethods ( 'uc_scalar' => 'foo' );
850 · Aliasing
852 Returns a string containing a different meta-method type to use for
854 those same arguments.
855 For example a simple sub-class that defines a method type
857 stored_value might look like this:
858 package My::UpperCaseMethods;
860 use Class::MakeMethods '-isasubclass';
861 sub regular_scalar { return 'Basic::Hash:scalar' }
863 And here's an example usage:
865 use My::UpperCaseMethods ( 'regular_scalar' => [ 'foo' ] );
867 · Rewriting
869 Returns one or more array references with different meta-method
871 types and arguments to use.
872 For example, the below meta-method definition reviews the name of
874 each method it's passed and creates different types of meta-methods
875 based on whether the declared name is in all upper case:
876 package My::UpperCaseMethods;
878 use Class::MakeMethods '-isasubclass';
879 sub auto_detect {
881 my $class = shift;
882 my @rewrite = ( [ 'Basic::Hash:scalar' ],
883 [ '::My::UpperCaseMethods:uc_scalar' ] );
884 foreach ( @_ ) {
885 my $name_is_uppercase = ( $_ eq uc($_) ) ? 1 : 0;
886 push @{ $rewrite[ $name_is_uppercase ] }, $_
887 }
888 return @rewrite;
889 }
890 The following invocation would then generate a regular scalar
892 accessor method foo, and a uc_scalar method BAR:
893 use My::UpperCaseMethods ( 'auto_detect' => [ 'foo', 'BAR' ] );
895 · Generator Object
897 Returns an object with a method named make_methods which will be
899 responsible for returning subroutine name/code pairs.
900 See Class::MakeMethods::Template for an example.
902 · Self-Contained
904 Your code may do whatever it wishes, and return an empty list.
906 Access to Options
908 Global option values are available through the _context() class method
910 at the time that method generation is being performed.
911 package My::Maker;
913 sub my_methodtype {
914 my $class = shift;
915 warn "Installing in " . $class->_context('TargetClass');
916 ...
917 }
918 · TargetClass
920 Class into which code should be installed.
922 · MakerClass
924 Which subclass of Class::MakeMethods will generate the methods?
926 · ForceInstall
928 Controls whether generated methods will be installed over pre-
930 existing methods in the target package.
931
933 License and Support
934 For distribution, installation, support, copyright and license informa‐
936 tion, see Class::MakeMethods::Docs::ReadMe.
937 Package Documentation
939 A collection of sample uses is available in Class::MakeMeth‐
941 ods::Docs::Examples.
942 See the documentation for each family of subclasses:
944 · Class::MakeMethods::Basic
946 · Class::MakeMethods::Standard
948 · Class::MakeMethods::Composite
950 · Class::MakeMethods::Template
952 A listing of available method types from each of the different sub‐
954 classes is provided in Class::MakeMethods::Docs::Catalog.
955 Related Modules
957 For a brief survey of the numerous modules on CPAN which offer some
959 type of method generation, see Class::MakeMethods::Docs::RelatedMod‐
960 ules.
961 In several cases, Class::MakeMethods provides functionality closely
963 equivalent to that of an existing module, and emulator modules are pro‐
964 vided to map the existing module's interface to that of
965 Class::MakeMethods. See Class::MakeMethods::Emulator for more informa‐
966 tion.
967 If you have used Class::MethodMaker, you will note numerous similari‐
969 ties between the two. Class::MakeMethods is based on Class::Method‐
970 Maker, but has been substantially revised in order to provide a range
971 of new features. Backward compatibility and conversion documentation
972 is provded in Class::MakeMethods::Emulator::MethodMaker.
973 Perl Docs
975 See perlboot for a quick introduction to objects for beginners. For an
977 extensive discussion of various approaches to class construction, see
978 perltoot and perltootc (called perltootc in the most recent versions of
979 Perl).
980 See "Making References" in perlref, point 4 for more information on
982 closures. (FWIW, I think there's a big opportunity for a "perlfunt"
983 podfile bundled with Perl in the tradition of "perlboot" and "perl‐
984 toot", exploring the utility of function references, callbacks, clo‐
985 sures, and continuations... There are a bunch of useful references
986 available, but not a good overview of how they all interact in a Perl‐
987 ish way.)
988perl v5.8.8 2004-09-06 MakeMethods(3)