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

PERL VERSION SUPPORT

71       This module has a long-term perl support period.  That means it will
72       not require a version of perl released fewer than five years ago.
73
74       Although it may work on older versions of perl, no guarantee is made
75       that the minimum required version will not be increased.  The version
76       may be increased for any reason, and there is no promise that patches
77       will be accepted to lower the minimum required perl.
78

METHODS

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

TODO

277       •   publish and bring in Log::Speak (simple quiet/verbose output)
278
279       •   publish and use our internal enhanced describe_options
280
281       •   publish and use our improved simple input routines
282

AUTHOR

284       Ricardo Signes <rjbs@semiotic.systems>
285

CONTRIBUTORS

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