1Rose::Object::MakeMethoUdsse:r:GCeonnetrriicb(u3t)ed PerRlosDeo:c:uOmbejnetcatt:i:oMnakeMethods::Generic(3)
2
3
4

NAME

6       Rose::Object::MakeMethods::Generic - Create simple object methods.
7

SYNOPSIS

9         package MyObject;
10
11         use Rose::Object::MakeMethods::Generic
12         (
13           scalar =>
14           [
15             'power',
16             'error',
17           ],
18
19           'scalar --get_set_init' => 'name',
20
21           'boolean --get_set_init' => 'is_tall',
22
23           boolean =>
24           [
25             'is_red',
26             'is_happy' => { default => 1 },
27           ],
28
29           array =>
30           [
31             jobs       => {},
32             job        => { interface => 'get_set_item', hash_key => 'jobs' },
33             clear_jobs => { interface => 'clear', hash_key => 'jobs' },
34             reset_jobs => { interface => 'reset', hash_key => 'jobs' },
35           ],
36
37           hash =>
38           [
39             param        => { hash_key => 'params' },
40             params       => { interface => 'get_set_all' },
41             param_names  => { interface => 'keys', hash_key => 'params' },
42             param_values => { interface => 'values', hash_key => 'params' },
43             param_exists => { interface => 'exists', hash_key => 'params' },
44             delete_param => { interface => 'delete', hash_key => 'params' },
45
46             clear_params => { interface => 'clear', hash_key => 'params' },
47             reset_params => { interface => 'reset', hash_key => 'params' },
48           ],
49         );
50
51         sub init_name    { 'Fred' }
52         sub init_is_tall { 1 }
53         ...
54
55         $obj = MyObject->new(power => 5);
56
57         print $obj->name; # Fred
58
59         $obj->do_something or die $obj->error;
60
61         $obj->is_tall;        # true
62         $obj->is_tall(undef); # false (but defined)
63         $obj->is_tall;        # false (but defined)
64
65         $obj->is_red;         # undef
66         $obj->is_red(1234);   # true
67         $obj->is_red('');     # false (but defined)
68         $obj->is_red;         # false (but defined)
69
70         $obj->is_happy;       # true
71
72         $obj->params(a => 1, b => 2);   # add pairs
73         $val = $obj->param('b');        # 2
74         $obj->param_exists('x');        # false
75
76         $obj->jobs('butcher', 'baker'); # add values
77         $obj->job(0 => 'sailor');       # set value
78         $job = $obj->job(0);            # 'sailor'
79

DESCRIPTION

81       Rose::Object::MakeMethods::Generic is a method maker that inherits from
82       Rose::Object::MakeMethods.  See the Rose::Object::MakeMethods
83       documentation to learn about the interface.  The method types provided
84       by this module are described below.  All methods work only with hash-
85       based objects.
86

METHODS TYPES

88       scalar
89           Create get/set methods for scalar attributes.
90
91           Options
92               "hash_key"
93                   The key inside the hash-based object to use for the storage
94                   of this attribute. Defaults to the name of the method.
95
96               "init_method"
97                   The name of the method to call when initializing the value
98                   of an undefined attribute.  This option is only applicable
99                   when using the "get_set_init" interface.  Defaults to the
100                   method name with the prefix "init_" added.
101
102               "interface"
103                   Choose one of the two possible interfaces.  Defaults to
104                   "get_set".
105
106           Interfaces
107               "get_set"
108                   Creates a simple get/set accessor method for an object
109                   attribute.  When called with an argument, the value of the
110                   attribute is set.  The current value of the attribute is
111                   returned.
112
113               "get_set_init"
114                   Behaves like the "get_set" interface unless the value of
115                   the attribute is undefined.  In that case, the method
116                   specified by the "init_method" option is called and the
117                   attribute is set to the return value of that method.
118
119           Example:
120
121               package MyObject;
122
123               use Rose::Object::MakeMethods::Generic
124               (
125                 scalar => 'power',
126                 'scalar --get_set_init' => 'name',
127               );
128
129               sub init_name { 'Fred' }
130               ...
131
132               $obj->power(99);    # returns 99
133               $obj->name;         # returns "Fred"
134               $obj->name('Bill'); # returns "Bill"
135
136       boolean
137           Create get/set methods for boolean attributes.  For each argument
138           to these methods, the only thing that matters is whether it
139           evaluates to true or false.  The return value is either, true,
140           false (but defined), or undef if the value has never been set.
141
142           Options
143               "default"
144                   Determines the default value of the attribute.  This option
145                   is only applicable when using the "get_set" interface.
146
147               "hash_key"
148                   The key inside the hash-based object to use for the storage
149                   of this attribute. Defaults to the name of the method.
150
151               "init_method"
152                   The name of the method to call when initializing the value
153                   of an undefined attribute.  Again, the only thing that
154                   matters about the return value of this method is whether or
155                   not it is true or false.  This option is only applicable
156                   when using the "get_set_init" interface. Defaults to the
157                   method name with the prefix "init_" added.
158
159               "interface"
160                   Choose one of the two possible interfaces.  Defaults to
161                   "get_set".
162
163           Interfaces
164               "get_set"
165                   Creates a simple get/set accessor method for a boolean
166                   object attribute. When called with an argument, the value
167                   of the attribute is set to true if the argument evaluates
168                   to true, false (but defined) otherwise.  The current value
169                   of the attribute is returned.
170
171                   If Class::XSAccessor version 0.14 or later is installed and
172                   the "ROSE_OBJECT_NO_CLASS_XSACCESOR" environment variable
173                   is not set to a true value, then Class::XSAccessor will be
174                   used to generated the method.
175
176               "get_set_init"
177                   Behaves like the "get_set" interface unless the value of
178                   the attribute is undefined.  In that case, the method
179                   specified by the "init_method" option is called and the
180                   attribute is set based on the boolean value of the return
181                   value of that method.
182
183           Example:
184
185               package MyObject;
186
187               use Rose::Object::MakeMethods::Generic
188               (
189                 'boolean --get_set_init' => 'is_tall',
190
191                 boolean =>
192                 [
193                   'is_red',
194                   'is_happy' => { default => 1 },
195                 ],
196               );
197
198               sub init_is_tall { 'blah' }
199               ...
200
201               $obj->is_tall;        # returns true
202               $obj->is_tall(undef); # returns false (but defined)
203               $obj->is_tall;        # returns false (but defined)
204
205               $obj->is_red;         # returns undef
206               $obj->is_red(1234);   # returns true
207               $obj->is_red('');     # returns false (but defined)
208               $obj->is_red;         # returns false (but defined)
209
210               $obj->is_happy;       # returns true
211
212       hash
213           Create methods to manipulate hash attributes.
214
215           Options
216               "hash_key"
217                   The key inside the hash-based object to use for the storage
218                   of this attribute.  Defaults to the name of the method.
219
220               "init_method"
221                   The name of the method to call when initializing the value
222                   of an undefined hash attribute.    This method should
223                   return a reference to a hash, and is only applicable when
224                   using the "get_set_init" interface. Defaults to the method
225                   name with the prefix "init_" added.
226
227               "interface"
228                   Choose which interface to use.  Defaults to "get_set".
229
230           Interfaces
231               "get_set"
232                   If called with no arguments, returns a list of key/value
233                   pairs in list context or a reference to the actual hash
234                   stored by the object in scalar context.
235
236                   If called with one argument, and that argument is a
237                   reference to a hash, that hash reference is used as the new
238                   value for the attribute.  Returns a list of key/value pairs
239                   in list context or a reference to the actual hash stored by
240                   the object in scalar context.
241
242                   If called with one argument, and that argument is a
243                   reference to an array, then a list of the hash values for
244                   each key in the array is returned.
245
246                   If called with one argument, and it is not a reference to a
247                   hash or an array, then the hash value for that key is
248                   returned.
249
250                   If called with an even number of arguments, they are taken
251                   as name/value pairs and are added to the hash.  It then
252                   returns a list of key/value pairs in list context or a
253                   reference to the actual hash stored by the object in scalar
254                   context.
255
256                   Passing an odd number of arguments greater than 1 causes a
257                   fatal error.
258
259               "get_set_init"
260                   Behaves like the "get_set" interface unless the attribute
261                   is undefined. In that case, the method specified by the
262                   "init_method" option is called and the attribute is set to
263                   the return value of that method, which should be a
264                   reference to a hash.
265
266               "get_set_inited"
267                   Behaves like the "get_set" interface unless the attribute
268                   is undefined. In that case, it is initialized to an empty
269                   hash before proceeding as usual.
270
271               "get_set_all"
272                   If called with no arguments, returns a list of key/value
273                   pairs in list context or a reference to the actual hash
274                   stored by the object in scalar context.
275
276                   If called with one argument, and that argument is a
277                   reference to a hash, that hash reference is used as the new
278                   value for the attribute.  Returns a list of key/value pairs
279                   in list context or a reference to the actual hash stored by
280                   the object in scalar context.
281
282                   Otherwise, the hash is emptied and the arguments are taken
283                   as name/value pairs that are then added to the hash.  It
284                   then returns a list of key/value pairs in list context or a
285                   reference to the actual hash stored by the object in scalar
286                   context.
287
288               "get_set_init_all"
289                   Behaves like the "get_set_all" interface unless the
290                   attribute is undefined. In that case, the method specified
291                   by the "init_method" option is called and the attribute is
292                   set to the return value of that method, which should be a
293                   reference to a hash.
294
295               "clear"
296                   Sets the attribute to an empty hash.
297
298               "reset"
299                   Sets the attribute to undef.
300
301               "delete"
302                   Deletes the key(s) passed as arguments.  Failure to pass
303                   any arguments causes a fatal error.
304
305               "exists"
306                   Returns true of the argument exists in the hash, false
307                   otherwise. Failure to pass an argument or passing more than
308                   one argument causes a fatal error.
309
310               "keys"
311                   Returns the keys of the hash in list context, or a
312                   reference to an array of the keys of the hash in scalar
313                   context.  The keys are not sorted.
314
315               "names"
316                   An alias for the "keys" interface.
317
318               "values"
319                   Returns the values of the hash in list context, or a
320                   reference to an array of the values of the hash in scalar
321                   context.  The values are not sorted.
322
323           Example:
324
325               package MyObject;
326
327               use Rose::Object::MakeMethods::Generic
328               (
329                 hash =>
330                 [
331                   param        => { hash_key =>'params' },
332                   params       => { interface=>'get_set_all' },
333                   param_names  => { interface=>'keys',   hash_key=>'params' },
334                   param_values => { interface=>'values', hash_key=>'params' },
335                   param_exists => { interface=>'exists', hash_key=>'params' },
336                   delete_param => { interface=>'delete', hash_key=>'params' },
337
338                   clear_params => { interface=>'clear', hash_key=>'params' },
339                   reset_params => { interface=>'reset', hash_key=>'params' },
340                 ],
341               );
342               ...
343
344               $obj = MyObject->new;
345
346               $obj->params; # undef
347
348               $obj->params(a => 1, b => 2); # add pairs
349               $val = $obj->param('b'); # 2
350
351               %params = $obj->params; # copy hash keys and values
352               $params = $obj->params; # get hash ref
353
354               $obj->params({ c => 3, d => 4 }); # replace contents
355
356               $obj->param_exists('a'); # false
357
358               $keys = join(',', sort $obj->param_names);  # 'c,d'
359               $vals = join(',', sort $obj->param_values); # '3,4'
360
361               $obj->delete_param('c');
362               $obj->param(f => 7, g => 8);
363
364               $vals = join(',', sort $obj->param_values); # '4,7,8'
365
366               $obj->clear_params;
367               $params = $obj->params; # empty hash
368
369               $obj->reset_params;
370               $params = $obj->params; # undef
371
372       array
373           Create methods to manipulate array attributes.
374
375           Options
376               "hash_key"
377                   The key inside the hash-based object to use for the storage
378                   of this attribute.  Defaults to the name of the method.
379
380               "init_method"
381                   The name of the method to call when initializing the value
382                   of an undefined array attribute.    This method should
383                   return a reference to an array.  This option is only
384                   applicable when using the "get_set_init", "push", and "add"
385                   interfaces.  When using the "get_set_init" interface,
386                   "init_method" defaults to the method name with the prefix
387                   "init_" added.
388
389               "interface"
390                   Choose which interface to use.  Defaults to "get_set".
391
392           Interfaces
393               "get_set"
394                   If called with no arguments, returns the array contents in
395                   list context or a reference to the actual array stored by
396                   the object in scalar context.
397
398                   If called with one argument, and that argument is a
399                   reference to an array, that array reference is used as the
400                   new value for the attribute. Returns the array contents in
401                   list context or a reference to the actual array stored by
402                   the object in scalar context.
403
404                   If called with one argument, and that argument is not a
405                   reference to an array, or if called with more than one
406                   argument, then the array contents are replaced by the
407                   arguments.  Returns the array contents in list context or a
408                   reference to the actual array stored by the object in
409                   scalar context.
410
411               "get_set_init"
412                   Behaves like the "get_set" interface unless the attribute
413                   is undefined. In that case, the method specified by the
414                   "init_method" option is called and the attribute is set to
415                   the return value of that method, which should be a
416                   reference to an array.
417
418               "get_set_inited"
419                   Behaves like the "get_set" interface unless the attribute
420                   is undefined. In that case, it is initialized to an empty
421                   array before proceeding as usual.
422
423               "get_set_item"
424                   If called with one argument, returns the item at that array
425                   index.
426
427                   If called with two arguments, sets the item at the array
428                   index specified by the first argument to the value
429                   specified by the second argument.
430
431                   Failure to pass any arguments causes a fatal error.
432
433               "exists"
434                   Returns true of the argument exists in the hash, false
435                   otherwise. Failure to pass an argument or passing more than
436                   one argument causes a fatal error.
437
438               "add"
439                   An alias for the "push" interface.
440
441               "push"
442                   If called with a list or a reference to an array, the
443                   contents of the list or referenced array are added to the
444                   end of the array.  If called with no arguments, a fatal
445                   error will occur.
446
447               "pop"
448                   Remove an item from the end of the array and returns it.
449                   If an integer argument is passed, then that number of items
450                   is removed and returned. Otherwise, just one is removed and
451                   returned.
452
453               "shift"
454                   Remove an item from the start of the array and returns it.
455                   If an integer argument is passed, then that number of items
456                   is removed and returned. Otherwise, just one is removed and
457                   returned.
458
459               "unshift"
460                   If called with a list or a reference to an array, the
461                   contents of the list or referenced array are added to the
462                   start of the array.  If called with no arguments, a fatal
463                   error will occur.
464
465               "clear"
466                   Sets the attribute to an empty array.
467
468               "reset"
469                   Sets the attribute to undef.
470
471           Example:
472
473               package MyObject;
474
475               use Rose::Object::MakeMethods::Generic
476               (
477                 array =>
478                 [
479                   jobs       => {},
480                   job        => { interface => 'get_set_item',
481                                   hash_key  => 'jobs' },
482                   clear_jobs => { interface => 'clear', hash_key => 'jobs' },
483                   reset_jobs => { interface => 'reset', hash_key => 'jobs' },
484                 ],
485               );
486               ...
487
488               $obj = MyObject->new;
489
490               $jobs = $obj->jobs; # undef
491
492               $obj->clear_jobs();
493               $jobs = $obj->jobs; # ref to empty array
494
495               $obj->jobs('butcher', 'baker'); # add values
496               $vals = join(',', $obj->jobs);  # 'butcher,baker'
497
498               $obj->jobs([ 'candlestick', 'maker' ]); # replace values
499
500               $vals = join(',', $obj->jobs); # 'candlestick,maker'
501
502               $job = $obj->job(0);      # 'candlestick'
503               $obj->job(0 => 'sailor'); # set value
504               $job = $obj->job(0);      # 'sailor'
505
506               $obj->reset_jobs;
507               $jobs = $obj->jobs; # undef
508

AUTHOR

510       John C. Siracusa (siracusa@gmail.com)
511

LICENSE

513       Copyright (c) 2010 by John C. Siracusa.  All rights reserved.  This
514       program is free software; you can redistribute it and/or modify it
515       under the same terms as Perl itself.
516
517
518
519perl v5.28.1                      2013-10-R0o4se::Object::MakeMethods::Generic(3)
Impressum