/ 
MOP4Import-Declare-0.050
River stage one • 3 direct dependents • 3 total dependents
/ MOP4Import::Base::CLI_JSON

NAME

MOP4Import::Base::CLI_JSON - Runnable-Module with JSON args/outputs

SYNOPSIS

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"}]]]

DESCRIPTION

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)).

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.

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.

CLASS METHODS

run (\@ARGV, \%option_shortcuts)

__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.

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.

Command name interpretation rule

Then first word in @ARGV is taken and treated as command name. Command name is resolved to a module method in following ways:

cmd_$COMMAND

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.

$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.

If results are empty list, program exit with code 1 (unless --no-exit-code option is given).

??UNKNOWN??

If the command name does not meet all above, cli_unknown_subcommand hook is called instead.

OPTIONS

These options control run method.

quiet

suppress output of method invocation.

scalar

evaluate methods in scalar context

output

default 'json'

flatten

output each result separately (instead of single json array)

undef-as

default => 'null'

no-exit-code

suppress setting exit-code.

binary

keep STDIN/OUT/ERR binary friendly. (default 0)

METHODS

All public APIs are named starting with cli_... prefix.

cli_output

cli_invoke

cli_precmd

cli_unknown_subcommand

COMMANDS

help

This provides default implementation of usage output.

SEE ALSO

App::Cmd - if your main goal is writing full-fleged CLI.

LICENSE

Copyright (C) Kobayasi, Hiroaki.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Kobayasi, Hiroaki <buribullet@gmail.com>