Linux Certif

Toute la documentation sur la certification Linux LPI

App::Cmd.3pm

NAME

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

VERSION

version 0.203

SYNOPSIS

in yourcmd:

   use YourApp -run;
 
 

in YourApp.pm:

   package YourApp;
   use App::Cmd::Setup -app;
   1;
 
 

in YourApp/Command/blort.pm:

   package YourApp::Command::blort;
   use YourApp -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.

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

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

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

•

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

COPYRIGHT AND AUTHOR

Copyright 2005-2006, (code (simply)). 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.