CatalystX::Usul::Programs - Provide support for command line programs
This document describes CatalystX::Usul::Programs version 0.6.$Revision: 1165 $
# In YourClass.pm use base qw(CatalystX::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
$self = CatalystX::Usul::Programs->new({ ... })
Return a new program object. The optional argument is a hash ref which may contain these attributes:
The name of the application to which the program using this class belongs. It is used to find the application installation directory which will contain the configuration file
Additional Getopts::Mixed command line initialisation arguments are appended to the default list shown below:
The method in the subclass to call
Turn debugging on
Print long help text extracted from this POD
Print short help text extracted from this POD
Print error messages in the selected language. If no language is supplied print the error code and attributes
Do not prompt to turn debugging on
The method that is dispatched to can access the key/value pairs from the $self->vars hash ref
$self->vars
Quiet. Suppresses the usual started/finished information messages
Boolean which if true causes program debug output to be generated. Defaults to false
Environment variable containing the path to a file which contains the application installation directory. Defaults to the environment variable <uppercase application name>_HOME
The path to a file which contains the application installation directory.
Boolean which if true will stop the constructor from prompting the user to turn debugging on. Defaults to false
Defaults to /opt/<application name>
The name of the program. Defaults to the value returned by caller
Boolean which if true suppresses the usual started/finished information messages. Defaults to false
Initialise the contents of the hash used to instantiate the object. It is a private method, so do not call it
Called by the constructor to complete the object instantiation
$leader = $self->add_leader( $text, $args );
Prepend $self->name to each line of $text. If $args->{no_lead} exists then do nothing. Return $text with leader prepended
$self->name
$text
$args->{no_lead}
$key = $self->anykey( $prompt );
Prompt string defaults to 'Press any key to continue...'. Calls and returns prompt. Requires the user to press any key on the keyboard (that generates a character response)
$bool = $self->can_call( $method );
Returns true if $self has a method given by $method that has defined the method method attribute
$self
$method
Returns the command line debug flag to match the current debug state
$self->dump_self;
Dumps out the self referential object using Data::Dumper
$self->error( $text, $args );
Calls "loc" with the passed args. Logs the result at the error level, then adds the program leader and prints the result to STDERR
$self->fatal( $text, $args );
Calls "loc" 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
$line = $self->get_line( $question, $default, $quit, $width, $newline );
Prompts the user to enter a single line response to $question which is printed to STDOUT with a program leader. If $quit is true then the options to quit is included in the prompt. If the $width argument is defined then the string is formatted to the specified width which is $width or $self->pwdith or 40. If $newline is true a newline character is appended to the prompt so that the user get a full line of input
$question
$quit
$width
$self->pwdith
$newline
$res_obj = $self->get_meta( $dir );
Extracts; name, version, author and abstract from the META.yml file. Optionally look in $dir for the file instead of $self->appldir. Returns a response object with accessors defined
$dir
$self->appldir
$option = $self->get_line( $question, $default, $quit, $width, $options );
Prompts the user to select one from the list of options
($uid, $gid) = $self->get_owner( $post_install_config_hash_ref );
Returns the numeric user and group ids of the application owner
$self->info( $text, $args );
Calls "loc" with the passed args. Logs the result at the info level, then adds the program leader and prints the result to STDOUT
$self->interpolate_cmd( $cmd, @args );
Flattens @args and returns an array ref of all the passed parameters. If _interpolate_${cmd}_cmd exists it is called instead and is expected to create the returned array ref
@args
_interpolate_${cmd}_cmd
$self->list_methods
Prints a list of methods that can be called through this program
$local_text = $self->loc( $key, $args );
Localizes the message. Calls "loc" in CatalystX::Usul
$self->output( $text, $args );
Calls "loc" with the passed args. Adds the program leader and prints the result to STDOUT
$line = $self->prompt( 'key' => 'value', ... );
This was taken from IO::Prompt which has an obscure bug in it. Much simplified the following keys are supported
Return the first character typed
Default response
The character to echo in place of the one typed
Prompt string
$picfg_hash_ref = $self->read_post_install_config;
Returns a hash ref of the post installation config which was written to the control directory during the installation process
$rv = $self->run;
Call the method specified by the -c option on the command line if it exists and "can_call" returns true. Returns the exit code
-c
$self->usage( $verbosity );
Print out usage information from POD. The $verbosity is; 0, 1 or 2
$verbosity
$self->warning( $text, $args );
Calls "loc" with the passed args. Logs the result at the warn level, then adds the program leader and prints the result to STDOUT
$self->yorn( $question, $default, $quit, $width );
Prompt the user to respond to a yes or no question. The $question is printed to STDOUT with a program leader. The $default argument is 0|1. If $quit is true then the option to quit is included in the prompt. If the $width argument is defined then the string is formatted to the specified width which is $width or $self->pwdith or 40
$default
0|1
$self->_build_debug();
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
($cntrl, %cntrl) = $self->_get_control_chars( $handle );
Returns a string of pipe separated control characters and a hash of symbolic names and values
$path = $self->_get_homedir( 'myApplication' );
Search through subdirectories of @INC looking for the file myApplication.xml. Uses the location of this file to return the path to the installation directory
$tempdir = $self->inflate( '__appldir(var/tmp)__' );
Inflates symbolic pathnames with their actual runtime values
Sets the specified attribute from the command line option
$self->_raw_mode( $handle );
Puts the terminal in raw input mode
$self->_restore_mode( $handle );
Restores line input mode to the terminal
None
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) 2011 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 CatalystX::Usul, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CatalystX::Usul
CPAN shell
perl -MCPAN -e shell install CatalystX::Usul
For more information on module installation, please visit the detailed CPAN module installation guide.