Provided by: libapp-cmd-perl_0.336-1_all bug

NAME

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

VERSION

       version 0.336

SYNOPSIS

       in yourcmd:

         use YourApp;
         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 abstract { "blortex algorithm" }

         sub description { "Long description on blortex algorithm" }

         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 execute {
           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.

PERL VERSION

       This library should run on perls released even a long time ago.  It should work on any
       version of perl released in the last five years.

       Although it may work on older versions of perl, no guarantee is made that the minimum
       required version will not be increased.  The version may be increased for any reason, and
       there is no promise that patches will be accepted to lower the minimum required perl.

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

         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
       Normally App::Cmd uses @ARGV for its commandline arguments. You can override this method
       to change that behavior for testing or otherwise.

   default_args
       If "prepare_args" is not changed and there are no arguments in @ARGV, this method is
       called and should return an arrayref to be used as the arguments to the program.  By
       default, it returns an empty arrayref.

   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
       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__;

   allow_any_unambiguous_abbrev
       If this method returns true (which, by default, it does not), then any unambiguous
       abbreviation for a registered command name will be allowed as a means to use that command.
       For example, given the following commands:

         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
       The top level usage line. Looks something like

         "yourapp <command> [options]"

   global_opt_spec
       Returns a list with help command unless "no_help_plugin" has been specified or an empty
       list. Can be overridden for pre-dispatch option processing.  This is useful for flags like
       --verbose.

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

       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

AUTHOR

       Ricardo Signes <cpan@semiotic.systems>

CONTRIBUTORS

       •   Adam Prime <aprime@oanda.com>

       •   ambs <ambs@cpan.org>

       •   Andreas Hernitscheck <andreash@lxhe.(none)>

       •   A. Sinan Unur <nanis@cpan.org>

       •   Chris 'BinGOs' Williams <chris@bingosnet.co.uk>

       •   David Golden <dagolden@cpan.org>

       •   David Steinbrunner <dsteinbrunner@pobox.com>

       •   Davor Cubranic <cubranic@stat.ubc.ca>

       •   Denis Ibaev <dionys@gmail.com>

       •   Diab Jerius <djerius@cfa.harvard.edu>

       •   Glenn Fowler <cebjyre@cpan.org>

       •   Ingy dot Net <ingy@ingy.net>

       •   Jakob Voss <jakob@nichtich.de>

       •   Jakob Voss <voss@gbv.de>

       •   Jérôme Quelin <jquelin@gmail.com>

       •   John SJ Anderson <genehack@genehack.org>

       •   Karen Etheridge <ether@cpan.org>

       •   Kent Fredric <kentfredric@gmail.com>

       •   Lucas Theisen <ltheisen@mitre.org>

       •   Matthew Astley <mca@sanger.ac.uk>

       •   Michael McClimon <michael@mcclimon.org>

       •   mokko <mauricemengel@gmail.com>

       •   Olivier Mengué <dolmen@cpan.org>

       •   Ricardo Signes <rjbs@semiotic.systems>

       •   Ryan C. Thompson <rct@thompsonclan.org>

       •   Salvatore Bonaccorso <carnil@debian.org>

       •   Sawyer X <xsawyerx@cpan.org>

       •   Sergey Romanov <sromanov-dev@yandex.ru>

       •   Stephan Loyd <stephanloyd9@gmail.com>

       •   Stephen Caldwell <steve@campusexplorer.com>

       •   Yuval Kogman <nuffin@cpan.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2023 by Ricardo Signes.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.