/ 
Class-Usul-v0.17.9
River stage one • 3 direct dependents • 3 total dependents
/ Class::Usul::Programs

Name

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

Version

This document describes Class::Usul::Programs version v0.17.$Rev: 8 $

Synopsis

# In YourClass.pm
use Class::Usul::Moose;

extends qw(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

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

Quietens the usual started/finished information messages

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

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

$cmd_line_option = $self->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 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

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

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.json or META.yml file. Looks in the optional $dir directory for the file in addition to $self->appldir and $self->ctrldir. Returns a response object with read-only accessors defined

get_option

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

Returns the selected option number from the list of possible options passed in the $question argument

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

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

_output_version

$self->_output_version

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

print_usage_text

Empty method used to override MooseX::Getop::Basic's latest API incantation. Used to be _getopt_full_usage which we still have to maintain because *we* do not break backward compatibility

__prompt

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

quiet

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

Custom accessor/mutator for the _quiet 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

_output_usage

$self->_output_usage( $verbosity );

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

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

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

__get_control_chars

($cntrl, %cntrl) = __get_control_chars( $handle );

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

__raw_mode

__raw_mode( $handle );

Puts the terminal in raw input mode

__restore_mode

__restore_mode( $handle );

Restores line input mode to the terminal

Diagnostics

Turning debug on produces some more output

Dependencies

Class::Inspector
Class::Usul
Class::Usul::IPC
Class::Usul::File
Class::Usul::TraitFor::LoadingClasses
Class::Usul::TraitFor::UntaintedGetopts
Encode
File::HomeDir
IO::Interactive
MooseX::Getopt::Dashes
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) 2013 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