Name

CatalystX::Usul::Programs - Provide support for command line programs

Version

0.3.$Revision: 612 $

Synopsis

# In YourClass.pm
use base qw(CatalystX::Usul::Programs);

# In yourProg.pl
use base qw(YourClass);

exit YourClass->new( appclass => 'MyApplication' )->dispatch;

Description

This base class provides methods common to command line programs. The constructor can initialise a multi-lingual message catalog if required

Subroutines/Methods

new

$obj = CatalystX::Usul::Programs->new({ ... })

Return a new program object. The optional argument is a hash ref which may contain these attributes:

applclass

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 XML file

arglist

Additional Getopts::Mixed command line initialisation arguments are appended to the default list shown below:

c method: The method in the subclass to dispatch to
D: Turn debugging on
H: Print long help text extracted from this POD
h: Print short help text extracted from this POD
L language: Print error messages in the selected language. If no language is supplied print the error code and attributes
n: Do not prompt to turn debugging on
o key=value: The method that is dispatched to can access the key/value pairs from the $self->vars hash ref
S: Suppresses the usual started/finished information messages

debug

Boolean which if true causes program debug output to be generated. Defaults to false

evar

Environment variable containing the path to a file which contains the application installation directory. Defaults to the environment variable <uppercase application name>_HOME

install

The path to a file which contains the application installation directory.

n

Boolean which if true will stop the constructor from prompting the user to turn debugging on. Defaults to false

prefix

Defaults to /opt/<application name>

script

The name of the program. Defaults to the value returned by caller

silent

Boolean which if true suppresses the usual started/finished information messages. Defaults to false

add_leader

$leader = $obj->add_leader( $text, $args );

Prepend $obj->name to each line of $text. If $args->{no_lead} exists then do nothing. Return $text with leader prepended

anykey

$key = $obj->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)

config

$obj = $obj->config();

Return a reference to self

dispatch

$rv = $obj->dispatch;

Call the method specified by the -c option on the command line. Returns the exit code

error

$obj->error( $text, $args );

Calls CatalystX::Usul::localize with the passed args. Logs the result at the error level, then adds the program leader and prints the result to STDERR

fatal

$obj->fatal( $text, $args );

Calls CatalystX::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

get_debug_option

$obj->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

get_line

$line = $obj->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 $obj->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

get_meta

$res_obj = $obj->get_meta( $dir );

Extracts; name, version, author and abstract from the META.yml file. Optionally look in $dir for the file instead of $obj->appldir. Returns a response object with accessors defined

info

$obj->info( $text, $args );

Calls CatalystX::Usul::localize with the passed args. Logs the result at the info level, then adds the program leader and prints the result to STDOUT

output

$obj->output( $text, $args );

Calls CatalystX::Usul::localize with the passed args. Adds the program leader and prints the result to STDOUT

prompt

$line = $obj->prompt( 'key' => 'value', ... );

This was taken from IO::Prompt which has an obscure bug in it. Much simplified the following keys are supported

-1: Return the first character typed
-d: Default response
-e: The character to echo in place of the one typed
-p: Prompt string

stash

Return $self

usage

$obj->usage( $verbosity );

Print out usage information from POD. The $verbosity is; 0, 1 or 2

warning

$obj->warning( $text, $args );

Calls CatalystX::Usul::localize with the passed args. Logs the result at the warning level, then adds the program leader and prints the result to STDOUT

yorn

$obj->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 $obj->pwdith or 40

_bootstrap

Initialise the contents of the self referential hash

_get_control_chars

($cntrl, %cntrl) = $obj->_get_control_chars( $handle );

Returns a string of pipe separated control characters and a hash of symbolic names and values

_get_homedir

$path = $obj->_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

_inflate

$tempdir = $obj->inflate( '__appldir(var/tmp)__' );

Inflates symbolic pathnames with their actual runtime values

_load_messages

_load_os_depends

_load_vars_ref

_new_log_object

_set_attr

Sets the specified attribute from the command line option

_raw_mode

$obj->_raw_mode( $handle );

Puts the terminal in raw input mode

_restore_mode

$obj->_restore_mode( $handle );

Restores line input mode to the terminal

Configuration and Environment

None

Diagnostics

Turning debug on produces some more output

Dependencies

CatalystX::Usul
CatalystX::Usul::InflateSymbols
Class::Null
Getopt::Mixed
IO::Interactive
IPC::SRLock
Log::Handler
Term::ReadKey
XML::Simple

Incompatibilities

There are no known incompatibilities in this module

Bugs and Limitations

There are no known bugs in this module. Please report problems to the address below. Patches are welcome

Author

Peter Flanigan, <Support at RoxSoft.co.uk>

License and Copyright

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)