NAME
App::Base::Script::Common - Behaviors common to App::Base::Script and App::Base::Daemon
DESCRIPTION
App::Base::Script::Common provides infrastructure that is common to the App::Base::Script and App::Base::Daemon classes, including options parsing.
REQUIRED SUBCLASS METHODS
documentation
Returns a scalar (string) containing the documentation portion of the script's usage statement.
__run
For INTERNAL USE ONLY: Used by subclasses such as App::Base::Script and App::Base::Daemon to redefine dispatch rules to their own required subclass methods such as script_run() and daemon_run().
error
All App::Base::Script::Common-implementing classes must have an error() method that handles exceptional cases which also require a shutdown of the running script/daemon/whatever.
OPTIONAL SUBCLASS METHODS
options
Concrete subclasses can specify their own options list by defining a method called options() which returns an arrayref of hashes with the parameters required to create App::Base::Script::Option objects. Alternatively, your script/daemon can simply get by with the standard --help option provided by its role.
ATTRIBUTES
_option_values
The (parsed) option values, including defaults values if none were specified, for all of the options declared by $self. This accessor should not be called directly; use getOption() instead.
orig_args
An arrayref of arguments as they existed prior to option parsing.
parsed_args
An arrayref of the arguments which remained after option parsing.
script_name
The name of the running script, computed from $0.
METHODS
BUILDARGS
Combines the results of base_options() and options() and then parses the command-line arguments of the script. Exits with a readable error message if the script was invoked in a nonsensical or invalid manner.
all_options
Returns the composition of options() and base_options() as list of App::Base::Script::Option objects.
base_options
The options provided for every classes which implements App::Base::Script::Common. See BUILT-IN OPTIONS
switch_name_width
Computes the maximum width of any of the switch (option) names.
switches
Generates the switch table output of the usage statement.
cli_template
The template usage form that should be shown to the user in the usage statement when --help or an invalid invocation is provided.
Defaults to "(program name) [options]", which is pretty standard Unix.
usage
Outputs a statement explaining the usage of the script, then exits.
getOption
Returns the value of a specified option. For example, getOption('help') returns 1 or 0 depending on whether the --help option was specified. For option types which are non-boolean (see App::Base::Script::Option) the return value is the actual string/integer/float provided on the common line - or undef if none was provided.
run
Runs the script, returning the return value of __run
_parse_arguments
Parses the arguments in @ARGV, returning a hashref containing:
- -
-
The parsed arguments (that is, those that should remain in @ARGV)
- -
-
The option values, as a hashref, including default values
- -
-
Whether the parsing encountered any errors
__error
Dispatches its arguments to the subclass-provided error() method (see REQUIRED SUBCLASS METHODS), then exits.
USAGE
Invocation of a App::Base::Script::Common-based program is accomplished as follows:
- -
-
Define a class that derives (via 'use Moose' and 'with') from App::Base::Script::Common
- -
-
Instantiate an object of that class via new( )
- -
-
Run the program by calling run( ). The return value of run( ) is the exit status of the script, and should typically be passed back to the calling program via exit()
The new() method
A Moose-style constructor for the App::Base::Script::Common-derived class. Every such class has one important attribute: options -- an array ref of hashes describing options to be added to the command-line processing for the script. See App::Base::Script::Option for more information.
Options handling
One of the most useful parts of App::Base::Script::Common is the simplified access to options processing. The getOption() method allows your script to determine the value of a given option, determined as follows:
If given as a command line option (registered via options hashref)
The default value specified in the App::Base::Script::Option object that was passed to the options() attribute at construction time.
For example, if your script registers an option 'foo' by saying
my $object = MyScript->new(
options => [
App::Base::Script::Option->new(
name => "foo",
documentation => "The foo option",
option_type => "integer",
default => 7,
),
]
);Then in script_run() you can say
my $foo = $self->getOption("foo")And $foo will be resolved as follows:
A --foo value specified as a command-line switch
The default value specified at registration time ("bar")
BUILT-IN OPTIONS
--help
Print a usage statement