Hash::...::Args(3pm)

📦

version 1.18 · 2 versions

1.18 · fedora 43 (latest)
1.18 · fedora 44

NAME 💖

Hash::AutoHash::Args — object-oriented processing of keyword-based argument lists. also this is the page for Hash::...::Args(3pm) bestie, so welcome to the group chat 💅

VERSION ✨

Version 1.18 — yes queen, that's the version.

SYNOPSIS 🦋

use Hash::AutoHash::Args;
my $args=new Hash::AutoHash::Args(name=>'Joe',
                                  HOBBIES=>'hiking',hobbies=>'cooking');

# access argument values as HASH elements
my $name=$args->{name};
my $hobbies=$args->{hobbies};

# access argument values via methods
my $name=$args->name;
my $hobbies=$args->hobbies;

# set local variables from argument values -- two equivalent ways
use Hash::AutoHash::Args qw(autoargs_get);
my($name,$hobbies)=@$args{qw(name hobbies)};
my($name,$hobbies)=autoargs_get($args,qw(name hobbies));

# alias $args to regular hash for more concise hash notation
use Hash::AutoHash::Args qw(autoargs_alias);
autoargs_alias($args,%args);
my($name,$hobbies)=@args{qw(name hobbies)}; # get argument values
$args{name}='Joseph';                       # set argument value

DESCRIPTION 🌸

okay so this class is literally here to make keyword argument lists less of a headache. it replaces Class::AutoClass::Args. if you wanna know what's new, go read "DIFFERENCES FROM Class::AutoClass::Args". and if you want a subclass that's more compatible with the original, go look at Hash::AutoHash::Args::V0 👑

the new method takes a list, an ARRAY, or a HASH of keyword=>value pairs, another Hash::AutoHash::Args object, or literally any object that can be coerced into a HASH. it normalizes the keywords so case and leading dashes ('-') get ignored. these keywords are all the same:

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

you can access arguments with HASH notation or method notation; these are equivalent (assuming the keyword 'name' exists in $args):

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

you can also change argument values with either notation:

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

keywords get normalized automatically, so these are all equivalent:

my $name=$args->{name};               # lower case HASH key
my $name=$args->{Name};               # capitalized HASH key
my $name=$args->{NAME};               # upper case HASH key
my $name=$args->{NaMe};               # mixed case HASH key
my $name=$args->{-name};              # leading - in HASH key

and these are also all equivalent, and equivalent to the ones above assuming 'name' exists in $args:

my $name=$args->name;                 # lower case method
my $name=$args->Name;                 # capitalized method
my $name=$args->NAME;                 # upper case method
my $name=$args->NaMe;                 # mixed case method

one caution bestie: when you use method notation, keywords have to be syntactically legal method names and cannot have leading dashes. this is NOT legal:

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

repeated keyword arguments get converted into an ARRAY of the values.

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

is equivalent to

new Hash::AutoHash::Args(hobbies=>['hiking', 'cooking'])

caution: when you set values using HASH or method notation, the grouping of repeated arguments does NOT happen. so,

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

leaves 'hobbies' set to the last value presented, namely 'rowing', and so does

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

new keywords can be added with either notation. for example,

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

if a keyword doesn't exist, method notation returns nothing, while HASH notation returns undef. this difference matters in array context (including when you pass 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 think the method behavior (returning nothing) is more natural and it's 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.

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

by aliasing $args to %args, you avoid needing to dereference the variable when using hash notation. admittedly, this is a minor convenience, but then again, this entire class is about convenience. periodt 💅

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

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

💖 `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`

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

ok bestie note the glow-up here: set_args hands you back nothing, but autoargs_set hands you back the object 🫶 they're the same vibe, just one gives you something to hold onto.

🦋 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 you're using hash notation. Before you use this function, you must import it into the caller's namespace using the common Perl idiom of listing the function in a 'use' statement. iykyk 💅

use Hash::AutoHash::Args qw(autoargs_alias);

🎀 `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`

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`

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`

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`

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

the argument list has an even number of elements, and
the first argument starts with a dash ('-').

Obviously, this is not fully general.

Returns: boolean

Args: argument list as given

🌈 `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

the argument list has an odd number of elements, or
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. So like,

@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 super apparent. Look at this:

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

there'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. 😭 literally the same bytes, two totally different meanings.

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`

Usage: autoargs_clear($args)

Function: Delete entire contents of $args

Args: Hash::AutoHash::Args object

Returns: nothing

💀 `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`

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`

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`

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`

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`

Usage: $count=autoargs_count($args)

Function: Get the number keywords that are present in $args

Args: Hash::AutoHash::Args object

Returns: number

🧚 `autoargs_empty`

Usage: if (autoargs_empty($args) { ... }

Function: Test whether $args is empty

Args: Hash::AutoHash::Args object

Returns: boolean

🌈 `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

💫 DIFFERENCES FROM Class::AutoClass::Args 💫

okay so this class is basically the glow-up of its precursor, Class::AutoClass::Args, and the major ways they differ are... a lot. let's go:

Masked keywords 🎭

In Class::AutoClass::Args, SO many methods and functions were defined in the Class::AutoClass::Args namespace. and those methods and functions "masked" keywords with the same names, which made it literally 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. not the vibe!!

my $values=$args->get_args(qw(name hobbies)); # old bug: gets value of 'name'

get_args now returns an ARRAY of the requested argument values. slay 💅

my $values=get_args($args,qw(name hobbies));  # now: gets ARRAY of both values

Tied HASH 🎀

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.

$args->{name}='Joe';          # old & new: sets 'name' keyword
$args->{NAME}='Joe';          # old: sets 'NAME' HASH element
                              # new: sets 'name' keyword

Implementation using Hash::AutoHash 🦋

Hash::AutoHash::Args is implemented as a subclass of Hash::AutoHash.

🌈 SEE ALSO 🌈

Hash::AutoHash is the base class of this one. Class::AutoClass::Args is replaced by this class. Hash::AutoHash::Args::V0 is a subclass which is more compatible with Class::AutoClass::Args.

Hash::AutoHash::MultiValued, Hash::AutoHash::AVPairsSingle, Hash::AutoHash::AVPairsMulti, Hash::AutoHash::Record are other subclasses of Hash::AutoHash.

perltie and Tie::Hash present background on tied hashes. 📚

👑 AUTHOR 👑

Nat Goodman, "<natg at shore.net>"

😭 BUGS AND CAVEATS 😭

Please report any bugs or feature requests to "bug-hash-autohash at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Hash-AutoHash>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. bestie customer service fr fr 🫶

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. (yes, that thing from up there 👆)

💖 SUPPORT 💖

You can find documentation for this module with the perldoc command.

perldoc Hash::AutoHash::Args

You can also look for information at:

RT: CPAN's request tracker

<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Hash-AutoHash-Args>

AnnoCPAN: Annotated CPAN documentation

<http://annocpan.org/dist/Hash-AutoHash-Args>

CPAN Ratings

<http://cpanratings.perl.org/d/Hash-AutoHash-Args>

Search CPAN

<http://search.cpan.org/dist/Hash-AutoHash-Args/>

🎀 COPYRIGHT & LICENSE 🎀

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See <http://dev.perl.org/licenses/> for more information.

and that's a wrap on the whole page, bestie!! 🥳 this version came to you courtesy of perl v5.42.0, dated 2025-07-25, and it's the Hash::...::Args(3pm) page — go forth and args responsibly 💜🦋✨

📦 where this page comes from

fedora 43: perl-Hash-AutoHash-Args 1.18-23.fc43 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

Hash::...::Args(3pm)

NAME 💖

VERSION ✨

SYNOPSIS 🦋

DESCRIPTION 🌸

new ✨

Getting and setting argument values 🎀

Caveats 💀

Wholesale manipulation of arguments 🌈

get_args

autoargs_get

getall_args

set_args

💖 set_args

✨ autoargs_set

🦋 Aliasing object to hash: autoargs_alias

🎀 autoargs_alias

🌸 Functions to normalize keywords

💜 fix_args

⭐ fix_keyword

🍓 fix_keywords

💅 Functions to check format of argument list

🧚 is_keyword

🌈 is_positional

👑 Why the Combination of Positional and Keyword Forms is Ambiguous

🔥 Functions for hash-like operations

🫶 autoargs_clear

💀 autoargs_delete

🌟 autoargs_exists

🦋 autoargs_each

✨ autoargs_keys

💖 autoargs_values

🎀 autoargs_count

🧚 autoargs_empty

🌈 autoargs_notempty

💫 DIFFERENCES FROM Class::AutoClass::Args 💫

🌈 SEE ALSO 🌈

👑 AUTHOR 👑

😭 BUGS AND CAVEATS 😭

Known Bugs and Caveats 🕵️

💖 SUPPORT 💖

🎀 COPYRIGHT & LICENSE 🎀

💖 `set_args`

✨ `autoargs_set`

🦋 Aliasing object to hash: `autoargs_alias`

🎀 `autoargs_alias`

💜 `fix_args`

⭐ `fix_keyword`

🍓 `fix_keywords`

🧚 `is_keyword`

🌈 `is_positional`

🫶 `autoargs_clear`

💀 `autoargs_delete`

🌟 `autoargs_exists`

🦋 `autoargs_each`

✨ `autoargs_keys`

💖 `autoargs_values`

🎀 `autoargs_count`

🧚 `autoargs_empty`

🌈 `autoargs_notempty`