NAME

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

VERSION

version 0.006

 $Id: /my/cs/projects/app-cmd/trunk/lib/App/Cmd.pm 25139 2006-08-25T12:48:02.868748Z rjbs  $

SYNOPSIS

in yourcmd:

  use YourApp::Cmd;
  
  Your::Cmd->new->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 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!
    die $self->usage->text 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

  plugin_search_path - The path to search for commands in. Defaults to
                       "YourClass::Command"

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.

plugin_search_path

Returns the plugin_search_path as set.

This is a method because it's fun to override it with

  use constant plugin_search_path => __PACKAGE__;

and stuff.

set_global_options

  $app->set_global_options( { } );

This is a separate method because it's more of a hook than an accessor.

global_options

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

This field contains 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.

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.

execute_command

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

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

prepare_command

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

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

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.

cpanm App::Cmd

perl -MCPAN -e shell
install App::Cmd