NAME
Sub::Spec::CmdLine - Access Perl subs via command line
VERSION
version 0.08
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) => \%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? We want YAML parsing (ability to pass data structures via command line), parsing of arg_pos and arg_greedy, stricter behaviour (dies on error).
One problem with Getopt::Long: all options get set to undef even if not specified. So currently we delete undef keys in %$args.
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
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.