1MakeMethods::Composite:U:sHearshC(o3n)tributed Perl DocuMmaeknetMaettihoonds::Composite::Hash(3)
2
3
4

NAME

6       Class::MakeMethods::Composite::Hash - Composite hash methods
7

SYNOPSIS

9         package MyObject;
10         use Class::MakeMethods::Composite::Hash (
11           new => 'new',
12           scalar => [ 'foo', 'bar' ],
13           array => 'my_list',
14           hash => 'my_index',
15         );
16         ...
17
18         my $obj = MyObject->new( foo => 'Foozle' );
19         print $obj->foo();
20
21         $obj->bar('Barbados');
22         print $obj->bar();
23
24         $obj->my_list(0 => 'Foozle', 1 => 'Bang!');
25         print $obj->my_list(1);
26
27         $obj->my_index('broccoli' => 'Blah!', 'foo' => 'Fiddle');
28         print $obj->my_index('foo');
29

DESCRIPTION

31       The Composite::Hash suclass of MakeMethods provides a basic constructor
32       and accessors for blessed-hash object instances.
33
34   Class::MakeMethods Calling Interface
35       When you "use" this package, the method declarations you provide as
36       arguments cause subroutines to be generated and installed in your
37       module.
38
39       You can also omit the arguments to "use" and instead make methods at
40       runtime by passing the declarations to a subsequent call to make().
41
42       You may include any number of declarations in each call to "use" or
43       make(). If methods with the same name already exist, earlier calls to
44       "use" or make() win over later ones, but within each call, later
45       declarations superceed earlier ones.
46
47       You can install methods in a different package by passing "-TargetClass
48       => package" as your first arguments to "use" or "make".
49
50       See Class::MakeMethods for more details.
51
52   Class::MakeMethods::Basic Declaration Syntax
53       The following types of Basic declarations are supported:
54
55generator_type => "method_name"
56
57generator_type => "name_1 name_2..."
58
59generator_type => [ "name_1", "name_2", ...]
60
61       See the "METHOD GENERATOR TYPES" section below for a list of the
62       supported values of generator_type.
63
64       For each method name you provide, a subroutine of the indicated type
65       will be generated and installed under that name in your module.
66
67       Method names should start with a letter, followed by zero or more
68       letters, numbers, or underscores.
69
70   Class::MakeMethods::Composite Declaration Syntax
71       The Composite syntax also provides several ways to optionally associate
72       a hash of additional parameters with a given method name.
73
74generator_type => [ "name_1" => { param=>value... }, ... ]
75
76           A hash of parameters to use just for this method name.
77
78           (Note: to prevent confusion with self-contained definition hashes,
79           described below, parameter hashes following a method name must not
80           contain the key 'name'.)
81
82generator_type => [ [ "name_1", "name_2", ... ] => {
83           param=>value... } ]
84
85           Each of these method names gets a copy of the same set of
86           parameters.
87
88generator_type => [ { "name"=>"name_1", param=>value... }, ... ]
89
90           By including the reserved parameter "name", you create a self-
91           contained declaration with that name and any associated hash
92           values.
93
94       Basic declarations, as described above, are given an empty parameter
95       hash.
96

METHOD GENERATOR TYPES

98   new - Constructor
99       For each method name passed, returns a subroutine with the following
100       characteristics:
101
102       •   Has a reference to a sample item to copy. This defaults to a
103           reference to an empty hash, but you may override this with the
104           "'defaults' => hash_ref"  method parameter.
105
106       •   If called as a class method, makes a new hash and blesses it into
107           that class.
108
109       •   If called on a hash-based instance, makes a copy of it and blesses
110           the copy into the same class as the original instance.
111
112       •   If passed a list of key-value pairs, appends them to the new hash.
113           These arguments override any copied values, and later arguments
114           with the same name will override earlier ones.
115
116       •   Returns the new instance.
117
118       Sample declaration and usage:
119
120         package MyObject;
121         use Class::MakeMethods::Composite::Hash (
122           new => 'new',
123         );
124         ...
125
126         # Bare constructor
127         my $empty = MyObject->new();
128
129         # Constructor with initial values
130         my $obj = MyObject->new( foo => 'Foozle', bar => 'Barbados' );
131
132         # Copy with overriding value
133         my $copy = $obj->new( bar => 'Bob' );
134
135   new --with_values - Constructor
136       For each method name passed, returns a subroutine with the following
137       characteristics:
138
139       •   May be called as a class method, or (equivalently) on any existing
140           object of that class.
141
142       •   Creates a hash, blesses it into the class, and returns the new
143           instance.
144
145       •   If no arguments are provided, the returned hash will be empty. If
146           passed a single hash-ref argument, copies its contents into the new
147           hash. If called with multiple arguments, treats them as key-value
148           pairs, and copies them into the new hash. (Note that this is a
149           "shallow" copy, not a "deep" clone.)
150
151   scalar - Instance Accessor
152       For each method name passed, uses a closure to generate a subroutine
153       with the following characteristics:
154
155       •   Must be called on a hash-based instance.
156
157       •   Has a specific hash key to use to access the related value for each
158           instance.  This defaults to the method name, but you may override
159           this with the "'hash_key' =" string> method parameter.
160
161       •   If called without any arguments returns the current value.
162
163       •   If called with an argument, stores that as the value, and returns
164           it.
165
166       •   If called with multiple arguments, stores a reference to a new
167           array with those arguments as contents, and returns that array
168           reference.
169
170       Sample declaration and usage:
171
172         package MyObject;
173         use Class::MakeMethods::Composite::Hash (
174           scalar => 'foo',
175         );
176         ...
177
178         # Store value
179         $obj->foo('Foozle');
180
181         # Retrieve value
182         print $obj->foo;
183
184   array - Instance Ref Accessor
185       For each method name passed, uses a closure to generate a subroutine
186       with the following characteristics:
187
188       •   Must be called on a hash-based instance.
189
190       •   Has a specific hash key to use to access the related value for each
191           instance.  This defaults to the method name, but you may override
192           this with the "'hash_key' =" string> method parameter.
193
194       •   The value for each instance will be a reference to an array (or
195           undef).
196
197       •   If called without any arguments, returns the current array-ref
198           value (or undef).
199
200       •   If called with a single non-ref argument, uses that argument as an
201           index to retrieve from the referenced array, and returns that value
202           (or undef).
203
204       •   If called with a single array ref argument, uses that list to
205           return a slice of the referenced array.
206
207       •   If called with a list of argument pairs, each with a non-ref index
208           and an associated value, stores the value at the given index in the
209           referenced array. If the instance's value was previously undefined,
210           a new array is autovivified. The current value in each position
211           will be overwritten, and later arguments with the same index will
212           override earlier ones. Returns the current array-ref value.
213
214       •   If called with a list of argument pairs, each with the first item
215           being a reference to an array of up to two numbers, loops over each
216           pair and uses those numbers to splice the value array.
217
218           The first controlling number is the position at which the splice
219           will begin. Zero will start before the first item in the list.
220           Negative numbers count backwards from the end of the array.
221
222           The second number is the number of items to be removed from the
223           list. If it is omitted, or undefined, or zero, no items are
224           removed. If it is a positive integer, that many items will be
225           returned.
226
227           If both numbers are omitted, or are both undefined, they default to
228           containing the entire value array.
229
230           If the second argument is undef, no values will be inserted; if it
231           is a non-reference value, that one value will be inserted; if it is
232           an array-ref, its values will be copied.
233
234           The method returns the items that removed from the array, if any.
235
236       Sample declaration and usage:
237
238         package MyObject;
239         use Class::MakeMethods::Composite::Hash (
240           array => 'bar',
241         );
242         ...
243
244         # Clear and set contents of list
245         print $obj->bar([ 'Spume', 'Frost' ] );
246
247         # Set values by position
248         $obj->bar(0 => 'Foozle', 1 => 'Bang!');
249
250         # Positions may be overwritten, and in any order
251         $obj->bar(2 => 'And Mash', 1 => 'Blah!');
252
253         # Retrieve value by position
254         print $obj->bar(1);
255
256         # Direct access to referenced array
257         print scalar @{ $obj->bar() };
258
259       There are also calling conventions for slice and splice operations:
260
261         # Retrieve slice of values by position
262         print join(', ', $obj->bar( undef, [0, 2] ) );
263
264         # Insert an item at position in the array
265         $obj->bar([3], 'Potatoes' );
266
267         # Remove 1 item from position 3 in the array
268         $obj->bar([3, 1], undef );
269
270         # Set a new value at position 2, and return the old value
271         print $obj->bar([2, 1], 'Froth' );
272
273   hash - Instance Ref Accessor
274       For each method name passed, uses a closure to generate a subroutine
275       with the following characteristics:
276
277       •   Must be called on a hash-based instance.
278
279       •   Has a specific hash key to use to access the related value for each
280           instance.  This defaults to the method name, but you may override
281           this with the "'hash_key' =" string> method parameter.
282
283       •   The value for each instance will be a reference to a hash (or
284           undef).
285
286       •   If called without any arguments, returns the contents of the hash
287           in list context, or a hash reference in scalar context (or undef).
288
289       •   If called with one non-ref argument, uses that argument as an index
290           to retrieve from the referenced hash, and returns that value (or
291           undef).
292
293       •   If called with one array-ref argument, uses the contents of that
294           array to retrieve a slice of the referenced hash.
295
296       •   If called with one hash-ref argument, sets the contents of the
297           referenced hash to match that provided.
298
299       •   If called with a list of key-value pairs, stores the value under
300           the given key in the referenced hash. If the instance's value was
301           previously undefined, a new hash is autovivified. The current value
302           under each key will be overwritten, and later arguments with the
303           same key will override earlier ones. Returns the contents of the
304           hash in list context, or a hash reference in scalar context.
305
306       Sample declaration and usage:
307
308         package MyObject;
309         use Class::MakeMethods::Composite::Hash (
310           hash => 'baz',
311         );
312         ...
313
314         # Set values by key
315         $obj->baz('foo' => 'Foozle', 'bar' => 'Bang!');
316
317         # Values may be overwritten, and in any order
318         $obj->baz('broccoli' => 'Blah!', 'foo' => 'Fiddle');
319
320         # Retrieve value by key
321         print $obj->baz('foo');
322
323         # Retrive slice of values by position
324         print join(', ', $obj->baz( ['foo', 'bar'] ) );
325
326         # Direct access to referenced hash
327         print keys %{ $obj->baz() };
328
329         # Reset the hash contents to empty
330         @{ $obj->baz() } = ();
331
332   object - Instance Ref Accessor
333       For each method name passed, uses a closure to generate a subroutine
334       with the following characteristics:
335
336       •   Must be called on a hash-based instance.
337
338       •   Has a specific hash key to use to access the related value for each
339           instance.  This defaults to the method name, but you may override
340           this with the "'hash_key' =" string> method parameter.
341
342       •   The value for each instance will be a reference to an object (or
343           undef).
344
345       •   If called without any arguments returns the current value.
346
347       •   If called with an argument, stores that as the value, and returns
348           it,
349
350       Sample declaration and usage:
351
352         package MyObject;
353         use Class::MakeMethods::Composite::Hash (
354           object => 'foo',
355         );
356         ...
357
358         # Store value
359         $obj->foo( Foozle->new() );
360
361         # Retrieve value
362         print $obj->foo;
363

SEE ALSO

365       See Class::MakeMethods for general information about this distribution.
366
367       See Class::MakeMethods::Composite for more about this family of
368       subclasses.
369
370
371
372perl v5.36.0                      2023-01-20   MakeMethods::Composite::Hash(3)
Impressum