MOP4Import::Base::CLI_JSON - Runnable-Module with JSON args/outputs
In MyScript.pm
#!/usr/bin/env perl package MyScript; use MOP4Import::Base::CLI_JSON -as_base, [fields => qw/verbose structs/]; sub cmd_foo : Doc("This prints FOO") { print "FOO\n" } sub bar { (my MY $self) = @_; ([arguments => @ARGV], [structs => $self->{structs}]) } MY->run(\@ARGV, {h => "help", v => 'verbose', d => 'debug'}) unless caller; 1;
From shell:
% chmod a+x MyScript.pm % ./MyScript.pm -h Usage: MyScript.pm [--opt=value].. <Command> ARGS... Commands: foo This prints FOO help Options from MyScript: --verbose --structs Options from MOP4Import::Base::CLI_JSON: --help show this help message --quiet to be (somewhat) quiet --scalar evaluate methods in scalar context --output choose output serializer (json/tsv/dump) --flatten output each result separately (instead of single json array) --undef-as serialize undef as this value. used in tsv output --no-exit-code exit with 0(EXIT_SUCCESS) even when result was falsy/empty --binary keep STDIN/OUT/ERR binary friendly % % ./MyScript.pm foo FOO % % ./MyScript.pm --structs='[1,2,{"x":"y"}]' bar '["baz",{"qux":"quux"}]' '{"other":"arg"}' [["arguments",["baz",{"qux":"quux"}],{"other":"arg"}],["structs",[1,2,{"x":"y"}]]]
MOP4Import::Base::CLI_JSON is my latest boilerplate base class to write Runnable-Module. Using this module as a base class, you can run most methods directly from shell. It treats subcommand names and options basically like following:
(Sub)comands are (basically) mapped to methods.
(Posix style long) options before given command are used to create instance(via __PACKAGE__->new(%opts)).
__PACKAGE__->new(%opts)
You can pass complex structures like arrays and hashes as option values and arguments to methods in JSON array/object literal syntax. Results of method invocation are printed with JSON serializer by default. You can override this behavior by implementing official command methods cmd_$COMMAND.
cmd_$COMMAND
As noted in the above doc, design goal of this module is *NOT* to provide complete feature-rich human-friendly CLI base class. Instead, it aims to make most methods in developping modules testable/useable via CLI (and perl -d) from very beginning of its development so that we can develop perl modules more rapidly via CLI-tested pieces of codes.
__PACKAGE__->run(\@ARGV) unless caller;
This method parses arguments, invokes appropriate command and usually emits its result to STDOUT.
Accepted options are a subset of posix style options (--name and --name=value only). --name value is not allowed, intentionally. If value part of options are recognized as JSON arrays/objects, they are automatically deserialized as perl's arrays/hashes.
--name
--name=value
--name value
If run() gets optional second argument hash, it is used to accept short name for options like following:
__PACKAGE__->run(\@ARGV, {h => 'help', v => 'verbose'}) unless caller;
In above, -h is recognized samely as --help and -v as --verbose.
-h
--help
-v
--verbose
Then first word in @ARGV is taken and treated as command name. Command name is resolved to a module method in following ways:
@ARGV
If there is a method named cmd_$COMMAND, it is assumed that this method is officially designed for CLI invocation. For official command, run() just invokes it and do nothing else. Callee method is responsible to handle its output and possibly exit code.
run()
$COMMAND
If there is a method exactly matches to specified command, it is invoked via cli_invoke($method, @args). It invokes the method in array context (unless --scalar option is given). Results are printed by cli_output() with JSON serializer. If option --flatten is given, cli_output is called for each element of the results instead.
--scalar
cli_output()
--flatten
If results are empty list, program exit with code 1 (unless --no-exit-code option is given).
--no-exit-code
If the command name does not meet all above, cli_unknown_subcommand hook is called instead.
cli_unknown_subcommand
These options control run method.
suppress output of method invocation.
evaluate methods in scalar context
default 'json'
output each result separately (instead of single json array)
default => 'null'
suppress setting exit-code.
keep STDIN/OUT/ERR binary friendly. (default 0)
All public APIs are named starting with cli_... prefix.
cli_...
This provides default implementation of usage output.
App::Cmd - if your main goal is writing full-fleged CLI.
Copyright (C) Kobayasi, Hiroaki.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Kobayasi, Hiroaki <buribullet@gmail.com>
To install MOP4Import::Declare, copy and paste the appropriate command in to your terminal.
cpanm
cpanm MOP4Import::Declare
CPAN shell
perl -MCPAN -e shell install MOP4Import::Declare
For more information on module installation, please visit the detailed CPAN module installation guide.