1Class::MethodMaker::EngUisneer(3C)ontributed Perl DocumeCnltaastsi:o:nMethodMaker::Engine(3)
2
3
4

NAME

6       Class::MethodMaker::Engine - The parameter passing, method installation
7       & non-data-structure methods of Class::MethodMaker.
8

SYNOPSIS

10       This class is for internal implementation only.  It is not a public
11       API.
12
13       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

The Class::MethodMaker Method Installation Engine

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
22       This is implicitly called as part of a "use" statement:
23
24         use Class::MethodMaker
25           [ scalar => [qw/ foo bar baz /],
26             new    => [qw/ new /]        ,
27           ];
28
29       is equivalent to
30
31         Class::MethodMaker->import([scalar => [qw/ foo bar baz /],
32                                     new    => [qw/ new /]        ,
33                                    ]);
34
35       See perldoc -f use for details of this equivalence.
36
37       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
41       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
53   parse_options
54       Parse the arguments given to import and call create_methods
55       appropriately.  See main text for options syntax.
56
57       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
71             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
88       ARGUMENTS
89           target_class
90               The class into which to install components
91
92           args
93               The arguments to parse, as a single arrayref.
94
95           options
96               A hashref of options to apply to all components created by this
97               call (subject to overriding by explicit option calls).
98
99           renames
100               A hashref of renames to apply to all components created by this
101               call (subject to overriding by explicit rename calls).
102
103   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
109       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
121       ARGUMENTS
122           targetclass
123               The class to add methods to.
124
125           type
126               The basic data structure to use for the component, e.g.,
127               "scalar".
128
129           compname
130               Component name.  The name must be a valid identifier, i.e., a
131               continuous non-empty string of word ("\w") characters, of which
132               the first may not be a digit.
133
134           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
143           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
153               So, if a type would normally install methods
154
155                 '*_foo', '*_gop', '*_tom'
156
157               and optionally installs (but not by default)
158
159                 '*_bar', '*_wiz', '*_hal'
160
161               using a renames value of
162
163                 { '*_foo' => '*_fig',
164                   '*_gop' => undef,
165                   '*_bar' => '*_bar',
166                   '*_hal' => '*_sal',
167                 }
168
169               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
174               The value may actually be an arrayref, in which case the
175               function may be called by any of the multiple names specified.
176
177   install_methods
178       SYNOPSIS
179             Class::MethodMaker->install_methods
180               ($classname, { incr => sub { $i++ },
181                              decr => sub { $i-- },
182                            }
183               );
184
185       ARGUMENTS
186           target
187               The class into which the methods are to be installed
188
189           methods
190               The methods to install, as a hashref.  Keys are the method
191               names; values are the methods themselves, as code refs.
192

Non-data-structure components

194   new
195         use Class::MethodMaker
196           [ new => 'new' ];
197
198       Creates a basic constructor.
199
200       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
204       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
208       Options
209
210       -hash
211           The constructor 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
216             package MyClass;
217             use Class::MethodMaker
218               [ new    => [qw/ -hash new /],
219                 scalar => [qw/ b c /],
220               ];
221
222             sub d {
223               my $self = shift;
224               $self->{d} = $_[0]
225                 if @_;
226               return $self->{d};
227             }
228
229             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
235           Note that this can also call user-supplied methods that have the
236           name of the component.
237
238           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
242             my $m = MyClass->new({ b => 1, c => 2, d => 3 });
243
244           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
248       -init
249           This option causes the new method to call an initializer 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
255             use Class::MethodMaker
256               [ new => [qw/ -init new1 /, { -init => 'bob' } => 'init2' ]];
257
258           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
262           It is the responsibility of the user to ensure that an "init"
263           method (or whatever name) is defined.
264
265       -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
271   abstract
272         use Class::MethodMaker
273           [ abstract => [ qw / foo bar baz / ] ];
274
275       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
277       overridden in a useful subclass.
278
279   copy
280         use Class::MethodMaker
281           [ copy => [qw/ shallow -deep deep /] ];
282
283       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
289       Implementation Note:
290
291       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
298       Note that deep copying does not currently support the copying of
299       coderefs, ties or XS-based objects.
300

AUTHOR

302       Martyn J. Pearce <fluffy@cpan.org>
303
304
305
306perl v5.28.1                      2015-03-31     Class::MethodMaker::Engine(3)
Impressum