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

0.3.$Revision: 612 $

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

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

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

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

   $obj = 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 XML file

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

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

   $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

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

   $obj = $obj->config();

Return a reference to self

   $rv = $obj->dispatch;

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

   $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

   $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

   $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

   $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

   $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

   $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

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

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

   $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

Return $self

   $obj->usage( $verbosity );

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

   $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

   $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

Initialise the contents of the self referential hash

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

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

   $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

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

Inflates symbolic pathnames with their actual runtime values

Sets the specified attribute from the command line option

   $obj->_raw_mode( $handle );

Puts the terminal in raw input mode

   $obj->_restore_mode( $handle );

Restores line input mode to the terminal

None

Turning debug on produces some more output

CatalystX::Usul

CatalystX::Usul::InflateSymbols

Class::Null

Getopt::Mixed

IO::Interactive

IPC::SRLock

Log::Handler

Term::ReadKey

XML::Simple

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>

Copyright (c) 2008 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