Parameters are required by default. To make a parameter optional, add a question mark before it:

%vals = Params(qw( first second ?third ))->args(@_);

Note that no required parameters may follow an optional parameter.

If one wants to "slurp" all remaining arguments into one value, add an asterisk before it:

%vals = Params(qw( first *second ))->args(@_);

So the above example call would set the values

%vals = (
first => 1,
second => [ 2, 3 ]
);

Note that the slurp argument is required unless it also includes a question-mark:

%vals = Params(qw( first *?second ))->args(@_);

You can also mark options as being allowed when called with named parameters only by adding a plus sign before them:

%vals = Params(qw( common +?obscure +?strange +?weird ))->args(@_);

This is useful when there are many options which are rarely needed (and too awkward to use in positional calling), or may have dangerous side effects if accidentally specified with a positional calling style. (The order of named-only parameters does not matter.)

You can also enforce named-only calling conventions on a subroutine by omitting question-marks from at least one parameter:

%vals = Params(qw( +first +second ))->args(@_);

As of version 0.04, default values can also be specified:

%vals = Params(qw( first=1 second=2 ))->args(@_);

Defaults can be delimited with quotes:

%vals = Params( 'first="some string"' ))->args(@_);

You can also specify aliases by separating them with a vertical bar:

%vals = Params(qw( hour|hh minute|min|mm seconds|sec|ss ))->args(@_);

All named parameter calls using aliases will be stored using the first name.

In general use of aliases are not recommended for subroutines. (This feature is a hook for implementing script-wide "getopts"-like functions.)

Complex Parameter Templates

You may use more complex templates if you need to specify additional information, such as callbacks:

One can use this to change or add new named parameters based on the values of existing parameters. However, one should use ParamsNC so that the modified template is not cached.

In many cases you should use the "needs" option and avoid dynamically updating the parameters.

Note that dynamically-added parameters cannot dynamically add other parameters (at least not in this version).

The $hashref is a reference to the values being returned. One may not be able to rely on a specific parameter being set before the callback is executed, however.

Note that the order that callbacks are called is not determined, so do not rely on one callback being called before another.

Do not call any internal methods aside from those documented here, as they do not have a defined behavior and may change in future versions.

comment

An optional comment describing the field. This is currently unused but may be displayed in error messages in future versions.

Compatability with Previous Versions

Note that the formatting for simple parameter templates has changed since version 0.03, and the complex parameter templates were not implemented until version 0.04, so it is best to specify a minimum version in use statements

use Params::Smart 0.04;

CAVEATS

Because Perl5 treats hashes as lists, this module attempts to interpret the arguments as a hash of named parameters first. If some hash keys match, and some do not, then it assumes there has been an error. If no keys match, then it assumes that it the arguments are positional.

In theory one can pass positional arguments where every other argument matches a hash key, or one can pass a hash with the wrong keys (possible if one copies/pastes code from the wrong call) and so it is treated as a positional argument.

This is probably uncommon for most data, but subroutines should take extra care to check if values are within allowed ranges. There may even be security issues if users can blindly specify data that they know can cause this confusion. If the application is critical enough, then this may not be an appropriate module to use (at least not until the ability to distinguish between lists and hashes is improved).

To diagnose potential bugs, or to enforce named or positional calling one can check the "_named" parameter.

A future version might make use of Perl internals to get around this problem.

SEE ALSO

This module is superficially similar in function to Getargs::Mixed but does not require named parameters to have an initial dash ('-').