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
67 that each method pick one form or the other, as the combination is
68 inherently ambiguous (see below).
69 Consider a method, foo, that takes two arguments, a first name and a
71 last_name name. The positional form might be
72 $object->foo('Nat', 'Goodman')
74 while the keyword form might be
76 $object->foo(first_name=>'Nat', last_name=>'Goodman')
78 In keyword form, keywords are insensitive to case and leading dashes:
80 the keywords
81 first_name, -first_name, -FIRST_NAME, --FIRST_NAME, First_Name, -First_Name
83 are all equivalent. Internally, for those who care, our convention is
85 to use uppercase, un-dashed keys for the attributes of an object.
86 We convert repeated keyword arguments into an ARRAY ref of the values.
88 Thus:
89 $object->foo(first_name=>'Nat', first_name=>'Nathan')
91 is equivalent to
93 $object->foo(first_name=>['Nat', 'Nathan'])
95 Keyword arguments can be specified via ARRAY or HASH refs which are
97 dereferenced back to their elements, e.g.,
98 $object->foo([first_name=>'Nat', last_name=>'Goodman'])
100 $object->foo({first_name=>'Nat', last_name=>'Goodman'})
102 are both equivalent to
104 $object->foo(first_name=>'Nat', last_name=>'Goodman')
106 We can get away with this, because we encourage method writers to
108 choose between positional and keyword argument lists. If a method uses
109 positional arguments, it will interpret
110 $object->foo($array)
112 as a call that is setting the first_name parameter to $array, while if
114 it uses keyword arguments, it will dereference the array to a list of
115 keyword, value pairs.
116 We also allow the argument list to be an object. This is often used in
118 new to accomplish what a C++ programmer would call a cast. In simple
119 cases, the object is just treated as a HASH ref and its attributes are
120 passed to a the method as keyword, value pairs.
121 Why the Combination of Positional and Keyword Forms is Ambiguous
123 The keyword => value notation is just a Perl shorthand for stating two
125 list members with the first one quoted. Thus,
126 $object->foo(first_name=>'Nat', last_name=>'Goodman')
128 is completely equivalent to
130 $object->foo('first_name', 'Nat', 'last_name', 'Goodman')
132 The ambiguity of allowing both positional and keyword forms should now
134 be apparent. In this example,
135 $object->foo('first_name', 'Nat')
137 there is s no way to tell whether the program is calling foo with the
139 first_name parameter set to the value 'first_name' and the last_name
140 parameter set to 'Nat', vs. calling foo with the first_name parameter
141 set to 'Nat' and the last_name parameter left undefined.
142 If a program wishes to permit both forms, we suggest that keywords be
144 required to start with '-' (and that values do not start with '-').
145 Obviously, this is not fully general. We provide a method, _is_posi‐
146 tional, that checks this convention. Subclasses are free to ignore
147 this.
148 Protocol for Object Creation and Initializaton
150 We expect objects to be created by invoking new on its class. For
152 example
153 $object = new SomeClass(first=>'Nat', last=>'Goodman')
155 To correctly initialize objects that participate in multiple inheri‐
157 tance, we use a technqiue described in Chapter 10 of Paul Fenwick's
158 excellent
159 tutorial on Object Oriented Perl (see http://perltrain‐
160 ing.com.au/notes/perloo.pdf). (We experimented with Damian Conway's
161 interesting NEXT pseudo-pseudo-class discussed in Chapter 11 of Fen‐
162 wick's tutorial
163 available in CPAN at http://search.cpan.org/author/DCON‐
164 WAY/NEXT-0.50/lib/NEXT.pm,
165 but could not get it to traverse the inheritance structure in the cor‐
166 rect,
167 top-down order.)
168 AutoClass class provides a 'new' method that expects a keyword argument
170 list. This method processes the argument list as discussed in
171 L<Argument Processing>: it figures out the syntactic form (list of
172 keyword, value pairs, vs. ARRAY ref vs. HASH ref, etc.). It then
173 converts the argument list into a canonical form, which is a list of
174 keyword, value pairs with all keywords uppercased and de-dashed. Once
175 the argument list is in this form, subsequent code treats it as a HASH
176 ref.
177 AutoClass::new initializes the object's class structure from top to
179 bottom, and is careful to initialize each class exactly once even in
180 the presence of multiple inheritance. The net effect is that objects
181 are initialized top-down as expected; a subclass object can assume that
182 all superior classes are initialized by the time subclass initializa‐
183 tion occurs.
184 AutoClass automatically initializes attributes and synonyms declared
186 when the class is defined. If additional initialization is required,
187 the class writer can provide an _init_self method. _init_self is
188 called after all superclasses are initialized and after the automatic
189 initialization for the class has been done.
190 AutoClass initializes attributes and synonyms by calling the set meth‐
192 ods for these elements with the like-named parameter -- it does not
193 simply slam the parameter into a slot in the object''s HASH. This
194 allows the class writer implement non-standard initialization within
195 the set method.
196 The main case where a subclass needs its own 'new' method is if it
198 wishes to allow positional arguments. In this case, the subclass 'new'
199 is responsible for is responsible for recognizing that positional argu‐
200 ments are being used (if the class permits keyword arguments also), and
201 converting the positional arguments into keyword, value form. At this
202 point, the method can simply call AutoClass::new with the converted
203 argument list.
204 The subclass should not generally call SUPER::new as this would force
206 redundant argument processing in any super-class that also has its own
207 new. It would also force the super-class new to be smart enough to
208 handle positional as well as keyword parameters, which as we've noted
209 is inherently ambiguous.
210 =head1 KNOWN BUGS AND CAVEATS
212 This is still a work in progress.
214 =head2 Bugs, Caveats, and ToDos
216 1) There is no way to manipulate the arguments that are sent to the
218 real base class. There should be a way to specify a subroutine that
219 reformats these if needed.
220 2) DESTROY not handled
222 3) Autogeneration of methods is hand crafted. It may be better to
224 use Class::MakeMethods or Damian Conway's Multimethod class for
225 doing signature-based method dispatch
226 4) Caveat: In order to specify that a class that uses AutoClass should return
228 undef (versus an uninitialized (but blessed) object), one need to set:
229 $self->{__NULLIFY__}=1;
230
232 Email natg@shore.net
233
235 Email ccavnor@systemsbiology.net
236
238 Copyright (c) 2003 Institute for Systems Biology (ISB). All Rights
239 Reserved.
240 This module is free software; you can redistribute it and/or modify it
242 under the same terms as Perl itself.
243
245 The rest of the documentation describes the methods. Note that inter‐
246 nal methods are preceded with _
247 new
249 Title : new
251 Usage : $object=new Foo(first_name=>'Nat', last_name=>'Goodman')
252 where Foo is a subclass of AutoClass
253 Function: Create and initialize object
254 Returns : New object of class $class
255 Args : Any arguments needed by subclasses
256 -->> Arguments must be in keyword form. See DESCRIPTION for more.
257 Notes : Tries to invoke superclass to actually create the object
258 _init
260 Title : _init
262 Usage : $self->_init($class,$args)
263 Function: Initialize new object
264 Returns : nothing useful
265 Args : $class -- lexical (static) class being initialized, not the
266 actual (dynamic) class of $self
267 $arg -- argument list in canonical keyword form
268 Notes : Adapted from Chapter 10 of Paul Fenwick''s excellent tutorial on
269 Object Oriented Perl (see http://perltraining.com.au/notes/perloo.pdf).
270 set
272 Title : set
274 Usage : $self->set(-first_name=>'Nat',-last_name=>'Goodman')
275 Function: Set multiple attributes in existing object
276 Args : Parameter list in same format as for new
277 Returns : nothing
278 set_attributes
280 Title : set_attributes
282 Usage : $self->set_attributes([qw(first_name last_name)],$args)
283 Function: Set multiple attributes from a Class::AutoClass::Args object
284 Any attribute value that is present in $args is set
285 Args : ARRAY ref of attributes
286 Class::AutoClass::Args object
287 Returns : nothing
288 get
290 Title : get
292 Usage : ($first,$last)=$self->get(qw(-first_name,-last_name))
293 Function: Get values for multiple attributes
294 Args : Attribute names
295 Returns : List of attribute values
296 AUTO_ATTRIBUTES
298 Title : AUTO_ATTRIBUTES
300 Usage : @auto_attributes=AUTO_ATTRIBUTES('SubClass')
301 @auto_attributes=$self->AUTO_ATTRIBUTES();
302 Function: Get @AUTO_ATTRIBUTES for lexical class.
303 @AUTO_ATTRIBUTES is defined by class writer. These are attributes for which get and set methods
304 are automatically generated. _init automatically
305 initializes these attributes from like-named parameters in
306 the argument list
307 Args : class
308 OTHER_ATTRIBUTES
310 Title : OTHER_ATTRIBUTES
312 Usage : @other_attributes=OTHER_ATTRIBUTES('SubClass')
313 @other_attributes=$self->OTHER_ATTRIBUTES();
314 Function: Get @OTHER_ATTRIBUTES for lexical class.
315 @OTHER_ATTRIBUTES is defined by class writer. These are attributes for which get and set methods
316 are not automatically generated. _init automatically
317 initializes these attributes from like-named parameters in
318 the argument list
319 Args : class
320 SYNONYMS
322 Title : SYNONYMS
324 Usage : %synonyms=SYNONYMS('SubClass')
325 %synonyms=$self->SYNONYMS();
326 Function: Get %SYNONYMS for lexical class.
327 %SYNONYMS is defined by class writer. These are alternate names for attributes generally
328 defined in superclasses. get and set methods are
329 automatically generated. _init automatically initializes
330 these attributes from like-named parameters in the argument
331 list
332 Args : class
333 declare
335 Title : declare
337 Usage : @AUTO_ATTRIBUTES=qw(sex address dob);
338 @OTHER_ATTRIBUTES=qw(age);
339 %SYNONYMS=(name=>'id');
340 AutoClass::declare(__PACKAGE__,'lower⎪upper');
341 Function: Generate get and set methods for simple attributes and synonyms.
342 Method names are identical to the attribute names including case
343 Returns : nothing
344 Args : lexical class being created -- should always be __PACKAGE__
345 ARRAY ref of attributes
346 HASH ref of synonyms. Keys are new names, values are old
347 code that indicates whether method should also be generated
348 with all lower or upper case names
349 _enumerate
351 Title : _enumerate
353 Usage : _enumerate($class);
354 Function: locates classes that have a callable constructor
355 Args : a class reference
356 Returns : list of internal classes, a class with a callable constructor
357 _fix_args
359 Title : _fix_args
361 Usage : $args=_fix_args(-name=>'Nat',-name=>Goodman,address=>'Seattle')
362 $args=$self->_fix_args(@args)
363 Function: Convert argument list into canonical form. This is a HASH ref in
365 which keys are uppercase with no leading dash, and repeated
366 keyword arguments are merged into an ARRAY ref. In the
367 example above, the argument list would be converted to this
368 hash
369 (NAME=>['Nat', 'Goodman'],ADDRESS=>'Seattle')
370 Returns : argument list in canonical form
371 Args : argument list in any keyword form
372 _fix_keyword
374 Title : _fix_keyword
376 Usage : $keyword=_fix_keyword('-name')
377 @keywords=_fix_keyword('-name','-address');
378 Function: Convert a keyword or list of keywords into canonical form. This
379 is uppercase with no leading dash. In the example above,
380 '-name' would be converted to 'NAME'. Non-scalars are left
381 unchanged.
382 Returns : keyword or list of keywords in canonical form
383 Args : keyword or list of keywords
384 _set_attributes
386 Title : _set_attributes
388 Usage : my %synonyms=SYNONYMS($class);
389 my $attributes=[AUTO_ATTRIBUTES($class),
390 OTHER_ATTRIBUTES($class),
391 keys %synonyms];
392 $self->_set_attributes($attributes,$args);
393 Function: Set a list of simple attributes from a canonical argument list
394 Returns : nothing
395 Args : $attributes -- ARRAY ref of attributes to be set
396 $args -- argument list in canonical keyword (hash) form
397 Notes : The function calls the set method for each attribute passing
398 it the like-named parameter from the argument list
399 _is_positional
401 Title : _is_positional
403 Usage : if (_is_positional(@args)) {
404 ($arg1,$arg2,$arg3)=@args;
405 }
406 Function: Checks whether an argument list conforms to our convention
407 for positional arguments. The function returns true if
408 (1) the argument list has an odd number of elements, or
409 (2) the first argument starts with a dash ('-').
410 Obviously, this is not fully general.
411 Returns : boolean
412 Args : argument list
413 Notes : As explained in DESCRIPTION, we recommend that methods not
414 support both positional and keyford argument lists, as this
415 is inherently ambiguous.
416 BUGS : NOT YET TESTED in this version
417 set_class_defaults
419 Title : set_class_defaults
421 Usage : $self->set_class_defaults($attributes,$class,$args);
422 Function: Set default values for class argument
423 Args : reference to the class and a Class::AutoClass::Args object
424 which contains the arguments to set
425 Returns : nothing
426perl v5.8.8 2006-04-06 Class::AutoClass(3)