Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
App::Cmd(3)	      User Contributed Perl Documentation	   App::Cmd(3)

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

VERSION
       version 0.331

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.

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 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
       o   publish and bring in	Log::Speak (simple quiet/verbose output)

       o   publish and use our internal	enhanced describe_options

       o   publish and use our improved	simple input routines

AUTHOR
       Ricardo Signes <rjbs@cpan.org>

CONTRIBUTORS
       o   Adam	Prime <aprime@oanda.com>

       o   ambs	<ambs@cpan.org>

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

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

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

       o   David Golden	<dagolden@cpan.org>

       o   David Steinbrunner <dsteinbrunner@pobox.com>

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

       o   Denis Ibaev <dionys@gmail.com>

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

       o   Glenn Fowler	<cebjyre@cpan.org>

       o   Ingy	dot Net	<ingy@ingy.net>

       o   Jakob Voss <jakob@nichtich.de>

       o   Jakob Voss <voss@gbv.de>

       o   JA(C)rA'me Quelin <jquelin@gmail.com>

       o   John	SJ Anderson <genehack@genehack.org>

       o   Karen Etheridge <ether@cpan.org>

       o   Kent	Fredric	<kentfredric@gmail.com>

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

       o   mokko <mauricemengel@gmail.com>

       o   Olivier MenguA(C) <dolmen@cpan.org>

       o   Ricardo SIGNES <rjbs@codesimply.com>

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

       o   Salvatore Bonaccorso	<carnil@debian.org>

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

       o   Stephen Caldwell <steve@campusexplorer.com>

       o   Yuval Kogman	<nuffin@cpan.org>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2016 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.

perl v5.32.0			  2016-07-17			   App::Cmd(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | TODO | AUTHOR | CONTRIBUTORS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=App::Cmd&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help