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:
30 package MyClass;
32 use Class::MethodMaker
34 [ scalar => [qw/ name /],
35 new => [qw/ new /],
36 ];
37 This creates a class, of which new instances may be created using
39 "new", each with a single scalar component called "name". Name may be
40 queried and (re)set using the methods "name", "name_reset" and
41 "name_isset":
42 package main;
44 my $m = MyClass->new;
46 my $n;
47 $\ = "\n";
48 print $m->name_isset ? "true" : "false"; # false
50 $m->name("foo");
52 $n = $m->name;
53 print defined $n ? "->$n<-" : "*undef*"; # ->foo<-
54 print $m->name_isset ? "true" : "false"; # true
55 $m->name(undef);
57 $n = $m->name;
58 print defined $n ? "->$n<-" : "*undef*"; # *undef*
59 print $m->name_isset ? "true" : "false"; # true
60 $m->name_reset;
62 $n = $m->name;
63 print defined $n ? "->$n<-" : "*undef*"; # *undef*
64 print $m->name_isset ? "true" : "false"; # false
65 The available component types are scalar, array, hash. Certain non-
67 data-type utilities are also provided: new, for constructors, deep_copy
68 and copy for object copies, and abstract for creating abstract methods.
69 Each of the components take common options. These include -static, for
71 per-class rather than per-instance data, -type, to restrict the data
72 stored to certain types (e.g., objects of a certain class), -forward to
73 forward (proxy) given methods onto components, -default/-default_ctor
74 to set default values for components, -tie_class to tie the storage of
75 a data type to a given class, -read_cb/-store_cb to call user-defined
76 functions on read/store (without the overhead/complexity of ties; and
77 allowing callbacks on existing tie classes).
78 Detailed Use
80 "Class::MethodMaker" installs components into a class, by means of
82 methods that interrogate and amend those components. A component,
83 sometimes referred in other documentation as a slot is a group of one
84 or more attributes (variables) that are associated with an instance of
85 a class (sometimes called an object), or occasionally a class itself
86 (often referred to as a static component). A component is intended as
87 a cohesive unit of data that should only normally be interrogated or
88 set through the methods provided.
89 Given an instance of a class where each instance represents a car,
91 examples of components are the "make" and "model" (each of which would
92 be a simple scalar, a string), the engine (a simple scalar, an instance
93 of Engine::Combustion), and the wheels (an array of instances of
94 Wheel). Note that the wheels form one component, an array. Of course,
95 the implementor might instead choose to use four components, each being
96 a scalar wheel.
97 To have the components created, the principle use of Class::MethodMaker
99 is to specify the type (data-structure) and name of each component to
100 the import method of Class::MethodMaker
101 package MyClass;
103 use Class::MethodMaker
105 [ scalar => 'name',
106 new => [qw/ new /],
107 ];
108 In this example, the import is called implicitly via the "use" state‐
110 ment. The components are installed in the package in effect where the
111 import is called. The argument to import is arranged as pairs, where
112 the first of each pair is the type of the data-structure, the second is
113 the arguments for that data-structure; in the most simple case, the
114 name of a component to install using that data-structure. The second
115 of the pair should be an arrayref if not a simple name.
116 Data-structures may be repeated in the call:
118 use Class::MethodMaker
120 [ scalar => 'name1',
121 new => [qw/ new /],
122 scalar => 'name2',
123 ];
124 It is an error to attempt to install a two or more components with the
126 same name twice.
127 Options may be given to data structures to amend the nature and behav‐
129 iour of the components created. Some options are common across all
130 data structure (e.g., "static") whilst some are specific to their
131 respective data structures. Option syntax is laid out in detail below.
132 In simple, options are provided by way of hashrefs from option name to
133 option value. Options and component names are order-sensitive; options
134 appearing after a component do not affect that component. Options only
135 apply to the data-structure to which they are specified. Boolean
136 options (e.g., static) may be abbreviated to -option to set, !option to
137 unset, without a hashref.
138 use Class::MethodMaker
140 [ scalar => [+{ -type => 'File::stat' }, qw/ -static name /],
141 new => 'new',
142 ];
143 There are also non-data-structure methods that may be created by
145 Class::MethodMaker. "new" is an example of one such value; it instead
146 causes a standard "new" method to be created for the calling class.
147 The arguments and options syntax remains the same, but many options
148 clearly do not apply (e.g., "type" for "new").
149 Interaction with Superclasses
151 Basically, "Class::MethodMaker" takes no notice of class hierarchies.
153 If you choose to install a component x in a class B that is a subclass
154 of class A that already has a component x, then the methods addressing
155 x in B will simply override those in class A in the usual fashion.
156 "Class::MethodMaker" takes no special action for this situation. This
157 is a feature.
158 Option Syntax
160 The arguments to Class::MethodMaker are passed in a single arrayref, as
162 pairs, with the first of each pair being the name of the data-struc‐
163 ture, and the second being the arguments to that structure.
164 use Class::MethodMaker
166 [ scalar => 'name',
167 new => [qw/ new /],
168 ];
169 The second of the pair may in the most simple case be a single scalar
171 that is the name of a component to use.
172 use Class::MethodMaker
174 [ scalar => 'bob', ];
175 For anything more complex, the second argument must itself be an
177 arrayreference. Simple names within this arrayreference are again
178 taken as component names to use; in the following example, both "foo"
179 and "bar" scalar components are created:
180 use Class::MethodMaker
182 [ scalar => [qw/ foo bar /], ];
183 Options to the data-structure, to change the behaviour of the compo‐
185 nent, or methods available, etc., are specified by the presence of a
186 hash reference in line with the component names. Each key of the
187 hashref is the name of an option; the corresponding value is the option
188 value. Option names are easily recognized by a leading hyphen ("-")
189 (or leading exclamation mark, "!"). The options affect only the compo‐
190 nents named after the option itself. In the following example, "foo"
191 is non-static (the default), whilst bar is a static:
192 use Class::MethodMaker
194 [ scalar => ['foo', { -static => 1 }, 'bar'], ];
195 Naturally, options may be altered by later settings overriding earlier
197 ones. The example below has exactly the same effect as the one above:
198 use Class::MethodMaker
200 [ scalar => [{ -static => 1 }, 'bar', { -static => 0 }, 'foo'], ];
201 Options that are boolean (on/off) valued, such as "-static", may be
203 specified external to any hashref as "-optionname" to set them on and
204 "!optionname" to set them off. The example below has exactly the same
205 effect as the one above:
206 use Class::MethodMaker
208 [ scalar => [ qw/ -static bar !static foo /], ];
209 Options that take a value, e.g., "-type", must be specified within a
211 hashref:
212 use Class::MethodMaker
214 [ scalar => [ +{ type => 'File::stat' }, 'bob' ], ];
215 Options affect is limited by the scope of the nearest enclosing
217 arrayref. This particularly means that for multiple invocations of a
218 data structure type, options on earlier invocations do not affect later
219 ones. In the following example, "foo" is non-static (the default),
220 whilst bar is a static:
221 use Class::MethodMaker
223 [ scalar => [ qw/ -static bar /],
224 scalar => [ 'foo' ],
225 ];
226 This is true even if later invocations do not use an arrayref. The
228 example below has exactly the same effect as the one above:
229 use Class::MethodMaker
231 [ scalar => [ qw/ -static bar /],
232 scalar => 'foo',
233 ];
234 Arrayrefs may be employed within a set of arguments for a single data-
236 structure to likewise limit scope. The example below has exactly the
237 same effect as the one above:
238 use Class::MethodMaker
240 [ scalar => [ [ qw/ -static bar / ], 'foo' ],
241 ];
242 Method Renaming
244 Methods may be renamed, by providing options that map from one generic
246 name to another. These are identified by the presence of a '*' in the
247 option name.
248 The example below installs component "a" as a scalar, but the method
250 that would normally be installed as "a_get" is instead installed as
251 "get_a", and likewise "set_a" is installed in place of "a_set".
252 use Class::MethodMaker
254 [ scalar => [ { '*_get' => 'get_*',
255 '*_set' => 'set_*', },
256 'a' ],
257 ];
258 Default & Optional Methods
260 Class::MethodMaker installs a number of methods by default. Some meth‐
262 ods, considered to be useful only to a subset of developers are
263 installed only on request. Each method is marked in the text to state
264 whether it is installed by default or only upon request.
265 To request that a non-default method is installed, one needs to rename
267 it (even possibly to its normal name). So, to install the *_get method
268 for a scalar attribute (as *_get), the syntax is:
269 package MyClass;
271 use Class::MethodMaker
272 [ scalar => [{'*_get' => '*_get'}, 'a'] ];
273 The method may be installed using a non-default name using similar syn‐
275 tax:
276 package MyClass;
278 use Class::MethodMaker
279 [ scalar => [{'*_get' => 'get_*'}, 'a'] ];
280 The client may choose to not install a default method by renaming it to
282 undef:
283 use Class::MethodMaker
285 [ scalar => [{'*' => undef }, 'a'] ];
286 Note Class::MethodMaker will not install a method in place of an exist‐
288 ing method, so if the intent is to not install a default method because
289 the client has their own version, an alternative to the above is to
290 define the client version before calling Class::MethodMaker.
291 Naming & Method-Design Conventions
293 The standard method names are designed with predictability and class
295 extendibility in mind.
296 Naming
298 For any component x that Class::MethodMaker creates, the method names
300 are always "x" or "x_*". This enables predictability, for you do not
301 need to remember which methods are named "x_*" and which *_x, and also
302 you can name methods that you create by avoiding prefixing them with
303 "x", and so avoid any clash with Class::MethodMaker-generated methods
304 (even if Class::MethodMaker is upgraded with shiny new extra methods).
305 Class::MethodMaker users may rename methods (see "Method Renaming").
306 For any data-structure component (scalar, array, hash, etc.) x that
308 Class::MethodMaker creates, the method "x" sets the value of that com‐
309 ponent: i.e., overriding any existing value, not amending or modifying.
310 E.g., for array components, "x" does not push or pull values but all
311 old values are removed, and new ones placed in their stead:
312 package MyClass;
314 use Class::MethodMaker
315 [ array => 'a',
316 new => 'new',
317 ];
318 package main;
320 my $m = MyClass->new;
321 $m->a(4,5);
322 print join(' ', $m->a), "\n"; # 4 5
323 $m->a(6,7);
324 print join(' ', $m->a), "\n"; # 6 7
325 The method returns the new value of the component:
327 print join(' ', $m->a(8,9)), "\n"; # 8 9
329 Note that calling the method with an empty list does not reset the
331 value to empty; this is so that normal lookups work on the method
332 (i.e., if
333 $m->a
335 emptied the component, then
337 @a = $m->a
339 would always give an empty list: not that useful.
341 Set/Unset
343 Each data-structure component has the concept of being set/unset as a
345 whole, independent of individual members being set. Each component
346 starts life unset (unless a default or default option or tie class has
347 been supplied), and is becomes set by any assignment. The component is
348 then reset with the *_reset method. Thus it is possible to distinguish
349 between a component that has been set to an explicitly empty value, and
350 one that has not been set (or been reset). This distinction is analo‐
351 gous to the distinction in hashes between a missing key and a key whose
352 value is undef.
353 package MyClass;
355 use Class::MethodMaker
356 [ new => 'new',
357 scalar => 'x',
358 ];
359 package main;
361 my $m = MyClass->new;
362 $\ = "\n";
364 print $m->x_isset ? "true" : "false"; # false; components start this way
365 my $x = $m->x;
367 print defined $n ? "->$n<-" : '*undef*'; # *undef*
368 print $m->x_isset ? "true" : "false"; # false; reading doesn't set
369 $m->x(undef);
371 $x = $m->x;
372 print $m->x_isset ? "true" : "false"; # true;
373 print defined $n ? "->$n<-" : '*undef*'; # ->foo<-
374 $m->x("foo");
376 $x = $m->x;
377 print $m->x_isset ? "true" : "false"; # true; undef is valid value
378 print defined $n ? "->$n<-" : '*undef*'; # *undef*
379 $m->x_reset;
381 $x = $m->x;
382 print defined $n ? "->$n<-" : '*undef*'; # *undef*
383 print $m->x_isset ? "true" : "false"; # false
384 It is not an error to query the value of an unset component: the value
386 is undef. Querying (any passive command, or pure function) an unset
387 component does not cause it to become set; only assigning (any active
388 command, or procedure) changes the set status of a component.
389 NOTE THAT lvalues are still experimental (as of perl 5.8.0), and so
391 their implementation may change r disappear in the future. Note that
392 lvalue use defeats type-checking. This may be considered a bug, and so
393 may be fixed if possible at some point in the future.
394 Other Design Considerations
396 Further design goals for Class::MethodMaker version 2:
398 Consistency of Options
400 The options passed to components are now handled in a single place,
401 to try to be phrased consistently. As many options as possible are
402 common to all data-structures.
403 Flexibility
405 It is intended that all common class-construction options are sup‐
406 ported across all data-types, so that e.g., defaults, ties, typing
407 may be used with your data-structure of choice, and combined.
408 Speed
410 The methods are intended to be as fast as possible, within other
411 constraints outlined here.
412 Options to "use"/"import"
414 "-target_class"
416 By default, the target class is determined to be the last (latest)
417 class in the call stack that is not a Class::MethodMaker::Engine
418 subtype. This is what is wanted 99% of the time, and typical users
419 need not worry. However, the target class may be set explicitly in
420 the call to "use"/"import":
421 use Class::MethodMaker
423 [ -target_class => 'X',
424 scalar => [qw/ a /],
425 -target_class => 'Y',
426 scalar => [qw/ b /],
427 ];
428 Note that the "-target_class" option is order sensitive: it affects
430 only components requested after it in the call to "use"/"import".
431 As shown, the same call may handle specify multiple target classes.
432 Any components requested before the first "-target_class" are cre‐
433 ated in the default-determined class, as outlined above.
434 Setting the target class in this way does not persist over multiple
436 calls to "use"/"import". A subsequent call to either will use the
437 default-determined class as target (unless again overriden by
438 "-target_class").
439 Standard Options for Data-Structure Components.
441 The following options are observed by all data structure components
443 (scalar, array, hash).
444 -static
446 package MyClass;
447 use Class::MethodMaker
448 [ scalar => [qw/ -static s /], ];
449 This option causes components to hold class-specific, rather than
451 instance-specific values. Thus:
452 package main;
454 my $m = MyClass->new;
455 my $n = MyClass->new;
456 $m->a(4,5);
457 print join(' ', $m->a), "\n"; # 4 5
458 print join(' ', $n->a), "\n"; # 4 5
459 $n->a(6,7);
460 print join(' ', $n->a), "\n"; # 6 7
461 print join(' ', $m->a), "\n"; # 6 7
462 -type
464 use Class::MethodMaker
465 [ scalar => [{ -type => 'File::stat' }, 'st' ]];
466 Takes the name of a class, and checks that all values assigned to
468 the component are of the appropriate type (uses UNIVERSAL::isa, so
469 subtypes are permissible).
470 -forward
472 This option takes as value an arrayref (or a simple scalar). The
473 values specify a list of methods that when called on an instance of
474 the target class, are "forwarded on" to the given component. For
475 example,
476 package X;
478 use Class::MethodMaker
480 [scalar => [{ -type => 'File::stat',
481 -forward => [qw/ mode size /], },
482 'st1',
483 ],
484 ])},
485 any call of "mode" or "size" on an instance of "X" wil simply call
487 the method of the same name on the value stored in the component
488 "st1", with the same arguments, and returns the value(s) of this
489 call.
490 Forwarding only applies to the first named component (since the
492 methodname is fixed, without the a componentname part). This is
493 because the components are installed in the order in which they are
494 created, and Class::MethodMaker never overwrites a pre-existing
495 method. So, in the following example, "mode" and "size" forward to
496 the "st1" component, and "read" forwards to the "st2" component.
497 package MyClass;
499 Class::MethodMaker->import([scalar =>
500 [{ -type => 'File::stat',
501 -forward => [qw/ mode
502 size /],
503 },
504 qw( st1 ),
505 { -type => 'IO::Handle',
506 -forward => 'read', },
507 qw( st2 ),
508 ]])},
509 Forwarding a method to a component of composite data type (e.g.,
511 array, hash) causes the method to be mapped over the values of that
512 component. The returned value is appropriate to the component
513 type; so a method forwarded to an array will return a list, like
514 the array that is the component, but with each value being the
515 instead result of applying the forwarded method to the correspond‐
516 ing value of the array.
517 The following code populates the @sizes array with the sizes of
519 /etc/passwd, /etc/group, in that order.
520 package main;
522 my $m = MyClass->new;
523 $m->st1("/etc/passwd", "/etc/group");
524 my @sizes = $m->size;
525 Calling the forwarding method in a scalar context will get the same
527 results, but as an arrayref:
528 my $sizes = $m->size; # [ 921, 598 ] for example
530 Likewise, forwarding to a hash component will return a hash from
532 original key to result of method on the corresponding component, or
533 an equivalent hashref in scalar context.
534 -default
536 use Class::MethodMaker
537 [ scalar => [{ -default => 7 }, 'df1' ]];
538 Takes a simple value; must be either undef or an instance of the
540 appropriate type if "-type" has also been specified. Whenever a
541 component is new or reset, its value(s) default to the value given.
542 Hence *_isset will always return true for that component. For com‐
543 pound data-structures, the default applies to the each element of
544 the structure, not the compound itself. So, for array structures,
545 the default applies to each element of the array, not the array
546 itself.
547 It is an error to specify the "-default" option and the
549 "-default_ctor" option simultaneously.
550 -default_ctor
552 use Class::MethodMaker
553 [scalar => [{ -default_ctor => sub {
554 Y->new(-3);
555 },
556 'df2',
557 { -type => 'Y',
559 -default_ctor => 'new' },
560 'df3',
561 ]
562 ];
563 Takes a coderef to call to generate the default value. This is
565 called the first time a value is required, and afterwards whenever
566 reset is called. The subr is called with one argument, which is
567 the object upon which the component exists (or the name of the
568 class upon which the component is created, if the call is made on
569 the class).
570 If the "-type" option is in effect, then the value may be a simple
572 value, which shall be considered the name of a method to call on
573 the class specified by "-type".
574 It is an error to specify the "-default" option and the
576 "-default_ctor" option simultaneously.
577 -tie_class
579 # @z is an audit trail
580 my @z;
581 package W;
582 use Tie::Scalar;
583 use base qw( Tie::StdScalar );
584 sub TIESCALAR { push @z, [ 'TIESCALAR' ]; $_[0]->SUPER::TIESCALAR }
585 sub FETCH { push @z, [ 'FETCH' ]; $_[0]->SUPER::FETCH }
586 sub STORE { push @z, [ STORE => $_[1] ]; $_[0]->SUPER::STORE($_[1]) }
587 sub DESTROY { push @z, [ 'DESTROY' ]; $_[0]->SUPER::DESTROY }
588 sub UNTIE { push @z, [ UNTIE => $_[1] ]; $_[0]->SUPER::UNTIE($_[1]) }
589 package X;
591 Class::MethodMaker->import([scalar =>
592 [{ -type => 'File::stat',
593 -tie_class => 'W',
594 -forward => [qw/ mode
595 size /],
596 },
597 qw( tie1 ),
598 new => 'new',
599 ]]);
600 This option takes a simple value as argument, which is taken be the
602 name of a class that is to be tied to the storage for the compo‐
603 nent, e.g., for an array component, a class that implements the API
604 for tied arrays is needed (see Tie::Array for more information on
605 this). Likewise for scalar components, hash components, etc. Note
606 that it is the component that is tied, not the data items.
607 package main;
609 my $x = X->new;
610 # @z is empty
612 my $stat1 = stat "/etc/passwd";
614 my $stat2 = stat "/etc/group";
615 $x->tie1($stat1);
616 # @z is (['TIESCALAR'], ['STORE', $stat1])
618 my $y = $x->tie1;
620 # $y is $stat1
622 # @z is (['TIESCALAR'], ['STORE', $stat1], ['FETCH'])
623 $x->tie1($stat2);
625 # @z is (['TIESCALAR'], ['STORE', $stat1], ['FETCH'], ['STORE', $stat2])
627 $x->tie1_reset;
629 # @z is (['TIESCALAR'], ['STORE', $stat1], ['FETCH'], ['STORE', $stat2],\
631 # ['DESTROY'])
632 -tie_args
634 package X;
635 Class::MethodMaker->import
636 ([scalar => [{ -tie_class => 'V',
637 -tie_args => [enum => [qw/A B C/],
638 default => 'B'],
639 },
640 qw( tie2 ),
641 ]]);
642 This option takes an array reference, whose members are passed as
644 arguments to any tie invoked on the component (by virtue
645 "-tie_class"). If "-tie_class" is not in force, this is ignored.
646 As a convenience measure, a single argument may be passed directly,
648 rather than embedding in an array ref --- unless that arg is an
649 array ref itself...
650 -read_cb
652 The implementation of this option is incomplete
653 package MyClass;
655 use Class::MethodMaker
656 [ scalar => [{ -read_cb => sub { ($_[1]⎪⎪0) + 1 } }, 'rcb1' ]
657 new => 'new';
658 ];
659 This option takes as argument a coderef, which is called whenever a
661 value is read. It is called with two arguments: the instance upon
662 which the method was called, and the value stored in the component.
663 The return value of the given coderef is the value which is passed
664 to the caller of the method as the component value. Thus, the
665 above example adds one to whatever the stored value is. Note that
666 the value is returned to the callee, but not stored in the object
667 package main;
669 my $m = MyClass->new;
670 $m->rcb1(4);
671 my $n = $x->rcb1; # 5
672 my $n = $x->rcb1; # 5
673 -store_cb
675 The implementation of this option is incomplete
676 package MyClass;
678 use Class::MethodMaker
679 [ scalar => [{ -store_cb => sub { $_[1] + 1 } }, 'scb1' ]
680 new => 'new';
681 ];
682 This option takes as argument a coderef, which is called whenever a
684 value is stored. It is called with four arguments: the instance
685 upon which the method was called, the value to store in the compo‐
686 nent, the name of the component, and the previous value of the com‐
687 ponent (if any; if the given element of the component was previ‐
688 ously unset, only three arguments are passed).
689 The return value of the given coderef is the value which is actu‐
691 ally stored in the component. Thus, the above example stores 1
692 greater than the value passed in.
693 package main;
695 my $m = MyClass->new;
696 $m->scb1(4);
697 my $n = $x->scb1; # 5
698 Generally, store callbacks are cheaper than read callbacks, because
700 values are read more often than they are stored. But that is a
701 generalization. YMMV.
702
704 Some new facilities may be marked as EXPERIMENTAL in the documentation.
705 These facilities are being trialled, and whilst it is hoped that they
706 will become mainstream code, no promises are made. They may change or
707 disappear at any time. Caveat Emptor. The maintainer would be
708 delighted to hear any feedback particularly regarding such facilities,
709 be it good or bad, so long as it is constructive.
710 Some old facilities may be marked as COMPATIBILITY in the documenta‐
712 tion. These facilities are being maintained purely for compatibility
713 with old versions of this module, but will ultimately disappear. They
714 are normally replaced by alternatives that are considered preferable.
715 Please avoid using them, and consider amending any existing code that
716 does use them not to. If you believe that their removal will cast an
717 unacceptable pall over your life, please contact the maintainer.
718
720 Class::MethodMaker::Engine, Class::MethodMaker::scalar, Class::Method‐
721 Maker::array, Class::MethodMaker::hash, Class::MethodMaker::V1Compat
722perl v5.8.8 2005-11-26 Class::MethodMaker(3)