NAME
    Sub::Spec::CmdLine - Access Perl subs via command line

VERSION
    version 0.10

SYNOPSIS
    In your module:

     package YourModule;
     our %SUBS;

     $SUBS{foo} = {
         summary => 'Foo!',
         args => {
             arg  => ...,
             arg2 => ...
         },
         ...
     };
     sub foo {
        ...
     }

     ...
     1;

    In your script:

     #!/usr/bin/perl
     use Sub::Spec::CmdLine qw(run);
     run(module=>'YourModule', sub=>'foo');

    In the command-line:

     % script.pl --help
     % script.pl --arg value --arg2 '[an, array, in, yaml, syntax]' ...

    For running multiple subs, in your script:

     use Sub::Spec::CmdLine qw(run);
     run(subcommands => {
         foo => { module=>'YourModule', sub=>'foo'},
         bar => { module=>'YourModule', sub=>'bar'},
         ...
     });

    In the command-line:

     % script.pl --help
     % script.pl --list
     % script.pl foo --help
     % script.pl foo --arg value --arg2 ...
     % script.pl bar --blah ...

DESCRIPTION
    This module utilize sub specs (as defined by Sub::Spec) to let your subs
    be accessible from the command-line.

    This module uses Log::Any logging framework. Use something like
    Log::Any::App, etc to see more logging statements for debugging.

    NOTE: This module is not ready for public consumption yet. It will be
    after Data::Sah and Sub::Spec is released.

FUNCTIONS
    None of the functions are exported by default, but they are exportable.

  parse_argv(\@argv, $sub_spec[, \%opts]) => \%args
    Parse command line argument @argv into hash %args, suitable for passing
    into subs.

    Uses Getopt::Long to parse the result. You can Getopt::Long::Configure
    beforehand to modify behaviour (e.g. if you want no_permute).

    Note: As with GetOptions, this function modifies its argument, @argv.

    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.

    Options in %opts:

    *   strict => BOOL (default 1)

        If set to 0, will still return parsed argv even if there are errors.

  gen_usage($sub_spec) => TEXT
    Generate usage information for a sub (typically used for --help).

  format_result($sub_res[, \%opts]) => TEXT
    Format result from sub into various formats

    Options:

    *   format => FORMAT (optional, default 'text')

        Format can be 'text' (pretty text or nonpretty text), 'pretty'
        (pretty text, generated by Data::Format::Pretty::Console under
        interactive=1), 'nopretty' (also generated by
        Data::Format::Pretty::Console under interactive=0), 'yaml', 'json',
        'php' (generated by PHP::Serialization's serialize()).

    *   default_success_message => STR (optional, default none)

        If output format is text ('text', 'pretty', 'nopretty') and result
        code is 200 and there is no data returned, this
        default_success_message is used. Example: 'Success'.

  run(%args)
    Run sub from the command line, which essentially comprises these steps:

    *   Parse command-line options in @ARGV (using parse_argv())

        Also, display help using gen_usage() if given '--help' or '-h' or
        '-?'.

    *   Call sub

    *   Format the return value from sub (using format_result())

    *   Exit with appropriate exit code

        0 if 200, or CODE-300.

    Arguments:

    *   summary => STR

    *   module => STR

    *   sub => STR

    *   subcommands => {NAME => {module=>..., sub=>..., summary=>...}, ...}

        module and sub should be specified if you only have one sub to run.
        If you have several subs to run, assign each of them to a
        subcommand, e.g.:

         summary     => 'Maintain a directory containing git repos',
         module      => 'Git::Bunch',
         subcommands => {
           backup  => { }, # module defaults to main module argument,
           status  => { }, # sub defaults to the same name as subcommand name
         },

    *   exit => BOOL (optional, default 1)

        If set to 0, instead of exiting with exit(), return the exit code
        instead.

    *   require => BOOL (optional, default 1)

        If set to 0, do not try to require the module.

SEE ALSO
    Sub::Spec

    Sub::Spec::Pod

    MooseX::Getopt

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.