/ 
App-Cmd-0.009
River stage three • 98 direct dependents • 962 total dependents
/ App::Cmd

NAME

App::Cmd - write command line apps with less suffering

VERSION

version 0.009

SYNOPSIS

in yourcmd:

use YourApp::Cmd;

Your::Cmd->run;

in YourApp/Cmd.pm:

package YourApp::Cmd;
use base qw(App::Cmd);
1;

in YourApp/Cmd/Command/blort.pm:

package YourApp::Cmd::Command::blort;
use base qw(App::Cmd::Command);
use strict; use warnings;

sub opt_spec {
  return (
    [ "blortex|X",  "use the blortex algorithm" ],
    [ "recheck|r",  "recheck all results"       ],
  );
}

sub validate_args {
  my ($self, $opt, $args) = @_;

  # no args allowed but options!
  $self->usage_error("No args allowed") if @$args;
}

sub run {
  my ($self, $opt, $args) = @_;

  my $result = $opt->{blortex} ? blortex() : blort();

  recheck($result) if $opt->{recheck};

  print $result;
}

and, finally, at the command line:

knight!rjbs$ yourcmd blort --recheck

All blorts successful.

DESCRIPTION

App::Cmd is intended to make it easy to write complex command-line applications without having to think about most of the annoying things usually involved.

For information on how to start using App::Cmd, see App::Cmd::Tutorial.

METHODS

new

my $cmd = App::Cmd->new(\%arg);

This method returns a new App::Cmd object. During initialization, command plugins will be loaded.

Valid arguments are:

no_commands_plugin - if true, the command list plugin is not added

no_help_plugin     - if true, the help plugin is not added

plugin_search_path - The path to search for commands in. Defaults to
                     results of plugin_search_path method

If no_commands_plugin is not given, App::Cmd::Command::commands will be required, and it will be registered to handle all of its command names not handled by other plugins.

If no_help_plugin is not given, App::Cmd::Command::help will be required, and it will be registered to handle all of its command names not handled by other plugins. Note: "help" is the default command, so if you do not load the default help plugin, you should provide our own or override the default_command method.

run

$cmd->run;

This method runs the application. If called the class, it will instantiate a new App::Cmd object to run.

It determines the requested command (generally by consuming the first command-line argument), finds the plugin to handle that command, parses the remaining arguments according to that plugin's rules, and runs the plugin.

prepare_command

my ($cmd, $opt, @args) = $app->prepare_command(@ARGV);

This method will load the plugin for the requested command, use its options to parse the command line arguments, and eventually return everything necessary to actually execute the command.

default_command

This method returns the name of the command to run if none is given on the command line. The default default is "help"

execute_command

$app->execute_command($cmd, \%opt, @args);

This method will invoke validate_args and then run on $cmd.

plugin_search_path

This method returns the plugin_search_path as set. The default implementation, if called on "YourApp::Cmd" will return "YourApp::Cmd::Command"

This is a method because it's fun to override it with, for example:

use constant plugin_search_path => __PACKAGE__;

global_options

if ($cmd->app->global_options->{verbose}) { ... }

This method returns the running application's global options as a hashref. If there are no options specified, an empty hashref is returend.

set_global_options

$app->set_global_options(\%opt);

This method sets the global options.

command_names

my @names = $cmd->command_names;

This returns the commands names which the App::Cmd object will handle.

command_plugins

my @plugins = $cmd->command_plugins;

This method returns the package names of the plugins that implement the App::Cmd object's commands.

plugin_for

my $plugin = $cmd->plugin_for($command);

This method returns the plugin (module) for the given command. If no plugin implements the command, it returns false.

get_command

my ($command_name, $opt, @args) = $app->get_command(@args);

Process arguments and into a command name and (optional) global options.

usage

print $self->app->usage->text;

Returns the usage object for the global options.

usage_desc

The top level usage line. Looks something like

"yourapp [options] <command>"

global_opt_spec

Returns an empty list. Can be overridden for pre-dispatch option processing. This is useful for flags like --verbose.

usage_error

$self->usage_error("Your mother!");

Used to die with nice usage output, during validate_args.

TODO

Lots of stuff! This list isn't close to complete yet, I'm still adding to it.

  • improve the tutorial

  • publish and bring in Log::Speak (simple quiet/verbose output)

  • publish and use our internal enhanced describe_options

  • publish and use our improved simple input routines

  • publish and use our remaining little CLI tools

  • make it simple to write a command with no subcommands

AUTHOR AND COPYRIGHT

Copyright 2005-2006, (code (simply)). All rights reserved; App::Cmd and bundled code are free software, released under the same terms as perl itself.

App:Cmd was originally written as Rubric::CLI by Ricardo SIGNES in 2005. It was refactored extensively by Ricardo SIGNES and John Cappiello and released as App::Cmd in 2006. Yuval Kogman performed significant refactoring and other improvements on the code.