Class::MakeMethods::Standard::Hash(3pm)

1MakeMethods::Standard::UHsaesrh(C3o)ntributed Perl DocumMeankteaMteitohnods::Standard::Hash(3)
2
3
4

NAME

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

SYNOPSIS

9         package MyObject;
10         use Class::MakeMethods::Standard::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 Standard::Hash suclass of MakeMethods provides a basic constructor
32       and accessors for blessed-hash object instances.
33
34       Calling Conventions
35
36       When you "use" this package, the method names you provide as arguments
37       cause subroutines to be generated and installed in your module.
38
39       See "Calling Conventions" in Class::MakeMethods::Standard for more
40       information.
41
42       Declaration Syntax
43
44       To declare methods, pass in pairs of a method-type name followed by one
45       or more method names.
46
47       Valid method-type names for this package are listed in "METHOD GENERA‐
48       TOR TYPES".
49
50       See "Declaration Syntax" in Class::MakeMethods::Standard and "Parameter
51       Syntax" in Class::MakeMethods::Standard for more information.
52

METHOD GENERATOR TYPES

54       new - Constructor
55
56       For each method name passed, returns a subroutine with the following
57       characteristics:
58
59       ·   Has a reference to a sample item to copy. This defaults to a refer‐
60           ence to an empty hash, but you may override this with the
61           "'defaults' =" hash_ref>  method parameter.
62
63       ·   If called as a class method, makes a new hash and blesses it into
64           that class.
65
66       ·   If called on a hash-based instance, makes a copy of it and blesses
67           the copy into the same class as the original instance.
68
69       ·   If passed a list of key-value pairs, appends them to the new hash.
70           These arguments override any copied values, and later arguments
71           with the same name will override earlier ones.
72
73       ·   Returns the new instance.
74
75       Sample declaration and usage:
76
77         package MyObject;
78         use Class::MakeMethods::Standard::Hash (
79           new => 'new',
80         );
81         ...
82
83         # Bare constructor
84         my $empty = MyObject->new();
85
86         # Constructor with initial values
87         my $obj = MyObject->new( foo => 'Foozle', bar => 'Barbados' );
88
89         # Copy with overriding value
90         my $copy = $obj->new( bar => 'Bob' );
91
92       scalar - Instance Accessor
93
94       For each method name passed, uses a closure to generate a subroutine
95       with the following characteristics:
96
97       ·   Must be called on a hash-based instance.
98
99       ·   Has a specific hash key to use to access the related value for each
100           instance.  This defaults to the method name, but you may override
101           this with the "'hash_key' =" string> method parameter.
102
103       ·   If called without any arguments returns the current value.
104
105       ·   If called with an argument, stores that as the value, and returns
106           it,
107
108       Sample declaration and usage:
109
110         package MyObject;
111         use Class::MakeMethods::Standard::Hash (
112           scalar => 'foo',
113         );
114         ...
115
116         # Store value
117         $obj->foo('Foozle');
118
119         # Retrieve value
120         print $obj->foo;
121
122       array - Instance Ref Accessor
123
124       For each method name passed, uses a closure to generate a subroutine
125       with the following characteristics:
126
127       ·   Must be called on a hash-based instance.
128
129       ·   Has a specific hash key to use to access the related value for each
130           instance.  This defaults to the method name, but you may override
131           this with the "'hash_key' =" string> method parameter.
132
133       ·   The value for each instance will be a reference to an array (or
134           undef).
135
136       ·   If called without any arguments, returns the contents of the array
137           in list context, or an array reference in scalar context (or
138           undef).
139
140       ·   If called with a single array ref argument, sets the contents of
141           the array to match the contents of the provided one.
142
143       ·   If called with a single numeric argument, uses that argument as an
144           index to retrieve from the referenced array, and returns that value
145           (or undef).
146
147       ·   If called with a two arguments, the first undefined and the second
148           an array ref argument, uses that array's contents as a list of
149           indexes to return a slice of the referenced array.
150
151       ·   If called with a list of argument pairs, each with a numeric index
152           and an associated value, stores the value at the given index in the
153           referenced array. If the instance's value was previously undefined,
154           a new array is autovivified. The current value in each position
155           will be overwritten, and later arguments with the same index will
156           override earlier ones. Returns the current array-ref value.
157
158       ·   If called with a list of argument pairs, each with the first item
159           being a reference to an array of up to two numbers, loops over each
160           pair and uses those numbers to splice the value array.
161
162           The first controlling number is the position at which the splice
163           will begin. Zero will start before the first item in the list. Neg‐
164           ative numbers count backwards from the end of the array.
165
166           The second number is the number of items to be removed from the
167           list. If it is omitted, or undefined, or zero, no items are
168           removed. If it is a positive integer, that many items will be
169           returned.
170
171           If both numbers are omitted, or are both undefined, they default to
172           containing the entire value array.
173
174           If the second argument is undef, no values will be inserted; if it
175           is a non-reference value, that one value will be inserted; if it is
176           an array-ref, its values will be copied.
177
178           The method returns the items that removed from the array, if any.
179
180       Sample declaration and usage:
181
182         package MyObject;
183         use Class::MakeMethods::Standard::Hash (
184           array => 'bar',
185         );
186         ...
187
188         # Clear and set contents of list
189         print $obj->bar([ 'Spume', 'Frost' ] );
190
191         # Set values by position
192         $obj->bar(0 => 'Foozle', 1 => 'Bang!');
193
194         # Positions may be overwritten, and in any order
195         $obj->bar(2 => 'And Mash', 1 => 'Blah!');
196
197         # Retrieve value by position
198         print $obj->bar(1);
199
200         # Direct access to referenced array
201         print scalar @{ $obj->bar() };
202
203       There are also calling conventions for slice and splice operations:
204
205         # Retrieve slice of values by position
206         print join(', ', $obj->bar( undef, [0, 2] ) );
207
208         # Insert an item at position in the array
209         $obj->bar([3], 'Potatoes' );
210
211         # Remove 1 item from position 3 in the array
212         $obj->bar([3, 1], undef );
213
214         # Set a new value at position 2, and return the old value
215         print $obj->bar([2, 1], 'Froth' );
216
217       hash - Instance Ref Accessor
218
219       For each method name passed, uses a closure to generate a subroutine
220       with the following characteristics:
221
222       ·   Must be called on a hash-based instance.
223
224       ·   Has a specific hash key to use to access the related value for each
225           instance.  This defaults to the method name, but you may override
226           this with the "'hash_key' =" string> method parameter.
227
228       ·   The value for each instance will be a reference to a hash (or
229           undef).
230
231       ·   If called without any arguments, returns the contents of the hash
232           in list context, or a hash reference in scalar context (or undef).
233
234       ·   If called with one non-ref argument, uses that argument as an index
235           to retrieve from the referenced hash, and returns that value (or
236           undef).
237
238       ·   If called with one array-ref argument, uses the contents of that
239           array to retrieve a slice of the referenced hash.
240
241       ·   If called with one hash-ref argument, sets the contents of the ref‐
242           erenced hash to match that provided.
243
244       ·   If called with a list of key-value pairs, stores the value under
245           the given key in the referenced hash. If the instance's value was
246           previously undefined, a new hash is autovivified. The current value
247           under each key will be overwritten, and later arguments with the
248           same key will override earlier ones. Returns the contents of the
249           hash in list context, or a hash reference in scalar context.
250
251       Sample declaration and usage:
252
253         package MyObject;
254         use Class::MakeMethods::Standard::Hash (
255           hash => 'baz',
256         );
257         ...
258
259         # Set values by key
260         $obj->baz('foo' => 'Foozle', 'bar' => 'Bang!');
261
262         # Values may be overwritten, and in any order
263         $obj->baz('broccoli' => 'Blah!', 'foo' => 'Fiddle');
264
265         # Retrieve value by key
266         print $obj->baz('foo');
267
268         # Retrive slice of values by position
269         print join(', ', $obj->baz( ['foo', 'bar'] ) );
270
271         # Direct access to referenced hash
272         print keys %{ $obj->baz() };
273
274         # Reset the hash contents to empty
275         %{ $obj->baz() } = ();
276
277       object - Instance Ref Accessor
278
279       For each method name passed, uses a closure to generate a subroutine
280       with the following characteristics:
281
282       ·   Must be called on a hash-based instance.
283
284       ·   Has a specific hash key to use to access the related value for each
285           instance.  This defaults to the method name, but you may override
286           this with the "'hash_key' =" string> method parameter.
287
288       ·   The value for each instance will be a reference to an object (or
289           undef).
290
291       ·   If called without any arguments returns the current value.
292
293       ·   If called with an argument, stores that as the value, and returns
294           it,
295
296       Sample declaration and usage:
297
298         package MyObject;
299         use Class::MakeMethods::Standard::Hash (
300           object => 'foo',
301         );
302         ...
303
304         # Store value
305         $obj->foo( Foozle->new() );
306
307         # Retrieve value
308         print $obj->foo;
309

NAME

SYNOPSIS

DESCRIPTION

METHOD GENERATOR TYPES

SEE ALSO