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

1MakeMethods::Standard::UAsrerrayC(o3n)tributed Perl DocuMmaeknetMaettihoonds::Standard::Array(3)
2
3
4

NAME

6       Class::MakeMethods::Standard::Array - Methods for Array objects
7

SYNOPSIS

9         package MyObject;
10         use Class::MakeMethods::Standard::Array (
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::Array suclass of MakeMethods provides a basic constructor
32       and accessors for blessed-array 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
51   Positional Accessors and %FIELDS
52       Each accessor method is assigned the next available array index at
53       which to store its value.
54
55       The mapping between method names and array positions is stored in a
56       hash named %FIELDS in the declaring package. When a package declares
57       its first positional accessor, its %FIELDS are initialized by searching
58       its inheritance tree.
59
60       Warning: Subclassing packages that use positional accessors is somewhat
61       fragile, since you may end up with two distinct methods assigned to the
62       same position. Specific cases to avoid are:
63
64       ·   If you inherit from more than one class with positional accessors,
65           the positions used by the two sets of methods will overlap.
66
67       ·   If your superclass adds additional positional accessors after you
68           declare your first, they will overlap yours.
69

METHOD GENERATOR TYPES

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

NAME

SYNOPSIS

DESCRIPTION

METHOD GENERATOR TYPES

SEE ALSO