MooseX::App(3pm)

1MooseX::App(3)        User Contributed Perl Documentation       MooseX::App(3)
2
3
4

NAME

6       MooseX::App - Write user-friendly command line apps with even less
7       suffering
8

SYNOPSIS

10       In your base class:
11
12         package MyApp;
13         use MooseX::App qw(Color);
14
15         option 'global_option' => (
16             is            => 'rw',
17             isa           => 'Bool',
18             documentation => q[Enable this to do fancy stuff],
19         ); # Global option
20
21         has 'private' => (
22             is              => 'rw',
23         ); # not exposed
24
25       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
29         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
33         # 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
41         option 'some_option' => (
42             is            => 'rw',
43             isa           => 'Int',
44             required      => 1,
45             documentation => q[Very important option!],
46         ); # Option
47
48         sub run {
49             my ($self) = @_;
50             # Do something
51         }
52
53       And then you need a simple wrapper script (called eg. myapp):
54
55        #!/usr/bin/env perl
56        use MyApp;
57        MyApp->new_with_command->run;
58
59       On the command line:
60
61        bash$ myapp help
62        usage:
63            myapp <command> [long options...]
64            myapp help
65
66        global options:
67            --global_option    Enable this to do fancy stuff [Flag]
68            --help --usage -?  Prints this usage information. [Flag]
69
70        available commands:
71            some_command    Description of some command
72            another_command Description of another command
73            help            Prints this usage information
74
75       or
76
77        bash$ myapp some_command --help
78        usage:
79            myapp some_command <SOME_PARAMETER> [long options...]
80            myapp help
81            myapp some_command --help
82
83        parameters:
84            some_parameter     Some parameter that you need to supply [Required]
85
86        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

DESCRIPTION

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
100       MooseX-App will then
101
102       ·   Find, load and initialise the command classes (see
103           MooseX::App::Simple for single class/command applications)
104
105       ·   Create automated help and documentation from modules POD as well as
106           attributes metadata and type constraints
107
108       ·   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
113       ·   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
117       Commandline options are defined using the 'option' keyword which
118       accepts the same attributes as Moose' 'has' keyword.
119
120         option 'some_option' => (
121             is            => 'rw',
122             isa           => 'Str',
123         );
124
125       This is equivalent to
126
127         has 'some_option' => (
128             is            => 'rw',
129             isa           => 'Str',
130             traits        => ['AppOption'],   # Load extra metaclass
131             cmd_type      => 'option',        # Set attribute type
132         );
133
134       Single letter options are treated as flags and may be combined with
135       eachother.  However such options must have a Boolean type constraint.
136
137        option 'verbose' => (
138             is            => 'rw',
139             isa           => 'Bool',
140             cmd_flag      => 'v',
141         );
142
143       Positional parameters are defined with the 'parameter' keyword
144
145         parameter 'some_option' => (
146             is            => 'rw',
147             isa           => 'Str',
148         );
149
150       This is equivalent to
151
152         has 'some_option' => (
153             is            => 'rw',
154             isa           => 'Str',
155             traits        => ['AppOption'],
156             cmd_type      => 'parameter',
157         );
158
159       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
163       Furthermore, all options and parameters can also be supplied via %ENV
164
165         option 'some_option' => (
166             is            => 'rw',
167             isa           => 'Str',
168             cmd_env       => 'SOME_OPTION', # sets the env key
169         );
170
171       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
175       ·   ArrayRef: Specify multiple values ('--opt value1 --opt value2',
176           also see app_permute and cmd_split)
177
178       ·   HashRef: Specify multiple key value pairs ('--opt key=value --opt
179           key2=value2', also see app_permute)
180
181       ·   Enum: Display all possibilities
182
183       ·   Bool: Flags that do not require values
184
185       ·   Int, Num: Used for proper error messages
186
187       Read the Tutorial for getting started with a simple MooseX::App command
188       line application.
189

METHODS

191   new_with_command
192        my $myapp_command = MyApp->new_with_command();
193
194       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
198       You can pass a hash of default/fallback params to new_with_command
199
200        my $obj = MyApp->new_with_command(%default);
201
202       Optionally you can pass a custom ARGV to this constructor
203
204        my $obj = MyApp->new_with_command( ARGV => \@myARGV );
205
206       However, if you do so you must take care of propper @ARGV encoding
207       yourself.
208
209   initialize_command_class
210        my $obj = MyApp->initialize_command_class($command_name,%default);
211
212       Helper method to instantiate the command class for the given command.
213

GLOBAL OPTIONS

215       These options may be used to alter the default behaviour of MooseX-App.
216
217   app_base
218        app_base 'my_script'; # Defaults to $0
219
220       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
224   app_fuzzy
225        app_fuzzy 1; # default
226        OR
227        app_fuzzy 0;
228
229       Enables fuzzy matching of commands and attributes. Is turned on by
230       default.
231
232   app_strict
233        app_strict 0; # default
234        OR
235        app_strict 1;
236
237       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
243       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
246   app_prefer_commandline
247        app_prefer_commandline 0; # default
248        or
249        app_prefer_commandline 1;
250
251       Specifies if parameters/options supplied via @ARGV,%ENV should take
252       precedence over arguments passed directly to new_with_command.
253
254   app_namespace
255        app_namespace 'MyApp::Commands', 'YourApp::MoreCommands';
256        OR
257        app_namespace();
258
259       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
263       If app_namespace is called with no arguments then autoloading of
264       command classes will be disabled entirely.
265
266   app_exclude
267        app_exclude 'MyApp::Commands::Roles','MyApp::Commands::Utils';
268
269       A sub namespace included via app_namespace (or the default behaviour)
270       can be excluded using app_exclude.
271
272   app_command_name
273        app_command_name {
274            my ($package_short,$package_full) = @_;
275            # munge package name;
276            return $command_name;
277        };
278
279       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
283   app_command_register
284        app_command_register
285           do      => 'MyApp::Commands::DoSomething',
286           undo    => 'MyApp::Commands::UndoSomething';
287
288       This keyword can be used to register additional commands. Especially
289       useful in conjunction with app_namespace and disabled autoloading.
290
291   app_description
292        app_description qq[Description text];
293
294       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
298   app_usage
299        app_usage qq[myapp --option ...];
300
301       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
306   app_permute
307        app_permute 0; # default
308        OR
309        app_permute 1;
310
311       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

GLOBAL ATTRIBUTES

317       All MooseX::App classes will have two extra attributes
318
319   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
324   help_flag
325       Help flag that is set when help was requested.
326

ATTRIBUTE OPTIONS

328       Options and parameters accept extra attributes for customisation:
329
330       ·   cmd_tags - Extra tags (as used by the help)
331
332       ·   cmd_flag - Override option/parameter name
333
334       ·   cmd_aliases - Additional option/parameter name aliases
335
336       ·   cmd_split - Split values into ArrayRefs on this token
337
338       ·   cmd_position - Specify option/parameter order in help
339
340       ·   cmd_env - Read options/parameters from %ENV
341
342       ·   cmd_count - Value of option equals to number of occurrences in
343           @ARGV
344
345       ·   cmd_negate - Adds an option to negate boolean flags
346
347       Refer to MooseX::App::Meta::Role::Attribute::Option for detailed
348       documentation.
349

METADATA

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
355       ·   Package names
356
357       ·   required options for Moose attributes
358
359       ·   documentation options for Moose attributes
360
361       ·   Moose type constraints (Bool, ArrayRef, HashRef, Int, Num, and
362           Enum)
363
364       ·   Documentation set via app_description, app_usage,
365           command_short_description, command_long_description and
366           command_usage
367
368       ·   POD (NAME, ABSTRACT, DESCRIPTION, USAGE, SYNOPSIS, OVERVIEW,
369           COPYRIGHT, LICENSE, COPYRIGHT AND LICENSE, AUTHOR and AUTHORS
370           sections)
371
372       ·   Dzil ABSTRACT tag if no POD is available yet
373

PLUGINS

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
379        use MooseX::App qw(PluginA PluginB);
380
381       Currently the following plugins are shipped with MooseX::App
382
383       ·   MooseX::App::Plugin::BashCompletion
384
385           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
389       ·   MooseX::App::Plugin::Color
390
391           Colorful output for your MooseX::App applications.
392
393       ·   MooseX::App::Plugin::Config
394
395           Config files for MooseX::App applications.
396
397       ·   MooseX::App::Plugin::ConfigHome
398
399           Try to find config files in users home directory.
400
401       ·   MooseX::App::Plugin::Term
402
403           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
407       ·   MooseX::App::Plugin::Typo
408
409           Handle typos in command names and provide suggestions.
410
411       ·   MooseX::App::Plugin::Version
412
413           Adds a command to display the version and license of your
414           application.
415
416       ·   MooseX::App::Plugin::Man
417
418           Display full manpage of application and commands.
419
420       ·   MooseX::App::Plugin::MutexGroup
421
422           Allow for mutally exclusive options.
423
424       ·   MooseX::App::Plugin::Depends
425
426           Adds dependent options.
427
428       Refer to Writing MooseX-App Plugins for documentation on how to create
429       your own plugins.
430

CAVEATS & KNOWN BUGS

432       Startup time may be an issue - escpecially if you load many plugins. If
433       you do not require the functionality of plugins and ability for fine
434       grained customisation (or Moose for that matter) then you should
435       probably use MooX::Options or MooX::Cmd.
436
437       In some cases - especially when using non-standard class inheritance -
438       you may end up with command classes lacking the help attribute. In this
439       case you need to include the following line in your base class or
440       command classes.
441
442        with qw(MooseX::App::Role::Common);
443
444       When manually registering command classes (eg. via
445       app_command_register) in multiple base classes with different sets of
446       plugins (why would you ever want to do that?), then meta attributes may
447       lack some attribute metaclasses. In this case you need to load the
448       missing attribute traits explicitly:
449
450        option 'argument' => (
451           depends => 'otherargument',
452           trait   => ['MooseX::App::Plugin::Depends::Meta::Attribute'], # load trait
453        );
454

SUPPORT

464       Please report any bugs or feature requests via
465       <https://github.com/maros/MooseX-App/issues/new>. I will be notified,
466       and then you'll automatically be notified of progress on your report as
467       I make changes.
468

AUTHOR

470           Maroš Kollár
471           CPAN ID: MAROS
472           maros [at] k-1.com
473
474           http://www.k-1.com
475

CONTRIBUTORS

477       Special thanks to all contributors.
478
479       In no particular order: Andrew Jones, George Hartzell, Steve Nolte,
480       Michael G, Thomas Klausner, Yanick Champoux, Edward Baudrez, David
481       Golden, J.R. Mash, Thilo Fester, Gregor Herrmann, Sergey Romanov,
482       Sawyer X, Roman F., Hunter McMillen, Maik Hentsche, Alexander Stoddard,
483       Marc Logghe, Tina Müller, Lisa Hare
484
485       You are more than welcome to contribute to MooseX-App. Please have a
486       look at the
487       <https://github.com/maros/MooseX-App/issues?q=is%3Aissue+is%3Aopen+label%3AWishlist>
488       list of open wishlist issues for ideas.
489

COPYRIGHT

491       MooseX::App is Copyright (c) 2012-17 Maroš Kollár.
492
493       This library is free software and may be distributed under the same
494       terms as perl itself. The full text of the licence can be found in the
495       LICENCE file included with this module.
496
497
498
499perl v5.28.0                      2017-09-24                    MooseX::App(3)