1MakeMethods::Composite:U:sAerrraCyo(n3t)ributed Perl DocMuamkeenMteatthioodns::Composite::Array(3)
2
6 Class::MakeMethods::Composite::Array - Basic array methods
7
9 package MyObject;
10 use Class::MakeMethods::Composite::Array (
11 new => 'new',
12 scalar => [ 'foo', 'bar' ],
13 array => 'my_list',
14 hash => 'my_index',
15 );
16 ...
17 my $obj = MyObject->new( foo => 'Foozle' );
19 print $obj->foo();
20 $obj->bar('Barbados');
22 print $obj->bar();
23 $obj->my_list(0 => 'Foozle', 1 => 'Bang!');
25 print $obj->my_list(1);
26 $obj->my_index('broccoli' => 'Blah!', 'foo' => 'Fiddle');
28 print $obj->my_index('foo');
29
31 The Composite::Array suclass of MakeMethods provides a basic
32 constructor and accessors for blessed-array object instances.
33 Class::MakeMethods Calling Conventions
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 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 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 You can install methods in a different package by passing "-TargetClass
48 => package" as your first arguments to "use" or "make".
49 See Class::MakeMethods for more details.
51 Class::MakeMethods::Basic Declaration Syntax
53 The following types of Basic declarations are supported:
54 • generator_type => "method_name"
56 • generator_type => "name_1 name_2..."
58 • generator_type => [ "name_1", "name_2", ...]
60 See the "METHOD GENERATOR TYPES" section below for a list of the
62 supported values of generator_type.
63 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 Method names should start with a letter, followed by zero or more
68 letters, numbers, or underscores.
69 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 • generator_type => [ "name_1" => { param=>value... }, ... ]
75 A hash of parameters to use just for this method name.
77 (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 • generator_type => [ [ "name_1", "name_2", ... ] => {
83 param=>value... } ]
84 Each of these method names gets a copy of the same set of
86 parameters.
87 • generator_type => [ { "name"=>"name_1", param=>value... }, ... ]
89 By including the reserved parameter "name", you create a self
91 contained declaration with that name and any associated hash
92 values.
93 Basic declarations, as described above, are treated as having an empty
95 parameter hash.
96 Positional Accessors and %FIELDS
98 Each accessor method is assigned the next available array index at
99 which to store its value.
100 The mapping between method names and array positions is stored in a
102 hash named %FIELDS in the declaring package. When a package declares
103 its first positional accessor, its %FIELDS are initialized by searching
104 its inheritance tree.
105 Warning: Subclassing packages that use positional accessors is somewhat
107 fragile, since you may end up with two distinct methods assigned to the
108 same position. Specific cases to avoid are:
109 • If you inherit from more than one class with positional accessors,
111 the positions used by the two sets of methods will overlap.
112 • If your superclass adds additional positional accessors after you
114 declare your first, they will overlap yours.
115
117 new - Constructor
118 For each method name passed, returns a subroutine with the following
119 characteristics:
120 • Has a reference to a sample item to copy. This defaults to a
122 reference to an empty array, but you may override this with the
123 "'defaults' =" array_ref> method parameter.
124 • If called as a class method, makes a new array containing values
126 from the sample item, and blesses it into that class.
127 • If called on an array-based instance, makes a copy of it and
129 blesses the copy into the same class as the original instance.
130 • If passed a list of method-value pairs, calls each named method
132 with the associated value as an argument.
133 • Returns the new instance.
135 Sample declaration and usage:
137 package MyObject;
139 use Class::MakeMethods::Composite::Array (
140 new => 'new',
141 );
142 ...
143 # Bare constructor
145 my $empty = MyObject->new();
146 # Constructor with initial sequence of method calls
148 my $obj = MyObject->new( foo => 'Foozle', bar => 'Barbados' );
149 # Copy with overriding sequence of method calls
151 my $copy = $obj->new( bar => 'Bob' );
152 new_with_values - Constructor
154 For each method name passed, returns a subroutine with the following
155 characteristics:
156 • May be called as a class method, or (equivalently) on any existing
158 object of that class.
159 • Creates an array, blesses it into the class, and returns the new
161 instance.
162 • If no arguments are provided, the returned array will be empty. If
164 passed a single array-ref argument, copies its contents into the
165 new array. If called with multiple arguments, copies them into the
166 new array. (Note that this is a "shallow" copy, not a "deep"
167 clone.)
168 Sample declaration and usage:
170 package MyObject;
172 use Class::MakeMethods::Composite::Array (
173 new => 'new',
174 );
175 ...
176 # Bare constructor
178 my $empty = MyObject->new();
179 # Constructor with initial sequence of method calls
181 my $obj = MyObject->new( foo => 'Foozle', bar => 'Barbados' );
182 # Copy with overriding sequence of method calls
184 my $copy = $obj->new( bar => 'Bob' );
185 scalar - Instance Accessor
187 For each method name passed, uses a closure to generate a subroutine
188 with the following characteristics:
189 • Must be called on an array-based instance.
191 • Determines the array position associated with the method name, and
193 uses that as an index into each instance to access the related
194 value. This defaults to the next available slot in %FIELDS, but you
195 may override this with the "'array_index' =" number> method
196 parameter, or by pre-filling the contents of %FIELDS.
197 • If called without any arguments returns the current value (or
199 undef).
200 • If called with an argument, stores that as the value, and returns
202 it,
203 • If called with multiple arguments, stores a reference to a new
205 array with those arguments as contents, and returns that array
206 reference.
207 Sample declaration and usage:
209 package MyObject;
211 use Class::MakeMethods::Composite::Array (
212 scalar => 'foo',
213 );
214 ...
215 # Store value
217 $obj->foo('Foozle');
218 # Retrieve value
220 print $obj->foo;
221 array - Instance Ref Accessor
223 For each method name passed, uses a closure to generate a subroutine
224 with the following characteristics:
225 • Must be called on an array-based instance.
227 • Determines the array position associated with the method name, and
229 uses that as an index into each instance to access the related
230 value. This defaults to the next available slot in %FIELDS, but you
231 may override this with the "'array_index' =" number> method
232 parameter, or by pre-filling the contents of %FIELDS.
233 • The value for each instance will be a reference to an array (or
235 undef).
236 • If called without any arguments, returns the current array-ref
238 value (or undef).
239 • If called with a single non-ref argument, uses that argument as an
241 index to retrieve from the referenced array, and returns that value
242 (or undef).
243 • If called with a single array ref argument, uses that list to
245 return a slice of the referenced array.
246 • If called with a list of argument pairs, each with a non-ref index
248 and an associated value, stores the value at the given index in the
249 referenced array. If the instance's value was previously undefined,
250 a new array is autovivified. The current value in each position
251 will be overwritten, and later arguments with the same index will
252 override earlier ones. Returns the current array-ref value.
253 • If called with a list of argument pairs, each with the first item
255 being a reference to an array of up to two numbers, loops over each
256 pair and uses those numbers to splice the value array.
257 The first controlling number is the position at which the splice
259 will begin. Zero will start before the first item in the list.
260 Negative numbers count backwards from the end of the array.
261 The second number is the number of items to be removed from the
263 list. If it is omitted, or undefined, or zero, no items are
264 removed. If it is a positive integer, that many items will be
265 returned.
266 If both numbers are omitted, or are both undefined, they default to
268 containing the entire value array.
269 If the second argument is undef, no values will be inserted; if it
271 is a non-reference value, that one value will be inserted; if it is
272 an array-ref, its values will be copied.
273 The method returns the items that removed from the array, if any.
275 Sample declaration and usage:
277 package MyObject;
279 use Class::MakeMethods::Composite::Array (
280 array => 'bar',
281 );
282 ...
283 # Clear and set contents of list
285 print $obj->bar([ 'Spume', 'Frost' ] );
286 # Set values by position
288 $obj->bar(0 => 'Foozle', 1 => 'Bang!');
289 # Positions may be overwritten, and in any order
291 $obj->bar(2 => 'And Mash', 1 => 'Blah!');
292 # Retrieve value by position
294 print $obj->bar(1);
295 # Direct access to referenced array
297 print scalar @{ $obj->bar() };
298 There are also calling conventions for slice and splice operations:
300 # Retrieve slice of values by position
302 print join(', ', $obj->bar( undef, [0, 2] ) );
303 # Insert an item at position in the array
305 $obj->bar([3], 'Potatoes' );
306 # Remove 1 item from position 3 in the array
308 $obj->bar([3, 1], undef );
309 # Set a new value at position 2, and return the old value
311 print $obj->bar([2, 1], 'Froth' );
312 hash - Instance Ref Accessor
314 For each method name passed, uses a closure to generate a subroutine
315 with the following characteristics:
316 • Must be called on an array-based instance.
318 • Determines the array position associated with the method name, and
320 uses that as an index into each instance to access the related
321 value. This defaults to the next available slot in %FIELDS, but you
322 may override this with the "'array_index' =" number> method
323 parameter, or by pre-filling the contents of %FIELDS.
324 • The value for each instance will be a reference to a hash (or
326 undef).
327 • If called without any arguments, returns the contents of the hash
329 in list context, or a hash reference in scalar context (or undef).
330 • If called with one non-ref argument, uses that argument as an index
332 to retrieve from the referenced hash, and returns that value (or
333 undef).
334 • If called with one array-ref argument, uses the contents of that
336 array to retrieve a slice of the referenced hash.
337 • If called with one hash-ref argument, sets the contents of the
339 referenced hash to match that provided.
340 • If called with a list of key-value pairs, stores the value under
342 the given key in the referenced hash. If the instance's value was
343 previously undefined, a new hash is autovivified. The current value
344 under each key will be overwritten, and later arguments with the
345 same key will override earlier ones. Returns the contents of the
346 hash in list context, or a hash reference in scalar context.
347 Sample declaration and usage:
349 package MyObject;
351 use Class::MakeMethods::Composite::Array (
352 hash => 'baz',
353 );
354 ...
355 # Set values by key
357 $obj->baz('foo' => 'Foozle', 'bar' => 'Bang!');
358 # Values may be overwritten, and in any order
360 $obj->baz('broccoli' => 'Blah!', 'foo' => 'Fiddle');
361 # Retrieve value by key
363 print $obj->baz('foo');
364 # Retrive slice of values by position
366 print join(', ', $obj->baz( ['foo', 'bar'] ) );
367 # Direct access to referenced hash
369 print keys %{ $obj->baz() };
370 # Reset the hash contents to empty
372 @{ $obj->baz() } = ();
373 object - Instance Ref Accessor
375 For each method name passed, uses a closure to generate a subroutine
376 with the following characteristics:
377 • Must be called on an array-based instance.
379 • Determines the array position associated with the method name, and
381 uses that as an index into each instance to access the related
382 value. This defaults to the next available slot in %FIELDS, but you
383 may override this with the "'array_index' =" number> method
384 parameter, or by pre-filling the contents of %FIELDS.
385 • The value for each instance will be a reference to an object (or
387 undef).
388 • If called without any arguments returns the current value.
390 • If called with an argument, stores that as the value, and returns
392 it,
393 Sample declaration and usage:
395 package MyObject;
397 use Class::MakeMethods::Composite::Hash (
398 object => 'foo',
399 );
400 ...
401 # Store value
403 $obj->foo( Foozle->new() );
404 # Retrieve value
406 print $obj->foo;
407
409 See Class::MakeMethods for general information about this distribution.
410 See Class::MakeMethods::Composite for more about this family of
412 subclasses.
413perl v5.36.0 2023-01-20 MakeMethods::Composite::Array(3)