The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
App-CLI-Toolkit-0.03
River stage zero No dependents
++
/ App::CLI::Toolkit

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:

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.