/ 
Class-Usul-0.41.1
River stage one • 3 direct dependents • 3 total dependents
/ Class::Usul::Programs

Name

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

Synopsis

# In YourClass.pm
use Moo;

extends q(Class::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

Configuration and Environment

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

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

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

params

List of value that are passed to the method called by "run"

v verbose

Repeatable boolean that increases the verbosity of the output

Subroutines/Methods

BUILDARGS

Called just before the object is constructed this method modifier determines the location of the config file

BUILD

Called just after the object is constructed this methods handles dispatching to the help methods and prompting for the debug state

add_leader

$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

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

$cmd_line_option = $self->debug_flag

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

dump_self - Dumps the program object

$self->dump_self;

Dumps out the self referential object using Data::Printer

error

$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

_exit_usage

$self->_exit_usage( $verbosity );

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

_exit_version

$self->_exit_version

Prints out the version of the C::U::Programs subclass and the exits

fatal

$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

_get_debug_option

$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

_get_homedir

$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

help - Display help text about a method

$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

info

$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

interpolate_cmd

$cmd = $self->interpolate_cmd( $cmd, @args );

Calls _interpolate_${cmd}_cmd to apply the arguments to the command in a command specific way

list_methods - Lists available command line methods

$self->list_methods;

Lists the methods (marked by the method subroutine attribute) that can be called via the run method

loc

$localized_text = $self->loc( $key, @options );

Localizes the message. Calls "localize" in Class::Usul::L10N. Adds the constant DEFAULT_L10N_DOMAINS to the list of domain files that are searched. Adds $self->locale and $self-config->name >> (search domain) to the arguments passed to localize

output

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

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

quiet

$bool = $self->quiet( $bool );

Custom accessor/mutator for the quiet_flag attribute. Will throw if you try to turn quiet mode off

run

$rv = $self->run;

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

run_chain

$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

warning

$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

Diagnostics

Turning debug on produces some more output

Dependencies

Class::Inspector
Class::Usul::IPC
Class::Usul::File
Class::Usul::Options
Encode
Moo
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) 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