/ 
Sub-Spec-GetArgs-Argv-0.06
/ Sub::Spec::GetArgs::Argv

NAME

Sub::Spec::GetArgs::Argv - Get subroutine arguments from command line arguments (@ARGV)

VERSION

version 0.06

SYNOPSIS

use Sub::Spec::GetArgs::Argv;

my $res = get_args_from_argv(argv=>\@ARGV, spec=>$spec, ...);

DESCRIPTION

This module provides get_args_from_argv(), which parses command line arguments (@ARGV) into subroutine arguments (%args). This module is used by Sub::Spec::CmdLine.

This module uses Log::Any for logging framework.

This module's functions has Sub::Spec specs.

FUNCTIONS

None are exported by default, but they are exportable.

get_args_from_argv(%args) -> RESULT

Get subroutine arguments (%args) from command-line arguments (@ARGV).

Using information in sub spec's ~args~ clause, parse command line arguments ~@argv~ into hash ~%args~, suitable for passing into subs.

Uses Getopt::Long's GetOptions to parse the result.

As with GetOptions, this function modifies its ~argv~ argument.

Why would one use this function instead of using Getopt::Long directly? Among other reasons, we want YAML parsing (ability to pass data structures via command line) and parsing of arg_pos and arg_greedy.

* How this routine translates the args spec clause

Bool types can be specified using:

: --ARGNAME

or

: --noARGNAME

All the other types can be specified using:

: --ARGNAME VALUE

or

: --ARGNAME=VALUE

VALUE will be parsed as YAML for nonscalar types (hash, array). If you want to force YAML parsing for scalar types (e.g. when you want to specify undef, *~* in YAML) you can use:

: --ARGNAME-yaml=VALUE

but you need to set *per_arg_yaml* to true.

Argument aliases (~arg_aliases~) clause for each argument is also parsed. For example:

: args => { : argname => [bool => { : summary => '...', : arg_aliases => { : a => {}, : arg => {}, : }, : } : }

Then -a and --arg are also available in addition to --argname.

This function also (using [[cpanmod:Sub::Spec::GetArgs::Array]]) groks ~arg_pos~ and ~arg_greedy~ type clause, for example:

: $SPEC{multiply2} = { : summary => 'Multiply 2 numbers (a & b)', : args => { : a => ['num*' => {arg_pos=>0}], : b => ['num*' => {arg_pos=>1}], : } : }

then on the command-line any of below is valid:

: % multiply2 --a 2 --b 3 : % multiply2 2 --b 3; # first non-option argument is fed into a (arg_pos=0) : % multiply2 2 3; # first argument is fed into a, second into b (arg_pos=1)

Arguments (* denotes required arguments):

  • argv* => array

    If not specified, defaults to @ARGV

  • extra_getopts => hash

    Specify extra Getopt::Long specification.

    If specified, add extra Getopt::Long specification (as long as it doesn't clash with spec arg). This is used, for example, by Sub::Spec::CmdLine::run() to add general options --help, --version, --list, etc so it can mixed with spec arg options, for convenience.

  • per_arg_yaml => bool (default 0)

    Whether to recognize --ARGNAME-yaml.

    This is useful for example if you want to specify a value which is not expressible from the command-line, like *undef*.

    : script.pl --name-yaml '~'

  • spec* => hash

  • strict => bool (default 1)

    Strict mode.

    If set to 0, will still return parsed argv even if there are parsing errors. If set to 1 (the default), will die upon error.

    Normally you would want to use strict mode, for more error checking. Setting off strict is used by, for example, Sub::Spec::BashComplete.

FAQ

SEE ALSO

Sub::Spec

Sub::Spec::CmdLine

AUTHOR

Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Steven Haryanto.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.