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

  no_version_plugin  - if true, the version plugin is not added

  show_version_cmd -   if true, the version command will be shown in the
                       command list

  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 your own or override the "default_command" method.

If "no_version_plugin" is not given, App::Cmd::Command::version will be required to show the application's version with command "--version". By default, the version command is not included in the command list. Pass "show_version_cmd" to include the version command in the list.

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.

It passes the contents of the global argument array (@ARGV) to ""prepare_command"", but @ARGV is not altered by running an App::Cmd.

prepare_args

default_args

abstract

   sub abstract { "command description" }

Defines the command abstract: a short description that will be printed in the main command options list.

description

   sub description { "Long description" }

Defines a longer command description that will be shown when the user asks for help on a specific command.

arg0

full_arg0

  my $program_name = $app->arg0;

  my $full_program_name = $app->full_arg0;

These methods return the name of the program invoked to run this application. This is determined by inspecting $0 when the App::Cmd object is instantiated, so it's probably correct, but doing weird things with App::Cmd could lead to weird values from these methods.

If the program was run like this:

  knight!rjbs$ ~/bin/rpg dice 3d6

Then the methods return:

  arg0      - rpg
  full_arg0 - /Users/rjbs/bin/rpg

These values are captured when the App::Cmd object is created, so it is safe to assign to $0 later.

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

execute_command

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

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

plugin_search_path

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

  use constant plugin_search_path => __PACKAGE__;

allow_any_unambiguous_abbrev

  reticulate
  reload
  rasterize

Then the user could use "ret" for "reticulate" or "ra" for "rasterize" and so on.

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 returned.

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_groups

  my @groups = $cmd->commands_groups;

This method can be implemented to return a grouped list of command names with optional headers. Each group is given as arrayref and each header as string. If an empty list is returned, the commands plugin will show two groups without headers: the first group is for the "help" and "commands" commands, and all other commands are in the second group.

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

  "yourapp <command> [options]"

global_opt_spec

usage_error

  $self->usage_error("Something's wrong!");

Used to die with nice usage output, during "validate_args".