The 'new' method accepts a list, ARRAY, or HASH of keyword=>value pairs, another Hash::AutoHash::Args object, or any object that can be coerced into a HASH . It normalizes the keywords to ignore case and leading dashes ('-'). The following keywords are all equivalent:

name, -name, -NAME, --NAME, Name, -Name

Arguments can be accessed using HASH or method notation; the following are equivalent (assuming the keyword 'name' exists in $args).

my $name=$args->{name};
my $name=$args->name;

Arguments values can also be changed using either notation:

$args->{name}='Jonathan';
$args->name('Jonathan');

Keywords are normalized automatically; the following are all equivalent.

We find the method behavior (returning nothing) to be more natural and is the behavior in Class::AutoClass::Args. Unfortunately, Perl does not support this behavior with HASH notation; if the tied hash code returns nothing, Perl converts this into undef before passing the result to the caller. Too bad.

You can alias the object to a regular hash for more concise hash notation.

Title : new
Usage : $args=new Hash::AutoHash::Args
(name=>'Joe',HOBBIES=>'hiking',hobbies=>'cooking')
-- OR --
$args=new Hash::AutoHash::Args($another_args_object)
-- OR --
$args=new Hash::AutoHash::Args
([name=>'Joe',HOBBIES=>'hiking',hobbies=>'cooking'])
-- OR --
$args=new Hash::AutoHash::Args
({name=>'Joe',HOBBIES=>'hiking',hobbies=>'cooking'})
Function: Create a normalized argument list
Returns : Hash::AutoHash::Args object that represents the given arguments
Args : Argument list in keyword=>value form
The usual case is a list (as in form 1 above). It can also be
another Hash::AutoHash::Args object (as in form 2 above), any object
that can be coerced into a HASH (form not illustrated), an ARRAY (form
3 above), or HASH (form 4)
Caution : In form 4, the order in which the two 'hobbies' arguments are
processed is arbitrary. This means that the value of $args->hobbies
could have 'hiking' and 'cooking' in either order.

When using method notation, keywords must be syntactically legal method names and cannot include leading dashes. The following is NOT legal.

my $name=$args->-name; # leading dash in method name - ILLEGAL

Setting individual keywords does not preserve multiple values

When arguments are set via 'new', 'set_args', 'autoargs_set', or method notation repeated keyword arguments are converted into an ARRAY of the values. When setting individual keywords using either HASH or notation, this does NOT occur. Thus,

$args=new Hash::AutoHash::Args(hobbies=>'hiking',hobbies=>'cooking');

sets 'hobbies' to an ARRAY of the two hobbies, but

@$args{qw(hobbies hobbies)}=qw(running rowing);

leaves 'hobbies' set to the last value presented, namely 'rowing'.

When arguments are set via any mechanism, the new value or values replace the existing value(s); the new values are NOT added to the existing value(s). Thus

$args->hobbies('running');
$args->hobbies('rowing');

leaves 'hobbies' set to the last value presented, namely 'rowing'.

This is a semantic oddity from Class::AutoClass::Args that we have kept for compatibility reasons. It seems not to cause problems in practice, because this class is mostly used in a "write-once" pattern.

Non-existent keywords

If a keyword does not exist, the method notation returns nothing, while the HASH notation returns undef. This difference matters in array context (including when passing the result as a parameter).

The class also provides several functions for wholesale manipulation of arguments. To use these functions, you must import them into the caller's namespace using the common Perl idiom of listing the desired functions in a 'use' statement. For example,

You can alias a Hash::AutoHash::Args object to a regular hash to avoid the need to dereference the variable when using hash notation. Before using this function, you must import it into the caller's namespace using the common Perl idiom of listing the function in a 'use' statement.

use Hash::AutoHash::Args qw(autoargs_alias);
Title : autoargs_alias
Usage : autoargs_alias($args,%args)
Function: Link $args to %args such that they will have exactly the same value.
Args : Hash::AutoHash::Args object and hash
Returns : Hash::AutoHash::Args object

These functions normalize keywords as explained in DESCRIPTION. To use these functions, they must be imported into the caller's namespace using the common Perl idiom of listing the desired functions in a 'use' statement.

Title : fix_args
Usage : $hash=fix_args(-name=>'Joe',HOBBIES=>'hiking',hobbies=>'cooking')
Function: Normalize each keyword to lowercase with no leading dashes and gather
the values of repeated keywords into ARRAYs.
Args : Argument list in keyword=>value form exactly as for 'new', 'set_args', and
'autoargs_set'.
Returns : HASH of normalized keyword=>value pairs

Title : fix_keyword
Usage : $keyword=fix_keyword('-NaMe')
-- OR --
@keywords=fix_keyword('-NaMe','---hobbies');
Function: Normalize each keyword to lowercase with no leading dashes.
Args : array of one or more strings
Returns : array of normalized strings

Title : is_keyword
Usage : if (is_keyword(@args)) {
$args=new Hash::AutoHash::Args (@args);
}
Function: Checks whether an argument list looks like it is in keyword form.
The function returns true if
(1) the argument list has an even number of elements, and
(2) the first argument starts with a dash ('-').
Obviously, this is not fully general.
Returns : boolean
Args : argument list as given

Title : is_positional
Usage : if (is_positional(@args)) {
($arg1,$arg2,$arg3)=@args;
}
Function: Checks whether an argument list looks like it is in positional form.
The function returns true if
(1) the argument list has an odd number of elements, or
(2) the first argument does not start with a dash ('-').
Obviously, this is not fully general.
Returns : boolean
Args : argument list as given

The keyword => value notation is just a Perl shorthand for stating two list members with the first one quoted. Thus,

@list=(first_name=>'John', last_name=>'Doe')

is completely equivalent to

@list=('first_name', 'John', 'last_name', 'Doe')

The ambiguity of allowing both positional and keyword forms should now be apparent. In this example,

new Hash::AutoHash::Args ('first_name', 'John')

there is s no way to tell whether the program is specifying a keyword argument list with the parameter 'first_name' set to the value "John' or a positional argument list with the values ''first_name' and 'John' being passed to the first two parameters.

If a program wishes to permit both forms, we suggest the convention used in BioPerl that keywords be required to start with '-' (and that values do not start with '-'). Obviously, this is not fully general.

Title : autoargs_each
Usage : while (my($keyword,$value)=autoargs_each($args)) { ... }
-- OR --
while (my $keyword=autoargs_each($args)) { ... }
Function: Iterate over all keyword=>value pairs or all keywords present in $args
Args : Hash::AutoHash::Args object
Returns : list context: next keyword=>value pair in $args or empty list at end
scalar context: next keyword in $args or undef at end

In Class::AutoClass::Args, numerous methods and functions were defined in the Class::AutoClass::Args namespace. These methods and functions "masked" keywords with the same names and made it impossible to use method notation to access arguments with these names. Examples include 'new', 'get_args', 'can', 'isa', 'import', and 'AUTOLOAD' among others.

Some of the offending methods and functions were defined explicitly by Class::AutoClass::Args (eg, 'new', 'get_args'), while others were inherited from UNIVERSAL (the base class of everything, e.g, 'can', 'isa') or used implicitly by Perl to implement common features (eg, 'import', 'AUTOLOAD').

Hash::AutoHash::Args has a cleaner namespace: no keywords are masked.

CAUTION: As of version 1.13, it is not possible to use method notation for keys with the same names as methods inherited from UNIVERSAL (the base class of everything). These are 'can', 'isa', 'DOES', and 'VERSION'. The reason is that as of Perl 5.9.3, calling UNIVERSAL methods as functions is deprecated and developers are encouraged to use method form instead. Previous versions of AutoHash are incompatible with CPAN modules that adopt this style.

Object vs. class methods

Some of the methods that remain in the Hash::AutoHash::Args namespace are logically object-methods (ie, logically apply to individual Hash::AutoHash::Args objects, eg, 'AUTOLOAD'), while others are logically class-methods (ie, apply to the entire class, eg, 'import').

For methods that are logically class methods, the code checks whether the method was invoked on a class or an object and "does the right thing".

The 'new' method warrants special mention. In normal use, 'new' is almost always invoked as a class method, eg,

new Hash::AutoHash::Args(name=>'Joe')

This invokes the 'new' method on Hash::AutoHash::Args which constructs a new object as expected. If, however, 'new' is invoked on an object, eg,

$args->new

the code accesses the keyword named 'new'.

Methods vs. functions

Functions are subs that do not operate on objects or classes. Class::AutoClass::Args provided the following functions in its namespace:

_fix_args, fix_keyword, fix_keywords, is_keyword, is_positional

With Hash::AutoHash::Args, the caller must import these functions into its own namespace using the common Perl idiom of listing the desired functions when 'using' Hash::AutoHash::Args.

New hash-like functions

This class provides additional functions that perform hash-like operations, for example testing whether a keyword exists, getting the values of all keywords, or clearing all arguments. You can import any of these functions into your code.

Bug fix: get_args in scalar context

In scalar context, get_args is supposed to return an ARRAY of argument values. Instead, in Class::AutoClass::Args, it returned the value of the first argument.

In Class::AutoClass::Args, the HASH underlying the object was an ordinary Perl HASH. In this class, it's a tied HASH (see perltie, Tie::Hash). The key difference is that keywords are normalized even when HASH notation is used.

Thus, in Class::AutoClass::Args, the following two statements had different effects, whereas in this class they are equivalent.