1Rose::Class::MakeMethodUss:e:rSeCto(n3t)ributed Perl DocRuomseen:t:aCtliaosns::MakeMethods::Set(3)
2
3
4

NAME

6       Rose::Class::MakeMethods::Set - Create class methods to manage sets.
7

SYNOPSIS

9         package MyClass;
10
11         use Rose::Class::MakeMethods::Set
12         (
13           inheritable_set =>
14           [
15             required_name =>
16             {
17               add_implies => 'add_valid_name',
18               test_method => 'name_is_required',
19             },
20           ],
21
22           inherited_set =>
23           [
24             valid_name =>
25             {
26               test_method => 'name_is_valid',
27             },
28           ],
29         );
30
31         ...
32
33         package MySubClass;
34         our @ISA = qw(MyClass);
35         ...
36
37         MyClass->add_valid_names('A', 'B', 'C');
38         MyClass->add_required_name('D');
39
40         $v1 = join(',', MyClass->valid_names);       # 'A,B,C,D';
41         $r1 = join(',', MyClass->required_names);    # 'D'
42
43         $v2 = join(',', MySubClass->valid_names);    # 'A,B,C,D';
44         $r2 = join(',', MySubClass->required_names); # 'D'
45
46         MySubClass->add_required_names('X', 'Y');
47
48         $v2 = join(',', MySubClass->valid_names);    # 'A,B,C,D,X,Y';
49         $r2 = join(',', MySubClass->required_names); # 'D,X,Y'
50
51         MySubClass->delete_valid_names('B', 'X');
52
53         $v1 = join(',', MyClass->valid_names);       # 'A,B,C,D';
54         $r1 = join(',', MyClass->required_names);    # 'D'
55
56         $v2 = join(',', MySubClass->valid_names);    # 'A,C,D,Y';
57         $r2 = join(',', MySubClass->required_names); # 'D,X,Y'
58
59         MySubClass->delete_required_name('D');
60
61         $v1 = join(',', MyClass->valid_names);       # 'A,B,C,D';
62         $r1 = join(',', MyClass->required_names);    # 'D'
63
64         $v2 = join(',', MySubClass->valid_names);    # 'A,C,D,Y';
65         $r2 = join(',', MySubClass->required_names); # 'X,Y'
66

DESCRIPTION

68       Rose::Class::MakeMethods::Set is a method maker that inherits from
69       Rose::Object::MakeMethods.  See the Rose::Object::MakeMethods
70       documentation to learn about the interface.  The method types provided
71       by this module are described below.  All methods work only with
72       classes, not objects.
73

METHODS TYPES

75       inheritable_set
76           Create a family of class methods for managing an inheritable set of
77           items, each with an optional associated value.  Each item must be a
78           string, or must stringify to a unique string value, since a hash is
79           used internally to store the set.
80
81           The set is inherited by subclasses, but any subclass that accesses
82           or manipulates the set in any way will immediately get its own
83           private copy of the set as it exists in the superclass at the time
84           of the access or manipulation.  The superclass from which the set
85           is copied is the closest ("least super") class that has ever
86           accessed or manipulated this set.
87
88           These may sound like wacky rules, but it may help to know that this
89           family of methods was created for use in the Rose::HTML::Objects
90           family of modules to manage the set of required HTML attributes
91           (and their optional default values) for various HTML tags.
92
93           Options
94               "add_implies"
95                   A method name, or reference to a list of method names, to
96                   call when an item is added to the set.  Each added
97                   attribute is passed as an argument to each method in the
98                   "add_implies" list.
99
100               "add_method"
101                   The name of the class method used to add a single item to
102                   the set. Defaults to the method name with the prefix "add_"
103                   added.
104
105               "adds_method"
106                   The name of the class method used to add one or more items
107                   to the set. Defaults to "add_method" with "s" added to the
108                   end.
109
110               "clear_method"
111                   The name of the class method used to clear the contents of
112                   the set. Defaults to "plural_name" with a "clear_" prefix
113                   added.
114
115               "delete_implies"
116                   A method name, or reference to a list of method names, to
117                   call when an item is removed from the set.  Each deleted
118                   attribute is passed as an argument to each method in the
119                   "delete_implies" list.
120
121               "delete_method"
122                   The name of the class method used to remove a single item
123                   from the set. Defaults to the method name with the prefix
124                   "delete_" added.
125
126               "deletes_method"
127                   The name of the class method used to remove one or more
128                   items from the set. Defaults to "plural_name" with a
129                   "delete_" prefix added.
130
131               "hash_method"
132                   The name of the class method that returns a reference to
133                   the actual hash that contains the set of items in scalar
134                   context, and a shallow copy of the hash in list context.
135                   Defaults to "plural_name" with "_hash" added to the end.
136
137               "interface"
138                   Choose the interface.  This is kind of pointless since
139                   there is only one interface right now.  Defaults to "all",
140                   obviously.
141
142               "list_method"
143                   The name of the class method that returns a reference to a
144                   sorted list of items in scalar context, or a sorted list in
145                   list context.  If called with any arguments, the set is
146                   cleared with a call to "clear_method", then the set is
147                   repopulated by passing all of the arguments to a call to
148                   "adds_method".  The method name defaults to "plural_name".
149
150               "plural_name"
151                   The plural name of the items, used to construct the default
152                   names for some other methods.  Defaults to the method name
153                   with "s" added.
154
155               "test_method"
156                   The name of the class method that tests for the existence
157                   of an item in the set.  Defaults to the method name with
158                   the prefix "is_" added.
159
160               "value_method"
161                   The name of the class method used to get and set the
162                   (optional) value associated with each item in the set.
163                   Defaults to the method name with "_value" added to the end.
164
165           Interfaces
166               "all"
167                   Creates the entire family of methods described above.  The
168                   example below illustrates their use.
169
170           Example:
171
172               package MyClass;
173
174               use Rose::Class::MakeMethods::Set
175               (
176                 inheritable_set =>
177                 [
178                   valid_name =>
179                   {
180                     test_method    => 'name_is_valid',
181                     delete_implies => 'delete_required_name',
182                   },
183
184                   required_name =>
185                   {
186                     add_implies => 'add_valid_name',
187                     test_method => 'name_is_required',
188                   },
189                 ],
190               );
191
192               package MySubClass;
193               our @ISA = qw(MyClass);
194               ...
195
196               MyClass->add_valid_names('A', 'B', 'C');
197               MyClass->add_required_name('D');
198
199               $v1 = join(',', MyClass->valid_names);       # 'A,B,C,D';
200               $r1 = join(',', MyClass->required_names);    # 'D'
201
202               $v2 = join(',', MySubClass->valid_names);    # 'A,B,C,D';
203               $r2 = join(',', MySubClass->required_names); # 'D'
204
205               MySubClass->add_required_names('X', 'Y');
206
207               $v2 = join(',', MySubClass->valid_names);    # 'A,B,C,D,X,Y';
208               $r2 = join(',', MySubClass->required_names); # 'D,X,Y'
209
210               MySubClass->delete_valid_names('B', 'X');
211
212               $v1 = join(',', MyClass->valid_names);       # 'A,B,C,D';
213               $r1 = join(',', MyClass->required_names);    # 'D'
214
215               $v2 = join(',', MySubClass->valid_names);    # 'A,C,D,Y';
216               $r2 = join(',', MySubClass->required_names); # 'D,Y'
217
218               MySubClass->delete_required_name('D');
219
220               $v1 = join(',', MyClass->valid_names);       # 'A,B,C,D';
221               $r1 = join(',', MyClass->required_names);    # 'D'
222
223               $v2 = join(',', MySubClass->valid_names);    # 'A,C,D,Y';
224               $r2 = join(',', MySubClass->required_names); # 'Y'
225
226               MyClass->name_is_required('D');    # true
227               MySubClass->name_is_required('D'); # false
228
229               $h = MyClass->valid_names_hash;
230
231               # Careful!  This is the actual hash used for set storage!
232               # You should use delete_valid_name() instead!
233               delete $h->{'C'};
234
235               MySubClass->required_name_value(Y => 'xval');
236
237               print MySubClass->required_name_value('Y'); # 'xval'
238
239               %r = MySubClass->required_names_hash;
240
241               print $r{'Y'}; # 'xval'
242
243               # Okay: %r is a (shallow) copy, not the actual hash
244               delete $r{'Y'};
245
246       inherited_set
247           Create a family of class methods for managing an inherited set of
248           items. Each item must be a string, or must stringify to a unique
249           string value, since a hash is used internally to store the set.
250
251           An inherited set is made up of the union of the sets of all
252           superclasses, minus any items that are explicitly deleted in the
253           current class.
254
255           Options
256               "add_implies"
257                   A method name, or reference to a list of method names, to
258                   call when an item is added to the set.  Each added
259                   attribute is passed as an argument to each method in the
260                   "add_implies" list.
261
262               "add_method"
263                   The name of the class method used to add a single item to
264                   the set. Defaults to the method name with the prefix "add_"
265                   added.
266
267               "adds_method"
268                   The name of the class method used to add one or more items
269                   to the set. Defaults to "add_method" with "s" added to the
270                   end.
271
272               "cache_method"
273                   The name of the class method used to retrieve (or generate,
274                   if it doesn't exist) the internal cache for the set.  This
275                   should be considered a private method, but it is listed
276                   here because it does take up a spot in the method
277                   namespace.  Defaults to "plural_name" with "_cache" added
278                   to the end.
279
280               "clear_method"
281                   The name of the class method used to clear the contents of
282                   the set. Defaults to "plural_name" with a "clear_" prefix
283                   added.
284
285               "delete_implies"
286                   A method name, or reference to a list of method names, to
287                   call when an item is removed from the set.  Each deleted
288                   attribute is passed as an argument to each method in the
289                   "delete_implies" list.
290
291               "delete_method"
292                   The name of the class method used to remove a single item
293                   from the set. Defaults to the method name with the prefix
294                   "delete_" added.
295
296               "deletes_method"
297                   The name of the class method used to remove one or more
298                   items from the set. Defaults to "plural_name" with a
299                   "delete_" prefix added.
300
301               "hash_method"
302                   The name of the class method that returns a hash (in list
303                   context) or a reference to a hash (in scalar context) that
304                   contains the set of items. The existence of a key in the
305                   hash indicates its existence in the set. Defaults to
306                   "plural_name" with "_hash" added to the end.
307
308               "inherit_method"
309                   The name of the class method used to indicate that an
310                   inherited value that was previously deleted from the set
311                   should return to being inherited.  Defaults to the method
312                   name with the prefix "inherit_" added.
313
314               "inherits_method"
315                   The name of the class method used to indicate that one or
316                   more inherited values that were previously deleted from the
317                   set should return to being inherited.  Defaults to the
318                   "inherit_method" name with "s" added to the end.
319
320               "interface"
321                   Choose the interface.  This is kind of pointless since
322                   there is only one interface right now.  Defaults to "all",
323                   obviously.
324
325               "list_method"
326                   The name of the class method that returns a reference to a
327                   sorted list of items in scalar context, or a sorted list in
328                   list context.  If called with any arguments, the set is
329                   cleared with a call to "clear_method", then the set is
330                   repopulated by passing all of the arguments to a call to
331                   "adds_method".  The method name defaults to "plural_name".
332
333               "plural_name"
334                   The plural name of the items, used to construct the default
335                   names for some other methods.  Defaults to the method name
336                   with "s" added.
337
338               "test_method"
339                   The name of the class method that tests for the existence
340                   of an item in the set.  Defaults to the method name with
341                   the prefix "is_" added.
342
343           Interfaces
344               "all"
345                   Creates the entire family of methods described above.  The
346                   example below illustrates their use.
347
348           Example:
349
350               package MyClass;
351
352               use Rose::Class::MakeMethods::Set
353               (
354                 inherited_set =>
355                 [
356                   valid_name =>
357                   {
358                     test_method     => 'name_is_valid',
359                     delete_implies  => 'delete_required_name',
360                     inherit_implies => 'inherit_required_name',
361                   },
362
363                   required_name =>
364                   {
365                     add_implies => 'add_valid_name',
366                     test_method => 'name_is_required',
367                   },
368                 ],
369               );
370               ...
371
372               package MySubClass;
373               our @ISA = qw(MyClass);
374               ...
375
376               MyClass->add_valid_names('A', 'B', 'C');
377               MyClass->add_required_name('D');
378
379
380               $v1 = join(',', MyClass->valid_names);       # 'A,B,C,D';
381               $r1 = join(',', MyClass->required_names);    # 'D'
382
383               $v2 = join(',', MySubClass->valid_names);    # 'A,B,C,D';
384               $r2 = join(',', MySubClass->required_names); # 'D'
385
386               MyClass->add_required_names('X', 'Y');
387
388               $v2 = join(',', MySubClass->valid_names);    # 'A,B,C,D,X,Y';
389               $r2 = join(',', MySubClass->required_names); # 'D,X,Y'
390
391               MySubClass->delete_valid_names('B', 'X');
392
393               $v1 = join(',', MyClass->valid_names);       # 'A,B,C,D,X,Y';
394               $r1 = join(',', MyClass->required_names);    # 'D,X,Y'
395
396               $v2 = join(',', MySubClass->valid_names);    # 'A,C,D,Y';
397               $r2 = join(',', MySubClass->required_names); # 'D,Y'
398
399               MySubClass->delete_required_name('D');
400
401               $v1 = join(',', MyClass->valid_names);       # 'A,B,C,D,X,Y';
402               $r1 = join(',', MyClass->required_names);    # 'D,X,Y'
403
404               $v2 = join(',', MySubClass->valid_names);    # 'A,C,D,Y';
405               $r2 = join(',', MySubClass->required_names); # 'Y'
406
407               MySubClass->inherit_required_name('D');
408
409               $v1 = join(',', MyClass->valid_names);       # 'A,B,C,D,X,Y';
410               $r1 = join(',', MyClass->required_names);    # 'D,X,Y'
411
412               $v2 = join(',', MySubClass->valid_names);    # 'A,C,D,Y';
413               $r2 = join(',', MySubClass->required_names); # 'D,Y'
414
415               MySubClass->delete_valid_name('D');
416
417               $v1 = join(',', MyClass->valid_names);       # 'A,B,C,D,X,Y';
418               $r1 = join(',', MyClass->required_names);    # 'D,X,Y'
419
420               $v2 = join(',', MySubClass->valid_names);    # 'A,C,Y';
421               $r2 = join(',', MySubClass->required_names); # 'Y'
422
423               MySubClass->inherit_valid_name('D');
424
425               $v1 = join(',', MyClass->valid_names);       # 'A,B,C,D,X,Y';
426               $r1 = join(',', MyClass->required_names);    # 'D,X,Y'
427
428               $v2 = join(',', MySubClass->valid_names);    # 'A,C,D,Y';
429               $r2 = join(',', MySubClass->required_names); # 'D,Y'
430
431               MyClass->delete_valid_name('D');
432
433               $v1 = join(',', MyClass->valid_names);       # 'A,B,C,X,Y';
434               $r1 = join(',', MyClass->required_names);    # 'X,Y'
435
436               $v2 = join(',', MySubClass->valid_names);    # 'A,C,Y';
437               $r2 = join(',', MySubClass->required_names); # 'Y'
438
439               MySubClass->add_required_name('D');
440
441               $v1 = join(',', MyClass->valid_names);       # 'A,B,C,X,Y';
442               $r1 = join(',', MyClass->required_names);    # 'X,Y'
443
444               $v2 = join(',', MySubClass->valid_names);    # 'A,C,D,Y';
445               $r2 = join(',', MySubClass->required_names); # 'D,Y'
446
447               $h = MyClass->valid_names_hash;
448
449               # This has no affect on the set.  $h is not a reference to the
450               # actual hash used for set storage.
451               delete $h->{'C'};
452
453               $v1 = join(',', MyClass->valid_names);       # 'A,B,C,X,Y';
454               $r1 = join(',', MyClass->required_names);    # 'X,Y'
455

AUTHOR

457       John C. Siracusa (siracusa@gmail.com)
458

LICENSE

460       Copyright (c) 2010 by John C. Siracusa.  All rights reserved.  This
461       program is free software; you can redistribute it and/or modify it
462       under the same terms as Perl itself.
463
464
465
466perl v5.38.0                      2023-07-21  Rose::Class::MakeMethods::Set(3)
Impressum