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

VERSION
    This document describes version 0.36 of Perinci::Sub::GetArgs::Argv
    (from Perl distribution Perinci-Sub-GetArgs-Argv), released on
    2014-07-08.

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. For explanation on how command-line options are
    processed, see Perinci::CmdLine's documentation.

    This module uses Log::Any for logging framework.

    This module has Rinci metadata.

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 to be able to parse complex types.

    This function exists mostly to support command-line options parsing for
    Perinci::CmdLine. See its documentation, on the section of command-line
    options/argument parsing.

    Arguments ('*' denotes required arguments):

    *   allow_extra_elems => *bool* (default: 0)

        Allow extra/unassigned elements in argv.

        If set to 1, then if there are array elements unassigned to one of
        the arguments, instead of generating an error, the function will
        just ignore them.

        This option will be passed to Perinci::Sub::GetArgs::Array's
        allow*extra*elems.

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

    *   meta_is_normalized => *bool* (default: 0)

        Can be set to 1 if your metadata is normalized, to avoid duplicate
        effort.

    *   on_missing_required_args => *code*

        Execute code when there is missing required args.

        This can be used to give a chance to supply argument value from
        other sources if not specified by command-line options.
        Perinci::CmdLine, for example, uses this hook to supply value from
        STDIN or file contents (if argument has "cmdline_src" specification
        key set).

        This hook will be called for each missing argument. It will be
        supplied hash arguments: (arg => $the*missing*argument*name, args =*
        $the>resulting*args*so*far, spec =* $the>arg_spec).

        The hook can return true if it succeeds in making the missing
        situation resolved. In this case, the function won't complain about
        missing argument for the corresponding argument.

    *   per_arg_json => *bool* (default: 0)

        Whether to recognize --ARGNAME-json.

        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-json 'null'

        But every other string will need to be quoted:

            % script.pl --name-json '"foo"'

        See also: per*arg*yaml. You should enable just one instead of
        turning on both.

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

        See also: per*arg*json. You should enable just one instead of
        turning on both.

    *   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::Sub::Complete.

    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.

FAQ
SEE ALSO
    Perinci

HOMEPAGE
    Please visit the project's homepage at
    <https://metacpan.org/release/Perinci-Sub-GetArgs-Argv>.

SOURCE
    Source repository is at
    <https://github.com/sharyanto/perl-Perinci-Sub-GetArgs-Argv>.

BUGS
    Please report any bugs or feature requests on the bugtracker website
    <https://rt.cpan.org/Public/Dist/Display.html?Name=Perinci-Sub-GetArgs-A
    rgv>

    When submitting a bug or request, please include a test-file or a patch
    to an existing test-file that illustrates the bug or desired feature.

AUTHOR
    Steven Haryanto <stevenharyanto@gmail.com>

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

