1MooseX::App(3) User Contributed Perl Documentation MooseX::App(3)
2
6 MooseX::App - Write user-friendly command line apps with even less
7 suffering
8
10 In your base class:
11 package MyApp;
13 use MooseX::App qw(Color);
14 option 'global_option' => (
16 is => 'rw',
17 isa => 'Bool',
18 documentation => q[Enable this to do fancy stuff],
19 ); # Global option
20 has 'private' => (
22 is => 'rw',
23 ); # not exposed
24 Write multiple command classes (If you have only a single command class
26 you should use MooseX::App::Simple instead). Packackes in the namespace
27 may be deeply nested.
28 package MyApp::SomeCommand;
30 use MooseX::App::Command; # important (also imports Moose)
31 extends qw(MyApp); # optional, only if you want to use global options from base class
32 # Positional parameter
34 parameter 'some_parameter' => (
35 is => 'rw',
36 isa => 'Str',
37 required => 1,
38 documentation => q[Some parameter that you need to supply],
39 );
40 option 'some_option' => (
42 is => 'rw',
43 isa => 'Int',
44 required => 1,
45 documentation => q[Very important option!],
46 ); # Option
47 sub run {
49 my ($self) = @_;
50 # Do something
51 }
52 And then you need a simple wrapper script (called eg. myapp):
54 #!/usr/bin/env perl
56 use MyApp;
57 MyApp->new_with_command->run;
58 On the command line:
60 bash$ myapp help
62 usage:
63 myapp <command> [long options...]
64 myapp help
65 global options:
67 --global_option Enable this to do fancy stuff [Flag]
68 --help --usage -? Prints this usage information. [Flag]
69 available commands:
71 some_command Description of some command
72 another_command Description of another command
73 help Prints this usage information
74 or
76 bash$ myapp some_command --help
78 usage:
79 myapp some_command <SOME_PARAMETER> [long options...]
80 myapp help
81 myapp some_command --help
82 parameters:
84 some_parameter Some parameter that you need to supply [Required]
85 options:
87 --global_option Enable this to do fancy stuff [Flag]
88 --some_option Very important option! [Int,Required]
89 --help --usage -? Prints this usage information. [Flag]
90
92 MooseX-App is a highly customisable helper to write user-friendly
93 command line applications without having to worry about most of the
94 annoying things usually involved. Just take any existing Moose class,
95 add a single line ("use MooseX-App qw(PluginA PluginB ...);") and
96 create one class for each command in an underlying namespace. Options
97 and positional parameters can be defined as simple Moose accessors
98 using the "option" and "parameter" keywords respectively.
99 MooseX-App will then
101 • Find, load and initialise the command classes (see
103 MooseX::App::Simple for single class/command applications)
104 • Create automated help and documentation from modules POD as well as
106 attributes metadata and type constraints
107 • Read, encode and validate the command line options and positional
109 parameters entered by the user from @ARGV and %ENV (and possibly
110 prompt the user for additional parameters see
111 MooseX::App::Plugin::Term)
112 • Provide helpful error messages if user input cannot be validated
114 (either missing or wrong attributes or Moose type constraints not
115 satisfied) or if the user requests help.
116 Commandline options are defined using the 'option' keyword which
118 accepts the same attributes as Moose' 'has' keyword.
119 option 'some_option' => (
121 is => 'rw',
122 isa => 'Str',
123 );
124 This is equivalent to
126 has 'some_option' => (
128 is => 'rw',
129 isa => 'Str',
130 traits => ['AppOption'], # Load extra metaclass
131 cmd_type => 'option', # Set attribute type
132 );
133 Single letter options are treated as flags and may be combined with
135 each other. However such options must have a Boolean type constraint.
136 option 'verbose' => (
138 is => 'rw',
139 isa => 'Bool',
140 cmd_flag => 'v',
141 );
142 Positional parameters are defined with the 'parameter' keyword
144 parameter 'some_option' => (
146 is => 'rw',
147 isa => 'Str',
148 );
149 This is equivalent to
151 has 'some_option' => (
153 is => 'rw',
154 isa => 'Str',
155 traits => ['AppOption'],
156 cmd_type => 'parameter',
157 );
158 All keywords are imported by Moosex::App (in the app base class) and
160 MooseX::App::Command (in the command class) or MooseX::App::Simple
161 (single class application).
162 Furthermore, all options and parameters can also be supplied via %ENV
164 option 'some_option' => (
166 is => 'rw',
167 isa => 'Str',
168 cmd_env => 'SOME_OPTION', # sets the env key
169 );
170 Moose type constraints help MooseX::App to construct helpful error
172 messages and parse @ARGV in a meaningful way. The following type
173 constraints are supported:
174 • ArrayRef: Specify multiple values ('--opt value1 --opt value2',
176 also see app_permute and cmd_split)
177 • HashRef: Specify multiple key value pairs ('--opt key=value --opt
179 key2=value2', also see app_permute)
180 • Enum: Display all possibilities
182 • Bool: Flags that do not require values
184 • Int, Num: Used for proper error messages
186 Read the Tutorial for getting started with a simple MooseX::App command
188 line application.
189
191 new_with_command
192 my $myapp_command = MyApp->new_with_command();
193 This constructor reads the command line arguments and tries to create a
195 command class instance. If it fails it returns a
196 MooseX::App::Message::Envelope object holding an error message.
197 You can pass a hash of default/fallback params to new_with_command
199 my $obj = MyApp->new_with_command(%default);
201 Optionally you can pass a custom ARGV to this constructor
203 my $obj = MyApp->new_with_command( ARGV => \@myARGV );
205 However, if you do so you must take care of propper @ARGV encoding
207 yourself.
208 initialize_command_class
210 my $obj = MyApp->initialize_command_class($command_name,%default);
211 Helper method to instantiate the command class for the given command.
213
215 These options may be used to alter the default behaviour of MooseX-App.
216 app_base
218 app_base 'my_script'; # Defaults to $0
219 Usually MooseX::App will take the name of the calling wrapper script to
221 construct the program name in various help messages. This name can be
222 changed via the app_base function.
223 app_fuzzy
225 app_fuzzy 1; # default
226 OR
227 app_fuzzy 0;
228 Enables fuzzy matching of commands and attributes. Is turned on by
230 default.
231 app_strict
233 app_strict 0; # default
234 OR
235 app_strict 1;
236 If strict is enabled the program will terminate with an error message
238 if superfluous/unknown positional parameters are supplied. If disabled
239 all extra parameters will be copied to the extra_argv attribute.
240 Unknown options (with leading dashes) will always yield an error
241 message.
242 The command_strict config in the command classes allows one to set this
244 option individually for each command in the respective command class.
245 app_prefer_commandline
247 app_prefer_commandline 0; # default
248 or
249 app_prefer_commandline 1;
250 Specifies if parameters/options supplied via @ARGV,%ENV should take
252 precedence over arguments passed directly to new_with_command.
253 app_namespace
255 app_namespace 'MyApp::Commands', 'YourApp::MoreCommands';
256 OR
257 app_namespace();
258 Usually MooseX::App will take the package name of the base class as the
260 namespace for commands. This namespace can be changed and you can add
261 multiple extra namespaces.
262 If app_namespace is called with no arguments then autoloading of
264 command classes will be disabled entirely.
265 app_exclude
267 app_exclude 'MyApp::Commands::Roles','MyApp::Commands::Utils';
268 A sub namespace included via app_namespace (or the default behaviour)
270 can be excluded using app_exclude.
271 app_command_name
273 app_command_name {
274 my ($package_short,$package_full) = @_;
275 # munge package name;
276 return $command_name;
277 };
278 This coderef can be used to control how autoloaded package names should
280 be translated to command names. If this command returns nothing the
281 respective command class will be skipped and not loaded.
282 app_command_register
284 app_command_register
285 do => 'MyApp::Commands::DoSomething',
286 undo => 'MyApp::Commands::UndoSomething';
287 This keyword can be used to register additional commands. Especially
289 useful in conjunction with app_namespace and disabled autoloading.
290 app_description
292 app_description qq[Description text];
293 Set the app description text. If not set this information will be taken
295 from the Pod DESCRIPTION or OVERVIEW sections. (see command_description
296 to set usage per command)
297 app_usage
299 app_usage qq[myapp --option ...];
300 Set a custom usage text. If not set this will be taken from the Pod
302 SYNOPSIS or USAGE section. If both sections are not available, the
303 usage information will be autogenerated. (see command_usage to set
304 usage per command)
305 app_permute
307 app_permute 0; # default
308 OR
309 app_permute 1;
310 Allows one to specify multiple values with one key. So instead of
312 writing "--list element1 --list element2 --list element3" one might
313 write "--list element1 element2 element3" for ArrayRef elements.
314 HashRef elements may be expressed as "--hash key=value key2=value2".
315
317 All MooseX::App classes will have two extra attributes
318 extra_argv
320 Carries all parameters from @ARGV that were not consumed (only if
321 app_strict is turned off, otherwise superfluous parameters will raise
322 an exception).
323 help_flag
325 Help flag that is set when help was requested.
326
328 Options and parameters accept extra attributes for customisation:
329 • cmd_tags - Extra tags (as used by the help)
331 • cmd_flag - Override option/parameter name
333 • cmd_aliases - Additional option/parameter name aliases
335 • cmd_split - Split values into ArrayRefs on this token or RegEx
337 • cmd_position - Specify option/parameter order in help
339 • cmd_env - Read options/parameters from %ENV
341 • cmd_count - Value of option equals to number of occurrences in
343 @ARGV
344 • cmd_negate - Adds an option to negate boolean flags
346 Refer to MooseX::App::Meta::Role::Attribute::Option for detailed
348 documentation.
349
351 MooseX::App will use your class metadata and POD to construct the
352 commands and helpful error- or usage-messages. These bits of
353 information are utilised and should be provided if possible:
354 • Package names
356 • required options for Moose attributes
358 • documentation options for Moose attributes
360 • Moose type constraints (Bool, ArrayRef, HashRef, Int, Num, and
362 Enum)
363 • Documentation set via app_description, app_usage,
365 command_short_description, command_long_description and
366 command_usage
367 • POD (NAME, ABSTRACT, DESCRIPTION, USAGE, SYNOPSIS, OVERVIEW,
369 COPYRIGHT, LICENSE, COPYRIGHT AND LICENSE, AUTHOR and AUTHORS
370 sections)
371 • Dist::Zilla ABSTRACT tag if no POD is available yet
373
375 The behaviour of MooseX-App can be customised with plugins. To load a
376 plugin just pass a list of plugin names after the "use MooseX-App"
377 statement. (Attention: order sometimes matters)
378 use MooseX::App qw(PluginA PluginB);
380 Currently the following plugins are shipped with MooseX::App
382 • MooseX::App::Plugin::BashCompletion
384 Adds a command that generates a bash completion script for your
386 application. See third party MooseX::App::Plugin::ZshCompletion
387 for Z shell completion.
388 • MooseX::App::Plugin::Color
390 Colorful output for your MooseX::App applications.
392 • MooseX::App::Plugin::Config
394 Config files for MooseX::App applications.
396 • MooseX::App::Plugin::ConfigHome
398 Try to find config files in users home directory.
400 • MooseX::App::Plugin::Term
402 Prompt user for options and parameters that were not provided via
404 options or params. Prompt offers basic editing capabilities and
405 non-persistent history.
406 • MooseX::App::Plugin::Typo
408 Handle typos in command names and provide suggestions.
410 • MooseX::App::Plugin::Version
412 Adds a command to display the version and license of your
414 application.
415 • MooseX::App::Plugin::Man
417 Display full manpage of application and commands.
419 • MooseX::App::Plugin::MutexGroup
421 Allow for mutally exclusive options.
423 • MooseX::App::Plugin::Depends
425 Adds dependent options.
427 Refer to Writing MooseX-App Plugins for documentation on how to create
429 your own plugins.
430
432 Make sure to invoke your script with APP_DEVELOPER=1 ser during
433 development. This will come with a starup penalty but perform
434 additional checks for detecting wrong attribute/type constraint
435 combinations, name clashes, ...
436
438 Startup time may be an issue - escpecially if you load many plugins. If
439 you do not require the functionality of plugins and ability for fine
440 grained customisation (or Moose for that matter) then you should
441 probably use MooX::Options or MooX::Cmd.
442 In some cases - especially when using non-standard class inheritance -
444 you may end up with command classes lacking the help attribute. In this
445 case you need to include the following line in your base class or
446 command classes.
447 with qw(MooseX::App::Role::Common);
449 When manually registering command classes (eg. via
451 app_command_register) in multiple base classes with different sets of
452 plugins (why would you ever want to do that?), then meta attributes may
453 lack some attribute metaclasses. In this case you need to load the
454 missing attribute traits explicitly:
455 option 'argument' => (
457 depends => 'otherargument',
458 trait => ['MooseX::App::Plugin::Depends::Meta::Attribute'], # load trait
459 );
460
462 Read the Tutorial for getting started with a simple MooseX::App command
463 line application.
464 For alternatives you can check out
466 MooseX::App::Cmd, MooseX::Getopt, MooX::Options, MooX::Cmd and App::Cmd
468
470 Please report any bugs or feature requests via
471 <https://github.com/maros/MooseX-App/issues/new>. I will be notified,
472 and then you'll automatically be notified of progress on your report as
473 I make changes.
474
476 Maroš Kollár
477 CPAN ID: MAROS
478 maros [at] k-1.com
479 http://www.k-1.com
481
483 Special thanks to all contributors.
484 In no particular order: Andrew Jones, George Hartzell, Steve Nolte,
486 Michael G, Thomas Klausner, Yanick Champoux, Edward Baudrez, David
487 Golden, J.R. Mash, Thilo Fester, Gregor Herrmann, Sergey Romanov,
488 Sawyer X, Roman F., Hunter McMillen, Maik Hentsche, Alexander Stoddard,
489 Marc Logghe, Tina Müller, Lisa Hare, Jose Luis Martinez, Frank
490 Schreiner
491 You are more than welcome to contribute to MooseX-App. Please have a
493 look at the
494 <https://github.com/maros/MooseX-App/issues?q=is%3Aissue+is%3Aopen+label%3AWishlist>
495 list of open wishlist issues for ideas.
496
498 MooseX::App is Copyright (c) 2012-21 Maroš Kollár.
499 This library is free software and may be distributed under the same
501 terms as perl itself. The full text of the licence can be found in the
502 LICENCE file included with this module.
503perl v5.38.0 2023-08-08 MooseX::App(3)