1CLI::Osprey(3pm) User Contributed Perl Documentation CLI::Osprey(3pm)
2
6 CLI::Osprey - MooX::Options + MooX::Cmd + Sanity
7
9 version 0.08
10
12 in Hello.pm
13 package Hello;
15 use Moo;
16 use CLI::Osprey;
17 option 'message' => (
19 is => 'ro',
20 format => 's',
21 doc => 'The message to display',
22 default => 'Hello world!',
23 );
24 sub run {
26 my ($self) = @_;
27 print $self->message, "\n";
28 }
29 In hello.pl
31 use Hello;
33 Hello->new_with_options->run;
34
36 CLI::Osprey is a module to assist in writing commandline applications
37 with M* OO modules (Moose, Moo, Mo). With it, you structure your app as
38 one or more modules, which get instantiated with the commandline
39 arguments as attributes. Arguments are parsed using
40 Getopt::Long::Descriptive, and both long and short help messages as
41 well as complete manual pages are automatically generated. An app can
42 be a single command with options, or have sub-commands (like "git").
43 Sub-commands can be defined as modules (with options of their own) or
44 as simple coderefs.
45 Differences from MooX::Options
47 Osprey is deliberately similar to MooX::Options, and porting an app
48 that uses MooX::Options to Osprey should be fairly simple in most
49 cases. However there are a few important differences:
50 • Osprey is pure-perl, without any mandatory XS dependencies, meaning
52 it can be used in fatpacked scripts, and other situations where you
53 may need to run on diverse machines, where a C compiler and control
54 over the ennvironment aren't guaranteed.
55 • Osprey's support for sub-commands is built-in from the beginning.
57 We think this makes for a better experience than MooX::Options +
58 MooX::Cmd.
59 • While MooX::Options requires an option's primary name to be the
61 same as the attribute that holds it, and MooX::Cmd derives a sub-
62 command's name from the name of the module that implements it,
63 Osprey separates these, so that Perl identifier naming conventions
64 don't dictate your command line interface.
65 • Osprey doesn't use an automatic module finder (like
67 Module::Pluggable) to locate modules for sub-commands; their names
68 are given explicitly. This small amount of additional typing gives
69 you more control and less fragility.
70 There are also a few things MooX::Options has that Osprey lacks. While
72 they may be added in the future, I haven't seen the need yet. Currently
73 known missing feeatures are JSON options, "config_from_file" support,
74 "autosplit", and "autorange".
75 For JSON support, you can use a coercion on the attribute, turning it
77 from a string to a ref via "decode_json".
78 To default an app's options from a config file, you may want to do
80 something like this in your script file:
81 use JSON 'decode_json';
83 use Path::Tiny;
84 MyApp->new_with_options(
86 map decode_json(path($_)->slurp),
87 grep -f,
88 "$ENV{HOME}/.myapprc"
89 )->run;
90 Provided that "prefer_commandline" is true (which is the default), any
92 options in ".myapprc" will be used as defaults if that file exists, but
93 will still be overrideable from the commandline.
94
96 The following methods, will be imported into a class that uses
97 CLI::Osprey:
98 new_with_options
100 Parses commandline arguments, validates them, and calls the "new"
101 method with the resulting parameters. Any parameters passed to
102 "new_with_options" will also be passed to "new"; the
103 "prefer_commandline" import option controls which overrides which.
104 option
106 The "option" keyword acts like "has" (and accepts all of the arguments
107 that "has" does), but also registers the attribute as a commandline
108 option. See "OPTION PARAMETERS" for usage.
109 osprey_usage($code, @messages)
111 Displays a short usage message, the same as if the app was invoked with
112 the "-h" option. Also displays the lines of text in @messages if any
113 are passed. If $code is passed a defined value, exits with that as a
114 status.
115 osprey_help($code)
117 Displays a more substantial usage message, the same as if the app was
118 invoked with the "--help" option. If $code is passed a defined value,
119 exits with that as a status.
120 osprey_man
122 Displays a manual page for the app, containing long descriptive text
123 (if provided) about each command and option, then exits.
124
126 The parameters to "use CLI::Osprey" serve two roles: to customize
127 Osprey's behavior, and to provide information about the app and its
128 options for use in the usage messages. They are:
129 abbreviate
131 Default: true.
132 If "abbreviate" is set to a true value, then long options can be
134 abbreviated to the point of uniqueness. That is, "--long-option-name"
135 can be called as "--lon" as long as there are no other options starting
136 with those letters. An option can always be called by its full name,
137 even if it is a prefix of some longer option's name. If "abbreviate" is
138 false, options must always be called by their full names (or by a
139 defined short name).
140 added_order
142 Default: true.
143 If "added_order" is set to a true value, then two options with the same
145 "order" (or none at all) will appear in the help text in the same order
146 as their "option" keywords were executed. If it is false, they will
147 appear in alphabetical order instead.
148 desc
150 Default: none.
151 A short description of the command, to be shown at the top of the
153 manual page, and in the listing of subcommands if this command is a
154 subcommand.
155 description_pod
157 Default: none.
158 A description, of any length, in POD format, to be included as the
160 "DESCRIPTION" section of the command's manual page.
161 extra_pod
163 Default: none.
164 Arbitrary extra POD to be included between the "DESCRIPTION" and
166 "OPTIONS" sections of the manual page.
167 getopt_options
169 Default: "['require_order']".
170 Contains a list of options to control option parsing behavior (see
172 "Configuring Getopt::Long" in Getopt::Long). Note, however, that many
173 of these are not helpful with Osprey, and that using "permute" will
174 likely break subcommands entirely. MooX::Options calls this parameter
175 "flavour".
176 prefer_commandline
178 Default: true.
179 If true, command-line options override key/value pairs passed to
181 "new_with_options". If false, the reverse is true.
182 preserve_argv
184 Default: false.
185 If true, the @ARGV array will be localized for the duration of
187 "new_with_options", and will be left in the same state after option
188 parsing as it was before. If false, the @ARGV array will be modified by
189 option parsing, removing any recognized options, values, and
190 subcommands, and leaving behind any positional parameters or anything
191 after and including a "--" separator.
192 usage_string
194 Default: "USAGE: $program_name %o"
195 Provides the header of the usage message printed in response to the
197 "-h" option or an error in option processing. The format of the string
198 is described in "$usage_desc" in Getopt::Long::Descriptive.
199 on_demand
201 Default: false
202 If set to a true value, the commands' modules won't be loaded at
204 compile time, but if the command is invoked. This is useful for
205 minimizing compile time if the application has a lot of commands or the
206 commands are on the heavy side. Note that enabling the feature may
207 interfere with the ability to fatpack the application.
208
210 doc
211 Default: None.
212 Documentation for the option, used in "--help" output. For best
214 results, should be no more than a short paragraph.
215 format
217 Default: None (i.e. boolean).
218 The format of the option argument, same as Getopt::Long. An option with
220 no format is a boolean, not taking an additional argument. Other
221 formats are:
222 s string
224 i decimal integer
226 o integer (supports "0x" for hex, "0b" for binary, and 0 for octal).
228 f floating-point number
230 format_doc
232 Default: depends on "format".
233 Describes the type of an option's argument. For example, if the string
235 option "copy-to" specifies a hostname, you can give it "format_doc =>
236 "hostname"" and it will display as "--copy-to hostname" in the help
237 text, instead of "--copy-to string".
238 hidden
240 Default: false.
241 A "hidden" option will be recognized, but not listed in automatically
243 generated documentation.
244 negatable
246 Default: false.
247 Adds the "--no-" version of the option, which sets it to a false value.
249 Equivalent to "!" in Getopt::Long.
250 option
252 Default: Same as the attribute name, with underscores replaced by
253 hyphens.
254 Allows the command-line option for an attribute to differ from the
256 attribute name -- like "init_arg" except for the commandline.
257 long_doc
259 Default: none.
260 Long documentation of the option for the manual page. This is POD, so
262 POD formatting is available, and paragraphs need to be separated by
263 "\n\n". If not provided, the short documentation will be used instead.
264 order
266 Default: None.
267 Allows controlling the order that options are listed in the help text.
269 Options without an order attribute are sorted by the order their
270 "option" statements are executed, if "added_order" is true, and by
271 alphabetical order otherwise. They are placed as though they had order
272 9999, so use small values to sort before automaticall-sorted options,
273 and values of 10000 and up to sort at the end.
274 repeatable
276 Default: false.
277 Allows an option to be specified more than once. When used on a
279 "boolean" option with no "format", each appearace of the option will
280 increment the value by 1 (equivalent to "+" in Getopt::Long. When used
281 on an option with arguments, produces an arrayref, one value per
282 appearance of the option.
283 required
285 Default: false.
286 This is a Moo/Moose feature honored by Osprey. A "required" attribute
288 must be passed on the commandline unless it's passed to the
289 constructor. Generated documentation will show the option as non-
290 optional.
291 short
293 Default: None.
294 Gives an option a single-character "short" form, e.g. "-v" for
296 "--verbose".
297 spacer_before
299 Default: false.
300 Causes a blank line to appear before this option in help output.
302 spacer_after
304 Default: false.
305 Causes a blank line to appear after this option in help output.
307
309 An Osprey command can have subcommands with their own options,
310 documentation, etc., allowing for complicated applications under the
311 roof of a single command. Osprey will parse the options for all of the
312 commands in the chain, and construct them in top-to-bottom order, with
313 each subcommand receiving a reference to its parent.
314 Subcommand Classes
316 A subcommand can be another class, which also uses "CLI::Osprey". For
317 example:
318 package MyApp;
320 use Moo;
321 use CLI::Osprey;
322 option verbose => (
324 is => 'ro',
325 short => 'v',
326 );
327 subcommand frobnicate => 'MyApp::Frobnicate';
329 package MyApp::Frobnicate;
331 use Moo;
332 use CLI::Osprey;
333 option target => (
335 is => 'ro',
336 format => 's',
337 );
338 sub run {
340 my ($self) = @_;
341 if ($self->parent_command->verbose) {
342 say "Be dangerous, and unpredictable... and make a lot of noise.";
343 }
344 $self->do_something_with($self->target);
345 }
346 Inline Subcommands
348 A subcommand can also be specified as a coderef, for when a separate
349 class would be excessive. For example:
350 package Greet;
352 use Moo;
353 use CLI::Osprey;
354 option target => (
356 is => 'ro',
357 default => "world",
358 );
359 subcommand hello => sub {
361 my ($self, $parent) = @_;
362 say "Hello ", $parent->target;
363 };
364 subcommand goodbye => sub {
366 my ($self, $parent) = @_;
367 say "Goodbye ", $parent->target;
368 };
369 which can be invoked as "greet --target world hello". Inline
371 subcommands are implemented using CLI::Osprey::InlineSubcommand.
372
374 This module is based heavily on code from MooX::Options and takes
375 strong inspiration from MooX::Cmd and MooX::Options::Actions. Thanks to
376 celogeek, Jens Reshack, Getty, Tom Bloor, and all contributors to those
377 modules. Thanks to mst for prodding me to do this. Thanks Grinnz for
378 helping me update my dzillage.
379
381 Andrew Rodland <arodland@cpan.org>
382
384 This software is copyright (c) 2020 by Andrew Rodland.
385 This is free software; you can redistribute it and/or modify it under
387 the same terms as the Perl 5 programming language system itself.
388perl v5.34.0 2021-07-22 CLI::Osprey(3pm)