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
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 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
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
42 Motivation
43 "Make easy things easier."
44 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 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 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 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 A Contrived Example
62 Object-oriented Perl code is widespread -- you've probably seen code
63 like the below a million times:
64 my $obj = MyStruct->new( foo=>"Foozle", bar=>"Bozzle" );
66 if ( $obj->foo() =~ /foo/i ) {
67 $obj->bar("Barbados!");
68 }
69 print $obj->summary();
70 (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 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 Here's a possible implementation for the class whose interface is shown
83 above:
84 package MyStruct;
86 sub new {
88 my $callee = shift;
89 my $self = bless { @_ }, (ref $callee || $callee);
90 return $self;
91 }
92 sub foo {
94 my $self = shift;
95 if ( scalar @_ ) {
96 $self->{'foo'} = shift();
97 } else {
98 $self->{'foo'}
99 }
100 }
101 sub bar {
103 my $self = shift;
104 if ( scalar @_ ) {
105 $self->{'bar'} = shift();
106 } else {
107 $self->{'bar'}
108 }
109 }
110 sub summary {
112 my $self = shift;
113 join(', ', map { "\u$_: " . $self->$_() } qw( foo bar ) )
114 }
115 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 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 Here's the equivalent declaration for that same basic class:
125 package MyStruct;
127 use Class::MakeMethods::Standard::Hash (
128 'new' => 'new',
129 'scalar' => 'foo',
130 'scalar' => 'bar',
131 );
132 sub summary {
134 my $self = shift;
135 join(', ', map { "\u$_: " . $self->$_() } qw( foo bar ) )
136 }
137 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 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 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 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 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 • A collection of sample uses is available in
168 Class::MakeMethods::Docs::Examples.
169 • 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 • 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 • 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 • A listing of available method types from each of the different
185 subclasses is provided in Class::MakeMethods::Docs::Catalog.
186
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 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 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 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 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 scalar(),
211 which is responsible for generating simple scalar-accessor methods for
212 blessed-hash objects.
213 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 (For a listing of the four main groups of included subclasses, see
320 "Included Subclasses"" in ".)
321 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 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 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
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 However, the features described below are applicable to all subclasses.
349 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 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 • use Class::MakeMethods::MakerClass (
360 'MethodType' => [ Arguments ], ...
361 );
362 • Class::MakeMethods::MakerClass->make (
364 'MethodType' => [ Arguments ], ...
365 );
366 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 • use Class::MakeMethods (
372 'MakerClass:MethodType' => [ Arguments ], ...
373 );
374 • Class::MakeMethods->make (
376 'MakerClass:MethodType' => [ Arguments ], ...
377 );
378 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 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 • use Class::MakeMethods::Autoload 'MakerClass:MethodType';
389 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 • use Class::MakeMethods::Attribute 'MakerClass';
395 sub name :MakeMethod('MethodType' => Arguments);
397 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 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 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 If the same method is declared multiple times, earlier calls to "use"
414 or make() win over later ones, but within each call, later declarations
415 superceed earlier ones.
416 Here are some examples of the results of these precedence rules:
418 # 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 # 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 # 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 # 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 # 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 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 use Class::MakeMethods::MakerClass (
457 '-Param' => ParamValue,
458 'MethodType' => [ Arguments ], ...
459 );
460 Option settings apply to all subsequent method declarations within a
462 single "use" or "make" call.
463 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 -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 This allows you to construct or modify classes "from the outside":
476 package main;
478 use Class::MakeMethods::Basic::Hash(
480 -TargetClass => 'MyWidget',
481 'new' => ['create'],
482 'scalar' => ['foo', 'bar'],
483 );
484 $o = MyWidget->new( foo => 'Foozle' );
486 print $o->foo();
487 -MakerClass
489 By default, meta-methods are looked up in the package you called
490 use or make on.
491 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 use Class::MakeMethods (
497 '-MakerClass'=>'MakerClass',
498 'MethodType' => [ Arguments ]
499 );
500 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 For example, the following four statements are equivalent ways of
506 declaring a Basic::Hash scalar method named 'foo':
507 use Class::MakeMethods::Basic::Hash (
509 'scalar' => [ 'foo' ]
510 );
511 use Class::MakeMethods (
513 'Basic::Hash:scalar' => [ 'foo' ]
514 );
515 use Class::MakeMethods (
517 '-MakerClass'=>'Basic::Hash',
518 'scalar' => [ 'foo' ]
519 );
520 use Class::MakeMethods (
522 '-MakerClass'=>'::Class::MakeMethods::Basic::Hash',
523 'scalar' => [ 'foo' ]
524 );
525 -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 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 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 For example, it's common to mix and match various *::Hash methods, with
547 a scattering of Global or Inheritable methods:
548 use Class::MakeMethods (
550 'Basic::Hash:scalar' => 'foo',
551 'Composite::Hash:scalar' => [ 'bar' => { post_rules => [] } ],
552 'Standard::Global:scalar' => 'our_shared_baz'
553 );
554 Declaration Syntax
556 The following types of Simple declarations are supported:
557 • generator_type => 'method_name'
559 • generator_type => 'method_1 method_2...'
561 • generator_type => [ 'method_1', 'method_2', ...]
563 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 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 Method names should start with a letter, followed by zero or more
572 letters, numbers, or underscores.
573 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 • Each type can be followed by a single meta-method definition, or by
579 a reference to an array of them.
580 • If the argument is provided as a string containing spaces, it is
582 split and each word is treated as a separate argument.
583 • 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 For example, the following statements are equivalent ways of declaring
589 a pair of Basic::Hash scalar methods named 'foo' and 'bar':
590 use Class::MakeMethods::Basic::Hash (
592 'scalar' => [ 'foo', 'bar' ],
593 );
594 use Class::MakeMethods::Basic::Hash (
596 'scalar' => 'foo',
597 'scalar' => 'bar',
598 );
599 use Class::MakeMethods::Basic::Hash (
601 'scalar' => 'foo bar',
602 );
603 use Class::MakeMethods::Basic::Hash (
605 'scalar foo' => 'bar',
606 );
607 (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 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 • generator_type => [
619 'method_1' => { param=>value... }, ...
620 ]
621 A hash of parameters to use just for this method name.
623 (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 • generator_type => [
629 [ 'method_1', 'method_2', ... ] => { param=>value... }
630 ]
631 Each of these method names gets a copy of the same set of
633 parameters.
634 • generator_type => [
636 { 'name'=>'method_1', param=>value... }, ...
637 ]
638 By including the reserved parameter 'name', you create a self-
640 contained declaration with that name and any associated hash
641 values.
642 Simple declarations, as shown in the prior section, are treated as if
644 they had an empty parameter hash.
645 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 • generator_type => [
652 '-param' => 'value', 'method_1', 'method_2', ...
653 ]
654 Set a default value for the specified parameter to be passed to all
656 subsequent declarations.
657 • generator_type => [
659 '--' => { 'param' => 'value', ... }, 'method_1', 'method_2',
660 ...
661 ]
662 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 • generator_type => [
668 '--special_param', 'method_1', 'method_2', ...
669 ]
670 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 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
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 These messages are classified as follows (listed in increasing order of
687 desperation):
688 (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 Portions of the message which may vary are denoted with a %s.
696 Can't interpret meta-method template: argument is empty or undefined
698 (F)
699 Can't interpret meta-method template: unknown template name '%s'
701 (F)
702 Can't interpret meta-method template: unsupported template type '%s'
704 (F)
705 Can't make method %s(): template specifies unknown behavior '%s'
707 (F)
708 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 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 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 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 Compilation error: %s
729 (I)
730 Not an interpretable meta-method: '%s'
732 (I)
733 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 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 Unable to dynamically load $package: $%s
744 (F)
745 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 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 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
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 Creating A Subclass
765 The begining of a typical extension might look like the below:
766 package My::UpperCaseMethods;
768 use strict;
769 use Class::MakeMethods '-isasubclass';
770 sub my_method_type { ... }
772 You can name your subclass anything you want; it does not need to begin
774 with Class::MakeMethods.
775 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 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 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 (Names begining with an underscore, and the names "import" and "make",
792 are reserved for internal use by Class::MakeMethods.)
793 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 Implementation Options
799 Each method generation subroutine can be implemented in any one of the
800 following ways:
801 • Subroutine Generation
803 Returns a list of subroutine name/code pairs.
805 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 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 package My::UpperCaseMethods;
816 use Class::MakeMethods '-isasubclass';
817 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 Callers could then generate these methods as follows:
834 use My::UpperCaseMethods ( 'uc_scalar' => 'foo' );
836 • Aliasing
838 Returns a string containing a different meta-method type to use for
840 those same arguments.
841 For example a simple sub-class that defines a method type
843 stored_value might look like this:
844 package My::UpperCaseMethods;
846 use Class::MakeMethods '-isasubclass';
847 sub regular_scalar { return 'Basic::Hash:scalar' }
849 And here's an example usage:
851 use My::UpperCaseMethods ( 'regular_scalar' => [ 'foo' ] );
853 • Rewriting
855 Returns one or more array references with different meta-method
857 types and arguments to use.
858 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 package My::UpperCaseMethods;
864 use Class::MakeMethods '-isasubclass';
865 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 The following invocation would then generate a regular scalar
878 accessor method foo, and a uc_scalar method BAR:
879 use My::UpperCaseMethods ( 'auto_detect' => [ 'foo', 'BAR' ] );
881 • Generator Object
883 Returns an object with a method named make_methods which will be
885 responsible for returning subroutine name/code pairs.
886 See Class::MakeMethods::Template for an example.
888 • Self-Contained
890 Your code may do whatever it wishes, and return an empty list.
892 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 package My::Maker;
898 sub my_methodtype {
899 my $class = shift;
900 warn "Installing in " . $class->_context('TargetClass');
901 ...
902 }
903 • TargetClass
905 Class into which code should be installed.
907 • MakerClass
909 Which subclass of Class::MakeMethods will generate the methods?
911 • ForceInstall
913 Controls whether generated methods will be installed over pre-
915 existing methods in the target package.
916
918 License and Support
919 For distribution, installation, support, copyright and license
920 information, see Class::MakeMethods::Docs::ReadMe.
921 Package Documentation
923 A collection of sample uses is available in
924 Class::MakeMethods::Docs::Examples.
925 See the documentation for each family of subclasses:
927 • Class::MakeMethods::Basic
929 • Class::MakeMethods::Standard
931 • Class::MakeMethods::Composite
933 • Class::MakeMethods::Template
935 A listing of available method types from each of the different
937 subclasses is provided in Class::MakeMethods::Docs::Catalog.
938 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 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 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 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 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.)
969perl v5.36.0 2023-01-20 MakeMethods(3)