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

NAME

6       App::Cmd - write command line apps with less suffering
7

VERSION

9       version 0.331
10

SYNOPSIS

12       in yourcmd:
13
14         use YourApp;
15         YourApp->run;
16
17       in YourApp.pm:
18
19         package YourApp;
20         use App::Cmd::Setup -app;
21         1;
22
23       in YourApp/Command/blort.pm:
24
25         package YourApp::Command::blort;
26         use YourApp -command;
27         use strict; use warnings;
28
29         sub abstract { "blortex algorithm" }
30
31         sub description { "Long description on blortex algorithm" }
32
33         sub opt_spec {
34           return (
35             [ "blortex|X",  "use the blortex algorithm" ],
36             [ "recheck|r",  "recheck all results"       ],
37           );
38         }
39
40         sub validate_args {
41           my ($self, $opt, $args) = @_;
42
43           # no args allowed but options!
44           $self->usage_error("No args allowed") if @$args;
45         }
46
47         sub execute {
48           my ($self, $opt, $args) = @_;
49
50           my $result = $opt->{blortex} ? blortex() : blort();
51
52           recheck($result) if $opt->{recheck};
53
54           print $result;
55         }
56
57       and, finally, at the command line:
58
59         knight!rjbs$ yourcmd blort --recheck
60
61         All blorts successful.
62

DESCRIPTION

64       App::Cmd is intended to make it easy to write complex command-line
65       applications without having to think about most of the annoying things
66       usually involved.
67
68       For information on how to start using App::Cmd, see App::Cmd::Tutorial.
69

METHODS

71   new
72         my $cmd = App::Cmd->new(\%arg);
73
74       This method returns a new App::Cmd object.  During initialization,
75       command plugins will be loaded.
76
77       Valid arguments are:
78
79         no_commands_plugin - if true, the command list plugin is not added
80
81         no_help_plugin     - if true, the help plugin is not added
82
83         no_version_plugin  - if true, the version plugin is not added
84
85         show_version_cmd -   if true, the version command will be shown in the
86                              command list
87
88         plugin_search_path - The path to search for commands in. Defaults to
89                              results of plugin_search_path method
90
91       If "no_commands_plugin" is not given, App::Cmd::Command::commands will
92       be required, and it will be registered to handle all of its command
93       names not handled by other plugins.
94
95       If "no_help_plugin" is not given, App::Cmd::Command::help will be
96       required, and it will be registered to handle all of its command names
97       not handled by other plugins. Note: "help" is the default command, so
98       if you do not load the default help plugin, you should provide your own
99       or override the "default_command" method.
100
101       If "no_version_plugin" is not given, App::Cmd::Command::version will be
102       required to show the application's version with command "--version". By
103       default, the version command is not included in the command list. Pass
104       "show_version_cmd" to include the version command in the list.
105
106   run
107         $cmd->run;
108
109       This method runs the application.  If called the class, it will
110       instantiate a new App::Cmd object to run.
111
112       It determines the requested command (generally by consuming the first
113       command-line argument), finds the plugin to handle that command, parses
114       the remaining arguments according to that plugin's rules, and runs the
115       plugin.
116
117       It passes the contents of the global argument array (@ARGV) to
118       ""prepare_command"", but @ARGV is not altered by running an App::Cmd.
119
120   prepare_args
121       Normally App::Cmd uses @ARGV for its commandline arguments. You can
122       override this method to change that behavior for testing or otherwise.
123
124   default_args
125       If "prepare_args" is not changed and there are no arguments in @ARGV,
126       this method is called and should return an arrayref to be used as the
127       arguments to the program.  By default, it returns an empty arrayref.
128
129   abstract
130          sub abstract { "command description" }
131
132       Defines the command abstract: a short description that will be printed
133       in the main command options list.
134
135   description
136          sub description { "Long description" }
137
138       Defines a longer command description that will be shown when the user
139       asks for help on a specific command.
140
141   arg0
142   full_arg0
143         my $program_name = $app->arg0;
144
145         my $full_program_name = $app->full_arg0;
146
147       These methods return the name of the program invoked to run this
148       application.  This is determined by inspecting $0 when the App::Cmd
149       object is instantiated, so it's probably correct, but doing weird
150       things with App::Cmd could lead to weird values from these methods.
151
152       If the program was run like this:
153
154         knight!rjbs$ ~/bin/rpg dice 3d6
155
156       Then the methods return:
157
158         arg0      - rpg
159         full_arg0 - /Users/rjbs/bin/rpg
160
161       These values are captured when the App::Cmd object is created, so it is
162       safe to assign to $0 later.
163
164   prepare_command
165         my ($cmd, $opt, @args) = $app->prepare_command(@ARGV);
166
167       This method will load the plugin for the requested command, use its
168       options to parse the command line arguments, and eventually return
169       everything necessary to actually execute the command.
170
171   default_command
172       This method returns the name of the command to run if none is given on
173       the command line.  The default default is "help"
174
175   execute_command
176         $app->execute_command($cmd, \%opt, @args);
177
178       This method will invoke "validate_args" and then "run" on $cmd.
179
180   plugin_search_path
181       This method returns the plugin_search_path as set.  The default
182       implementation, if called on "YourApp::Cmd" will return
183       "YourApp::Cmd::Command"
184
185       This is a method because it's fun to override it with, for example:
186
187         use constant plugin_search_path => __PACKAGE__;
188
189   allow_any_unambiguous_abbrev
190       If this method returns true (which, by default, it does not), then any
191       unambiguous abbreviation for a registered command name will be allowed
192       as a means to use that command.  For example, given the following
193       commands:
194
195         reticulate
196         reload
197         rasterize
198
199       Then the user could use "ret" for "reticulate" or "ra" for "rasterize"
200       and so on.
201
202   global_options
203         if ($cmd->app->global_options->{verbose}) { ... }
204
205       This method returns the running application's global options as a
206       hashref.  If there are no options specified, an empty hashref is
207       returned.
208
209   set_global_options
210         $app->set_global_options(\%opt);
211
212       This method sets the global options.
213
214   command_names
215         my @names = $cmd->command_names;
216
217       This returns the commands names which the App::Cmd object will handle.
218
219   command_groups
220         my @groups = $cmd->commands_groups;
221
222       This method can be implemented to return a grouped list of command
223       names with optional headers. Each group is given as arrayref and each
224       header as string.  If an empty list is returned, the commands plugin
225       will show two groups without headers: the first group is for the "help"
226       and "commands" commands, and all other commands are in the second
227       group.
228
229   command_plugins
230         my @plugins = $cmd->command_plugins;
231
232       This method returns the package names of the plugins that implement the
233       App::Cmd object's commands.
234
235   plugin_for
236         my $plugin = $cmd->plugin_for($command);
237
238       This method returns the plugin (module) for the given command.  If no
239       plugin implements the command, it returns false.
240
241   get_command
242         my ($command_name, $opt, @args) = $app->get_command(@args);
243
244       Process arguments and into a command name and (optional) global
245       options.
246
247   usage
248         print $self->app->usage->text;
249
250       Returns the usage object for the global options.
251
252   usage_desc
253       The top level usage line. Looks something like
254
255         "yourapp <command> [options]"
256
257   global_opt_spec
258       Returns a list with help command unless "no_help_plugin" has been
259       specified or an empty list. Can be overridden for pre-dispatch option
260       processing.  This is useful for flags like --verbose.
261
262   usage_error
263         $self->usage_error("Something's wrong!");
264
265       Used to die with nice usage output, during "validate_args".
266

TODO

268       ·   publish and bring in Log::Speak (simple quiet/verbose output)
269
270       ·   publish and use our internal enhanced describe_options
271
272       ·   publish and use our improved simple input routines
273

AUTHOR

275       Ricardo Signes <rjbs@cpan.org>
276

CONTRIBUTORS

278       ·   Adam Prime <aprime@oanda.com>
279
280       ·   ambs <ambs@cpan.org>
281
282       ·   Andreas Hernitscheck <andreash@lxhe.(none)>
283
284       ·   A. Sinan Unur <nanis@cpan.org>
285
286       ·   Chris 'BinGOs' Williams <chris@bingosnet.co.uk>
287
288       ·   David Golden <dagolden@cpan.org>
289
290       ·   David Steinbrunner <dsteinbrunner@pobox.com>
291
292       ·   Davor Cubranic <cubranic@stat.ubc.ca>
293
294       ·   Denis Ibaev <dionys@gmail.com>
295
296       ·   Diab Jerius <djerius@cfa.harvard.edu>
297
298       ·   Glenn Fowler <cebjyre@cpan.org>
299
300       ·   Ingy dot Net <ingy@ingy.net>
301
302       ·   Jakob Voss <jakob@nichtich.de>
303
304       ·   Jakob Voss <voss@gbv.de>
305
306       ·   Jérôme Quelin <jquelin@gmail.com>
307
308       ·   John SJ Anderson <genehack@genehack.org>
309
310       ·   Karen Etheridge <ether@cpan.org>
311
312       ·   Kent Fredric <kentfredric@gmail.com>
313
314       ·   Matthew Astley <mca@sanger.ac.uk>
315
316       ·   mokko <mauricemengel@gmail.com>
317
318       ·   Olivier Mengué <dolmen@cpan.org>
319
320       ·   Ricardo SIGNES <rjbs@codesimply.com>
321
322       ·   Ryan C. Thompson <rct@thompsonclan.org>
323
324       ·   Salvatore Bonaccorso <carnil@debian.org>
325
326       ·   Sergey Romanov <sromanov-dev@yandex.ru>
327
328       ·   Stephen Caldwell <steve@campusexplorer.com>
329
330       ·   Yuval Kogman <nuffin@cpan.org>
331
333       This software is copyright (c) 2016 by Ricardo Signes.
334
335       This is free software; you can redistribute it and/or modify it under
336       the same terms as the Perl 5 programming language system itself.
337
338
339
340perl v5.30.1                      2020-01-29                       App::Cmd(3)
Impressum