1Class::MethodMaker(3) User Contributed Perl DocumentationClass::MethodMaker(3)
2
6 Class::MethodMaker - Create generic methods for OO Perl
7
9 use Class::MethodMaker
10 [ scalar => [qw/ foo bar baz /],
11 new => [qw/ new /] ,
12 ];
13
15 This module solves the problem of having to continually write accessor
16 methods for your objects that perform standard tasks.
17 The argument to 'use' is an arrayref, as pairs whose "keys" are the
19 names of types of generic methods generated by MethodMaker and whose
20 "values" tell method maker what methods to make.
21 To override any generated methods, it is sufficient to ensure that the
23 overriding method is defined when Class::MethodMaker is called. Note
24 that the "use" keyword introduces a "BEGIN" block, so you may need to
25 define (or at least declare) your overriding method in a "BEGIN" block.
26 Simple Use
28 A simple class made with "Class::MethodMaker" looks like this:
29 package MyClass;
31 use Class::MethodMaker
33 [ scalar => [qw/ name /],
34 new => [qw/ new /],
35 ];
36 This creates a class, of which new instances may be created using
38 "new", each with a single scalar component called "name". Name may be
39 queried and (re)set using the methods "name", "name_reset" and
40 "name_isset":
41 package main;
43 my $m = MyClass->new;
45 my $n;
46 $\ = "\n";
47 print $m->name_isset ? "true" : "false"; # false
49 $m->name("foo");
51 $n = $m->name;
52 print defined $n ? "->$n<-" : "*undef*"; # ->foo<-
53 print $m->name_isset ? "true" : "false"; # true
54 $m->name(undef);
56 $n = $m->name;
57 print defined $n ? "->$n<-" : "*undef*"; # *undef*
58 print $m->name_isset ? "true" : "false"; # true
59 $m->name_reset;
61 $n = $m->name;
62 print defined $n ? "->$n<-" : "*undef*"; # *undef*
63 print $m->name_isset ? "true" : "false"; # false
64 The available component types are scalar, array, hash. Certain non-
66 data-type utilities are also provided: new, for constructors, deep_copy
67 and copy for object copies, and abstract for creating abstract methods.
68 Each of the components take common options. These include -static, for
70 per-class rather than per-instance data, -type, to restrict the data
71 stored to certain types (e.g., objects of a certain class), -forward to
72 forward (proxy) given methods onto components, -default/-default_ctor
73 to set default values for components, -tie_class to tie the storage of
74 a data type to a given class, -read_cb/-store_cb to call user-defined
75 functions on read/store (without the overhead/complexity of ties; and
76 allowing callbacks on existing tie classes).
77 Detailed Use
79 "Class::MethodMaker" installs components into a class, by means of
80 methods that interrogate and amend those components. A component,
81 sometimes referred in other documentation as a slot is a group of one
82 or more attributes (variables) that are associated with an instance of
83 a class (sometimes called an object), or occasionally a class itself
84 (often referred to as a static component). A component is intended as
85 a cohesive unit of data that should only normally be interrogated or
86 set through the methods provided.
87 Given an instance of a class where each instance represents a car,
89 examples of components are the "make" and "model" (each of which would
90 be a simple scalar, a string), the engine (a simple scalar, an instance
91 of Engine::Combustion), and the wheels (an array of instances of
92 Wheel). Note that the wheels form one component, an array. Of course,
93 the implementor might instead choose to use four components, each being
94 a scalar wheel.
95 To have the components created, the principle use of Class::MethodMaker
97 is to specify the type (data-structure) and name of each component to
98 the import method of Class::MethodMaker
99 package MyClass;
101 use Class::MethodMaker
103 [ scalar => 'name',
104 new => [qw/ new /],
105 ];
106 In this example, the import is called implicitly via the "use"
108 statement. The components are installed in the package in effect where
109 the import is called. The argument to import is arranged as pairs,
110 where the first of each pair is the type of the data-structure, the
111 second is the arguments for that data-structure; in the most simple
112 case, the name of a component to install using that data-structure.
113 The second of the pair should be an arrayref if not a simple name.
114 Data-structures may be repeated in the call:
116 use Class::MethodMaker
118 [ scalar => 'name1',
119 new => [qw/ new /],
120 scalar => 'name2',
121 ];
122 It is an error to attempt to install a two or more components with the
124 same name twice.
125 Options may be given to data structures to amend the nature and
127 behaviour of the components created. Some options are common across
128 all data structure (e.g., "static") whilst some are specific to their
129 respective data structures. Option syntax is laid out in detail below.
130 In simple, options are provided by way of hashrefs from option name to
131 option value. Options and component names are order-sensitive; options
132 appearing after a component do not affect that component. Options only
133 apply to the data-structure to which they are specified. Boolean
134 options (e.g., static) may be abbreviated to -option to set, !option to
135 unset, without a hashref.
136 use Class::MethodMaker
138 [ scalar => [+{ -type => 'File::stat' }, qw/ -static name /],
139 new => 'new',
140 ];
141 There are also non-data-structure methods that may be created by
143 Class::MethodMaker. "new" is an example of one such value; it instead
144 causes a standard "new" method to be created for the calling class.
145 The arguments and options syntax remains the same, but many options
146 clearly do not apply (e.g., "type" for "new").
147 Interaction with Superclasses
149 Basically, "Class::MethodMaker" takes no notice of class hierarchies.
150 If you choose to install a component x in a class B that is a subclass
151 of class A that already has a component x, then the methods addressing
152 x in B will simply override those in class A in the usual fashion.
153 "Class::MethodMaker" takes no special action for this situation. This
154 is a feature.
155 Option Syntax
157 The arguments to Class::MethodMaker are passed in a single arrayref, as
158 pairs, with the first of each pair being the name of the data-
159 structure, and the second being the arguments to that structure.
160 use Class::MethodMaker
162 [ scalar => 'name',
163 new => [qw/ new /],
164 ];
165 The second of the pair may in the most simple case be a single scalar
167 that is the name of a component to use.
168 use Class::MethodMaker
170 [ scalar => 'bob', ];
171 For anything more complex, the second argument must itself be an
173 arrayreference. Simple names within this arrayreference are again
174 taken as component names to use; in the following example, both "foo"
175 and "bar" scalar components are created:
176 use Class::MethodMaker
178 [ scalar => [qw/ foo bar /], ];
179 Options to the data-structure, to change the behaviour of the
181 component, or methods available, etc., are specified by the presence of
182 a hash reference in line with the component names. Each key of the
183 hashref is the name of an option; the corresponding value is the option
184 value. Option names are easily recognized by a leading hyphen ("-")
185 (or leading exclamation mark, "!"). The options affect only the
186 components named after the option itself. In the following example,
187 "foo" is non-static (the default), whilst bar is a static:
188 use Class::MethodMaker
190 [ scalar => ['foo', { -static => 1 }, 'bar'], ];
191 Naturally, options may be altered by later settings overriding earlier
193 ones. The example below has exactly the same effect as the one above:
194 use Class::MethodMaker
196 [ scalar => [{ -static => 1 }, 'bar', { -static => 0 }, 'foo'], ];
197 Options that are boolean (on/off) valued, such as "-static", may be
199 specified external to any hashref as "-optionname" to set them on and
200 "!optionname" to set them off. The example below has exactly the same
201 effect as the one above:
202 use Class::MethodMaker
204 [ scalar => [ qw/ -static bar !static foo /], ];
205 Options that take a value, e.g., "-type", must be specified within a
207 hashref:
208 use Class::MethodMaker
210 [ scalar => [ +{ type => 'File::stat' }, 'bob' ], ];
211 Options affect is limited by the scope of the nearest enclosing
213 arrayref. This particularly means that for multiple invocations of a
214 data structure type, options on earlier invocations do not affect later
215 ones. In the following example, "foo" is non-static (the default),
216 whilst bar is a static:
217 use Class::MethodMaker
219 [ scalar => [ qw/ -static bar /],
220 scalar => [ 'foo' ],
221 ];
222 This is true even if later invocations do not use an arrayref. The
224 example below has exactly the same effect as the one above:
225 use Class::MethodMaker
227 [ scalar => [ qw/ -static bar /],
228 scalar => 'foo',
229 ];
230 Arrayrefs may be employed within a set of arguments for a single data-
232 structure to likewise limit scope. The example below has exactly the
233 same effect as the one above:
234 use Class::MethodMaker
236 [ scalar => [ [ qw/ -static bar / ], 'foo' ],
237 ];
238 Method Renaming
240 Methods may be renamed, by providing options that map from one generic
241 name to another. These are identified by the presence of a '*' in the
242 option name.
243 The example below installs component "a" as a scalar, but the method
245 that would normally be installed as "a_get" is instead installed as
246 "get_a", and likewise "set_a" is installed in place of "a_set".
247 use Class::MethodMaker
249 [ scalar => [ { '*_get' => 'get_*',
250 '*_set' => 'set_*', },
251 'a' ],
252 ];
253 Default & Optional Methods
255 Class::MethodMaker installs a number of methods by default. Some
256 methods, considered to be useful only to a subset of developers are
257 installed only on request. Each method is marked in the text to state
258 whether it is installed by default or only upon request.
259 To request that a non-default method is installed, one needs to rename
261 it (even possibly to its normal name). So, to install the *_get method
262 for a scalar attribute (as *_get), the syntax is:
263 package MyClass;
265 use Class::MethodMaker
266 [ scalar => [{'*_get' => '*_get'}, 'a'] ];
267 The method may be installed using a non-default name using similar
269 syntax:
270 package MyClass;
272 use Class::MethodMaker
273 [ scalar => [{'*_get' => 'get_*'}, 'a'] ];
274 The client may choose to not install a default method by renaming it to
276 undef:
277 use Class::MethodMaker
279 [ scalar => [{'*' => undef }, 'a'] ];
280 Note Class::MethodMaker will not install a method in place of an
282 existing method, so if the intent is to not install a default method
283 because the client has their own version, an alternative to the above
284 is to define the client version before calling Class::MethodMaker.
285 Naming & Method-Design Conventions
287 The standard method names are designed with predictability and class
288 extendibility in mind.
289 Naming
291 For any component x that Class::MethodMaker creates, the method names
293 are always "x" or "x_*". This enables predictability, for you do not
294 need to remember which methods are named "x_*" and which *_x, and also
295 you can name methods that you create by avoiding prefixing them with
296 "x", and so avoid any clash with Class::MethodMaker-generated methods
297 (even if Class::MethodMaker is upgraded with shiny new extra methods).
298 Class::MethodMaker users may rename methods (see "Method Renaming").
299 For any data-structure component (scalar, array, hash, etc.) x that
301 Class::MethodMaker creates, the method "x" sets the value of that
302 component: i.e., overriding any existing value, not amending or
303 modifying. E.g., for array components, "x" does not push or pull
304 values but all old values are removed, and new ones placed in their
305 stead:
306 package MyClass;
308 use Class::MethodMaker
309 [ array => 'a',
310 new => 'new',
311 ];
312 package main;
314 my $m = MyClass->new;
315 $m->a(4,5);
316 print join(' ', $m->a), "\n"; # 4 5
317 $m->a(6,7);
318 print join(' ', $m->a), "\n"; # 6 7
319 The method returns the new value of the component:
321 print join(' ', $m->a(8,9)), "\n"; # 8 9
323 Note that calling the method with an empty list does not reset the
325 value to empty; this is so that normal lookups work on the method
326 (i.e., if
327 $m->a
329 emptied the component, then
331 @a = $m->a
333 would always give an empty list: not that useful.
335 Set/Unset
337 Each data-structure component has the concept of being set/unset as a
339 whole, independent of individual members being set. Each component
340 starts life unset (unless a default or default option or tie class has
341 been supplied), and is becomes set by any assignment. The component is
342 then reset with the *_reset method. Thus it is possible to distinguish
343 between a component that has been set to an explicitly empty value, and
344 one that has not been set (or been reset). This distinction is
345 analogous to the distinction in hashes between a missing key and a key
346 whose value is undef.
347 package MyClass;
349 use Class::MethodMaker
350 [ new => 'new',
351 scalar => 'x',
352 ];
353 package main;
355 my $m = MyClass->new;
356 $\ = "\n";
358 print $m->x_isset ? "true" : "false"; # false; components start this way
359 my $x = $m->x;
361 print defined $n ? "->$n<-" : '*undef*'; # *undef*
362 print $m->x_isset ? "true" : "false"; # false; reading doesn't set
363 $m->x(undef);
365 $x = $m->x;
366 print $m->x_isset ? "true" : "false"; # true;
367 print defined $n ? "->$n<-" : '*undef*'; # ->foo<-
368 $m->x("foo");
370 $x = $m->x;
371 print $m->x_isset ? "true" : "false"; # true; undef is valid value
372 print defined $n ? "->$n<-" : '*undef*'; # *undef*
373 $m->x_reset;
375 $x = $m->x;
376 print defined $n ? "->$n<-" : '*undef*'; # *undef*
377 print $m->x_isset ? "true" : "false"; # false
378 It is not an error to query the value of an unset component: the value
380 is undef. Querying (any passive command, or pure function) an unset
381 component does not cause it to become set; only assigning (any active
382 command, or procedure) changes the set status of a component.
383 NOTE THAT lvalues are still experimental (as of perl 5.8.0), and so
385 their implementation may change r disappear in the future. Note that
386 lvalue use defeats type-checking. This may be considered a bug, and so
387 may be fixed if possible at some point in the future.
388 Other Design Considerations
390 Further design goals for Class::MethodMaker version 2:
392 Consistency of Options
394 The options passed to components are now handled in a single place,
395 to try to be phrased consistently. As many options as possible are
396 common to all data-structures.
397 Flexibility
399 It is intended that all common class-construction options are
400 supported across all data-types, so that e.g., defaults, ties,
401 typing may be used with your data-structure of choice, and
402 combined.
403 Speed
405 The methods are intended to be as fast as possible, within other
406 constraints outlined here.
407 Options to "use"/"import"
409 "-target_class"
410 By default, the target class is determined to be the last (latest)
411 class in the call stack that is not a Class::MethodMaker::Engine
412 subtype. This is what is wanted 99% of the time, and typical users
413 need not worry. However, the target class may be set explicitly in
414 the call to "use"/"import":
415 use Class::MethodMaker
417 [ -target_class => 'X',
418 scalar => [qw/ a /],
419 -target_class => 'Y',
420 scalar => [qw/ b /],
421 ];
422 Note that the "-target_class" option is order sensitive: it affects
424 only components requested after it in the call to "use"/"import".
425 As shown, the same call may handle specify multiple target classes.
426 Any components requested before the first "-target_class" are
427 created in the default-determined class, as outlined above.
428 Setting the target class in this way does not persist over multiple
430 calls to "use"/"import". A subsequent call to either will use the
431 default-determined class as target (unless again overridden by
432 "-target_class").
433 Standard Options for Data-Structure Components.
435 The following options are observed by all data structure components
436 (scalar, array, hash).
437 -static
439 package MyClass;
440 use Class::MethodMaker
441 [ scalar => [qw/ -static s /], ];
442 This option causes components to hold class-specific, rather than
444 instance-specific values. Thus:
445 package main;
447 my $m = MyClass->new;
448 my $n = MyClass->new;
449 $m->a(4,5);
450 print join(' ', $m->a), "\n"; # 4 5
451 print join(' ', $n->a), "\n"; # 4 5
452 $n->a(6,7);
453 print join(' ', $n->a), "\n"; # 6 7
454 print join(' ', $m->a), "\n"; # 6 7
455 -type
457 use Class::MethodMaker
458 [ scalar => [{ -type => 'File::stat' }, 'st' ]];
459 Takes the name of a class, and checks that all values assigned to
461 the component are of the appropriate type (uses UNIVERSAL::isa, so
462 subtypes are permissible).
463 -forward
465 This option takes as value an arrayref (or a simple scalar). The
466 values specify a list of methods that when called on an instance of
467 the target class, are "forwarded on" to the given component. For
468 example,
469 package X;
471 use Class::MethodMaker
473 [scalar => [{ -type => 'File::stat',
474 -forward => [qw/ mode size /], },
475 'st1',
476 ],
477 ])},
478 any call of "mode" or "size" on an instance of "X" will simply call
480 the method of the same name on the value stored in the component
481 "st1", with the same arguments, and returns the value(s) of this
482 call.
483 Forwarding only applies to the first named component (since the
485 methodname is fixed, without the a componentname part). This is
486 because the components are installed in the order in which they are
487 created, and Class::MethodMaker never overwrites a pre-existing
488 method. So, in the following example, "mode" and "size" forward to
489 the "st1" component, and "read" forwards to the "st2" component.
490 package MyClass;
492 Class::MethodMaker->import([scalar =>
493 [{ -type => 'File::stat',
494 -forward => [qw/ mode
495 size /],
496 },
497 qw( st1 ),
498 { -type => 'IO::Handle',
499 -forward => 'read', },
500 qw( st2 ),
501 ]])},
502 Forwarding a method to a component of composite data type (e.g.,
504 array, hash) causes the method to be mapped over the values of that
505 component. The returned value is appropriate to the component
506 type; so a method forwarded to an array will return a list, like
507 the array that is the component, but with each value being the
508 instead result of applying the forwarded method to the
509 corresponding value of the array.
510 The following code populates the @sizes array with the sizes of
512 /etc/passwd, /etc/group, in that order.
513 package main;
515 my $m = MyClass->new;
516 $m->st1("/etc/passwd", "/etc/group");
517 my @sizes = $m->size;
518 Calling the forwarding method in a scalar context will get the same
520 results, but as an arrayref:
521 my $sizes = $m->size; # [ 921, 598 ] for example
523 Likewise, forwarding to a hash component will return a hash from
525 original key to result of method on the corresponding component, or
526 an equivalent hashref in scalar context.
527 -default
529 use Class::MethodMaker
530 [ scalar => [{ -default => 7 }, 'df1' ]];
531 Takes a simple value; must be either undef or an instance of the
533 appropriate type if "-type" has also been specified. Whenever a
534 component is new or reset, its value(s) default to the value given.
535 Hence *_isset will always return true for that component. For
536 compound data-structures, the default applies to the each element
537 of the structure, not the compound itself. So, for array
538 structures, the default applies to each element of the array, not
539 the array itself.
540 It is an error to specify the "-default" option and the
542 "-default_ctor" option simultaneously.
543 -default_ctor
545 use Class::MethodMaker
546 [scalar => [{ -default_ctor => sub {
547 Y->new(-3);
548 },
549 'df2',
550 { -type => 'Y',
552 -default_ctor => 'new' },
553 'df3',
554 ]
555 ];
556 Takes a coderef to call to generate the default value. This is
558 called the first time a value is required, and afterwards whenever
559 reset is called. The subr is called with one argument, which is
560 the object upon which the component exists (or the name of the
561 class upon which the component is created, if the call is made on
562 the class).
563 If the "-type" option is in effect, then the value may be a simple
565 value, which shall be considered the name of a method to call on
566 the class specified by "-type".
567 It is an error to specify the "-default" option and the
569 "-default_ctor" option simultaneously.
570 -tie_class
572 # @z is an audit trail
573 my @z;
574 package W;
575 use Tie::Scalar;
576 use base qw( Tie::StdScalar );
577 sub TIESCALAR { push @z, [ 'TIESCALAR' ]; $_[0]->SUPER::TIESCALAR }
578 sub FETCH { push @z, [ 'FETCH' ]; $_[0]->SUPER::FETCH }
579 sub STORE { push @z, [ STORE => $_[1] ]; $_[0]->SUPER::STORE($_[1]) }
580 sub DESTROY { push @z, [ 'DESTROY' ]; $_[0]->SUPER::DESTROY }
581 sub UNTIE { push @z, [ UNTIE => $_[1] ]; $_[0]->SUPER::UNTIE($_[1]) }
582 package X;
584 Class::MethodMaker->import([scalar =>
585 [{ -type => 'File::stat',
586 -tie_class => 'W',
587 -forward => [qw/ mode
588 size /],
589 },
590 qw( tie1 ),
591 new => 'new',
592 ]]);
593 This option takes a simple value as argument, which is taken be the
595 name of a class that is to be tied to the storage for the
596 component, e.g., for an array component, a class that implements
597 the API for tied arrays is needed (see Tie::Array for more
598 information on this). Likewise for scalar components, hash
599 components, etc. Note that it is the component that is tied, not
600 the data items.
601 package main;
603 my $x = X->new;
604 # @z is empty
606 my $stat1 = stat "/etc/passwd";
608 my $stat2 = stat "/etc/group";
609 $x->tie1($stat1);
610 # @z is (['TIESCALAR'], ['STORE', $stat1])
612 my $y = $x->tie1;
614 # $y is $stat1
616 # @z is (['TIESCALAR'], ['STORE', $stat1], ['FETCH'])
617 $x->tie1($stat2);
619 # @z is (['TIESCALAR'], ['STORE', $stat1], ['FETCH'], ['STORE', $stat2])
621 $x->tie1_reset;
623 # @z is (['TIESCALAR'], ['STORE', $stat1], ['FETCH'], ['STORE', $stat2],\
625 # ['DESTROY'])
626 -tie_args
628 package X;
629 Class::MethodMaker->import
630 ([scalar => [{ -tie_class => 'V',
631 -tie_args => [enum => [qw/A B C/],
632 default => 'B'],
633 },
634 qw( tie2 ),
635 ]]);
636 This option takes an array reference, whose members are passed as
638 arguments to any tie invoked on the component (by virtue
639 "-tie_class"). If "-tie_class" is not in force, this is ignored.
640 As a convenience measure, a single argument may be passed directly,
642 rather than embedding in an array ref --- unless that arg is an
643 array ref itself...
644 -read_cb
646 The implementation of this option is incomplete
647 package MyClass;
649 use Class::MethodMaker
650 [ scalar => [{ -read_cb => sub { ($_[1]||0) + 1 } }, 'rcb1' ]
651 new => 'new';
652 ];
653 This option takes as argument a coderef, which is called whenever a
655 value is read. It is called with two arguments: the instance upon
656 which the method was called, and the value stored in the component.
657 The return value of the given coderef is the value which is passed
658 to the caller of the method as the component value. Thus, the
659 above example adds one to whatever the stored value is. Note that
660 the value is returned to the callee, but not stored in the object
661 package main;
663 my $m = MyClass->new;
664 $m->rcb1(4);
665 my $n = $x->rcb1; # 5
666 my $n = $x->rcb1; # 5
667 -store_cb
669 The implementation of this option is incomplete
670 package MyClass;
672 use Class::MethodMaker
673 [ scalar => [{ -store_cb => sub { $_[1] + 1 } }, 'scb1' ]
674 new => 'new';
675 ];
676 This option takes as argument a coderef, which is called whenever a
678 value is stored. It is called with four arguments: the instance
679 upon which the method was called, the value to store in the
680 component, the name of the component, and the previous value of the
681 component (if any; if the given element of the component was
682 previously unset, only three arguments are passed).
683 The return value of the given coderef is the value which is
685 actually stored in the component. Thus, the above example stores 1
686 greater than the value passed in.
687 package main;
689 my $m = MyClass->new;
690 $m->scb1(4);
691 my $n = $x->scb1; # 5
692 Generally, store callbacks are cheaper than read callbacks, because
694 values are read more often than they are stored. But that is a
695 generalization. YMMV.
696
698 Some new facilities may be marked as EXPERIMENTAL in the documentation.
699 These facilities are being trialled, and whilst it is hoped that they
700 will become mainstream code, no promises are made. They may change or
701 disappear at any time. Caveat Emptor. The maintainer would be
702 delighted to hear any feedback particularly regarding such facilities,
703 be it good or bad, so long as it is constructive.
704 Some old facilities may be marked as COMPATIBILITY in the
706 documentation. These facilities are being maintained purely for
707 compatibility with old versions of this module, but will ultimately
708 disappear. They are normally replaced by alternatives that are
709 considered preferable. Please avoid using them, and consider amending
710 any existing code that does use them not to. If you believe that their
711 removal will cast an unacceptable pall over your life, please contact
712 the maintainer.
713
715 Class::MethodMaker::Engine, Class::MethodMaker::scalar,
716 Class::MethodMaker::array, Class::MethodMaker::hash,
717 Class::MethodMaker::V1Compat
718perl v5.34.0 2022-01-21 Class::MethodMaker(3)