1Rose::Class::MakeMethodUss:e:rGeCnoenrtirci(b3u)ted PerlRoDsoec:u:mCelnatsast:i:oMnakeMethods::Generic(3)
2
6 Rose::Class::MakeMethods::Generic - Create simple class methods.
7
9 package MyClass;
10 use Rose::Class::MakeMethods::Generic
12 (
13 scalar =>
14 [
15 'error',
16 'type' => { interface => 'get_set_init' },
17 ],
18 inheritable_scalar => 'name',
20 );
21 sub init_type { 'special' }
23 ...
24 package MySubClass;
26 our @ISA = qw(MyClass);
27 ...
28 MyClass->error(123);
30 print MyClass->type; # 'special'
32 MyClass->name('Fred');
34 print MySubClass->name; # 'Fred'
35 MyClass->name('Wilma');
37 print MySubClass->name; # 'Wilma'
38 MySubClass->name('Bam');
40 print MyClass->name; # 'Wilma'
41 print MySubClass->name; # 'Bam'
42
44 Rose::Class::MakeMethods::Generic is a method maker that inherits from
45 Rose::Object::MakeMethods. See the Rose::Object::MakeMethods
46 documentation to learn about the interface. The method types provided
47 by this module are described below. All methods work only with
48 classes, not objects.
49
51 scalar
52 Create get/set methods for scalar class attributes.
53 Options
55 "init_method"
56 The name of the class method to call when initializing the
57 value of an undefined attribute. This option is only
58 applicable when using the "get_set_init" interface.
59 Defaults to the method name with the prefix "init_" added.
60 "interface"
62 Choose one of the two possible interfaces. Defaults to
63 "get_set".
64 Interfaces
66 "get_set"
67 Creates a simple get/set accessor method for a class
68 attribute. When called with an argument, the value of the
69 attribute is set. The current value of the attribute is
70 returned.
71 "get_set_init"
73 Behaves like the "get_set" interface unless the value of
74 the attribute is undefined. In that case, the class method
75 specified by the "init_method" option is called and the
76 attribute is set to the return value of that method.
77 Example:
79 package MyClass;
81 use Rose::Class::MakeMethods::Generic
83 (
84 scalar => 'power',
85 'scalar --get_set_init' => 'name',
86 );
87 sub init_name { 'Fred' }
89 ...
90 MyClass->power(99); # returns 99
92 MyClass->name; # returns "Fred"
93 MyClass->name('Bill'); # returns "Bill"
94 inheritable_boolean
96 Create get/set methods for boolean class attributes that are
97 inherited by subclasses until/unless their values are changed.
98 Options
100 "interface"
101 Choose the interface. This is kind of pointless since
102 there is only one interface right now. Defaults to
103 "get_set", obviously.
104 Interfaces
106 "get_set"
107 Creates a get/set accessor method for a class attribute.
108 When called with an argument, the value of the attribute is
109 set to 1 if that argument is true or 0 if it is false. The
110 value of the attribute is then returned.
111 If called with no arguments, and if the attribute was never
113 set for this class, then a left-most, breadth-first search
114 of the parent classes is initiated. The value returned is
115 taken from first parent class encountered that has ever had
116 this attribute set.
117 Example:
119 package MyClass;
121 use Rose::Class::MakeMethods::Generic
123 (
124 inheritable_boolean => 'enabled',
125 );
126 ...
127 package MySubClass;
129 our @ISA = qw(MyClass);
130 ...
131 package MySubSubClass;
133 our @ISA = qw(MySubClass);
134 ...
135 $x = MyClass->enabled; # undef
137 $y = MySubClass->enabled; # undef
138 $z = MySubSubClass->enabled; # undef
139 MyClass->enabled(1);
141 $x = MyClass->enabled; # 1
142 $y = MySubClass->enabled; # 1
143 $z = MySubSubClass->enabled; # 1
144 MyClass->enabled(0);
146 $x = MyClass->enabled; # 0
147 $y = MySubClass->enabled; # 0
148 $z = MySubSubClass->enabled; # 0
149 MySubClass->enabled(1);
151 $x = MyClass->enabled; # 0
152 $y = MySubClass->enabled; # 1
153 $z = MySubSubClass->enabled; # 1
154 MyClass->enabled(1);
156 MySubClass->enabled(undef);
157 $x = MyClass->enabled; # 1
158 $y = MySubClass->enabled; # 0
159 $z = MySubSubClass->enabled; # 0
160 MySubSubClass->enabled(1);
162 $x = MyClass->enabled; # 1
163 $y = MySubClass->enabled; # 0
164 $z = MySubSubClass->enabled; # 0
165 inheritable_scalar
167 Create get/set methods for scalar class attributes that are
168 inherited by subclasses until/unless their values are changed.
169 Options
171 "interface"
172 Choose the interface. This is kind of pointless since
173 there is only one interface right now. Defaults to
174 "get_set", obviously.
175 Interfaces
177 "get_set"
178 Creates a get/set accessor method for a class attribute.
179 When called with an argument, the value of the attribute is
180 set and then returned.
181 If called with no arguments, and if the attribute was never
183 set for this class, then a left-most, breadth-first search
184 of the parent classes is initiated. The value returned is
185 taken from first parent class encountered that has ever had
186 this attribute set.
187 Example:
189 package MyClass;
191 use Rose::Class::MakeMethods::Generic
193 (
194 inheritable_scalar => 'name',
195 );
196 ...
197 package MySubClass;
199 our @ISA = qw(MyClass);
200 ...
201 package MySubSubClass;
203 our @ISA = qw(MySubClass);
204 ...
205 $x = MyClass->name; # undef
207 $y = MySubClass->name; # undef
208 $z = MySubSubClass->name; # undef
209 MyClass->name('Fred');
211 $x = MyClass->name; # 'Fred'
212 $y = MySubClass->name; # 'Fred'
213 $z = MySubSubClass->name; # 'Fred'
214 MyClass->name('Wilma');
216 $x = MyClass->name; # 'Wilma'
217 $y = MySubClass->name; # 'Wilma'
218 $z = MySubSubClass->name; # 'Wilma'
219 MySubClass->name('Bam');
221 $x = MyClass->name; # 'Wilma'
222 $y = MySubClass->name; # 'Bam'
223 $z = MySubSubClass->name; # 'Bam'
224 MyClass->name('Koop');
226 MySubClass->name(undef);
227 $x = MyClass->name; # 'Koop'
228 $y = MySubClass->name; # undef
229 $z = MySubSubClass->name; # undef
230 MySubSubClass->name('Sam');
232 $x = MyClass->name; # 'Koop'
233 $y = MySubClass->name; # undef
234 $z = MySubSubClass->name; # 'Sam'
235 hash
237 Create methods to manipulate a hash of class attributes.
238 Options
240 "hash_key"
241 The key to use for the storage of this attribute. Defaults
242 to the name of the method.
243 "interface"
245 Choose which interface to use. Defaults to "get_set".
246 Interfaces
248 "get_set"
249 If called with no arguments, returns a list of key/value
250 pairs in list context or a reference to the actual hash
251 used to store values in scalar context.
252 If called with one argument, and that argument is a
254 reference to a hash, that hash reference is used as the new
255 value for the attribute. Returns a list of key/value pairs
256 in list context or a reference to the actual hash used to
257 store values in scalar context.
258 If called with one argument, and that argument is a
260 reference to an array, then a list of the hash values for
261 each key in the array is returned.
262 If called with one argument, and it is not a reference to a
264 hash or an array, then the hash value for that key is
265 returned.
266 If called with an even number of arguments, they are taken
268 as name/value pairs and are added to the hash. It then
269 returns a list of key/value pairs in list context or a
270 reference to the actual hash used to store values in scalar
271 context.
272 Passing an odd number of arguments greater than 1 causes a
274 fatal error.
275 "get_set_all"
277 If called with no arguments, returns a list of key/value
278 pairs in list context or a reference to the actual hash
279 used to store values in scalar context.
280 If called with one argument, and that argument is a
282 reference to a hash, that hash reference is used as the new
283 value for the attribute. Returns a list of key/value pairs
284 in list context or a reference to the actual hash used to
285 store values in scalar context.
286 Otherwise, the hash is emptied and the arguments are taken
288 as name/value pairs that are then added to the hash. It
289 then returns a list of key/value pairs in list context or a
290 reference to the actual hash used to store values in scalar
291 context.
292 "clear"
294 Sets the attribute to an empty hash.
295 "reset"
297 Sets the attribute to undef.
298 "delete"
300 Deletes the key(s) passed as arguments. Failure to pass
301 any arguments causes a fatal error.
302 "exists"
304 Returns true of the argument exists in the hash, false
305 otherwise. Failure to pass an argument or passing more than
306 one argument causes a fatal error.
307 "keys"
309 Returns the keys of the hash in list context, or a
310 reference to an array of the keys of the hash in scalar
311 context. The keys are not sorted.
312 "names"
314 An alias for the "keys" interface.
315 "values"
317 Returns the values of the hash in list context, or a
318 reference to an array of the values of the hash in scalar
319 context. The values are not sorted.
320 Example:
322 package MyClass;
324 use Rose::Class::MakeMethods::Generic
326 (
327 hash =>
328 [
329 param => { hash_key =>'params' },
330 params => { interface=>'get_set_all' },
331 param_names => { interface=>'keys', hash_key=>'params' },
332 param_values => { interface=>'values', hash_key=>'params' },
333 param_exists => { interface=>'exists', hash_key=>'params' },
334 delete_param => { interface=>'delete', hash_key=>'params' },
335 clear_params => { interface=>'clear', hash_key=>'params' },
337 reset_params => { interface=>'reset', hash_key=>'params' },
338 ],
339 );
340 ...
341 MyClass->params; # undef
343 MyClass->params(a => 1, b => 2); # add pairs
345 $val = MyClass->param('b'); # 2
346 %params = MyClass->params; # copy hash keys and values
348 $params = MyClass->params; # get hash ref
349 MyClass->params({ c => 3, d => 4 }); # replace contents
351 MyClass->param_exists('a'); # false
353 $keys = join(',', sort MyClass->param_names); # 'c,d'
355 $vals = join(',', sort MyClass->param_values); # '3,4'
356 MyClass->delete_param('c');
358 MyClass->param(f => 7, g => 8);
359 $vals = join(',', sort MyClass->param_values); # '4,7,8'
361 MyClass->clear_params;
363 $params = MyClass->params; # empty hash
364 MyClass->reset_params;
366 $params = MyClass->params; # undef
367 inheritable_hash
369 Create methods to manipulate a hash of class attributes that can be
370 inherited by subclasses.
371 The hash of attributes is inherited by subclasses using a one-time
373 copy. Any subclass that accesses or manipulates the hash in any
374 way will immediately get its own private copy of the hash as it
375 exists in the superclass at the time of the access or manipulation.
376 The superclass from which the hash is copied is the closest ("least
378 super") class that has ever accessed or manipulated this hash. The
379 copy is a "shallow" copy, duplicating only the keys and values.
380 Reference values are not recursively copied.
381 Setting to hash to undef (using the 'reset' interface) will cause
383 it to be re-copied from a superclass the next time it is accessed.
384 Options
386 "hash_key"
387 The key to use for the storage of this attribute. Defaults
388 to the name of the method.
389 "interface"
391 Choose which interface to use. Defaults to "get_set".
392 Interfaces
394 "get_set"
395 If called with no arguments, returns a list of key/value
396 pairs in list context or a reference to the actual hash
397 used to store values in scalar context.
398 If called with one argument, and that argument is a
400 reference to a hash, that hash reference is used as the new
401 value for the attribute. Returns a list of key/value pairs
402 in list context or a reference to the actual hash used to
403 store values in scalar context.
404 If called with one argument, and that argument is a
406 reference to an array, then a list of the hash values for
407 each key in the array is returned.
408 If called with one argument, and it is not a reference to a
410 hash or an array, then the hash value for that key is
411 returned.
412 If called with an even number of arguments, they are taken
414 as name/value pairs and are added to the hash. It then
415 returns a list of key/value pairs in list context or a
416 reference to the actual hash used to store values in scalar
417 context.
418 Passing an odd number of arguments greater than 1 causes a
420 fatal error.
421 "get_set_all"
423 If called with no arguments, returns a list of key/value
424 pairs in list context or a reference to the actual hash
425 used to store values in scalar context.
426 If called with one argument, and that argument is a
428 reference to a hash, that hash reference is used as the new
429 value for the attribute. Returns a list of key/value pairs
430 in list context or a reference to the actual hash used to
431 store values in scalar context.
432 Otherwise, the hash is emptied and the arguments are taken
434 as name/value pairs that are then added to the hash. It
435 then returns a list of key/value pairs in list context or a
436 reference to the actual hash used to store values in scalar
437 context.
438 "clear"
440 Sets the attribute to an empty hash.
441 "reset"
443 Sets the attribute to undef.
444 "delete"
446 Deletes the key(s) passed as arguments. Failure to pass
447 any arguments causes a fatal error.
448 "exists"
450 Returns true of the argument exists in the hash, false
451 otherwise. Failure to pass an argument or passing more than
452 one argument causes a fatal error.
453 "keys"
455 Returns the keys of the hash in list context, or a
456 reference to an array of the keys of the hash in scalar
457 context. The keys are not sorted.
458 "names"
460 An alias for the "keys" interface.
461 "values"
463 Returns the values of the hash in list context, or a
464 reference to an array of the values of the hash in scalar
465 context. The values are not sorted.
466 Example:
468 package MyClass;
470 use Rose::Class::MakeMethods::Generic
472 (
473 inheritable_hash =>
474 [
475 param => { hash_key =>'params' },
476 params => { interface=>'get_set_all' },
477 param_names => { interface=>'keys', hash_key=>'params' },
478 param_values => { interface=>'values', hash_key=>'params' },
479 param_exists => { interface=>'exists', hash_key=>'params' },
480 delete_param => { interface=>'delete', hash_key=>'params' },
481 clear_params => { interface=>'clear', hash_key=>'params' },
483 reset_params => { interface=>'reset', hash_key=>'params' },
484 ],
485 );
486 ...
487 package MySubClass;
489 our @ISA = qw(MyClass);
490 ...
491 MyClass->params; # undef
493 MyClass->params(a => 1, b => 2); # add pairs
495 $val = MyClass->param('b'); # 2
496 %params = MyClass->params; # copy hash keys and values
498 $params = MyClass->params; # get hash ref
499 # Inherit a copy of params from MyClass
501 $params = MySubClass->params; # { a => 1, b => 2 }
502 MyClass->params({ c => 3, d => 4 }); # replace contents
504 # MySubClass params are still as the existed at the time
506 # they were originally copied from MyClass
507 $params = MySubClass->params; # { a => 1, b => 2 }
508 # MySubClass can manipulate its own params as it wishes
510 MySubClass->param(z => 9);
511 $params = MySubClass->params; # { a => 1, b => 2, z => 9 }
513 MyClass->param_exists('a'); # false
515 $keys = join(',', sort MyClass->param_names); # 'c,d'
517 $vals = join(',', sort MyClass->param_values); # '3,4'
518 # Reset params (set to undef) so that they will be re-copied
520 # from MyClass the next time they're accessed
521 MySubClass->reset_params;
522 MyClass->delete_param('c');
524 MyClass->param(f => 7, g => 8);
525 $vals = join(',', sort MyClass->param_values); # '4,7,8'
527 # Inherit a copy of params from MyClass
529 $params = MySubClass->params; # { d => 4, f => 7, g => 8 }
530 inherited_hash
532 Create a family of class methods for managing an inherited hash.
533 An inherited hash is made up of the union of the hashes of all
535 superclasses, minus any keys that are explicitly deleted in the
536 current class.
537 Options
539 "add_implies"
540 A method name, or reference to a list of method names, to
541 call when a key is added to the hash. Each added
542 name/value pair is passed to each method in the
543 "add_implies" list, one pair at a time.
544 "add_method"
546 The name of the class method used to add a single
547 name/value pair to the hash. Defaults to the method name
548 with the prefix "add_" added.
549 "adds_method"
551 The name of the class method used to add one or more
552 name/value pairs to the hash. Defaults to "plural_name"
553 with the prefix "add_" added.
554 "cache_method"
556 The name of the class method used to retrieve (or generate,
557 if it doesn't exist) the internal cache for the hash. This
558 should be considered a private method, but it is listed
559 here because it does take up a spot in the method
560 namespace. Defaults to "plural_name" with "_cache" added
561 to the end.
562 "clear_method"
564 The name of the class method used to clear the contents of
565 the hash. Defaults to "plural_name" with a "clear_" prefix
566 added.
567 "delete_implies"
569 A method name, or reference to a list of method names, to
570 call when a key is removed from the hash. Each deleted key
571 is passed as an argument to each method in the
572 "delete_implies" list, one key per call.
573 "delete_method"
575 The name of the class method used to remove a single key
576 from the hash. Defaults to the method name with the prefix
577 "delete_" added.
578 "deletes_method"
580 The name of the class method used to remove one or more
581 keys from the hash. Defaults to "plural_name" with a
582 "delete_" prefix added.
583 "exists_method"
585 The name of the class method that tests for the existence
586 of a key in the hash. Defaults to the method name with the
587 suffix "_exists" added.
588 "get_set_all_method"
590 The name of the class method use to set or fetch the entire
591 hash. The hash may be passed as a reference to a hash or
592 as a list of name/value pairs. Returns the hash (in list
593 context) or a reference to a hash (in scalar context).
594 Defaults to "plural_name".
595 "hash_method"
597 This is an alias for the "get_set_all_method" parameter.
598 "inherit_method"
600 The name of the class method used to indicate that an
601 inherited key that was previously deleted from the hash
602 should return to being inherited. Defaults to the method
603 name with the prefix "inherit_" added.
604 "inherits_method"
606 The name of the class method used to indicate that one or
607 more inherited keys that were previously deleted from the
608 hash should return to being inherited. Defaults to the
609 "plural_name" with the prefix "inherit_" added.
610 "interface"
612 Choose the interface. This is kind of pointless since
613 there is only one interface right now. Defaults to "all",
614 obviously.
615 "keys_method"
617 The name of the class method that returns a reference to a
618 list of keys in scalar context, or a list of keys in list
619 context. Defaults to "plural_name" with "_keys" added to
620 the end.
621 "plural_name"
623 The plural version of the method name, used to construct
624 the default names for some other methods. Defaults to the
625 method name with "s" added.
626 Interfaces
628 "all"
629 Creates the entire family of methods described above. The
630 example below illustrates their use.
631 Example:
633 package MyClass;
635 use Rose::Class::MakeMethods::Generic
637 (
638 inherited_hash =>
639 [
640 pet_color =>
641 {
642 keys_method => 'pets',
643 delete_implies => 'delete_special_pet_color',
644 inherit_implies => 'inherit_special_pet_color',
645 },
646 special_pet_color =>
648 {
649 keys_method => 'special_pets',
650 add_implies => 'add_pet_color',
651 },
652 ],
653 );
654 ...
655 package MySubClass;
657 our @ISA = qw(MyClass);
658 ...
659 MyClass->pet_colors(Fido => 'white',
662 Max => 'black',
663 Spot => 'yellow');
664 MyClass->special_pet_color(Toby => 'tan');
666 MyClass->pets; # Fido, Max, Spot, Toby
668 MyClass->special_pets; # Toby
669 MySubClass->pets; # Fido, Max, Spot, Toby
671 MyClass->pet_color('Toby'); # tan
672 MySubClass->special_pet_color(Toby => 'gold');
674 MyClass->pet_color('Toby'); # tan
676 MyClass->special_pet_color('Toby'); # tan
677 MySubClass->pet_color('Toby'); # gold
679 MySubClass->special_pet_color('Toby'); # gold
680 MySubClass->inherit_pet_color('Toby');
682 MySubClass->pet_color('Toby'); # tan
684 MySubClass->special_pet_color('Toby'); # tan
685 MyClass->delete_pet_color('Max');
687 MyClass->pets; # Fido, Spot, Toby
689 MySubClass->pets; # Fido, Spot, Toby
690 MyClass->special_pet_color(Max => 'mauve');
692 MyClass->pets; # Fido, Max, Spot, Toby
694 MySubClass->pets; # Fido, Max, Spot, Toby
695 MyClass->special_pets; # Max, Toby
697 MySubClass->special_pets; # Max, Toby
698 MySubClass->delete_special_pet_color('Max');
700 MyClass->pets; # Fido, Max, Spot, Toby
702 MySubClass->pets; # Fido, Max, Spot, Toby
703 MyClass->special_pets; # Max, Toby
705 MySubClass->special_pets; # Toby
706
708 John C. Siracusa (siracusa@gmail.com)
709
711 Copyright (c) 2010 by John C. Siracusa. All rights reserved. This
712 program is free software; you can redistribute it and/or modify it
713 under the same terms as Perl itself.
714perl v5.28.1 2013-10-0R4ose::Class::MakeMethods::Generic(3)