1App::Cmd::Tutorial(3) User Contributed Perl DocumentationApp::Cmd::Tutorial(3)
2
6 App::Cmd::Tutorial - getting started with App::Cmd
7
9 version 0.334
10
12 App::Cmd is a set of tools designed to make it simple to write
13 sophisticated command line programs. It handles commands with multiple
14 subcommands, generates usage text, validates options, and lets you
15 write your program as easy-to-test classes.
16 An App::Cmd-based application is made up of three main parts: the
18 script, the application class, and the command classes.
19 The Script
21 The script is the actual executable file run at the command line. It
22 can generally consist of just a few lines:
23 #!/usr/bin/perl
25 use YourApp;
26 YourApp->run;
27 The Application Class
29 All the work of argument parsing, validation, and dispatch is taken
30 care of by your application class. The application class can also be
31 pretty simple, and might look like this:
32 package YourApp;
34 use App::Cmd::Setup -app;
35 1;
36 When a new application instance is created, it loads all of the command
38 classes it can find, looking for modules under the Command namespace
39 under its own name. In the above snippet, for example, YourApp will
40 look for any module with a name starting with "YourApp::Command::".
41 The Command Classes
43 We can set up a simple command class like this:
44 # ABSTRACT: set up YourApp
46 package YourApp::Command::initialize;
47 use YourApp -command;
48 1;
49 Now, a user can run this command, but he'll get an error:
51 $ yourcmd initialize
53 YourApp::Command::initialize does not implement mandatory method 'execute'
54 Oops! This dies because we haven't told the command class what it
56 should do when executed. This is easy, we just add some code:
57 sub execute {
59 my ($self, $opt, $args) = @_;
60 print "Everything has been initialized. (Not really.)\n";
62 }
63 Now it works:
65 $ yourcmd initialize
67 Everything has been initialized. (Not really.)
68 Default Commands
70 By default applications made with App::Cmd know two commands:
71 "commands" and "help".
72 commands
74 lists available commands.
75 $yourcmd commands
77 Available commands:
78 commands: list the application's commands
80 help: display a command's help screen
81 init: set up YourApp
83 Note that by default the commands receive a description from the "#
85 ABSTRACT" comment in the respective command's module, or from the
86 "=head1 NAME" Pod section.
87 help
89 allows one to query for details on command's specifics.
90 $yourcmd help initialize
92 yourcmd initialize [-z] [long options...]
93 -z --zero ignore zeros
95 Of course, it's possible to disable or change the default commands,
97 see App::Cmd.
98 Arguments and Options
100 In this example
101 $ yourcmd reset -zB --new-seed xyzzy foo.db bar.db
103 "-zB" and "--new-seed xyzzy" are "options" and "foo.db" and "bar.db"
105 are "arguments."
106 With a properly configured command class, the above invocation results
108 in nicely formatted data:
109 $opt = {
111 zero => 1,
112 no_backup => 1, #default value
113 new_seed => 'xyzzy',
114 };
115 $args = [ qw(foo.db bar.db) ];
117 Arguments are processed by Getopt::Long::Descriptive (GLD). To
119 customize its argument processing, a command class can implement a few
120 methods: "usage_desc" provides the usage format string; "opt_spec"
121 provides the option specification list; "validate_args" is run after
122 Getopt::Long::Descriptive, and is meant to validate the $args, which
123 GLD ignores. See Getopt::Long for format specifications.
124 The first two methods provide configuration passed to GLD's
126 "describe_options" routine. To improve our command class, we might add
127 the following code:
128 sub usage_desc { "yourcmd %o [dbfile ...]" }
130 sub opt_spec {
132 return (
133 [ "skip-refs|R", "skip reference checks during init", ],
134 [ "values|v=s@", "starting values", { default => [ 0, 1, 3 ] } ],
135 );
136 }
137 sub validate_args {
139 my ($self, $opt, $args) = @_;
140 # we need at least one argument beyond the options; die with that message
142 # and the complete "usage" text describing switches, etc
143 $self->usage_error("too few arguments") unless @$args;
144 }
145 Global Options
147 There are several ways of making options available everywhere
148 (globally). This recipe makes local options accessible in all commands.
149 To add a "--help" option to all your commands create a base class like:
151 package MyApp::Command;
153 use App::Cmd::Setup -command;
154 sub opt_spec {
156 my ( $class, $app ) = @_;
157 return (
158 [ 'help' => "this usage screen" ],
159 $class->options($app),
160 )
161 }
162 sub validate_args {
164 my ( $self, $opt, $args ) = @_;
165 if ( $opt->{help} ) {
166 my ($command) = $self->command_names;
167 $self->app->execute_command(
168 $self->app->prepare_command("help", $command)
169 );
170 exit;
171 }
172 $self->validate( $opt, $args );
173 }
174 Where "options" and "validate" are "inner" methods which your command
176 subclasses implement to provide command-specific options and
177 validation.
178 Note: this is a new file, previously not mentioned in this tutorial and
180 this tip does not recommend the use of global_opt_spec which offers an
181 alternative way of specifying global options.
182
184 This module has a long-term perl support period. That means it will
185 not require a version of perl released fewer than five years ago.
186 Although it may work on older versions of perl, no guarantee is made
188 that the minimum required version will not be increased. The version
189 may be increased for any reason, and there is no promise that patches
190 will be accepted to lower the minimum required perl.
191
193 • Delay using large modules using Class::Load, Module::Runtime or
194 "require" in your commands to save memory and make startup faster.
195 Since only one of these commands will be run anyway, there's no
196 need to preload the requirements for all of them.
197 • Add a "description" method to your commands for more verbose output
199 from the built-in help command.
200 sub description {
202 return "The initialize command prepares ...";
203 }
204 • To let your users configure default values for options, put a sub
206 like
207 sub config {
209 my $app = shift;
210 $app->{config} ||= TheLovelyConfigModule->load_config_file();
211 }
212 in your main app file, and then do something like:
214 package YourApp;
216 sub opt_spec {
217 my ( $class, $app ) = @_;
218 my ( $name ) = $class->command_names;
219 return (
220 [ 'blort=s' => "That special option",
221 { default => $app->config->{$name}{blort} || $fallback_default },
222 ],
223 );
224 }
225 Or better yet, put this logic in a superclass and process the
227 return value from an "inner" method:
228 package YourApp::Command;
230 sub opt_spec {
231 my ( $class, $app ) = @_;
232 return (
233 [ 'help' => "this usage screen" ],
234 $class->options($app),
235 )
236 }
237 • You need to activate "strict" and "warnings" as usual if you want
239 them. App::Cmd doesn't do that for you.
240
242 Some people find that for whatever reason, they wish to put Modules in
243 their "MyApp::Command::" namespace which are not commands, or not
244 commands intended for use by "MyApp".
245 Good examples include, but are not limited to, things like
247 "MyApp::Command::frobrinate::Plugin::Quietly", where "::Quietly" is
248 only useful for the "frobrinate" command.
249 The default behaviour is to treat such packages as errors, as for the
251 majority of use cases, things in "::Command" are expected to only be
252 commands, and thus, anything that, by our heuristics, is not a command,
253 is highly likely to be a mistake.
254 And as all commands are loaded simultaneously, an error in any one of
256 these commands will yield a fatal error.
257 There are a few ways to specify that you are sure you want to do this,
259 with varying ranges of scope and complexity.
260 Ignoring a Single Module.
262 This is the simplest approach, and most useful for one-offs.
263 package YourApp::Command::foo::NotACommand;
265 use YourApp -ignore;
267 <whatever you want here>
269 This will register this package's namespace with YourApp to be excluded
271 from its plugin validation magic. It otherwise makes no changes to
272 "::NotACommand"'s namespace, does nothing magical with @ISA, and
273 doesn't bolt any hidden functions on.
274 Its also probably good to notice that it is ignored only by "YourApp".
276 If for whatever reason you have two different "App::Cmd" systems under
277 which "::NotACommand" is visible, you'll need to set it ignored to
278 both.
279 This is probably a big big warning NOT to do that.
281 Ignoring Multiple modules from the App level.
283 If you really fancy it, you can override the "should_ignore" method
284 provided by "App::Cmd" to tweak its ignore logic. The most useful
285 example of this is as follows:
286 sub should_ignore {
288 my ( $self, $command_class ) = @_;
289 return 1 if not $command_class->isa( 'App::Cmd::Command' );
290 return;
291 }
292 This will prematurely mark for ignoring all packages that don't
294 subclass "App::Cmd::Command", which causes non-commands ( or perhaps
295 commands that are coded wrongly / broken ) to be silently skipped.
296 Note that by overriding this method, you will lose the effect of any of
298 the other ignore mechanisms completely. If you want to combine the
299 original "should_ignore" method with your own logic, you'll want to
300 steal "Moose"'s "around" method modifier.
301 use Moose::Util;
303 Moose::Util::add_method_modifier( __PACKAGE__, 'around', [
305 should_ignore => sub {
306 my $orig = shift;
307 my $self = shift;
308 return 1 if not $command_class->isa( 'App::Cmd::Command' );
309 return $self->$orig( @_ );
310 }]);
311
313 CPAN modules using App::Cmd <http://deps.cpantesters.org/depended-on-
314 by.pl?module=App%3A%3ACmd>
315
317 Ricardo Signes <rjbs@semiotic.systems>
318
320 This software is copyright (c) 2021 by Ricardo Signes.
321 This is free software; you can redistribute it and/or modify it under
323 the same terms as the Perl 5 programming language system itself.
324perl v5.34.0 2021-07-22 App::Cmd::Tutorial(3)