1Rose::Class::MakeMethodUss:e:rSeCto(n3t)ributed Perl DocRuomseen:t:aCtliaosns::MakeMethods::Set(3)
2
6 Rose::Class::MakeMethods::Set - Create class methods to manage sets.
7
9 package MyClass;
10 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 inherited_set =>
23 [
24 valid_name =>
25 {
26 test_method => 'name_is_valid',
27 },
28 ],
29 );
30 ...
32 package MySubClass;
34 our @ISA = qw(MyClass);
35 ...
36 MyClass->add_valid_names('A', 'B', 'C');
38 MyClass->add_required_name('D');
39 $v1 = join(',', MyClass->valid_names); # 'A,B,C,D';
41 $r1 = join(',', MyClass->required_names); # 'D'
42 $v2 = join(',', MySubClass->valid_names); # 'A,B,C,D';
44 $r2 = join(',', MySubClass->required_names); # 'D'
45 MySubClass->add_required_names('X', 'Y');
47 $v2 = join(',', MySubClass->valid_names); # 'A,B,C,D,X,Y';
49 $r2 = join(',', MySubClass->required_names); # 'D,X,Y'
50 MySubClass->delete_valid_names('B', 'X');
52 $v1 = join(',', MyClass->valid_names); # 'A,B,C,D';
54 $r1 = join(',', MyClass->required_names); # 'D'
55 $v2 = join(',', MySubClass->valid_names); # 'A,C,D,Y';
57 $r2 = join(',', MySubClass->required_names); # 'D,X,Y'
58 MySubClass->delete_required_name('D');
60 $v1 = join(',', MyClass->valid_names); # 'A,B,C,D';
62 $r1 = join(',', MyClass->required_names); # 'D'
63 $v2 = join(',', MySubClass->valid_names); # 'A,C,D,Y';
65 $r2 = join(',', MySubClass->required_names); # 'X,Y'
66
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
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 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 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 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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 Interfaces
166 "all"
167 Creates the entire family of methods described above. The
168 example below illustrates their use.
169 Example:
171 package MyClass;
173 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 required_name =>
185 {
186 add_implies => 'add_valid_name',
187 test_method => 'name_is_required',
188 },
189 ],
190 );
191 package MySubClass;
193 our @ISA = qw(MyClass);
194 ...
195 MyClass->add_valid_names('A', 'B', 'C');
197 MyClass->add_required_name('D');
198 $v1 = join(',', MyClass->valid_names); # 'A,B,C,D';
200 $r1 = join(',', MyClass->required_names); # 'D'
201 $v2 = join(',', MySubClass->valid_names); # 'A,B,C,D';
203 $r2 = join(',', MySubClass->required_names); # 'D'
204 MySubClass->add_required_names('X', 'Y');
206 $v2 = join(',', MySubClass->valid_names); # 'A,B,C,D,X,Y';
208 $r2 = join(',', MySubClass->required_names); # 'D,X,Y'
209 MySubClass->delete_valid_names('B', 'X');
211 $v1 = join(',', MyClass->valid_names); # 'A,B,C,D';
213 $r1 = join(',', MyClass->required_names); # 'D'
214 $v2 = join(',', MySubClass->valid_names); # 'A,C,D,Y';
216 $r2 = join(',', MySubClass->required_names); # 'D,Y'
217 MySubClass->delete_required_name('D');
219 $v1 = join(',', MyClass->valid_names); # 'A,B,C,D';
221 $r1 = join(',', MyClass->required_names); # 'D'
222 $v2 = join(',', MySubClass->valid_names); # 'A,C,D,Y';
224 $r2 = join(',', MySubClass->required_names); # 'Y'
225 MyClass->name_is_required('D'); # true
227 MySubClass->name_is_required('D'); # false
228 $h = MyClass->valid_names_hash;
230 # Careful! This is the actual hash used for set storage!
232 # You should use delete_valid_name() instead!
233 delete $h->{'C'};
234 MySubClass->required_name_value(Y => 'xval');
236 print MySubClass->required_name_value('Y'); # 'xval'
238 %r = MySubClass->required_names_hash;
240 print $r{'Y'}; # 'xval'
242 # Okay: %r is a (shallow) copy, not the actual hash
244 delete $r{'Y'};
245 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 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 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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 Interfaces
344 "all"
345 Creates the entire family of methods described above. The
346 example below illustrates their use.
347 Example:
349 package MyClass;
351 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 required_name =>
364 {
365 add_implies => 'add_valid_name',
366 test_method => 'name_is_required',
367 },
368 ],
369 );
370 ...
371 package MySubClass;
373 our @ISA = qw(MyClass);
374 ...
375 MyClass->add_valid_names('A', 'B', 'C');
377 MyClass->add_required_name('D');
378 $v1 = join(',', MyClass->valid_names); # 'A,B,C,D';
381 $r1 = join(',', MyClass->required_names); # 'D'
382 $v2 = join(',', MySubClass->valid_names); # 'A,B,C,D';
384 $r2 = join(',', MySubClass->required_names); # 'D'
385 MyClass->add_required_names('X', 'Y');
387 $v2 = join(',', MySubClass->valid_names); # 'A,B,C,D,X,Y';
389 $r2 = join(',', MySubClass->required_names); # 'D,X,Y'
390 MySubClass->delete_valid_names('B', 'X');
392 $v1 = join(',', MyClass->valid_names); # 'A,B,C,D,X,Y';
394 $r1 = join(',', MyClass->required_names); # 'D,X,Y'
395 $v2 = join(',', MySubClass->valid_names); # 'A,C,D,Y';
397 $r2 = join(',', MySubClass->required_names); # 'D,Y'
398 MySubClass->delete_required_name('D');
400 $v1 = join(',', MyClass->valid_names); # 'A,B,C,D,X,Y';
402 $r1 = join(',', MyClass->required_names); # 'D,X,Y'
403 $v2 = join(',', MySubClass->valid_names); # 'A,C,D,Y';
405 $r2 = join(',', MySubClass->required_names); # 'Y'
406 MySubClass->inherit_required_name('D');
408 $v1 = join(',', MyClass->valid_names); # 'A,B,C,D,X,Y';
410 $r1 = join(',', MyClass->required_names); # 'D,X,Y'
411 $v2 = join(',', MySubClass->valid_names); # 'A,C,D,Y';
413 $r2 = join(',', MySubClass->required_names); # 'D,Y'
414 MySubClass->delete_valid_name('D');
416 $v1 = join(',', MyClass->valid_names); # 'A,B,C,D,X,Y';
418 $r1 = join(',', MyClass->required_names); # 'D,X,Y'
419 $v2 = join(',', MySubClass->valid_names); # 'A,C,Y';
421 $r2 = join(',', MySubClass->required_names); # 'Y'
422 MySubClass->inherit_valid_name('D');
424 $v1 = join(',', MyClass->valid_names); # 'A,B,C,D,X,Y';
426 $r1 = join(',', MyClass->required_names); # 'D,X,Y'
427 $v2 = join(',', MySubClass->valid_names); # 'A,C,D,Y';
429 $r2 = join(',', MySubClass->required_names); # 'D,Y'
430 MyClass->delete_valid_name('D');
432 $v1 = join(',', MyClass->valid_names); # 'A,B,C,X,Y';
434 $r1 = join(',', MyClass->required_names); # 'X,Y'
435 $v2 = join(',', MySubClass->valid_names); # 'A,C,Y';
437 $r2 = join(',', MySubClass->required_names); # 'Y'
438 MySubClass->add_required_name('D');
440 $v1 = join(',', MyClass->valid_names); # 'A,B,C,X,Y';
442 $r1 = join(',', MyClass->required_names); # 'X,Y'
443 $v2 = join(',', MySubClass->valid_names); # 'A,C,D,Y';
445 $r2 = join(',', MySubClass->required_names); # 'D,Y'
446 $h = MyClass->valid_names_hash;
448 # 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 $v1 = join(',', MyClass->valid_names); # 'A,B,C,X,Y';
454 $r1 = join(',', MyClass->required_names); # 'X,Y'
455
457 John C. Siracusa (siracusa@gmail.com)
458
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.
463perl v5.36.0 2022-07-22 Rose::Class::MakeMethods::Set(3)