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.311
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 opt_spec {
30           return (
31             [ "blortex|X",  "use the blortex algorithm" ],
32             [ "recheck|r",  "recheck all results"       ],
33           );
34         }
35
36         sub validate_args {
37           my ($self, $opt, $args) = @_;
38
39           # no args allowed but options!
40           $self->usage_error("No args allowed") if @$args;
41         }
42
43         sub execute {
44           my ($self, $opt, $args) = @_;
45
46           my $result = $opt->{blortex} ? blortex() : blort();
47
48           recheck($result) if $opt->{recheck};
49
50           print $result;
51         }
52
53       and, finally, at the command line:
54
55         knight!rjbs$ yourcmd blort --recheck
56
57         All blorts successful.
58

DESCRIPTION

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

METHODS

67   new
68         my $cmd = App::Cmd->new(\%arg);
69
70       This method returns a new App::Cmd object.  During initialization,
71       command plugins will be loaded.
72
73       Valid arguments are:
74
75         no_commands_plugin - if true, the command list plugin is not added
76
77         no_help_plugin     - if true, the help plugin is not added
78
79         plugin_search_path - The path to search for commands in. Defaults to
80                              results of plugin_search_path method
81
82       If "no_commands_plugin" is not given, App::Cmd::Command::commands will
83       be required, and it will be registered to handle all of its command
84       names not handled by other plugins.
85
86       If "no_help_plugin" is not given, App::Cmd::Command::help will be
87       required, and it will be registered to handle all of its command names
88       not handled by other plugins. Note: "help" is the default command, so
89       if you do not load the default help plugin, you should provide our own
90       or override the "default_command" method.
91
92   run
93         $cmd->run;
94
95       This method runs the application.  If called the class, it will
96       instantiate a new App::Cmd object to run.
97
98       It determines the requested command (generally by consuming the first
99       command-line argument), finds the plugin to handle that command, parses
100       the remaining arguments according to that plugin's rules, and runs the
101       plugin.
102
103       It passes the contents of the global argument array (@ARGV) to
104       ""prepare_command"", but @ARGV is not altered by running an App::Cmd.
105
106   arg0
107   full_arg0
108         my $program_name = $app->arg0;
109
110         my $full_program_name = $app->full_arg0;
111
112       These methods return the name of the program invoked to run this
113       application.  This is determined by inspecting $0 when the App::Cmd
114       object is instantiated, so it's probably correct, but doing weird
115       things with App::Cmd could lead to weird values from these methods.
116
117       If the program was run like this:
118
119         knight!rjbs$ ~/bin/rpg dice 3d6
120
121       Then the methods return:
122
123         arg0      - rpg
124         full_arg0 - /Users/rjbs/bin/rpg
125
126       These values are captured when the App::Cmd object is created, so it is
127       safe to assign to $0 later.
128
129   prepare_command
130         my ($cmd, $opt, @args) = $app->prepare_command(@ARGV);
131
132       This method will load the plugin for the requested command, use its
133       options to parse the command line arguments, and eventually return
134       everything necessary to actually execute the command.
135
136   default_command
137       This method returns the name of the command to run if none is given on
138       the command line.  The default default is "help"
139
140   execute_command
141         $app->execute_command($cmd, \%opt, @args);
142
143       This method will invoke "validate_args" and then "run" on $cmd.
144
145   plugin_search_path
146       This method returns the plugin_search_path as set.  The default
147       implementation, if called on "YourApp::Cmd" will return
148       "YourApp::Cmd::Command"
149
150       This is a method because it's fun to override it with, for example:
151
152         use constant plugin_search_path => __PACKAGE__;
153
154   allow_any_unambiguous_abbrev
155       If this method returns true (which, by default, it does not), then any
156       unambiguous abbreviation for a registered command name will be allowed
157       as a means to use that command.  For example, given the following
158       commands:
159
160         reticulate
161         reload
162         rasterize
163
164       Then the user could use "ret" for "reticulate" or "ra" for "rasterize"
165       and so on.
166
167   global_options
168         if ($cmd->app->global_options->{verbose}) { ... }
169
170       This method returns the running application's global options as a
171       hashref.  If there are no options specified, an empty hashref is
172       returend.
173
174   set_global_options
175         $app->set_global_options(\%opt);
176
177       This method sets the global options.
178
179   command_names
180         my @names = $cmd->command_names;
181
182       This returns the commands names which the App::Cmd object will handle.
183
184   command_plugins
185         my @plugins = $cmd->command_plugins;
186
187       This method returns the package names of the plugins that implement the
188       App::Cmd object's commands.
189
190   plugin_for
191         my $plugin = $cmd->plugin_for($command);
192
193       This method returns the plugin (module) for the given command.  If no
194       plugin implements the command, it returns false.
195
196   get_command
197         my ($command_name, $opt, @args) = $app->get_command(@args);
198
199       Process arguments and into a command name and (optional) global
200       options.
201
202   usage
203         print $self->app->usage->text;
204
205       Returns the usage object for the global options.
206
207   usage_desc
208       The top level usage line. Looks something like
209
210         "yourapp [options] <command>"
211
212   global_opt_spec
213       Returns an empty list. Can be overridden for pre-dispatch option
214       processing.  This is useful for flags like --verbose.
215
216   usage_error
217         $self->usage_error("Something's wrong!");
218
219       Used to die with nice usage output, during "validate_args".
220

TODO

222       ·   publish and bring in Log::Speak (simple quiet/verbose output)
223
224       ·   publish and use our internal enhanced describe_options
225
226       ·   publish and use our improved simple input routines
227

AUTHOR

229       Ricardo Signes <rjbs@cpan.org>
230

232       This software is copyright (c) 2011 by Ricardo Signes.
233
234       This is free software; you can redistribute it and/or modify it under
235       the same terms as the Perl 5 programming language system itself.
236
237
238
239perl v5.12.3                      2011-03-18                       App::Cmd(3)
Impressum