1Class::MethodMaker::EngUisneer(3C)ontributed Perl DocumeCnltaastsi:o:nMethodMaker::Engine(3)
2
6 Class::MethodMaker::Engine - The parameter passing, method installation
7 & non-data-structure methods of Class::MethodMaker.
8
10 This class is for internal implementation only. It is not a public
11 API.
12 The non-data-structure methods do form part of the public API, but not
14 called directly: rather, called through the "use"/"import" interface,
15 as for data-structure methods.
16
18 import
21 This performs argument parsing ready for calling create_methods. In
23 particular, this is the point at which v1 & v2 calls are distinguished.
24 This is implicitly called as part of a "use" statement:
26 use Class::MethodMaker
28 [ scalar => [qw/ foo bar baz /],
29 new => [qw/ new /] ,
30 ];
31 is equivalent to
33 Class::MethodMaker->import([scalar => [qw/ foo bar baz /],
35 new => [qw/ new /] ,
36 ]);
37 See perldoc -f use for details of this equivalence.
39 The methods created are installed into the class calling the import -
41 or more accurately, the first class up the calling stack that is not
42 "Class::MethodMaker" or a subclass thereof.
43 SYNOPSIS
45 Class::MethodMaker->import([scalar => [+{ -type => 'File::Stat',
46 -forward => [qw/ mode size /],
47 '*_foo' => '*_fig',
48 '*_gop' => undef,
49 '*_bar' => '*_bar',
50 '*_hal' => '*_sal',
51 },
52 qw/ -static bob /,
53 ]
54 ]);
55 parse_options
57 Parse the arguments given to import and call create_methods appropri‐
59 ately. See main text for options syntax.
60 SYNOPSIS
62 Class::MethodMaker->parse_options('TargetClass',
63 [scalar =>
64 [{ -type => 'File::stat',
65 -forward => [qw/ mode
66 size /],
67 '*_foo' => '*_fig',
68 '*_gop' => undef,
69 '*_bar' => '*_bar',
70 '*_hal' => '*_sal',
71 },
72 qw( -static bob ),
73 ]])},
74 Class::MethodMaker->parse_options('TargetClass2',
76 [scalar =>
77 ['baz',
78 { -type => 'File::stat',
79 -forward => [qw/ mode
80 size /],
81 '*_foo' => '*_fog',
82 '*_bar' => '*_bar',
83 '*_hal' => '*_sal',
84 },
85 qw( -static bob ),
86 ]],
87 +{ -type => 'Math::BigInt', },
88 +{'*_foo' => '*_fig',
89 '*_gop' => undef,},
90 )},
91 ARGUMENTS
93 target_class
94 The class into which to install components
95 args
97 The arguments to parse, as a single arrayref.
98 options
100 A hashref of options to apply to all components created by this
101 call (subject to overriding by explicit option calls).
102 renames
104 A hashref of renames to apply to all components created by this
105 call (subject to overriding by explicit rename calls).
106 create_methods
108 Add methods to a class. Methods for multiple components may be added
110 this way, but create_methods handles only one set of options.
111 parse_options is responsible for sorting which options to apply to
112 which components, and calling create_methods appropriately.
113 SYNOPSIS
115 Class::MethodMaker->create_methods($target_class,
116 scalar => bob,
117 +{ static => 1,
118 type => 'File::Stat',
119 forward => [qw/ mode size /], },
120 +{ '*_foo' => '*_fig',
121 '*_gop' => undef,
122 '*_bar' => '*_bar',
123 '*_hal' => '*_sal', }
124 );
125 ARGUMENTS
127 targetclass
128 The class to add methods to.
129 type
131 The basic data structure to use for the component, e.g.,
132 "scalar".
133 compname
135 Component name. The name must be a valid identifier, i.e., a
136 continguous non-empty string of word ("\w") characters, of
137 which the first may not be a digit.
138 options
140 A hashref. Some options ("static", "type", "default",
141 "default_ctor") are handled by the auto-extender. These will
142 be invoked if the name is present as a key and the value is
143 true. Any other options are passed through to the method in
144 question. The options should be named as-is; no leading hyphen
145 should be applied (i.e., use "{static => 1}" not "{-static =>
146 1}").
147 renames
149 A list of customer renames. It is a hashref from method name
150 to rename. The method name is the generic name (i.e., featur‐
151 ing a "*" to replace with the component name). The rename is
152 the value to rename with. It may itself contain a "*" to
153 replace with the component name. If rename is undef, the
154 method is not installed. For methods that would not be
155 installed by default, use a rename value that is the same as
156 the method name.
157 So, if a type would normally install methods
159 '*_foo', '*_gop', '*_tom'
161 and optionally installs (but not by default)
163 '*_bar', '*_wiz', '*_hal'
165 using a renames value of
167 { '*_foo' => '*_fig',
169 '*_gop' => undef,
170 '*_bar' => '*_bar',
171 '*_hal' => '*_sal',
172 }
173 with a component name of "xx", then *_foo is installed as
175 "xx_fig", *_bar is installed as "xx_bar", *_wiz is not
176 installed, *_hal is installed as "xx_sal", *_gop is not
177 installed, and *_tom is installed as "xx_tom".
178 The value may actually be an arrayref, in which case the func‐
180 tion may be called by any of the multiple names specified.
181 install_methods
183 SYNOPSIS
185 Class::MethodMaker->install_methods
186 ($classname, { incr => sub { $i++ },
187 decr => sub { $i-- },
188 }
189 );
190 ARGUMENTS
192 target
193 The class into which the methods are to be installed
194 methods
196 The methods to install, as a hashref. Keys are the method
197 names; values are the methods themselves, as code refs.
198
200 new
203 use Class::MethodMaker
205 [ new => 'new' ];
206 Creates a basic constructor.
208 Takes a single string or a reference to an array of strings as its
210 argument. For each string creates a simple method that creates and
211 returns an object of the appropriate class.
212 The generated method may be called as a class method, as usual, or as
214 in instance method, in which case a new object of the same class as the
215 instance will be created.
216 Options
218 -hash
220 The contructor will accept as arguments a list of pairs, from com‐
221 ponent name to initial value. For each pair, the named component
222 is initialized by calling the method of the same name with the
223 given value. E.g.,
224 package MyClass;
226 use Class::MethodMaker
227 [ new => [qw/ -hash new /],
228 scalar => [qw/ b c /],
229 ];
230 sub d {
232 my $self = shift;
233 $self->{d} = $_[0]
234 if @_;
235 return $self->{d};
236 }
237 package main;
239 # The statement below implicitly calls
240 # $m->b(1); $m->c(2); $m->d(3)
241 # on the newly constructed m.
242 my $m = MyClass->new(b => 1, c => 2, d => 3);
243 Note that this can also call user-supplied methods that have the
245 name of the component.
246 Instead of a list of pairs, a single hashref may also be passed,
248 which will be expanded appropriately. So the above is equivalent
249 to:
250 my $m = MyClass->new({ b => 1, c => 2, d => 3 });
252 Advanced Users: Class::MethodMaker method renaming is taken into
254 account, so even if the "*" method is renamed or removed, this will
255 still work.
256 -init
258 This option causes the new method to call an initializor method.
259 The method is called "init" (original, eh?) by default, but the
260 option may be given an alternative value. The init method is
261 passed any arguments that were passed to the constructor, but the
262 method is invoked on the newly constructed instance.
263 use Class::MethodMaker
265 [ new => [qw/ -init new1 /, { -init => 'bob' } => 'init2' ]];
266 Constructing with new1 involves an implicit call to "init", whilst
268 constructing with new2 involves an implicit call to "bob" (instead
269 of "init").
270 It is the responsiblity of the user to ensure that an "init" method
272 (or whatever name) is defined.
273 -singleton
275 Creates a basic constructor which only ever returns a single
276 instance of the class: i.e., after the first call, repeated calls
277 to this constructor return the same instance. Note that the
278 instance is instantiated at the time of the first call, not before.
279 abstract
281 use Class::MethodMaker
283 [ abstract => [ qw / foo bar baz / ] ];
284 This creates a number of methods that will die if called. This is
286 intended to support the use of abstract methods, that must be overidden
287 in a useful subclass.
288 copy
290 use Class::MethodMaker
292 [ copy => [qw/ shallow -deep deep /] ];
293 This creates method that produce a copy of self. The copy is a by
295 default a shallow copy; any references will be shared by the instance
296 upon which the method is called and the returned newborn. One option
297 is taken, "-deep", which causes the method to create deep copies
298 instead (i.e., references are copied recursively).
299 Implementation Note:
301 Deep copies are performed using the "Storable" module if available,
303 else "Data::Dumper". The "Storable" module is liable to be much
304 quicker. However, this implementation note is not an API specifica‐
305 tion: the implementation details are open to change in a future version
306 as faster/better ways of performing a deep copy become available.
307 Note that deep copying does not currently support the copying of
309 coderefs, ties or XS-based objects.
310
312 Martyn J. Pearce <fluffy@cpan.org>
313perl v5.8.8 2005-11-26 Class::MethodMaker::Engine(3)