pericmd 035: Common options

We’ll take a short break from discussing tab completion. Let’s turn to one thing that we’ve taken for granted so far: common options. These are things like --help, --version, --format and so on. Where are they defined and how can we customize them?

When we instantiate our CLI application object with Perinci::CmdLine::Any->new, it will return either a Perinci::CmdLine::Lite (the default) or Perinci::CmdLine::Classic object, depending on some conditions/parameters. These classes are all subclasses of Perinci::CmdLine::Base.

Perinci::CmdLine::Base defines the following package variable:

our %copts = (

    version => {
        getopt  => "version|v",
        usage   => "--version (or -v)",
        handler => sub {
            my ($go, $val, $r) = @_;
            $r->{action} = 'version';
            $r->{skip_parse_subcommand_argv} = 1;
        },
    },

    help => {
        getopt  => 'help|h|?',
        summary => 'Display this help message',
        usage   => "--help (or -h, -?)",
        handler => sub {
            my ($go, $val, $r) = @_;
            $r->{action} = 'help';
            $r->{skip_parse_subcommand_argv} = 1;
        },
        order => 0, # high
    },

    format => {
        getopt  => 'format=s',
        summary => 'Choose output format, e.g. json, text',
        handler => sub {
            my ($go, $val, $r) = @_;
            $r->{format} = $val;
        },
    },
 
    ...

Later, each of Perinci::CmdLine::Lite and Perinci::CmdLine::Classic will copy from this hash into new object’s common_opts attribute. Some options will not be included, for example all the config-related common options (--config-profile, --config-path, --no-config), will be skipped if we don’t want config file support (read_config attribute is set to false). You get the final set of options in the common_opts attribute.

Customizing common options

Suppose you don’t want any common option (this makes the CLI app quite incovenient to use, but for the sake of the example…):

# myapp
use Perinci::CmdLine::Any;
Perinci::CmdLine::Any->new(common_opts=>{}, url=>'...');

When this program is run:

% myapp --help
Unknown option: help
ERROR 500: GetOptions failed

% myapp -v
Unknown option: v
ERROR 500: GetOptions failed

What you would like to do is sometimes just remove one or two common options or rename them, usually because they happen to conflict with your function argument. For example, suppose your function has an argument called format and you want the common option --format to be renamed to --output-format. You can already see the structure of the format common option from the previous listing, so:

# myapp
use Perinci::CmdLine::Any;
my $app = Perinci::CmdLine::Any->new(url=>'...');
$app->common_opts->{format}{getopt} = 'output-format=s';
$app->run;
Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s