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
19 This performs argument parsing ready for calling create_methods. In
20 particular, this is the point at which v1 & v2 calls are distinguished.
21 This is implicitly called as part of a "use" statement:
23 use Class::MethodMaker
25 [ scalar => [qw/ foo bar baz /],
26 new => [qw/ new /] ,
27 ];
28 is equivalent to
30 Class::MethodMaker->import([scalar => [qw/ foo bar baz /],
32 new => [qw/ new /] ,
33 ]);
34 See perldoc -f use for details of this equivalence.
36 The methods created are installed into the class calling the import -
38 or more accurately, the first class up the calling stack that is not
39 "Class::MethodMaker" or a subclass thereof.
40 SYNOPSIS
42 Class::MethodMaker->import([scalar => [+{ -type => 'File::Stat',
43 -forward => [qw/ mode size /],
44 '*_foo' => '*_fig',
45 '*_gop' => undef,
46 '*_bar' => '*_bar',
47 '*_hal' => '*_sal',
48 },
49 qw/ -static bob /,
50 ]
51 ]);
52 parse_options
54 Parse the arguments given to import and call create_methods
55 appropriately. See main text for options syntax.
56 SYNOPSIS
58 Class::MethodMaker->parse_options('TargetClass',
59 [scalar =>
60 [{ -type => 'File::stat',
61 -forward => [qw/ mode
62 size /],
63 '*_foo' => '*_fig',
64 '*_gop' => undef,
65 '*_bar' => '*_bar',
66 '*_hal' => '*_sal',
67 },
68 qw( -static bob ),
69 ]])},
70 Class::MethodMaker->parse_options('TargetClass2',
72 [scalar =>
73 ['baz',
74 { -type => 'File::stat',
75 -forward => [qw/ mode
76 size /],
77 '*_foo' => '*_fog',
78 '*_bar' => '*_bar',
79 '*_hal' => '*_sal',
80 },
81 qw( -static bob ),
82 ]],
83 +{ -type => 'Math::BigInt', },
84 +{'*_foo' => '*_fig',
85 '*_gop' => undef,},
86 )},
87 ARGUMENTS
89 target_class
90 The class into which to install components
91 args
93 The arguments to parse, as a single arrayref.
94 options
96 A hashref of options to apply to all components created by this
97 call (subject to overriding by explicit option calls).
98 renames
100 A hashref of renames to apply to all components created by this
101 call (subject to overriding by explicit rename calls).
102 create_methods
104 Add methods to a class. Methods for multiple components may be added
105 this way, but create_methods handles only one set of options.
106 parse_options is responsible for sorting which options to apply to
107 which components, and calling create_methods appropriately.
108 SYNOPSIS
110 Class::MethodMaker->create_methods($target_class,
111 scalar => bob,
112 +{ static => 1,
113 type => 'File::Stat',
114 forward => [qw/ mode size /], },
115 +{ '*_foo' => '*_fig',
116 '*_gop' => undef,
117 '*_bar' => '*_bar',
118 '*_hal' => '*_sal', }
119 );
120 ARGUMENTS
122 targetclass
123 The class to add methods to.
124 type
126 The basic data structure to use for the component, e.g.,
127 "scalar".
128 compname
130 Component name. The name must be a valid identifier, i.e., a
131 continguous non-empty string of word ("\w") characters, of
132 which the first may not be a digit.
133 options
135 A hashref. Some options ("static", "type", "default",
136 "default_ctor") are handled by the auto-extender. These will
137 be invoked if the name is present as a key and the value is
138 true. Any other options are passed through to the method in
139 question. The options should be named as-is; no leading hyphen
140 should be applied (i.e., use "{static => 1}" not "{-static =>
141 1}").
142 renames
144 A list of customer renames. It is a hashref from method name
145 to rename. The method name is the generic name (i.e.,
146 featuring a "*" to replace with the component name). The
147 rename is the value to rename with. It may itself contain a
148 "*" to replace with the component name. If rename is undef,
149 the method is not installed. For methods that would not be
150 installed by default, use a rename value that is the same as
151 the method name.
152 So, if a type would normally install methods
154 '*_foo', '*_gop', '*_tom'
156 and optionally installs (but not by default)
158 '*_bar', '*_wiz', '*_hal'
160 using a renames value of
162 { '*_foo' => '*_fig',
164 '*_gop' => undef,
165 '*_bar' => '*_bar',
166 '*_hal' => '*_sal',
167 }
168 with a component name of "xx", then *_foo is installed as
170 "xx_fig", *_bar is installed as "xx_bar", *_wiz is not
171 installed, *_hal is installed as "xx_sal", *_gop is not
172 installed, and *_tom is installed as "xx_tom".
173 The value may actually be an arrayref, in which case the
175 function may be called by any of the multiple names specified.
176 install_methods
178 SYNOPSIS
179 Class::MethodMaker->install_methods
180 ($classname, { incr => sub { $i++ },
181 decr => sub { $i-- },
182 }
183 );
184 ARGUMENTS
186 target
187 The class into which the methods are to be installed
188 methods
190 The methods to install, as a hashref. Keys are the method
191 names; values are the methods themselves, as code refs.
192
194 new
195 use Class::MethodMaker
196 [ new => 'new' ];
197 Creates a basic constructor.
199 Takes a single string or a reference to an array of strings as its
201 argument. For each string creates a simple method that creates and
202 returns an object of the appropriate class.
203 The generated method may be called as a class method, as usual, or as
205 in instance method, in which case a new object of the same class as the
206 instance will be created.
207 Options
209 -hash
211 The contructor will accept as arguments a list of pairs, from
212 component name to initial value. For each pair, the named
213 component is initialized by calling the method of the same name
214 with the given value. E.g.,
215 package MyClass;
217 use Class::MethodMaker
218 [ new => [qw/ -hash new /],
219 scalar => [qw/ b c /],
220 ];
221 sub d {
223 my $self = shift;
224 $self->{d} = $_[0]
225 if @_;
226 return $self->{d};
227 }
228 package main;
230 # The statement below implicitly calls
231 # $m->b(1); $m->c(2); $m->d(3)
232 # on the newly constructed m.
233 my $m = MyClass->new(b => 1, c => 2, d => 3);
234 Note that this can also call user-supplied methods that have the
236 name of the component.
237 Instead of a list of pairs, a single hashref may also be passed,
239 which will be expanded appropriately. So the above is equivalent
240 to:
241 my $m = MyClass->new({ b => 1, c => 2, d => 3 });
243 Advanced Users: Class::MethodMaker method renaming is taken into
245 account, so even if the "*" method is renamed or removed, this will
246 still work.
247 -init
249 This option causes the new method to call an initializor method.
250 The method is called "init" (original, eh?) by default, but the
251 option may be given an alternative value. The init method is
252 passed any arguments that were passed to the constructor, but the
253 method is invoked on the newly constructed instance.
254 use Class::MethodMaker
256 [ new => [qw/ -init new1 /, { -init => 'bob' } => 'init2' ]];
257 Constructing with new1 involves an implicit call to "init", whilst
259 constructing with new2 involves an implicit call to "bob" (instead
260 of "init").
261 It is the responsiblity of the user to ensure that an "init" method
263 (or whatever name) is defined.
264 -singleton
266 Creates a basic constructor which only ever returns a single
267 instance of the class: i.e., after the first call, repeated calls
268 to this constructor return the same instance. Note that the
269 instance is instantiated at the time of the first call, not before.
270 abstract
272 use Class::MethodMaker
273 [ abstract => [ qw / foo bar baz / ] ];
274 This creates a number of methods that will die if called. This is
276 intended to support the use of abstract methods, that must be overidden
277 in a useful subclass.
278 copy
280 use Class::MethodMaker
281 [ copy => [qw/ shallow -deep deep /] ];
282 This creates method that produce a copy of self. The copy is a by
284 default a shallow copy; any references will be shared by the instance
285 upon which the method is called and the returned newborn. One option
286 is taken, "-deep", which causes the method to create deep copies
287 instead (i.e., references are copied recursively).
288 Implementation Note:
290 Deep copies are performed using the "Storable" module if available,
292 else "Data::Dumper". The "Storable" module is liable to be much
293 quicker. However, this implementation note is not an API
294 specification: the implementation details are open to change in a
295 future version as faster/better ways of performing a deep copy become
296 available.
297 Note that deep copying does not currently support the copying of
299 coderefs, ties or XS-based objects.
300
302 Martyn J. Pearce <fluffy@cpan.org>
303perl v5.10.1 2010-05-10 Class::MethodMaker::Engine(3)