1App::Cmd(3) User Contributed Perl Documentation App::Cmd(3)
2
6 App::Cmd - write command line apps with less suffering
7
9 version 0.334
10
12 in yourcmd:
13 use YourApp;
15 YourApp->run;
16 in YourApp.pm:
18 package YourApp;
20 use App::Cmd::Setup -app;
21 1;
22 in YourApp/Command/blort.pm:
24 package YourApp::Command::blort;
26 use YourApp -command;
27 use strict; use warnings;
28 sub abstract { "blortex algorithm" }
30 sub description { "Long description on blortex algorithm" }
32 sub opt_spec {
34 return (
35 [ "blortex|X", "use the blortex algorithm" ],
36 [ "recheck|r", "recheck all results" ],
37 );
38 }
39 sub validate_args {
41 my ($self, $opt, $args) = @_;
42 # no args allowed but options!
44 $self->usage_error("No args allowed") if @$args;
45 }
46 sub execute {
48 my ($self, $opt, $args) = @_;
49 my $result = $opt->{blortex} ? blortex() : blort();
51 recheck($result) if $opt->{recheck};
53 print $result;
55 }
56 and, finally, at the command line:
58 knight!rjbs$ yourcmd blort --recheck
60 All blorts successful.
62
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 For information on how to start using App::Cmd, see App::Cmd::Tutorial.
69
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 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
80 new
81 my $cmd = App::Cmd->new(\%arg);
82 This method returns a new App::Cmd object. During initialization,
84 command plugins will be loaded.
85 Valid arguments are:
87 no_commands_plugin - if true, the command list plugin is not added
89 no_help_plugin - if true, the help plugin is not added
91 no_version_plugin - if true, the version plugin is not added
93 show_version_cmd - if true, the version command will be shown in the
95 command list
96 plugin_search_path - The path to search for commands in. Defaults to
98 results of plugin_search_path method
99 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 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 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 run
116 $cmd->run;
117 This method runs the application. If called the class, it will
119 instantiate a new App::Cmd object to run.
120 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 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 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 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 abstract
139 sub abstract { "command description" }
140 Defines the command abstract: a short description that will be printed
142 in the main command options list.
143 description
145 sub description { "Long description" }
146 Defines a longer command description that will be shown when the user
148 asks for help on a specific command.
149 arg0
151 full_arg0
152 my $program_name = $app->arg0;
153 my $full_program_name = $app->full_arg0;
155 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 If the program was run like this:
162 knight!rjbs$ ~/bin/rpg dice 3d6
164 Then the methods return:
166 arg0 - rpg
168 full_arg0 - /Users/rjbs/bin/rpg
169 These values are captured when the App::Cmd object is created, so it is
171 safe to assign to $0 later.
172 prepare_command
174 my ($cmd, $opt, @args) = $app->prepare_command(@ARGV);
175 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 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 execute_command
185 $app->execute_command($cmd, \%opt, @args);
186 This method will invoke "validate_args" and then "run" on $cmd.
188 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 This is a method because it's fun to override it with, for example:
195 use constant plugin_search_path => __PACKAGE__;
197 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 reticulate
205 reload
206 rasterize
207 Then the user could use "ret" for "reticulate" or "ra" for "rasterize"
209 and so on.
210 global_options
212 if ($cmd->app->global_options->{verbose}) { ... }
213 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 set_global_options
219 $app->set_global_options(\%opt);
220 This method sets the global options.
222 command_names
224 my @names = $cmd->command_names;
225 This returns the commands names which the App::Cmd object will handle.
227 command_groups
229 my @groups = $cmd->commands_groups;
230 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 command_plugins
239 my @plugins = $cmd->command_plugins;
240 This method returns the package names of the plugins that implement the
242 App::Cmd object's commands.
243 plugin_for
245 my $plugin = $cmd->plugin_for($command);
246 This method returns the plugin (module) for the given command. If no
248 plugin implements the command, it returns false.
249 get_command
251 my ($command_name, $opt, @args) = $app->get_command(@args);
252 Process arguments and into a command name and (optional) global
254 options.
255 usage
257 print $self->app->usage->text;
258 Returns the usage object for the global options.
260 usage_desc
262 The top level usage line. Looks something like
263 "yourapp <command> [options]"
265 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 usage_error
272 $self->usage_error("Something's wrong!");
273 Used to die with nice usage output, during "validate_args".
275
277 • publish and bring in Log::Speak (simple quiet/verbose output)
278 • publish and use our internal enhanced describe_options
280 • publish and use our improved simple input routines
282
284 Ricardo Signes <rjbs@semiotic.systems>
285
287 • Adam Prime <aprime@oanda.com>
288 • ambs <ambs@cpan.org>
290 • Andreas Hernitscheck <andreash@lxhe.(none)>
292 • A. Sinan Unur <nanis@cpan.org>
294 • Chris 'BinGOs' Williams <chris@bingosnet.co.uk>
296 • David Golden <dagolden@cpan.org>
298 • David Steinbrunner <dsteinbrunner@pobox.com>
300 • Davor Cubranic <cubranic@stat.ubc.ca>
302 • Denis Ibaev <dionys@gmail.com>
304 • Diab Jerius <djerius@cfa.harvard.edu>
306 • Glenn Fowler <cebjyre@cpan.org>
308 • Ingy dot Net <ingy@ingy.net>
310 • Jakob Voss <jakob@nichtich.de>
312 • Jakob Voss <voss@gbv.de>
314 • Jérôme Quelin <jquelin@gmail.com>
316 • John SJ Anderson <genehack@genehack.org>
318 • Karen Etheridge <ether@cpan.org>
320 • Kent Fredric <kentfredric@gmail.com>
322 • Lucas Theisen <ltheisen@mitre.org>
324 • Matthew Astley <mca@sanger.ac.uk>
326 • mokko <mauricemengel@gmail.com>
328 • Olivier Mengué <dolmen@cpan.org>
330 • Ryan C. Thompson <rct@thompsonclan.org>
332 • Salvatore Bonaccorso <carnil@debian.org>
334 • Sergey Romanov <sromanov-dev@yandex.ru>
336 • Stephan Loyd <stephanloyd9@gmail.com>
338 • Stephen Caldwell <steve@campusexplorer.com>
340 • Yuval Kogman <nuffin@cpan.org>
342
344 This software is copyright (c) 2021 by Ricardo Signes.
345 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.
348perl v5.36.0 2022-07-22 App::Cmd(3)