1Hash::AutoHash::Args(3)User Contributed Perl DocumentatioHnash::AutoHash::Args(3)
2
6 Hash::AutoHash::Args - Object-oriented processing of keyword-based
7 argument lists
8
10 Version 1.18
11
13 use Hash::AutoHash::Args;
14 my $args=new Hash::AutoHash::Args(name=>'Joe',
15 HOBBIES=>'hiking',hobbies=>'cooking');
16 # access argument values as HASH elements
18 my $name=$args->{name};
19 my $hobbies=$args->{hobbies};
20 # access argument values via methods
22 my $name=$args->name;
23 my $hobbies=$args->hobbies;
24 # set local variables from argument values -- two equivalent ways
26 use Hash::AutoHash::Args qw(autoargs_get);
27 my($name,$hobbies)=@$args{qw(name hobbies)};
28 my($name,$hobbies)=autoargs_get($args,qw(name hobbies));
29 # alias $args to regular hash for more concise hash notation
31 use Hash::AutoHash::Args qw(autoargs_alias);
32 autoargs_alias($args,%args);
33 my($name,$hobbies)=@args{qw(name hobbies)}; # get argument values
34 $args{name}='Joseph'; # set argument value
35
37 This class simplifies the handling of keyword argument lists. It
38 replaces Class::AutoClass::Args. See "DIFFERENCES FROM
39 Class::AutoClass::Args" for a discussion of what's new. See
40 Hash::AutoHash::Args::V0 for a subclass which is more compatible with
41 the original.
42 The 'new' method accepts a list, ARRAY, or HASH of keyword=>value
44 pairs, another Hash::AutoHash::Args object, or any object that can be
45 coerced into a HASH . It normalizes the keywords to ignore case and
46 leading dashes ('-'). The following keywords are all equivalent:
47 name, -name, -NAME, --NAME, Name, -Name
49 Arguments can be accessed using HASH or method notation; the following
51 are equivalent (assuming the keyword 'name' exists in $args).
52 my $name=$args->{name};
54 my $name=$args->name;
55 Arguments values can also be changed using either notation:
57 $args->{name}='Jonathan';
59 $args->name('Jonathan');
60 Keywords are normalized automatically; the following are all
62 equivalent.
63 my $name=$args->{name}; # lower case HASH key
65 my $name=$args->{Name}; # capitalized HASH key
66 my $name=$args->{NAME}; # upper case HASH key
67 my $name=$args->{NaMe}; # mixed case HASH key
68 my $name=$args->{-name}; # leading - in HASH key
69 The following are also all equivalent, and are equivalent to the ones
71 above assuming the keyword 'name' exists in $args.
72 my $name=$args->name; # lower case method
74 my $name=$args->Name; # capitalized method
75 my $name=$args->NAME; # upper case method
76 my $name=$args->NaMe; # mixed case method
77 One caution is that when using method notation, keywords must be
79 syntactically legal method names and cannot include leading dashes. The
80 following is NOT legal.
81 my $name=$args->-name; # leading dash in method - ILLEGAL
83 Repeated keyword arguments are converted into an ARRAY of the values.
85 new Hash::AutoHash::Args(hobbies=>'hiking', hobbies=>'cooking')
87 is equivalent to
89 new Hash::AutoHash::Args(hobbies=>['hiking', 'cooking'])
91 Caution: when setting values using HASH or method notation, the
93 grouping of repeated arguments does NOT occur. Thus,
94 @$args{qw(hobbies hobbies)}=qw(running rowing);
96 leaves 'hobbies' set to the last value presented, namely 'rowing', as
98 does
99 $args->hobbies('running');
101 $args->hobbies('rowing');
102 New keywords can be added using either notation. For example,
104 $args->{first_name}='Joe';
106 $args->last_name('Plumber');
107 If a keyword does not exist, the method notation returns nothing, while
109 the HASH notation returns undef. This difference matters in array
110 context (including when passing the result as a parameter).
111 my @list=$args->non_existent; # @list will contain 0 elements
113 my @list=$args->{non_existent}; # @list will contain 1 element
114 We find the method behavior (returning nothing) to be more natural and
116 is the behavior in Class::AutoClass::Args. Unfortunately, Perl does not
117 support this behavior with HASH notation; if the tied hash code returns
118 nothing, Perl converts this into undef before passing the result to the
119 caller. Too bad.
120 You can alias the object to a regular hash for more concise hash
122 notation.
123 use Hash::AutoHash::Args qw(autoargs_alias);
125 autoargs_alias($args,%args);
126 my($name,$hobbies)=@args{qw(name hobbies)};
127 $args{name}='Joseph';
128 By aliasing $args to %args, you avoid the need to dereference the
130 variable when using hash notation. Admittedly, this is a minor
131 convenience, but then again, this entire class is about convenience.
132 new
134 Title : new
135 Usage : $args=new Hash::AutoHash::Args
136 (name=>'Joe',HOBBIES=>'hiking',hobbies=>'cooking')
137 -- OR --
138 $args=new Hash::AutoHash::Args($another_args_object)
139 -- OR --
140 $args=new Hash::AutoHash::Args
141 ([name=>'Joe',HOBBIES=>'hiking',hobbies=>'cooking'])
142 -- OR --
143 $args=new Hash::AutoHash::Args
144 ({name=>'Joe',HOBBIES=>'hiking',hobbies=>'cooking'})
145 Function: Create a normalized argument list
146 Returns : Hash::AutoHash::Args object that represents the given arguments
147 Args : Argument list in keyword=>value form
148 The usual case is a list (as in form 1 above). It can also be
149 another Hash::AutoHash::Args object (as in form 2 above), any object
150 that can be coerced into a HASH (form not illustrated), an ARRAY (form
151 3 above), or HASH (form 4)
152 Caution : In form 4, the order in which the two 'hobbies' arguments are
153 processed is arbitrary. This means that the value of $args->hobbies
154 could have 'hiking' and 'cooking' in either order.
155 Getting and setting argument values
157 One way to get and set argument values is to treat the object as a HASH
158 and access the arguments as hash elements, eg,
159 my $args=new Hash::AutoHash::Args
161 (name=>'Joe',HOBBIES=>'hiking',hobbies=>'cooking');
162 my $name=$args->{name};
163 my($name,$hobbies)=@$args{qw(name hobbies)};
164 $args->{name}='Jonathan';
165 @$args{qw(name hobbies)}=('Joseph',['running','rowing']);
166 The HASH keys are normalized automatically exactly as in 'new'.
168 A second approach is to invoke a method with the name of the keyword.
170 Eg,
171 $args->name;
173 $args->name('Joseph'); # sets name to 'Joseph'
174 $args->hobbies('running','rowing'); # sets hobbies to ['running','rowing']
175 The method name is normalized exactly as in 'new'.
177 New keywords can be added using either notation. For example,
179 $args->{first_name}='Joe';
181 $args->last_name('Plumber');
182 If a keyword does not exist, the method notation returns nothing, while
184 the HASH notation returns undef. This difference matters in array
185 context (including when passing the result as a parameter).
186 my @list=$args->non_existent; # @list will contain 0 elements
188 my @list=$args->{non_existent}; # @list will contain 1 element
189 We find the method behavior (returning nothing) to be more natural and
191 is the behavior in Class::AutoClass::Args. Unfortunately, Perl does not
192 support this behavior with HASH notation.
193 You can alias the object to a regular hash to avoid the need to
195 dereference the variable when using hash notation.
196 use Hash::AutoHash::Args qw(autoargs_alias);
198 autoargs_alias($args,%args);
199 my($name,$hobbies)=@args{qw(name hobbies)};
200 $args{name}='Joseph';
201 Caveats
203 • Illegal method names
205 When using method notation, keywords must be syntactically legal
207 method names and cannot include leading dashes. The following is
208 NOT legal.
209 my $name=$args->-name; # leading dash in method name - ILLEGAL
211 • Setting individual keywords does not preserve multiple values
213 When arguments are set via 'new', 'set_args', 'autoargs_set', or
215 method notation repeated keyword arguments are converted into an
216 ARRAY of the values. When setting individual keywords using either
217 HASH or notation, this does NOT occur. Thus,
218 $args=new Hash::AutoHash::Args(hobbies=>'hiking',hobbies=>'cooking');
220 sets 'hobbies' to an ARRAY of the two hobbies, but
222 @$args{qw(hobbies hobbies)}=qw(running rowing);
224 leaves 'hobbies' set to the last value presented, namely 'rowing'.
226 When arguments are set via any mechanism, the new value or values
228 replace the existing value(s); the new values are NOT added to the
229 existing value(s). Thus
230 $args->hobbies('running');
232 $args->hobbies('rowing');
233 leaves 'hobbies' set to the last value presented, namely 'rowing'.
235 This is a semantic oddity from Class::AutoClass::Args that we have
237 kept for compatibility reasons. It seems not to cause problems in
238 practice, because this class is mostly used in a "write-once"
239 pattern.
240 • Non-existent keywords
242 If a keyword does not exist, the method notation returns nothing,
244 while the HASH notation returns undef. This difference matters in
245 array context (including when passing the result as a parameter).
246 my @list=$args->non_existent; # @list will contain 0 elements
248 my @list=$args->{non_existent}; # @list will contain 1 element
249 We find the method behavior (returning nothing) to be more natural;
251 unfortunately, Perl does not support this behavior with HASH
252 notation.
253 Wholesale manipulation of arguments
255 The class also provides several functions for wholesale manipulation of
256 arguments. To use these functions, you must import them into the
257 caller's namespace using the common Perl idiom of listing the desired
258 functions in a 'use' statement. For example,
259 use Hash::AutoHash::Args
261 qw(get_args getall_args set_args autoargs_get autoargs_set);
262 get_args
264 Title : get_args
266 Usage : ($name,$hobbies)=get_args($args,qw(-name hobbies))
267 Function: Get values for multiple keywords
268 Args : Hash::AutoHash::Args object and array or ARRAY of keywords
269 Returns : array or ARRAY of argument values
270 autoargs_get
272 Title : autoargs_get
274 Usage : ($name,$hobbies)=autoargs_get($args,qw(name -hobbies))
275 Function: Get values for multiple keywords. Synonym for 'get_args' provided
276 for stylistic consistency with Hash::AutoHash
277 Args : Hash::AutoHash::Args object and array or ARRAY of keywords
278 Returns : array or ARRAY of argument values
279 getall_args
281 Title : getall_args
283 Usage : %args=getall_args($args);
284 Function: Get all keyword, value pairs
285 Args : Hash::AutoHash::Args object
286 Returns : hash or HASH of key=>value pairs.
287 set_args
289 Title : set_args
291 Usage : set_args($args,
292 name=>'Joe the Plumber',-first_name=>'Joe',-last_name=>'Plumber')
293 -- OR --
294 set_args($args,['name','-first_name','-last_name'],
295 ['Joe the Plumber','Joe','Plumber'])
296 Function: Set multiple arguments in existing object
297 Args : Form 1. Hash::AutoHash::Args object and parameter list in same format
298 as for 'new'
299 Form 2. Hash::AutoHash::Args object and separate ARRAYs of keywords
300 and values
301 Returns : nothing
302 autoargs_set
304 Title : autoargs_set
306 Usage : autoargs_set($args,
307 name=>'Joe the Plumber',-first_name=>'Joe',-last_name=>'Plumber')
308 -- OR --
309 autoargs_set($args,['name','-first_name','-last_name'],
310 ['Joe the Plumber','Joe','Plumber'])
311 Function: Set multiple arguments in existing object.
312 Synonym for 'set_args' provided for stylistic consistency with
313 Hash::AutoHash
314 Args : Form 1. Hash::AutoHash::Args object and parameter list in same format
315 as for 'new'
316 Form 2. Hash::AutoHash::Args object and separate ARRAYs of keywords
317 and values
318 Returns : Hash::AutoHash::Args object
319 Aliasing object to hash: autoargs_alias
321 You can alias a Hash::AutoHash::Args object to a regular hash to avoid
322 the need to dereference the variable when using hash notation. Before
323 using this function, you must import it into the caller's namespace
324 using the common Perl idiom of listing the function in a 'use'
325 statement.
326 use Hash::AutoHash::Args qw(autoargs_alias);
328 Title : autoargs_alias
330 Usage : autoargs_alias($args,%args)
331 Function: Link $args to %args such that they will have exactly the same value.
332 Args : Hash::AutoHash::Args object and hash
333 Returns : Hash::AutoHash::Args object
334 Functions to normalize keywords
336 These functions normalize keywords as explained in DESCRIPTION. To use
337 these functions, they must be imported into the caller's namespace
338 using the common Perl idiom of listing the desired functions in a 'use'
339 statement.
340 use Hash::AutoHash::Args qw(fix_args fix_keyword fix_keywords);
342 fix_args
344 Title : fix_args
346 Usage : $hash=fix_args(-name=>'Joe',HOBBIES=>'hiking',hobbies=>'cooking')
347 Function: Normalize each keyword to lowercase with no leading dashes and gather
348 the values of repeated keywords into ARRAYs.
349 Args : Argument list in keyword=>value form exactly as for 'new', 'set_args', and
350 'autoargs_set'.
351 Returns : HASH of normalized keyword=>value pairs
352 fix_keyword
354 Title : fix_keyword
356 Usage : $keyword=fix_keyword('-NaMe')
357 -- OR --
358 @keywords=fix_keyword('-NaMe','---hobbies');
359 Function: Normalize each keyword to lowercase with no leading dashes.
360 Args : array of one or more strings
361 Returns : array of normalized strings
362 fix_keywords
364 Title : fix_keywords
366 Usage : $keyword=fix_keywords('-NaMe')
367 -- OR --
368 @keywords=fix_keywords('-NaMe','---hobbies');
369 Function: Synonym for fix_keyword
370 Args : array of one or more strings
371 Returns : array of normalized strings
372 Functions to check format of argument list
374 These functions can be used in a class (typically its 'new' method)
375 that wishes to support both keyword and positional argument lists. We
376 strongly discourage this practice for reasons discussed later.
377 To use these functions, they must be imported into the caller's
379 namespace.
380 use Hash::AutoHash::Args qw(is_keyword is_positional);
382 is_keyword
384 Title : is_keyword
386 Usage : if (is_keyword(@args)) {
387 $args=new Hash::AutoHash::Args (@args);
388 }
389 Function: Checks whether an argument list looks like it is in keyword form.
390 The function returns true if
391 (1) the argument list has an even number of elements, and
392 (2) the first argument starts with a dash ('-').
393 Obviously, this is not fully general.
394 Returns : boolean
395 Args : argument list as given
396 is_positional
398 Title : is_positional
400 Usage : if (is_positional(@args)) {
401 ($arg1,$arg2,$arg3)=@args;
402 }
403 Function: Checks whether an argument list looks like it is in positional form.
404 The function returns true if
405 (1) the argument list has an odd number of elements, or
406 (2) the first argument does not start with a dash ('-').
407 Obviously, this is not fully general.
408 Returns : boolean
409 Args : argument list as given
410 Why the Combination of Positional and Keyword Forms is Ambiguous
412 The keyword => value notation is just a Perl shorthand for stating two
414 list members with the first one quoted. Thus,
415 @list=(first_name=>'John', last_name=>'Doe')
417 is completely equivalent to
419 @list=('first_name', 'John', 'last_name', 'Doe')
421 The ambiguity of allowing both positional and keyword forms should now
423 be apparent. In this example,
424 new Hash::AutoHash::Args ('first_name', 'John')
426 there is s no way to tell whether the program is specifying a keyword
428 argument list with the parameter 'first_name' set to the value "John'
429 or a positional argument list with the values ''first_name' and 'John'
430 being passed to the first two parameters.
431 If a program wishes to permit both forms, we suggest the convention
433 used in BioPerl that keywords be required to start with '-' (and that
434 values do not start with '-'). Obviously, this is not fully general.
435 The methods 'is_keyword' and 'is_positional' check this convention.
437 Functions for hash-like operations
439 These functions provide hash-like operations on Hash::AutoHash::Args
440 objects.
441 To use these functions, you must imported then into the caller's
443 namespace, eg, as follows.
444 use Hash::AutoHash::Args qw(autoargs_clear autoargs_delete autoargs_each autoargs_exists
446 autoargs_keys autoargs_values
447 autoargs_count autoargs_empty autoargs_notempty);
448 autoargs_clear
450 Title : autoargs_clear
452 Usage : autoargs_clear($args)
453 Function: Delete entire contents of $args
454 Args : Hash::AutoHash::Args object
455 Returns : nothing
456 autoargs_delete
458 Title : autoargs_delete
460 Usage : autoargs_delete($args,@keywords)
461 Function: Delete keywords and their values from $args. The keywords are
462 automatically normalized
463 Args : Hash::AutoHash::Args object, list of keywords
464 Returns : nothing
465 autoargs_exists
467 Title : autoargs_exists
469 Usage : if (autoargs_exists($args,$keyword)) { ... }
470 Function: Test whether keyword is present in $args. The keyword is
471 automatically normalized
472 Args : Hash::AutoHash::Args object, keyword
473 Returns : boolean
474 autoargs_each
476 Title : autoargs_each
478 Usage : while (my($keyword,$value)=autoargs_each($args)) { ... }
479 -- OR --
480 while (my $keyword=autoargs_each($args)) { ... }
481 Function: Iterate over all keyword=>value pairs or all keywords present in $args
482 Args : Hash::AutoHash::Args object
483 Returns : list context: next keyword=>value pair in $args or empty list at end
484 scalar context: next keyword in $args or undef at end
485 autoargs_keys
487 Title : autoargs_keys
489 Usage : @keys=autoargs_keys($args)
490 Function: Get all keywords that are present in $args
491 Args : Hash::AutoHash::Args object
492 Returns : list of keywords
493 autoargs_values
495 Title : autoargs_values
497 Usage : @values=autoargs_values($args)
498 Function: Get the values of all keywords that are present in $args
499 Args : Hash::AutoHash::Args object
500 Returns : list of values
501 autoargs_count
503 Title : autoargs_count
505 Usage : $count=autoargs_count($args)
506 Function: Get the number keywords that are present in $args
507 Args : Hash::AutoHash::Args object
508 Returns : number
509 autoargs_empty
511 Title : autoargs_empty
513 Usage : if (autoargs_empty($args) { ... }
514 Function: Test whether $args is empty
515 Args : Hash::AutoHash::Args object
516 Returns : boolean
517 autoargs_notempty
519 Title : autoargs_notempty
521 Usage : if (autoargs_notempty($args) { ... }
522 Function: Test whether $args is not empty. Complement of autoargs_empty
523 Args : Hash::AutoHash::Args object
524 Returns : boolean
525
527 This class differs from its precursor, Class::AutoClass::Args, in the
528 following major ways:
529 • Masked keywords
531 In Class::AutoClass::Args, numerous methods and functions were
533 defined in the Class::AutoClass::Args namespace. These methods and
534 functions "masked" keywords with the same names and made it
535 impossible to use method notation to access arguments with these
536 names. Examples include 'new', 'get_args', 'can', 'isa', 'import',
537 and 'AUTOLOAD' among others.
538 Some of the offending methods and functions were defined explicitly
540 by Class::AutoClass::Args (eg, 'new', 'get_args'), while others were
541 inherited from UNIVERSAL (the base class of everything, e.g, 'can',
542 'isa') or used implicitly by Perl to implement common features (eg,
543 'import', 'AUTOLOAD').
544 Hash::AutoHash::Args has a cleaner namespace: no keywords are masked.
546 CAUTION: As of version 1.13, it is not possible to use method
548 notation for keys with the same names as methods inherited from
549 UNIVERSAL (the base class of everything). These are 'can', 'isa',
550 'DOES', and 'VERSION'. The reason is that as of Perl 5.9.3, calling
551 UNIVERSAL methods as functions is deprecated and developers are
552 encouraged to use method form instead. Previous versions of AutoHash
553 are incompatible with CPAN modules that adopt this style.
554 • Object vs. class methods
556 Some of the methods that remain in the Hash::AutoHash::Args namespace
558 are logically object-methods (ie, logically apply to individual
559 Hash::AutoHash::Args objects, eg, 'AUTOLOAD'), while others are
560 logically class-methods (ie, apply to the entire class, eg,
561 'import').
562 For methods that are logically class methods, the code checks whether
564 the method was invoked on a class or an object and "does the right
565 thing".
566 The 'new' method warrants special mention. In normal use, 'new' is
568 almost always invoked as a class method, eg,
569 new Hash::AutoHash::Args(name=>'Joe')
571 This invokes the 'new' method on Hash::AutoHash::Args which
573 constructs a new object as expected. If, however, 'new' is invoked
574 on an object, eg,
575 $args->new
577 the code accesses the keyword named 'new'.
579 • Methods vs. functions
581 Functions are subs that do not operate on objects or classes.
583 Class::AutoClass::Args provided the following functions in its
584 namespace:
585 _fix_args, fix_keyword, fix_keywords, is_keyword, is_positional
587 With Hash::AutoHash::Args, the caller must import these functions
589 into its own namespace using the common Perl idiom of listing the
590 desired functions when 'using' Hash::AutoHash::Args.
591 • New hash-like functions
593 This class provides additional functions that perform hash-like
595 operations, for example testing whether a keyword exists, getting the
596 values of all keywords, or clearing all arguments. You can import
597 any of these functions into your code.
598 • Bug fix: get_args in scalar context
600 In scalar context, get_args is supposed to return an ARRAY of
602 argument values. Instead, in Class::AutoClass::Args, it returned the
603 value of the first argument.
604 my $values=$args->get_args(qw(name hobbies)); # old bug: gets value of 'name'
606 get_args now returns an ARRAY of the requested argument values.
608 my $values=get_args($args,qw(name hobbies)); # now: gets ARRAY of both values
610 • Tied HASH
612 In Class::AutoClass::Args, the HASH underlying the object was an
614 ordinary Perl HASH. In this class, it's a tied HASH (see perltie,
615 Tie::Hash). The key difference is that keywords are normalized even
616 when HASH notation is used.
617 Thus, in Class::AutoClass::Args, the following two statements had
619 different effects, whereas in this class they are equivalent.
620 $args->{name}='Joe'; # old & new: sets 'name' keyword
622 $args->{NAME}='Joe'; # old: sets 'NAME' HASH element
623 # new: sets 'name' keyword
624 • Implementation using Hash::AutoHash
626 Hash::AutoHash::Args is implemented as a subclass of Hash::AutoHash.
628
630 Hash::AutoHash is the base class of this one. Class::AutoClass::Args
631 is replaced by this class. Hash::AutoHash::Args::V0 is a subclass which
632 is more compatible with Class::AutoClass::Args.
633 Hash::AutoHash::MultiValued, Hash::AutoHash::AVPairsSingle,
635 Hash::AutoHash::AVPairsMulti, Hash::AutoHash::Record are other
636 subclasses of Hash::AutoHash.
637 perltie and Tie::Hash present background on tied hashes.
639
641 Nat Goodman, "<natg at shore.net>"
642
644 Please report any bugs or feature requests to "bug-hash-autohash at
645 rt.cpan.org", or through the web interface at
646 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Hash-AutoHash>. I will
647 be notified, and then you'll automatically be notified of progress on
648 your bug as I make changes.
649 Known Bugs and Caveats
651 CPAN reports that "Make test fails under Perl 5.6.2, FreeBSD 5.2.1."
652 for the predecessor to this class, Class::AutoClass::Args. We are not
653 aware of any bugs in this class.
654 See caveats about accessing arguments via method notation.
656
658 You can find documentation for this module with the perldoc command.
659 perldoc Hash::AutoHash::Args
661 You can also look for information at:
663 • RT: CPAN's request tracker
665 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Hash-AutoHash-Args>
667 • AnnoCPAN: Annotated CPAN documentation
669 <http://annocpan.org/dist/Hash-AutoHash-Args>
671 • CPAN Ratings
673 <http://cpanratings.perl.org/d/Hash-AutoHash-Args>
675 • Search CPAN
677 <http://search.cpan.org/dist/Hash-AutoHash-Args/>
679
681 Copyright (c) 2008, 2009 Institute for Systems Biology (ISB). All
682 Rights Reserved.
683 This program is free software; you can redistribute it and/or modify it
685 under the terms of either: the GNU General Public License as published
686 by the Free Software Foundation; or the Artistic License.
687 See http://dev.perl.org/licenses/ for more information.
689perl v5.34.0 2021-07-22 Hash::AutoHash::Args(3)