new

 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.

Getting and setting argument values

One way to get and set argument values is to treat the object as a HASH and access the arguments as hash elements, eg,

  my $args=new Hash::AutoHash::Args
                (name=>'Joe',HOBBIES=>'hiking',hobbies=>'cooking');
  my $name=$args->{name};
  my($name,$hobbies)=@$args{qw(name hobbies)};
  $args->{name}='Jonathan';
  @$args{qw(name hobbies)}=('Joseph',['running','rowing']);

The HASH keys are normalized automatically exactly as in 'new'.

A second approach is to invoke a method with the name of the keyword. Eg,

  $args->name;
  $args->name('Joseph');                # sets name to 'Joseph'
  $args->hobbies('running','rowing');   # sets hobbies to ['running','rowing']

The method name is normalized exactly as in 'new'.

New keywords can be added using either notation. For example,

  $args->{first_name}='Joe';
  $args->last_name('Plumber');

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).

  my @list=$args->non_existent;   # @list will contain 0 elements
  my @list=$args->{non_existent}; # @list will contain 1 element

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.

You can alias the object to a regular hash to avoid the need to dereference the variable when using hash notation.

  use Hash::AutoHash::Args qw(autoargs_alias);
  autoargs_alias($args,%args);
  my($name,$hobbies)=@args{qw(name hobbies)};
  $args{name}='Joseph';

Caveats

• Illegal method names

  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).

    my @list=$args->non_existent;   # @list will contain 0 elements
    my @list=$args->{non_existent}; # @list will contain 1 element
      

  We find the method behavior (returning nothing) to be more natural; unfortunately, Perl does not support this behavior with HASH notation.

Wholesale manipulation of arguments

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,

 use Hash::AutoHash::Args
    qw(get_args getall_args set_args autoargs_get autoargs_set);

get_args

 Title   : get_args
 Usage   : ($name,$hobbies)=get_args($args,qw(-name hobbies))
 Function: Get values for multiple keywords
 Args    : Hash::AutoHash::Args object and array or ARRAY of keywords
 Returns : array or ARRAY of argument values

autoargs_get

 Title   : autoargs_get
 Usage   : ($name,$hobbies)=autoargs_get($args,qw(name -hobbies))
 Function: Get values for multiple keywords. Synonym for 'get_args' provided 
           for stylistic consistency with Hash::AutoHash
 Args    : Hash::AutoHash::Args object and array or ARRAY of keywords
 Returns : array or ARRAY of argument values

getall_args

 Title   : getall_args
 Usage   : %args=getall_args($args);
 Function: Get all keyword, value pairs
 Args    : Hash::AutoHash::Args object
 Returns : hash or HASH of key=>value pairs.

set_args

 Title   : set_args
 Usage   : set_args($args,
                    name=>'Joe the Plumber',-first_name=>'Joe',-last_name=>'Plumber')
           -- OR -- 
           set_args($args,['name','-first_name','-last_name'],
                          ['Joe the Plumber','Joe','Plumber'])
 Function: Set multiple arguments in existing object
 Args    : Form 1. Hash::AutoHash::Args object and parameter list in same format  
           as for 'new'
           Form 2. Hash::AutoHash::Args object and separate ARRAYs of keywords 
           and values
 Returns : nothing

autoargs_set

 Title   : autoargs_set
 Usage   : autoargs_set($args,
                        name=>'Joe the Plumber',-first_name=>'Joe',-last_name=>'Plumber')
           -- OR -- 
           autoargs_set($args,['name','-first_name','-last_name'],
                              ['Joe the Plumber','Joe','Plumber'])
 Function: Set multiple arguments in existing object. 
           Synonym for 'set_args' provided for stylistic consistency with 
           Hash::AutoHash
 Args    : Form 1. Hash::AutoHash::Args object and parameter list in same format  
           as for 'new'
           Form 2. Hash::AutoHash::Args object and separate ARRAYs of keywords 
           and values
 Returns : Hash::AutoHash::Args object

Aliasing object to hash: autoargs_alias

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

Functions to normalize keywords

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.

 use Hash::AutoHash::Args qw(fix_args fix_keyword fix_keywords);

fix_args

 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

fix_keyword

 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

fix_keywords

 Title   : fix_keywords
 Usage   : $keyword=fix_keywords('-NaMe')
           -- OR --
           @keywords=fix_keywords('-NaMe','---hobbies');
 Function: Synonym for fix_keyword
 Args    : array of one or more strings
 Returns : array of normalized strings

Functions to check format of argument list

These functions can be used in a class (typically its 'new' method) that wishes to support both keyword and positional argument lists. We strongly discourage this practice for reasons discussed later.

To use these functions, they must be imported into the caller's namespace.

 use Hash::AutoHash::Args qw(is_keyword is_positional);

is_keyword

 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

is_positional

 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

Why the Combination of Positional and Keyword Forms is Ambiguous

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.

The methods 'is_keyword' and 'is_positional' check this convention.

Functions for hash-like operations

These functions provide hash-like operations on Hash::AutoHash::Args objects.

To use these functions, you must imported then into the caller's namespace, eg, as follows.

 use Hash::AutoHash::Args qw(autoargs_clear autoargs_delete autoargs_each autoargs_exists 
                               autoargs_keys autoargs_values 
                               autoargs_count autoargs_empty autoargs_notempty);

autoargs_clear

 Title   : autoargs_clear
 Usage   : autoargs_clear($args)
 Function: Delete entire contents of $args
 Args    : Hash::AutoHash::Args object
 Returns : nothing

autoargs_delete

 Title   : autoargs_delete
 Usage   : autoargs_delete($args,@keywords)
 Function: Delete keywords and their values from $args. The keywords are
           automatically normalized
 Args    : Hash::AutoHash::Args object, list of keywords
 Returns : nothing

autoargs_exists

 Title   : autoargs_exists
 Usage   : if (autoargs_exists($args,$keyword)) { ... }
 Function: Test whether keyword is present in $args.  The keyword is
           automatically normalized
 Args    : Hash::AutoHash::Args object, keyword
 Returns : boolean

autoargs_each

 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

autoargs_keys

 Title   : autoargs_keys
 Usage   : @keys=autoargs_keys($args)
 Function: Get all keywords that are present in $args
 Args    : Hash::AutoHash::Args object
 Returns : list of keywords

autoargs_values

 Title   : autoargs_values
 Usage   : @values=autoargs_values($args)
 Function: Get the values of all keywords that are present in $args
 Args    : Hash::AutoHash::Args object
 Returns : list of values

autoargs_count

 Title   : autoargs_count
 Usage   : $count=autoargs_count($args)
 Function: Get the number keywords that are present in $args
 Args    : Hash::AutoHash::Args object
 Returns : number

autoargs_empty

 Title   : autoargs_empty
 Usage   : if (autoargs_empty($args) { ... }
 Function: Test whether $args is empty
 Args    : Hash::AutoHash::Args object
 Returns : boolean

autoargs_notempty

 Title   : autoargs_notempty
 Usage   : if (autoargs_notempty($args) { ... }
 Function: Test whether $args is not empty. Complement of autoargs_empty
 Args    : Hash::AutoHash::Args object
 Returns : boolean

Known Bugs and Caveats

CPAN reports that "Make test fails under Perl 5.6.2, FreeBSD 5.2.1." for the predecessor to this class, Class::AutoClass::Args. We are not aware of any bugs in this class.

See caveats about accessing arguments via method notation.