Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CLI::Osprey(3)	      User Contributed Perl Documentation	CLI::Osprey(3)

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:

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

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

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

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

perl v5.32.1			  2020-07-12			CLI::Osprey(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | IMPORTED METHODS | IMPORT PARAMETERS | OPTION PARAMETERS | SUBCOMMANDS | THANKS | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=CLI::Osprey&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help