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

VERSION
    version 0.17

SYNOPSIS
     use Perinci::Sub::GetArgs::Argv;

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

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

    This module uses Log::Any for logging framework.

    This module has Rinci metadata.

FAQ
SEE ALSO
    Perinci

FUNCTIONS
  get_args_from_argv(%args) -> [status, msg, result, meta]
    Get subroutine arguments (%args) from command-line arguments (@ARGV).

    Using information in function metadata's 'args' property, parse command
    line arguments '@argv' into hash '%args', suitable for passing into
    subs.

    Currently uses Getopt::Long's GetOptions to do the parsing.

    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 pos and greedy.

    *   How this routine uses the 'args' property

    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 'perargyaml' to true.

    This function also (using Perinci::Sub::GetArgs::Array) groks 'pos' and
    'greedy' argument specification, for example:

        $SPEC{multiply2} = {
            v => 1.1,
            summary => 'Multiply 2 numbers (a & b)',
            args => {
                a => ['num*' => {pos=>0}],
                b => ['num*' => {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 (pos=0)
        % multiply2 2 3;     # first argument is fed into a, second into b (pos=1)

    Arguments ('*' denotes required arguments):

    *   argv* => *array*

        If not specified, defaults to @ARGV

    *   check_required_args => *bool* (default: 1)

        Whether to check required arguments.

        If set to true, will check that required arguments (those with
        req=>1) have been specified. Normally you want this, but
        Perinci::CmdLine turns this off so users can run --help even when
        arguments are incomplete.

    *   extra_getopts_after => *array*

        Specify extra Getopt::Long specification.

        Just like extra_getopts_before, but the extra specification is put
        after function arguments specification so extra options can override
        function arguments.

    *   extra_getopts_before => *array*

        Specify extra Getopt::Long specification.

        If specified, insert extra Getopt::Long specification. This is used,
        for example, by Perinci::CmdLine::run() to add general options
        --help, --version, --list, etc so it can mixed with spec arg
        options, for convenience.

        Since the extra specification is put at the front (before function
        arguments specification), the extra options will not be able to
        override function arguments (this is how Getopt::Long works). For
        example, if extra specification contains --help, and one of function
        arguments happens to be 'help', the extra specification won't have
        any effect.

    *   meta* => *hash*

    *   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 '~'

    *   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, Perinci::BashComplete.

    Return value:

    Returns an enveloped result (an array). First element (status) is an
    integer containing HTTP status code (200 means OK, 4xx caller error, 5xx
    function error). Second element (msg) is a string containing error
    message, or 'OK' if status is 200. Third element (result) is optional,
    the actual result. Fourth element (meta) is called result metadata and
    is optional, a hash that contains extra information.

AUTHOR
    Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2012 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.