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.331
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 new
72 my $cmd = App::Cmd->new(\%arg);
73 This method returns a new App::Cmd object. During initialization,
75 command plugins will be loaded.
76 Valid arguments are:
78 no_commands_plugin - if true, the command list plugin is not added
80 no_help_plugin - if true, the help plugin is not added
82 no_version_plugin - if true, the version plugin is not added
84 show_version_cmd - if true, the version command will be shown in the
86 command list
87 plugin_search_path - The path to search for commands in. Defaults to
89 results of plugin_search_path method
90 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 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 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 run
107 $cmd->run;
108 This method runs the application. If called the class, it will
110 instantiate a new App::Cmd object to run.
111 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 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 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 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 abstract
130 sub abstract { "command description" }
131 Defines the command abstract: a short description that will be printed
133 in the main command options list.
134 description
136 sub description { "Long description" }
137 Defines a longer command description that will be shown when the user
139 asks for help on a specific command.
140 arg0
142 full_arg0
143 my $program_name = $app->arg0;
144 my $full_program_name = $app->full_arg0;
146 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 If the program was run like this:
153 knight!rjbs$ ~/bin/rpg dice 3d6
155 Then the methods return:
157 arg0 - rpg
159 full_arg0 - /Users/rjbs/bin/rpg
160 These values are captured when the App::Cmd object is created, so it is
162 safe to assign to $0 later.
163 prepare_command
165 my ($cmd, $opt, @args) = $app->prepare_command(@ARGV);
166 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 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 execute_command
176 $app->execute_command($cmd, \%opt, @args);
177 This method will invoke "validate_args" and then "run" on $cmd.
179 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 This is a method because it's fun to override it with, for example:
186 use constant plugin_search_path => __PACKAGE__;
188 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 reticulate
196 reload
197 rasterize
198 Then the user could use "ret" for "reticulate" or "ra" for "rasterize"
200 and so on.
201 global_options
203 if ($cmd->app->global_options->{verbose}) { ... }
204 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 set_global_options
210 $app->set_global_options(\%opt);
211 This method sets the global options.
213 command_names
215 my @names = $cmd->command_names;
216 This returns the commands names which the App::Cmd object will handle.
218 command_groups
220 my @groups = $cmd->commands_groups;
221 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 command_plugins
230 my @plugins = $cmd->command_plugins;
231 This method returns the package names of the plugins that implement the
233 App::Cmd object's commands.
234 plugin_for
236 my $plugin = $cmd->plugin_for($command);
237 This method returns the plugin (module) for the given command. If no
239 plugin implements the command, it returns false.
240 get_command
242 my ($command_name, $opt, @args) = $app->get_command(@args);
243 Process arguments and into a command name and (optional) global
245 options.
246 usage
248 print $self->app->usage->text;
249 Returns the usage object for the global options.
251 usage_desc
253 The top level usage line. Looks something like
254 "yourapp <command> [options]"
256 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 usage_error
263 $self->usage_error("Something's wrong!");
264 Used to die with nice usage output, during "validate_args".
266
268 · publish and bring in Log::Speak (simple quiet/verbose output)
269 · publish and use our internal enhanced describe_options
271 · publish and use our improved simple input routines
273
275 Ricardo Signes <rjbs@cpan.org>
276
278 · Adam Prime <aprime@oanda.com>
279 · ambs <ambs@cpan.org>
281 · Andreas Hernitscheck <andreash@lxhe.(none)>
283 · A. Sinan Unur <nanis@cpan.org>
285 · Chris 'BinGOs' Williams <chris@bingosnet.co.uk>
287 · David Golden <dagolden@cpan.org>
289 · David Steinbrunner <dsteinbrunner@pobox.com>
291 · Davor Cubranic <cubranic@stat.ubc.ca>
293 · Denis Ibaev <dionys@gmail.com>
295 · Diab Jerius <djerius@cfa.harvard.edu>
297 · Glenn Fowler <cebjyre@cpan.org>
299 · Ingy dot Net <ingy@ingy.net>
301 · Jakob Voss <jakob@nichtich.de>
303 · Jakob Voss <voss@gbv.de>
305 · Jérôme Quelin <jquelin@gmail.com>
307 · John SJ Anderson <genehack@genehack.org>
309 · Karen Etheridge <ether@cpan.org>
311 · Kent Fredric <kentfredric@gmail.com>
313 · Matthew Astley <mca@sanger.ac.uk>
315 · mokko <mauricemengel@gmail.com>
317 · Olivier Mengué <dolmen@cpan.org>
319 · Ricardo SIGNES <rjbs@codesimply.com>
321 · Ryan C. Thompson <rct@thompsonclan.org>
323 · Salvatore Bonaccorso <carnil@debian.org>
325 · Sergey Romanov <sromanov-dev@yandex.ru>
327 · Stephen Caldwell <steve@campusexplorer.com>
329 · Yuval Kogman <nuffin@cpan.org>
331
333 This software is copyright (c) 2016 by Ricardo Signes.
334 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.
337perl v5.32.0 2020-07-28 App::Cmd(3)