NAME
Rex::Dondley::ProcessTaskArgs - easier Rex task argument handling
VERSION
version 0.012
SYNOPSIS
use Rex::Dondley::ProcessTaskArgs;
task 'some_task' => sub {
# Process args passed to task
my $params = process_task_args( \@_, # arguments passed by user
available_key1 => 1, # a required argument
available_key2 => 0, # an optional argument
# optional array hash for default values
[
'default_value_for_key1',
'default_value_for_key2',
]
);
# Now retrieve the values as usual
my $key1 = $params->{key1};
my $key2 = $params->{key2};
};
# If no arguments are required, list of available keys can be simplified:
task 'another_task' => sub {
my $params = process_task_args( \@_, key1, key2 [ 'default_value_for_key1' ]);
};
# Params can also be returned in an array. The returned order is the same as
# the order of the list of available keys.
my ($one, $two, $three) = process_task_args( \@_, one => 1, two => 2, three => 3 );DESCRIPTION
This module is designed to alleviate some of the pain of processing arguments passed to tasks from the command line and from other tasks with the run_task() function. Think of it as a simpler, more specialized version of Params::Validate.
This module supplies a single function, process_task_args, which accepts three different types of arguments:
An array reference containing the original
@_special variable, followed by...A list containing the available keys and, optionally, which keys are required, followed by...
An optional array reference containing the default values in the order corresponding to the list of available keys
process_task_args does the following:
Ensures all required keys are given
If arguments do not have associated keys on the command line, it will assign them to the next avaiable key according to the order provided by the available key list
Replaces missing arguments with the default values, if provided
Ensures no extra arguments are supplied
Properly handles parameters passed via
run_task()as an arrayrun_task('some_task', params => [ 'some_value' ]);
Special Edge Cases: Setting arguments to a value of 1 and using keys as switches
A special case exists if an argument is required and has a default value and you are trying to set its value to "1". In such a case, your value will be overridden if you supplied a default value for the key in your default values argument.
To circumvent this unwanted behavior, you must make the key optional. Alternatively, remove the default value from the default values array and process the key manually.
Similarly, if you wish to use an argument as a switch, (i.e. setting a key without a value with --some_key), you must do the same.
Examples
Example #1
Given the following code:
task 'another_task' => sub {
my $params = process_task_args( \@_, key1, key2 [ 'default_value_for_key1' ] );
};And the following command line command:
rex some_task$params will be:
{ key1 => 'default_value_for_key1', key2 => undef };Example #2
Given the following code:
task 'another_task' => sub {
my ($key1, $key2) = process_task_args( \@_, key1, key2 [ 'default_value_for_key1' ] );
};And the following command line command:
rex some_task one two$key1 will have a value of `one` and $key2 will have a value of `two`.
This examples demonstrates that the function will return an array of values in an array context.
Example #3
Given the following code:
task 'another_task' => sub {
my $params = process_task_args( \@_, key1, key2 );
};And the following command line command:
rex some_task some_value$params will be:
{ key1 => 'some_value', key2 => undef };Example #4
Given the following code:
task 'another_task' => sub {
my $params = process_task_args( \@_, key1, key2 );
};And the following command line command:
rex some_task some_value another_value$params will be:
{ key1 => 'some_value', key2 => another_value };Example #4
Given the following code:
task 'another_task' => sub {
my $params = process_task_args( \@_, key1, key2 );
};And the following command line command:
rex some_task some_value --key1=another_value$params will be:
{ key1 => 'another_value', key2 => 'some_value' };Example #6
Given the following code:
task 'another_task' => sub {
my $params = process_task_args( \@_, key1 => 1, key2 => 1 );
};And the following command line command:
rex some_task --key1=another_valueERROR! because key2 is required and it was not supplied.
FUNCTIONS
my $params = process_task_args($array_ref, $available_key1 [ => 1|0 ], $available_key2 [ => 1|0 ], ..., [ $array_ref ]; =function my @values = process_task_args($array_ref, $available_key1 [ => 1|0 ], $available_key2 [ => 1|0 ], ..., [ $array_ref ];
The function will return values with keys as a hash reference in a scalar contect or as array with just the value depending on context. See "SYNOPSIS" and exmaples above for usage instructions.
SUPPORT
Perldoc
You can find documentation for this module with the perldoc command.
perldoc Rex::Dondley::ProcessTaskArgsWebsites
The following websites have more information about this module, and may be of help to you. As always, in addition to those websites please use your favorite search engine to discover more resources.
MetaCPAN
A modern, open-source CPAN search engine, useful to view POD in HTML format.
Source Code
The code is open to the world, and available for you to hack on. Please feel free to browse it and play with it, or whatever. If you want to contribute patches, please send me a diff or prod me to pull from your repository :)
https://github.com/sdondley/Rex-Dondley-ProcessTaskArgs
git clone git://github.com/sdondley/Rex-Dondley-ProcessTaskArgs.gitBUGS AND LIMITATIONS
You can make new bug reports, and view existing ones, through the web interface at https://github.com/sdondley/Rex-Dondley-ProcessTaskArgs/issues.
INSTALLATION
See perlmodinstall for information and options on installing Perl modules.
AUTHOR
Steve Dondley <s@dondley.com>
COPYRIGHT AND LICENSE
This software is copyright (c) 2020 by Steve Dondley.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.