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       When you "use" this package, the method names you provide as arguments
36       cause subroutines to be generated and installed in your module.
37
38       See "Calling Conventions" in Class::MakeMethods::Standard for more
39       information.
40
41   Declaration Syntax
42       To declare methods, pass in pairs of a method-type name followed by one
43       or more method names.
44
45       Valid method-type names for this package are listed in "METHOD
46       GENERATOR TYPES".
47
48       See "Declaration Syntax" in Class::MakeMethods::Standard and "Parameter
49       Syntax" in Class::MakeMethods::Standard for more information.
50

METHOD GENERATOR TYPES

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

NAME

SYNOPSIS

DESCRIPTION

METHOD GENERATOR TYPES

SEE ALSO