/ 
CatalystX-Usul-0.7.1181
/ CatalystX::Usul::Programs

Name

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

Version

This document describes CatalystX::Usul::Programs version 0.7.$Revision: 1181 $

Synopsis

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

# In yourProg.pl
use YourClass;

exit YourClass->new( appclass => 'YourApplicationClass' )->run;

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

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

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

appclass

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

arglist

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

c method

The method in the subclass to call

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

q

Quiet. 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

quiet

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

BUILDARGS

Initialise the contents of the hash used to instantiate the object. It is a private method, so do not call it

BUILD

Called by the constructor to complete the object instantiation

add_leader

$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

anykey

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

can_call

$bool = $self->can_call( $method );

Returns true if $self has a method given by $method that has defined the method method attribute

debug_flag

Returns the command line debug flag to match the current debug state

dump_self

$self->dump_self;

Dumps out the self referential object using Data::Dumper

error

$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

fatal

$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

get_line

$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

get_meta

$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

get_option

$option = $self->get_line( $question, $default, $quit, $width, $options );

Prompts the user to select one from the list of options

get_owner

($uid, $gid) = $self->get_owner( $post_install_config_hash_ref );

Returns the numeric user and group ids of the application owner

info

$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

interpolate_cmd

$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

list_methods

$self->list_methods

Prints a list of methods that can be called through this program

loc

$local_text = $self->loc( $key, $args );

Localizes the message. Calls "loc" in CatalystX::Usul

output

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

Calls "loc" with the passed args. Adds the program leader and prints the result to STDOUT

prompt

$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

-1

Return the first character typed

-d

Default response

-e

The character to echo in place of the one typed

-p

Prompt string

read_post_install_config

$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

run

$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

usage

$self->usage( $verbosity );

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

warning

$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

yorn

$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

_build_debug

$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

_build_log

_get_control_chars

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

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

_get_homedir

$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

_inflate

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

Inflates symbolic pathnames with their actual runtime values

_load_os_depends

_load_vars_ref

_set_attr

Sets the specified attribute from the command line option

_raw_mode

$self->_raw_mode( $handle );

Puts the terminal in raw input mode

_restore_mode

$self->_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
Log::Handler
Term::ReadKey
Text::Autoformat

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

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