1Class::AutoClass(3) User Contributed Perl Documentation Class::AutoClass(3)
2
6 1) get and set methods for simple attributes can be automatically
7 generated
8 2) argument lists are handled as described below
10 3) the protocol for object creation and initialization is close to
12 the 'textbook' approach generally suggested for object-oriented Perl
13 (see below)
14 4) object initialization is handled correctly in the presence of multiple inheritance
16 @AUTO_ATTRIBUTES is a list of 'attribute' names: get and set methods
18 are created for each attribute. By default, the name of the method
19 is identical to the attribute (but see $CASE below). Values of
20 attributes can be set via the 'new' constructor, %DEFAULTS, or the
21 'set' method as discussed below.
22 @CLASS_ATTRIBUTES is a list of class attributes: get and set methods
24 are created for each attribute. By default, the name of the method
25 is identical to the attribute (but see $CASE below). Values of
26 attributes can be set via the 'new' constructor, %DEFAULTS (initialized
27 at "declare time" (when the declare function is called) versus instance
28 attributes, which are of course initialized at runtime), standard
29 class variable access syntax ($PackageName::AttributeName), or the
30 'set' method as discussed below. Normal inheritance rules apply to
31 class attributes (but of course, instances of the same class share
32 the same class variable).
33 @OTHER_ATTRIBUTES is a list of attributes for which get and set
35 methods are NOT generated, but whose values can be set via the 'new'
36 constructor or the 'set' method as discussed below.
37 %SYNONYMS is a hash that defines synonyms for attribues. Each entry
39 is of the form 'new_attribute_name'=>'old_attribute_name'. get and
40 set methods are generated for the new names; these methods simply
41 call the method for the old name.
42 %DEFAULTS is a hash that defines default values for attributes. Each
44 entry is of the form 'attribute_name'=>'default_value'. get and
45 set methods are generated for each attributes.
46 $CASE controls whether additional methods are generated with all
48 upper or all lower case names. It should be a string containing the
49 strings 'upper' or 'lower' (case insenstive) if the desired case is
50 desired.
51 The declare function actually generates the method.
53 This should be called once and no where else.
54 AutoClass must be the first class in @ISA !! As usual, you create
56 objects by calling 'new'. Since AutoClass is the first class in @ISA,
57 it's 'new' method is the one that's called. AutoClass's 'new'
58 examines the rest of @ISA and searches for a superclass that is
59 capable of creating the object. If no such superclass is found,
60 AutoClass creates the object itself. Once the object is created,
61 AutoClass arranges to have all subclasses run their initialization
62 methods (_init_self) in a top-down order.
63 Argument Processing
65 We support positional and keyword argument lists, but we strongly urge
66 that each method pick one form or the other, as the combination is
67 inherently ambiguous (see below).
68 Consider a method, foo, that takes two arguments, a first name and a
70 last_name name. The positional form might be
71 $object->foo('Nat', 'Goodman')
73 while the keyword form might be
75 $object->foo(first_name=>'Nat', last_name=>'Goodman')
77 In keyword form, keywords are insensitive to case and leading dashes:
79 the keywords
80 first_name, -first_name, -FIRST_NAME, --FIRST_NAME, First_Name, -First_Name
82 are all equivalent. Internally, for those who care, our convention is
84 to use uppercase, un-dashed keys for the attributes of an object.
85 We convert repeated keyword arguments into an ARRAY ref of the values.
87 Thus:
88 $object->foo(first_name=>'Nat', first_name=>'Nathan')
90 is equivalent to
92 $object->foo(first_name=>['Nat', 'Nathan'])
94 Keyword arguments can be specified via ARRAY or HASH refs which are
96 dereferenced back to their elements, e.g.,
97 $object->foo([first_name=>'Nat', last_name=>'Goodman'])
99 $object->foo({first_name=>'Nat', last_name=>'Goodman'})
101 are both equivalent to
103 $object->foo(first_name=>'Nat', last_name=>'Goodman')
105 We can get away with this, because we encourage method writers to
107 choose between positional and keyword argument lists. If a method uses
108 positional arguments, it will interpret
109 $object->foo($array)
111 as a call that is setting the first_name parameter to $array, while if
113 it uses keyword arguments, it will dereference the array to a list of
114 keyword, value pairs.
115 We also allow the argument list to be an object. This is often used in
117 new to accomplish what a C++ programmer would call a cast. In simple
118 cases, the object is just treated as a HASH ref and its attributes are
119 passed to a the method as keyword, value pairs.
120 Why the Combination of Positional and Keyword Forms is Ambiguous
122 The keyword => value notation is just a Perl shorthand for stating two
123 list members with the first one quoted. Thus,
124 $object->foo(first_name=>'Nat', last_name=>'Goodman')
126 is completely equivalent to
128 $object->foo('first_name', 'Nat', 'last_name', 'Goodman')
130 The ambiguity of allowing both positional and keyword forms should now
132 be apparent. In this example,
133 $object->foo('first_name', 'Nat')
135 there is s no way to tell whether the program is calling foo with the
137 first_name parameter set to the value 'first_name' and the last_name
138 parameter set to 'Nat', vs. calling foo with the first_name parameter
139 set to 'Nat' and the last_name parameter left undefined.
140 If a program wishes to permit both forms, we suggest that keywords be
142 required to start with '-' (and that values do not start with '-').
143 Obviously, this is not fully general. We provide a method,
144 _is_positional, that checks this convention. Subclasses are free to
145 ignore this.
146 Protocol for Object Creation and Initializaton
148 We expect objects to be created by invoking new on its class. For
149 example
150 $object = new SomeClass(first=>'Nat', last=>'Goodman')
152 To correctly initialize objects that participate in multiple
154 inheritance, we use a technqiue described in Chapter 10 of Paul
155 Fenwick's excellent
156 tutorial on Object Oriented Perl (see
157 http://perltraining.com.au/notes/perloo.pdf). (We experimented with
158 Damian Conway's interesting NEXT pseudo-pseudo-class discussed in
159 Chapter 11 of Fenwick's tutorial
160 available in CPAN at
161 http://search.cpan.org/author/DCONWAY/NEXT-0.50/lib/NEXT.pm,
162 but could not get it to traverse the inheritance structure in the
163 correct,
164 top-down order.)
165 AutoClass class provides a 'new' method that expects a keyword argument
167 list. This method processes the argument list as discussed in
168 L<Argument Processing>: it figures out the syntactic form (list of
169 keyword, value pairs, vs. ARRAY ref vs. HASH ref, etc.). It then
170 converts the argument list into a canonical form, which is a list of
171 keyword, value pairs with all keywords uppercased and de-dashed. Once
172 the argument list is in this form, subsequent code treats it as a HASH
173 ref.
174 AutoClass::new initializes the object's class structure from top to
176 bottom, and is careful to initialize each class exactly once even in
177 the presence of multiple inheritance. The net effect is that objects
178 are initialized top-down as expected; a subclass object can assume that
179 all superior classes are initialized by the time subclass
180 initialization occurs.
181 AutoClass automatically initializes attributes and synonyms declared
183 when the class is defined. If additional initialization is required,
184 the class writer can provide an _init_self method. _init_self is
185 called after all superclasses are initialized and after the automatic
186 initialization for the class has been done.
187 AutoClass initializes attributes and synonyms by calling the set
189 methods for these elements with the like-named parameter -- it does not
190 simply slam the parameter into a slot in the object''s HASH. This
191 allows the class writer implement non-standard initialization within
192 the set method.
193 The main case where a subclass needs its own 'new' method is if it
195 wishes to allow positional arguments. In this case, the subclass 'new'
196 is responsible for is responsible for recognizing that positional
197 arguments are being used (if the class permits keyword arguments also),
198 and converting the positional arguments into keyword, value form. At
199 this point, the method can simply call AutoClass::new with the
200 converted argument list.
201 The subclass should not generally call SUPER::new as this would force
203 redundant argument processing in any super-class that also has its own
204 new. It would also force the super-class new to be smart enough to
205 handle positional as well as keyword parameters, which as we've noted
206 is inherently ambiguous.
207 =head1 KNOWN BUGS AND CAVEATS
209 This is still a work in progress.
211 =head2 Bugs, Caveats, and ToDos
213 1) There is no way to manipulate the arguments that are sent to the
215 real base class. There should be a way to specify a subroutine that
216 reformats these if needed.
217 2) DESTROY not handled
219 3) Autogeneration of methods is hand crafted. It may be better to
221 use Class::MakeMethods or Damian Conway's Multimethod class for
222 doing signature-based method dispatch
223 4) Caveat: In order to specify that a class that uses AutoClass should return
225 undef (versus an uninitialized (but blessed) object), one need to set:
226 $self->{__NULLIFY__}=1;
227
229 Email natg@shore.net
230
232 Email ccavnor@systemsbiology.net
233
235 Copyright (c) 2003 Institute for Systems Biology (ISB). All Rights
236 Reserved.
237 This module is free software; you can redistribute it and/or modify it
239 under the same terms as Perl itself.
240
242 The rest of the documentation describes the methods. Note that
243 internal methods are preceded with _
244 new
246 Title : new
247 Usage : $object=new Foo(first_name=>'Nat', last_name=>'Goodman')
248 where Foo is a subclass of AutoClass
249 Function: Create and initialize object
250 Returns : New object of class $class
251 Args : Any arguments needed by subclasses
252 -->> Arguments must be in keyword form. See DESCRIPTION for more.
253 Notes : Tries to invoke superclass to actually create the object
254 _init
256 Title : _init
257 Usage : $self->_init($class,$args)
258 Function: Initialize new object
259 Returns : nothing useful
260 Args : $class -- lexical (static) class being initialized, not the
261 actual (dynamic) class of $self
262 $arg -- argument list in canonical keyword form
263 Notes : Adapted from Chapter 10 of Paul Fenwick''s excellent tutorial on
264 Object Oriented Perl (see http://perltraining.com.au/notes/perloo.pdf).
265 set
267 Title : set
268 Usage : $self->set(-first_name=>'Nat',-last_name=>'Goodman')
269 Function: Set multiple attributes in existing object
270 Args : Parameter list in same format as for new
271 Returns : nothing
272 set_attributes
274 Title : set_attributes
275 Usage : $self->set_attributes([qw(first_name last_name)],$args)
276 Function: Set multiple attributes from a Class::AutoClass::Args object
277 Any attribute value that is present in $args is set
278 Args : ARRAY ref of attributes
279 Class::AutoClass::Args object
280 Returns : nothing
281 get
283 Title : get
284 Usage : ($first,$last)=$self->get(qw(-first_name,-last_name))
285 Function: Get values for multiple attributes
286 Args : Attribute names
287 Returns : List of attribute values
288 AUTO_ATTRIBUTES
290 Title : AUTO_ATTRIBUTES
291 Usage : @auto_attributes=AUTO_ATTRIBUTES('SubClass')
292 @auto_attributes=$self->AUTO_ATTRIBUTES();
293 Function: Get @AUTO_ATTRIBUTES for lexical class.
294 @AUTO_ATTRIBUTES is defined by class writer. These are attributes for which get and set methods
295 are automatically generated. _init automatically
296 initializes these attributes from like-named parameters in
297 the argument list
298 Args : class
299 OTHER_ATTRIBUTES
301 Title : OTHER_ATTRIBUTES
302 Usage : @other_attributes=OTHER_ATTRIBUTES('SubClass')
303 @other_attributes=$self->OTHER_ATTRIBUTES();
304 Function: Get @OTHER_ATTRIBUTES for lexical class.
305 @OTHER_ATTRIBUTES is defined by class writer. These are attributes for which get and set methods
306 are not automatically generated. _init automatically
307 initializes these attributes from like-named parameters in
308 the argument list
309 Args : class
310 SYNONYMS
312 Title : SYNONYMS
313 Usage : %synonyms=SYNONYMS('SubClass')
314 %synonyms=$self->SYNONYMS();
315 Function: Get %SYNONYMS for lexical class.
316 %SYNONYMS is defined by class writer. These are alternate names for attributes generally
317 defined in superclasses. get and set methods are
318 automatically generated. _init automatically initializes
319 these attributes from like-named parameters in the argument
320 list
321 Args : class
322 declare
324 Title : declare
325 Usage : @AUTO_ATTRIBUTES=qw(sex address dob);
326 @OTHER_ATTRIBUTES=qw(age);
327 %SYNONYMS=(name=>'id');
328 AutoClass::declare(__PACKAGE__,'lower|upper');
329 Function: Generate get and set methods for simple attributes and synonyms.
330 Method names are identical to the attribute names including case
331 Returns : nothing
332 Args : lexical class being created -- should always be __PACKAGE__
333 ARRAY ref of attributes
334 HASH ref of synonyms. Keys are new names, values are old
335 code that indicates whether method should also be generated
336 with all lower or upper case names
337 _enumerate
339 Title : _enumerate
340 Usage : _enumerate($class);
341 Function: locates classes that have a callable constructor
342 Args : a class reference
343 Returns : list of internal classes, a class with a callable constructor
344 _fix_args
346 Title : _fix_args
347 Usage : $args=_fix_args(-name=>'Nat',-name=>Goodman,address=>'Seattle')
348 $args=$self->_fix_args(@args)
349 Function: Convert argument list into canonical form. This is a HASH ref in
351 which keys are uppercase with no leading dash, and repeated
352 keyword arguments are merged into an ARRAY ref. In the
353 example above, the argument list would be converted to this
354 hash
355 (NAME=>['Nat', 'Goodman'],ADDRESS=>'Seattle')
356 Returns : argument list in canonical form
357 Args : argument list in any keyword form
358 _fix_keyword
360 Title : _fix_keyword
361 Usage : $keyword=_fix_keyword('-name')
362 @keywords=_fix_keyword('-name','-address');
363 Function: Convert a keyword or list of keywords into canonical form. This
364 is uppercase with no leading dash. In the example above,
365 '-name' would be converted to 'NAME'. Non-scalars are left
366 unchanged.
367 Returns : keyword or list of keywords in canonical form
368 Args : keyword or list of keywords
369 _set_attributes
371 Title : _set_attributes
372 Usage : my %synonyms=SYNONYMS($class);
373 my $attributes=[AUTO_ATTRIBUTES($class),
374 OTHER_ATTRIBUTES($class),
375 keys %synonyms];
376 $self->_set_attributes($attributes,$args);
377 Function: Set a list of simple attributes from a canonical argument list
378 Returns : nothing
379 Args : $attributes -- ARRAY ref of attributes to be set
380 $args -- argument list in canonical keyword (hash) form
381 Notes : The function calls the set method for each attribute passing
382 it the like-named parameter from the argument list
383 _is_positional
385 Title : _is_positional
386 Usage : if (_is_positional(@args)) {
387 ($arg1,$arg2,$arg3)=@args;
388 }
389 Function: Checks whether an argument list conforms to our convention
390 for positional arguments. The function returns true if
391 (1) the argument list has an odd number of elements, or
392 (2) the first argument starts with a dash ('-').
393 Obviously, this is not fully general.
394 Returns : boolean
395 Args : argument list
396 Notes : As explained in DESCRIPTION, we recommend that methods not
397 support both positional and keyford argument lists, as this
398 is inherently ambiguous.
399 BUGS : NOT YET TESTED in this version
400 set_class_defaults
402 Title : set_class_defaults
403 Usage : $self->set_class_defaults($attributes,$class,$args);
404 Function: Set default values for class argument
405 Args : reference to the class and a Class::AutoClass::Args object
406 which contains the arguments to set
407 Returns : nothing
408perl v5.12.0 2006-04-06 Class::AutoClass(3)