Provided by: libcli-osprey-perl_0.08-2_all 
NAME
CLI::Osprey - MooX::Options + MooX::Cmd + Sanity
VERSION
version 0.08
SYNOPSIS
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;
DESCRIPTION
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.
Differences from MooX::Options
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".
For JSON support, you can use a coercion on the attribute, turning it from a string to a
ref via "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.
IMPORTED METHODS
The following methods, will be imported into a class that uses CLI::Osprey:
new_with_options
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.
option
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.
osprey_usage($code, @messages)
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.
osprey_help($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.
osprey_man
Displays a manual page for the app, containing long descriptive text (if provided) about
each command and option, then exits.
IMPORT PARAMETERS
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:
abbreviate
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).
added_order
Default: true.
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.
desc
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.
description_pod
Default: none.
A description, of any length, in POD format, to be included as the "DESCRIPTION" section
of the command's manual page.
extra_pod
Default: none.
Arbitrary extra POD to be included between the "DESCRIPTION" and "OPTIONS" sections of the
manual page.
getopt_options
Default: "['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".
prefer_commandline
Default: true.
If true, command-line options override key/value pairs passed to "new_with_options". If
false, the reverse is true.
preserve_argv
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.
usage_string
Default: "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.
on_demand
Default: false
If set to a true value, the commands' modules won't be loaded at compile time, but if the
command is invoked. This is useful for minimizing compile time if the application has a
lot of commands or the commands are on the heavy side. Note that enabling the feature may
interfere with the ability to fatpack the application.
OPTION PARAMETERS
doc
Default: None.
Documentation for the option, used in "--help" output. For best results, should be no more
than a short paragraph.
format
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:
s string
i decimal integer
o integer (supports "0x" for hex, "0b" for binary, and 0 for octal).
f floating-point number
format_doc
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".
hidden
Default: false.
A "hidden" option will be recognized, but not listed in automatically generated
documentation.
negatable
Default: false.
Adds the "--no-" version of the option, which sets it to a false value. Equivalent to "!"
in Getopt::Long.
option
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.
long_doc
Default: none.
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.
order
Default: None.
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.
repeatable
Default: false.
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.
required
Default: false.
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.
short
Default: None.
Gives an option a single-character "short" form, e.g. "-v" for "--verbose".
spacer_before
Default: false.
Causes a blank line to appear before this option in help output.
spacer_after
Default: false.
Causes a blank line to appear after this option in help output.
SUBCOMMANDS
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.
Subcommand Classes
A subcommand can be another class, which also uses "CLI::Osprey". For example:
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);
}
Inline Subcommands
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.
THANKS
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.
AUTHOR
Andrew Rodland <arodland@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2020 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.