Class::Usul::Programs - Provide support for command line programs
# In YourClass.pm use Moo; extends q(Class::Usul::Programs); # In yourProg.pl use YourClass; exit YourClass->new( appclass => 'YourApplicationClass' )->run;
This base class provides methods common to command line programs. The constructor can initialise a multi-lingual message catalog if required
Supports this list of command line options:
c method
The method in the subclass to dispatch to
D
Turn debugging on
H help_manual
Print long help text extracted from this POD
h help_options
Print short help text extracted from this POD
? help_usage
L locale
Print text and error messages in the selected language. If no language catalog is supplied prints text and errors in terse English. Defaults to en_GB
en_GB
n noask
Do not prompt to turn debugging on
o options key=value
The method that is dispatched to can access the key/value pairs from the $self->options hash ref
$self->options
q quiet_flag
Quietens the usual started/finished information messages
version
Prints the programs version number and exits
Defines these attributes;
config_class
Overrides the default in the base class, setting it to Class::Usul::Config::Programs
Class::Usul::Config::Programs
params
List of value that are passed to the method called by "run"
v verbose
Repeatable boolean that increases the verbosity of the output
Called just before the object is constructed this method modifier determines the location of the config file
Called just after the object is constructed this methods handles dispatching to the help methods and prompting for the debug state
$leader = $self->add_leader( $text, $args );
Prepend $self->config->name to each line of $text. If $args->{no_lead} exists then do nothing. Return $text with leader prepended
$self->config->name
$text
$args->{no_lead}
$bool = $self->can_call( $method );
Returns true if $self has a method given by $method that has defined the method method attribute
$self
$method
$cmd_line_option = $self->debug_flag
Returns the command line debug flag to match the current debug state
$self->dump_self;
Dumps out the self referential object using Data::Printer
$self->error( $text, $args );
Calls Class::Usul::localize with the passed args. Logs the result at the error level, then adds the program leader and prints the result to STDERR
$self->_exit_usage( $verbosity );
Print out usage information from POD. The $verbosity is; 0, 1 or 2
$verbosity
$self->_exit_version
Prints out the version of the C::U::Programs subclass and the exits
$self->fatal( $text, $args );
Calls Class::Usul::localize with the passed args. Logs the result at the alert level, then adds the program leader and prints the result to STDERR. Exits with a return code of one
$self->_get_debug_option();
If it is an interactive session prompts the user to turn debugging on. Returns true if debug is on. Also offers the option to quit
$path = $self->_get_homedir( $args );
Environment variable containing the path to a file which contains the application installation directory. Defaults to the environment variable <uppercase application name>_HOME
Search through sub directories of @INC looking for the file yourApplication.json. Uses the location of this file to return the path to the installation directory
$exit_code = $self->help;
Searches the programs classes and roles to find the method implementation. Displays help text from the POD that describes the method
$self->info( $text, $args );
Calls Class::Usul::localize with the passed args. Logs the result at the info level, then adds the program leader and prints the result to STDOUT
$cmd = $self->interpolate_cmd( $cmd, @args );
Calls _interpolate_${cmd}_cmd to apply the arguments to the command in a command specific way
_interpolate_${cmd}_cmd
$self->list_methods;
Lists the methods (marked by the method subroutine attribute) that can be called via the run method
$localized_text = $self->loc( $message, @options );
Localizes the message. Calls "localize" in Class::Usul::L10N. The domains to search are in the l10n_domains configuration attribute. Adds $self->locale to the arguments passed to localize
l10n_domains
$self->locale
localize
$self->output( $text, $args );
Calls Class::Usul::localize with the passed args. Adds the program leader and prints the result to STDOUT
$bool = $self->quiet( $bool );
Custom accessor/mutator for the quiet_flag attribute. Will throw if you try to turn quiet mode off
quiet_flag
$rv = $self->run;
Call the method specified by the -c option on the command line. Returns the exit code
-c
$exit_code = $self->run_chain( $method );
Called by "run" when _get_run_method cannot determine which method to call. Outputs usage if $method is undefined. Logs an error if $method is defined but not (by definition a callable method). Returns exit code FAILED
_get_run_method
FAILED
$self->warning( $text, $args );
Calls Class::Usul::localize with the passed args. Logs the result at the warning level, then adds the program leader and prints the result to STDOUT
Turning debug on produces some more output
There are no known incompatibilities in this module
There are no known bugs in this module. Please report problems to the address below. Patches are welcome
Peter Flanigan, <Support at RoxSoft.co.uk>
<Support at RoxSoft.co.uk>
Copyright (c) 2014 Peter Flanigan. All rights reserved
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic
This program is distributed in the hope that it will be useful, but WITHOUT WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE
To install Class::Usul, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Class::Usul
CPAN shell
perl -MCPAN -e shell install Class::Usul
For more information on module installation, please visit the detailed CPAN module installation guide.