Differences from MooX::Options

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

new_with_options

option

osprey_usage($code, @messages)

osprey_help($code)

osprey_man

abbreviate

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

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

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

A description, of any length, in POD format, to be included as the "DESCRIPTION" section of the command's manual page.

extra_pod

Arbitrary extra POD to be included between the "DESCRIPTION" and "OPTIONS" sections of the manual page.

getopt_options

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

If true, command-line options override key/value pairs passed to "new_with_options". If false, the reverse is true.

preserve_argv

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

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

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.

doc

Documentation for the option, used in "--help" output. For best results, should be no more than a short paragraph.

format

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

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

A "hidden" option will be recognized, but not listed in automatically generated documentation.

negatable

Adds the "--no-" version of the option, which sets it to a false value. Equivalent to "!" in Getopt::Long.

option

Allows the command-line option for an attribute to differ from the attribute name -- like "init_arg" except for the commandline.

long_doc

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

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

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

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

Gives an option a single-character "short" form, e.g. "-v" for "--verbose".

spacer_before

Causes a blank line to appear before this option in help output.

spacer_after

Causes a blank line to appear after this option in help output.

Subcommand Classes

    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

    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.