CLI::Osprey - MooX::Options + MooX::Cmd + Sanity
version 0.04
in Hello.pm
package Hello; use Moo; use CLI::Osprey; option 'message' => ( is => 'ro', format => 's', doc => 'The message to display', default => 'Hello world!', ); sub run { my ($self) = @_; print $self->message, "\n"; }
In hello.pl
use Hello; Hello->new_with_options->run;
CLI::Osprey is a module to assist in writing commandline applications with M* OO modules (Moose, Moo, Mo). With it, you structure your app as one or more modules, which get instantiated with the commandline arguments as attributes. Arguments are parsed using Getopt::Long::Descriptive, and both long and short help messages as well as complete manual pages are automatically generated. An app can be a single command with options, or have sub-commands (like git). Sub-commands can be defined as modules (with options of their own) or as simple coderefs.
git
Osprey is deliberately similar to MooX::Options, and porting an app that uses MooX::Options to Osprey should be fairly simple in most cases. However there are a few important differences:
Osprey is pure-perl, without any mandatory XS dependencies, meaning it can be used in fatpacked scripts, and other situations where you may need to run on diverse machines, where a C compiler and control over the ennvironment aren't guaranteed.
Osprey's support for sub-commands is built-in from the beginning. We think this makes for a better experience than MooX::Options + MooX::Cmd.
While MooX::Options requires an option's primary name to be the same as the attribute that holds it, and MooX::Cmd derives a sub-command's name from the name of the module that implements it, Osprey separates these, so that Perl identifier naming conventions don't dictate your command line interface.
Osprey doesn't use an automatic module finder (like Module::Pluggable) to locate modules for sub-commands; their names are given explicitly. This small amount of additional typing gives you more control and less fragility.
There are also a few things MooX::Options has that Osprey lacks. While they may be added in the future, I haven't seen the need yet. Currently known missing feeatures are JSON options, config_from_file support, autosplit, and autorange.
config_from_file
autosplit
autorange
For JSON support, you can use a coercion on the attribute, turning it from a string to a ref via decode_json.
decode_json
To default an app's options from a config file, you may want to do something like this in your script file:
use JSON 'decode_json'; use Path::Tiny; MyApp->new_with_options( map decode_json(path($_)->slurp), grep -f, "$ENV{HOME}/.myapprc" )->run;
Provided that prefer_commandline is true (which is the default), any options in .myapprc will be used as defaults if that file exists, but will still be overrideable from the commandline.
prefer_commandline
.myapprc
The following methods, will be imported into a class that uses CLI::Osprey:
Parses commandline arguments, validates them, and calls the new method with the resulting parameters. Any parameters passed to new_with_options will also be passed to new; the prefer_commandline import option controls which overrides which.
new
new_with_options
The option keyword acts like has (and accepts all of the arguments that has does), but also registers the attribute as a commandline option. See "OPTION PARAMETERS" for usage.
option
has
Displays a short usage message, the same as if the app was invoked with the -h option. Also displays the lines of text in @messages if any are passed. If $code is passed a defined value, exits with that as a status.
-h
@messages
$code
Displays a more substantial usage message, the same as if the app was invoked with the --help option. If $code is passed a defined value, exits with that as a status.
--help
Displays a manual page for the app, containing long descriptive text (if provided) about each command and option, then exits.
The parameters to use CLI::Osprey serve two roles: to customize Osprey's behavior, and to provide information about the app and its options for use in the usage messages. They are:
use CLI::Osprey
Default: true.
If abbreviate is set to a true value, then long options can be abbreviated to the point of uniqueness. That is, --long-option-name can be called as --lon as long as there are no other options starting with those letters. An option can always be called by its full name, even if it is a prefix of some longer option's name. If abbreviate is false, options must always be called by their full names (or by a defined short name).
abbreviate
--long-option-name
--lon
If added_order is set to a true value, then two options with the same order (or none at all) will appear in the help text in the same order as their option keywords were executed. If it is false, they will appear in alphabetical order instead.
added_order
order
Default: none.
A short description of the command, to be shown at the top of the manual page, and in the listing of subcommands if this command is a subcommand.
A description, of any length, in POD format, to be included as the DESCRIPTION section of the command's manual page.
DESCRIPTION
Arbitrary extra POD to be included between the DESCRIPTION and OPTIONS sections of the manual page.
OPTIONS
Default: ['require_order'].
['require_order']
Contains a list of options to control option parsing behavior (see "Configuring Getopt::Long" in Getopt::Long). Note, however, that many of these are not helpful with Osprey, and that using permute will likely break subcommands entirely. MooX::Options calls this parameter flavour.
permute
flavour
If true, command-line options override key/value pairs passed to new_with_options. If false, the reverse is true.
Default: false.
If true, the @ARGV array will be localized for the duration of new_with_options, and will be left in the same state after option parsing as it was before. If false, the @ARGV array will be modified by option parsing, removing any recognized options, values, and subcommands, and leaving behind any positional parameters or anything after and including a -- separator.
@ARGV
--
Default: "USAGE: $program_name %o"
"USAGE: $program_name %o"
Provides the header of the usage message printed in response to the -h option or an error in option processing. The format of the string is described in "$usage_desc" in Getopt::Long::Descriptive.
Default: None.
Documentation for the option, used in --help output. For best results, should be no more than a short paragraph.
Default: None (i.e. boolean).
The format of the option argument, same as Getopt::Long. An option with no format is a boolean, not taking an additional argument. Other formats are:
string
decimal integer
integer (supports 0x for hex, 0b for binary, and 0 for octal).
0x
0b
0
floating-point number
Default: depends on "format".
Describes the type of an option's argument. For example, if the string option copy-to specifies a hostname, you can give it format_doc => "hostname" and it will display as "--copy-to hostname" in the help text, instead of "--copy-to string".
copy-to
format_doc => "hostname"
A hidden option will be recognized, but not listed in automatically generated documentation.
hidden
Adds the --no- version of the option, which sets it to a false value. Equivalent to ! in Getopt::Long.
--no-
!
Default: Same as the attribute name, with underscores replaced by hyphens.
Allows the command-line option for an attribute to differ from the attribute name -- like init_arg except for the commandline.
init_arg
Long documentation of the option for the manual page. This is POD, so POD formatting is available, and paragraphs need to be separated by "\n\n". If not provided, the short documentation will be used instead.
"\n\n"
Allows controlling the order that options are listed in the help text. Options without an order attribute are sorted by the order their option statements are executed, if "added_order" is true, and by alphabetical order otherwise. They are placed as though they had order 9999, so use small values to sort before automaticall-sorted options, and values of 10000 and up to sort at the end.
Allows an option to be specified more than once. When used on a "boolean" option with no "format", each appearace of the option will increment the value by 1 (equivalent to + in Getopt::Long. When used on an option with arguments, produces an arrayref, one value per appearance of the option.
+
This is a Moo/Moose feature honored by Osprey. A required attribute must be passed on the commandline unless it's passed to the constructor. Generated documentation will show the option as non-optional.
required
Gives an option a single-character "short" form, e.g. -v for --verbose.
-v
--verbose
Causes a blank line to appear before this option in help output.
Causes a blank line to appear after this option in help output.
An Osprey command can have subcommands with their own options, documentation, etc., allowing for complicated applications under the roof of a single command. Osprey will parse the options for all of the commands in the chain, and construct them in top-to-bottom order, with each subcommand receiving a reference to its parent.
A subcommand can be another class, which also uses CLI::Osprey. For example:
CLI::Osprey
package MyApp; use Moo; use CLI::Osprey; option verbose => ( is => 'ro', short => 'v', ); subcommand frobnicate => 'MyApp::Frobnicate'; package MyApp::Frobnicate; use Moo; use CLI::Osprey; option target => ( is => 'ro', format => 's', ); sub run { my ($self) = @_; if ($self->parent_command->verbose) { say "Be dangerous, and unpredictable... and make a lot of noise."; } $self->do_something_with($self->target); }
A subcommand can also be specified as a coderef, for when a separate class would be excessive. For example:
package Greet; use Moo; use CLI::Osprey; option target => ( is => 'ro', default => "world", ); subcommand hello => sub { my ($self, $parent) = @_; say "Hello ", $parent->target; }; subcommand goodbye => sub { my ($self, $parent) = @_; say "Goodbye ", $parent->target; };
which can be invoked as greet --target world hello. Inline subcommands are implemented using CLI::Osprey::InlineSubcommand.
greet --target world hello
This module is based heavily on code from MooX::Options and takes strong inspiration from MooX::Cmd and MooX::Options::Actions. Thanks to celogeek, Jens Reshack, Getty, Tom Bloor, and all contributors to those modules. Thanks to mst for prodding me to do this. Thanks Grinnz for helping me update my dzillage.
Andrew Rodland <arodland@cpan.org>
This software is copyright (c) 2018 by Andrew Rodland.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install CLI::Osprey, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CLI::Osprey
CPAN shell
perl -MCPAN -e shell install CLI::Osprey
For more information on module installation, please visit the detailed CPAN module installation guide.