Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
217 lines (138 sloc) 5.54 KB


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



#!/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->cli_run(\@ARGV, {h => "help", v => 'verbose', d => 'debug'}) unless caller;

From shell:

% chmod a+x
% ./ -h
Usage: [--opt=value].. <Command> ARGS...

  foo        This prints FOO

Options from MyScript:

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
% ./ foo
% ./ --structs='[1,2,{"x":"y"}]' bar '["baz",{"qux":"quux"}]' '{"other":"arg"}'


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.


cli_run (\@ARGV, \%option_shortcuts)

__PACKAGE__->cli_run(\@ARGV) unless caller;

This method parses arguments, invokes appropriate command and usually emits its result to STDOUT. Also there is an alias run() which points to cli_run() so that you do the same thing like below:

__PACKAGE__->run(\@ARGV) unless caller;

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 cli_run() gets optional second argument hash, it is used to accept short name for options like following:

__PACKAGE__->cli_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:


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.


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


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


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.







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

You can’t perform that action at this time.