view release on metacpan or  search on metacpan

lib/CLI/Osprey.pm  view on Meta::CPAN

    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;

=head1 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 L<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 C<git>). Sub-commands can be defined as modules (with options of their
own) or as simple coderefs.

=head2 Differences from MooX::Options

Osprey is deliberately similar to L<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:

=over 4

=item *

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.

=item *

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.

=item *

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.

=item *

Osprey doesn't use an automatic module finder (like L<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.

=back

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, C<config_from_file> support, C<autosplit>, and C<autorange>.

For JSON support, you can use a coercion on the attribute, turning it from a
string to a ref via C<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 C<prefer_commandline> is true (which is the default), any
options in C<.myapprc> will be used as defaults if that file exists, but will
still be overrideable from the commandline.

=head1 IMPORTED METHODS

The following methods, will be imported into a class that uses CLI::Osprey:

=head2 new_with_options

Parses commandline arguments, validates them, and calls the C<new> method with
the resulting parameters. Any parameters passed to C<new_with_options> will
also be passed to C<new>; the C<prefer_commandline> import option controls
which overrides which.

=head2 option

The C<option> keyword acts like C<has> (and accepts all of the arguments that
C<has> does), but also registers the attribute as a commandline option. See
L</OPTION PARAMETERS> for usage.

=head2 osprey_usage($code, @messages)

Displays a short usage message, the same as if the app was invoked with the
C<-h> option. Also displays the lines of text in C<@messages> if any are
passed. If C<$code> is passed a defined value, exits with that as a status.

=head2 osprey_help($code)

Displays a more substantial usage message, the same as if the app was invoked
with the C<--help> option. If C<$code> is passed a defined value, exits with
that as a status.

=head2 osprey_man

Displays a manual page for the app, containing long descriptive text (if
provided) about each command and option, then exits.