NAME
App::CLI::Toolkit - a helper module for generating command-line utilities
DESCRIPTION
App::CLI::Toolkit is designed to take the hassle out of writing command-line apps in Perl. It handles the parsing of both parameters and options (see below for the distinction) and generates usage information from the details you give it.
SYNOPSIS
use App::CLI::Toolkit;
my $app = App::CLI::Toolkit->new(
description = 'A replacement for cp',
params = [ qw(source dest) ],
options = {
'recursive|r' => 'If source is a directory, copies'
. 'the directory contents recursively',
'force|f' => 'If target already exists, overwrite it'
'verbose|v' => 'Produce verbose output'
}
);
print "Copying " . $app->source . " to " . $app->dest . "\n" if $app->verbose;
if ($app->recursive) {
# Do recursive gumbo
}
if ($app->force) {
# Don't take no for an answer
}
...
CONSTRUCTOR
App::CLI::Toolkit->new(%config)
Constructs a new App::CLI::Toolkit object
Constructor arguments
description
A description of what the app does. Used in the usage string that App::CLI::Toolkit generates.
Example:
$app = new App::CLI::Toolkit(description => 'A cool new replacement for grep!')
noautohelp
App::CLI::Toolkit automatically gives your app help options (-h and --help). Supply a noautohelp value that equates to true (e.g. 1) to suppress this.
options
A reference to a hash mapping option names to a description of what the option does. The hash keys follow the conventions of Getopt::Long.
params
A reference to an array of parameter names. When the app is invoked, parameters follow the app name on the command line.
Example:
$app = new App::CLI::Toolkit(params => ['name'])
print uc $app->name
Yields this result:
$ my-app fred
FRED
- Optional parameters
-
Parameters can be optional, in which case your application will provide a default if the user doesn't provide a parameter. For example, the target argument to
ln
is optional and defaults to the filename of the source in the current working directory.Specify an optional argument in
App::CLI::Toolkit
by adding?
to the end of the parameter name.Example:
$app = new App::CLI::Toolkit(params => ['target?']); print $app->target || $ENV{PWD} . "\n"
Yields this result:
$ my-app /var/tmp /var/tmp $ my-app /home/simon
- Multiple-Value Parameters
-
Applications can take one or more instances of a particular parameter. For example,
mv
takes one or more file arguments followed by a single target parameter.Specify a multiple-value argument in
App::CLI::Toolkit
by adding+
to the end of the parameter name.The accessor for multiple-value parameters returns a list, even if the user only supplied one value.
Example:
$app = new App::CLI::Toolkit(params => ['files+']); print join(', ', $app->files) . "\n"
Yields this result:
$ my-app foo bar wibble foo, bar, wibble
- Optional, Multiple-Value Parameters
-
Applications can take zero or more instances of a particular parameter. For example,
ls
takes either no parameters (in which case it lists the contents of the current working directory) or a list of parameters (in which case it lists the contents of each parameter).Specify an optional, multiple-value argument in
App::CLI::Toolkit
by adding*
to the end of the parameter name.The accessor for optional, multiple-value parameters returns a list, even if the user only supplied one value.
Example:
$app = new App::CLI::Toolkit(params => ['dirs*']); if ($app->dirs) { print join(', ', $app->dirs) . "\n"; } else { print "No dirs given, using $ENV{PWD}\n"; }
Yields this result:
$ my-app foo bar wibble foo, bar, wibble $ my-app foo foo $ my-app No dirs given, using /home/simon
- Some notes about optional and multiple-value parameters
-
You can only have one multiple-value parameter type per application.
You can't follow an optional parameter type with a non-optional parameter type.
METHODS
App-specific accessors
Your App::CLI::Toolkit object has methods named after each of the params and options specified in the constructor.
Example:
$app = App::CLI::Toolkit(
params => [ qw(foo bar?) ],
options => {
'verbose|v' => 'Give more verbose output',
}
)
print $app->foo;
print $app->bar if $app->bar;
print "Some verbose rubbish\n" if $app->verbose;
Where an option has multiple labels (eg. verbose
and v
in the above example), the accessor has the name of the first label in the list.
get(key)
Gets the value stored against key, where key is an option name or param label. This is an alternative to the convenience accessors named after the option name or param label.
Example:
$app = App::CLI::Toolkit(params => ['foo'])
print $app->foo; # prints the value of the 'foo' param
print $app->get('foo') # same
usage()
Gets the usage string for your application
AUTHOR
Simon Whitaker, <swhitaker at cpan.org>
BUGS
Please report any bugs or feature requests to bug-app-cli-toolkit at rt.cpan.org
, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-CLI-Toolkit. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc App::CLI::Toolkit
You can also look for information at:
RT: CPAN's request tracker
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
Search CPAN
ACKNOWLEDGEMENTS
Thanks to Chris Lokotsch for the code reviews.
COPYRIGHT & LICENSE
Copyright 2008 Simon Whitaker, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.