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

1MakeMethods::Standard::UIsnehrerCiotnatbrlieb(u3t)ed PerMlakDeoMceutmheondtsa:t:iSotnandard::Inheritable(3)
2
3
4

NAME

6       Class::MakeMethods::Standard::Inheritable - Overridable data
7

SYNOPSIS

9         package MyClass;
10
11         use Class::MakeMethods( 'Standard::Inheritable:scalar' => 'foo' );
12         # We now have an accessor method for an "inheritable" scalar value
13
14         MyClass->foo( 'Foozle' );   # Set a class-wide value
15         print MyClass->foo();       # Retrieve class-wide value
16
17         my $obj = MyClass->new(...);
18         print $obj->foo();          # All instances "inherit" that value...
19
20         $obj->foo( 'Foible' );      # until you set a value for an instance.
21         print $obj->foo();          # This now finds object-specific value.
22         ...
23
24         package MySubClass;
25         @ISA = 'MyClass';
26
27         print MySubClass->foo();    # Intially same as superclass,
28         MySubClass->foo('Foobar');  # but overridable per subclass,
29         print $subclass_obj->foo(); # and shared by its instances
30         $subclass_obj->foo('Fosil');# until you override them...
31         ...
32
33         # Similar behaviour for hashes and arrays is currently incomplete
34         package MyClass;
35         use Class::MakeMethods::Standard::Inheritable (
36           array => 'my_list',
37           hash => 'my_index',
38         );
39
40         MyClass->my_list(0 => 'Foozle', 1 => 'Bang!');
41         print MyClass->my_list(1);
42
43         MyClass->my_index('broccoli' => 'Blah!', 'foo' => 'Fiddle');
44         print MyClass->my_index('foo');
45

DESCRIPTION

47       The MakeMethods subclass provides accessor methods that search an
48       inheritance tree to find a value. This allows you to set a shared or
49       default value for a given class, optionally override it in a subclass,
50       and then optionally override it on a per-instance basis.
51
52       Note that all MakeMethods methods are inheritable, in the sense that
53       they work as expected for subclasses. These methods are different in
54       that the data accessed by each method can be inherited or overridden in
55       each subclass or instance. See "
56       Class::MakeMethods::Utility::Inheritable" for more about this type of
57       "inheritable" or overridable" data.
58
59   Calling Conventions
60       When you "use" this package, the method names you provide as arguments
61       cause subroutines to be generated and installed in your module.
62
63       See "Calling Conventions" in Class::MakeMethods::Standard for more
64       information.
65
66   Declaration Syntax
67       To declare methods, pass in pairs of a method-type name followed by one
68       or more method names.
69
70       Valid method-type names for this package are listed in "METHOD
71       GENERATOR TYPES".
72
73       See "Declaration Syntax" in Class::MakeMethods::Standard and "Parameter
74       Syntax" in Class::MakeMethods::Standard for more information.
75

METHOD GENERATOR TYPES

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

POD ERRORS

304       Hey! The above document had some coding errors, which are explained
305       below:
306
307       Around line 49:
308           L<> starts or ends with whitespace
309
310
311
312perl v5.34.0                      2022-01-M2a1keMethods::Standard::Inheritable(3)

NAME

SYNOPSIS

DESCRIPTION

METHOD GENERATOR TYPES

SEE ALSO

POD ERRORS