NAME

Getopt::Plus - Options wrapper with standard options, help system and more

SYNOPSIS

DESCRIPTION

CLASS CONSTANTS

FILE_SIZE_HUMAN

Map from file size in bytes to human name, as hashref, keys being name (full name, lowercase, no trailing 's') and abbrev (one/two-letter abbreviation).

Option Types

Permissable values to the type field of an option specifier.

OPT_FLOAT
OPT_INT
OPT_STRING
OPT_FDLEVEL
OPT_BOOLEAN

Error Codes

ERR_OK: Not an error at all. Hence the name.
ERR_ABNORMAL: Not so much an error as a non-erroneous circumstance worthy of signalling, e.g., grep finding no matches.
ERR_UTILITY: Again, not really an error, rather a utility function being called --- e.g., the --help or --version. This gets an error code because it is almost certainly an error to call from batch scripts.
ERR_USAGE: The program was called wrong.
ERR_IO_READ: Some problem reading from disk or network (system read).
ERR_IO_WRITE: Some problem writing to disk or network (system write).
ERR_DB_READ: Some problem reading from db or similar (application read).
ERR_DB_WRITE: Some problem writing to db or similar (application write).
ERR_EXTERNAL: Some problem with an external application.
ERR_INTERNAL: An internal logic error (the sort of thing that should never happen, but has been caught by an internal assertion or sanity check).
ERR_INPUT: Some problem with the input file (which was read fine, but contains bad data).
ERR_UNKNOWN

CLASS COMPONENTS

CLASS HIGHER-LEVEL FUNCTIONS

CLASS HIGHER-LEVEL PROCEDURES

find_exec

For each directory P of the current path (in order), check if the named program exists in P and is executable (just as the shell would when executing a command).

ARGUMENTS

exec: The name of the command to execute

RETURNS

path: If the command exists in the path, the path to the command. The path will be relative if the given path segment is. If the command does not exist in the path, then nothing (undef or the empty list) shall be returned.

ftime

This function is exported upon request.

SYNOPSIS

print ftime 86500; # 1d0h0m40s
print ftime 357;   # 5m57s

ARGUMENTS

time: time (duration) to format, as a number of seconds

RETURNS

The input time, formatted as days/hours/minutes/seconds (larger exponents produced only as needed)

commify

This function is exported upon request.

SYNOPSIS

print commify 1_535_343;          # 1,535,343
print commify 1_535_343.45459845; # 1,535,343.454,598,45

ARGUMENTS

number: number to commify.

RETURNS

The input number, with commas between groups 3 digits.

human_file_size

This function is exported upon request.

SYNOPSIS

print human_file_size(1_000);     # 1000b
print human_file_size(1_024);     # 1Kb
print human_file_size(1_535);     # 1Kb
print human_file_size(1_535_343); #1Mb

ARGUMENTS

bytes: An integer being a number of bytes

RETURNS

A human-readable representation of the size. That is, the bytes suffixed with the appropriate b/Kb/Mb/etc. exponent. Note that the mantissa is rounded to the nearest integer

INSTANCE CONSTRUCTION

new

Create & return a new thing.

SYNOPSIS

my $RSE =
  Getopt::Plus->new(scriptname => 'exec-monitor',
                    scriptsumm => 'Exec a process, monitor resources',
                    copyright  => <<'END',
This program is copyright __CYEARS__ Martyn J. Pearce. This program is free
software; you can redistribute it and/or modify it under the same terms
as Perl itself.
END
                    main       => sub {},
                    argtype    => 'exec',
                    arg_ary    => '+',
                    options    =>
                      [{
                        names     => [qw( output o )],
                        type      => OPT_FDLEVEL,
                        arg_reqd  => 1,
                        mandatory => 0,
                        summary   => 'No meaning',
                        desc      => 'No description',
                        default   => 'foo',
                        linkage   => sub {
                          my ($rse, $opt, $value) = @_;
                          Log::Info::enable_file_channel(MONITOR_CHANNEL,
                                                         $value,
                                                         'output',
                                                         MONITOR_SINK);
                          $sink_added = 1;
                        },
                       },
                      ],
                    );

$RSE->run;

ARGUMENTS

Arguments are taken as key => value pairs. Recognized keys are:

scriptname

Mandatory The canonical name of the script. This should not be $0 --- it should have no path, and be the canonical name. Hence, for gunzip , this would be gzip.

scriptsumm

Optional A one-line summary of the purpose of the script; suitable for the header (NAME) line of a man page.

copyright

Optional A (possibly multi-line) summary of the copyright status of this program. If no copyright option is provided, this program will state that it has no copyright. If the copyright contains the text __CYEARS__, this will be replaced with the approraite copyright years.

main

Mandatory This must be a coderef. It will be called once for each argument on the command line after options processing. Its arguments will be:

rse

This instance of Getopt::Plus.

arg_name

The ARGV item in question

output_fns

If output_suffix has any members, then this contains one filename for each member, constructed appending the member onto the basename of the arg_name, with any (single) trailing suffix stripped. The value is an arrayref.

Hence, if arg_name is /tmp/blibble.foo.baz, and output_suffix is set to (jim, kate), then output_fns is [blibble.foo.jim, blibble.foo.kate].

c_years

Optional An arrayref of copyright years. This is required if the copyright option contains the text __CYEARS__.

package

Optional The package from which this program comes. Please set this correctly, so a user can determine which package to install on their box to install this program (this is useful when, for example, asking a friend or colleague the origin a your cool script). The package name should not be a class name, e.g., Getopt::Plus, but a partial file name, e.g., Getopt-Plus.

version

Optional A version number. If the script comes from a package, then please use the version number of the package here, not some individual concept of version for the executable. This is for two reasons:

Since the executable is a part of the package, it presumably utilizes common libraries which have likely changed as the package got updated. Therefore the executable behaviour will have changed even if the specific script code has not.
Users typically install the package as a whole (after all, that's why they're distributed as packages...), so the version of the installed package is more useful than a script version number which has no direct connection.

options

Optional

An arrayref of option specifications.

Each specification is a hashref, with the following keys:

names

Mandatory An arrayref of available names for this option. Both short & long options are given here; any single-char option is a short option, any multi-char option is a long option. There is no meaning to the order, other than the "default" name comes first; this is used only by the linkage specifier.

type

Optional A specifier of the type of the argument, if any. Any value from Option Type is permissable. If not provided, this option brooks no argument.

Default: empty (no argument)

arg_reqd

Optional If true, the option requires an argument. The type argument is mandatory if this is true. The program will fail with status ERR_USAGE if this argument is provided without an argument.

Default: false

mandatory

Optional If true, this option must be invoked. The program will fail with status ERR_USAGE if this argument is not invoked. Mandatory arguments must have simple scalar linkage.

Default: false

linkage

Optional If provided, this may be any type that Getopt::Long accepts.

If the linkage is a coderef, it will be called as would Getopt::Long, with the exception that the subject RSE instance will be inserted as the first argument.

If linkage is not provided, then it must be provided in the first (linkages) argument to get_options, or else you will not be able to get at any values for the option (but the user will still be able to use it). This is probably only useful for compatibility options that are ignored.

summary

Optional A short summary of the meaning of the option. Keep it short (preferably 16 chars or less)

Default: the empty string

desc

Optional A long description of the meaning of the option.

Default: the empty string

default

Optional The default value of the option. Currently, this has no semantic value (but this may change in future). It is used for documentation, however.

Default: the empty string

hidden

Optional If true, the option is not documented. This is intended for developer-only options.

Default: false

Default: empty list.

check

Optional If provided, a coderef that is executed immediately after the options have been processed. It is passed a single argument, that this is RSE instance. This is intended to check that the program can run --- e.g., to detect incorrect options combinations, errors in the environment. Any return value is ignored; if an error is detected, call $rse->die, and the program will terminate appropriately before any real work is done.

This differs from initialize in that it runs in every mode.

Default: an empty coderef.

initialize

Optional If provided, a coderef that is executed prior to any call of main. It is passed a single argument, that this is RSE instance. This is intended to perform any initialization tasks common to all arguments. Any return value is ignored; if an error is detected, call $rse->die, and the program will terminate appropriately before any real work is done.

This differs from check in that it only runs in normal mode, so in other modes (e.g., requisite checking other verification modes), this is not run.

Default: an empty coderef.

finalize

Optional If provided, a coderef that is executed after to every call of main. It is passed a single argument, that this is RSE instance. This is intended to perform any cleanup tasks common to all arguments; often cleaning up resources allocated by initialize. Any return value is ignored; if an error is detected, call $rse->die, and the program will terminate appropriately.

This is analogous to initialize.

Default: an empty coderef.

end

Optional This is very much like finalize, but is run in all modes, even if one of these previous stages failed.

Default: an empty coderef.

argtype

Optional The type of each argument. This (currently) has no semantic value; it is used in documentation. A typical value might be 'file'. This makes sense only if arg_ary is not '0'.

arg_ary

Optional The number of args permissable to this executable (after any option processing).

Valid values are:

'0'
'1'
'+'
'*'

It is an error to specify an arg_ary that is not '0' without also specifying an argtype.

output_suffix

Optional If defined, then for every file specified on the command line, then output files named by adding the given extensions are considered to be created. The value should be a simple value or an arrayref.

dry_run

Optional If true, this program respects the --dry-run option. Do not set it unless it is true --- that would give the user a false sense of security.

The dry_run method will error if called on an instance that is does not have this option set.

If set to the special value 'hidden', then the option will be parsed and the dry_run method will work, but the option will be not documented to the user.

INSTANCE COMPONENTS

The following components are implemented via Class::MethodMaker

Scalar Components

mode: The current mode in force. Defaults to undef. This needs to be selected in the check block to have effect.

List Components

output_suffix: If defined, the output suffix to use. The value should not include any initial '.'. So, for mp3 files, use 'mp3', not '.mp3'. This is a list element; if it contains multiple values, then multiple output files are considered to be created. Output file names are always created in the same order as the suffixes in this list.

Hash Components

mode_info

A map from a mode name to details about that mode. This is for storage of run modes.

The detail itself must be a hashref; recognized keys are

initialize: A coderef
main: A coderef
finalize: A coderef

Boolean Components

args_done: Set this to true to prevent any main calls. Implemented to all callbacks from main to prevent further processing (without signalling an error).

INSTANCE HIGHER-LEVEL FUNCTIONS

dry_run

PREREQUISITES

This instance was created with the dry_run option set.

ARGUMENTS

None

RETURNS

dry_run: True if the program is in dry-run mode (the --dry-run option has been invoked).

run

Do the business.

parse command-line options
run check
select mode, and therefore initialize, main & finalize.
run initialize
check number of arguments
run main with each argument (or with undef, if permissable and no arguments provided)
run finalize
run end
exit with the appropriate error code

output_fn

ARGUMENTS

input_fn: Name of the input file to construct an output file name from.

RETURNS

output_fn+: Name of the output file. Not defined if output_suffix is not set. May be multiple names if multiple output_suffixes are set.

check_run

ARGUMENTS

The arguments are taken as key => value pairs. Like a hash. The recognized keys are:

cmd: Mandatory. The command to run, as an arrayref of items, where each item is itself an arrayref (a command, as a list of arguments), or a '|' symbol (to pipe commands into one another.)
name: Optional. A label for informational messages.
stdin: Optional. A scalar (filename) or scalar ref (ref to hold string) for std input.
stdout: Optional
stderr: Optional
expect: Optional. The error code to expect. Defaults to zero. check_run will croak if an unexpected error_code occurs.
err_code: Optional. The error code to set in case of failure. Defaults to ERR_EXTERNAL.
redirects: A list of redirects (other than std(in|out|err)), in IPC::Run notation.
dry_run: If true, observes the dry_run flag --- i.e., if dry_run is set, then the external executable is not run (but messages are still issued). Defaults to 0 (for backward compatibility).

INSTANCE HIGHER-LEVEL PROCEDURES

new_exit_value

Generate a new exit value for a given error type. An exception is thrown if no new exit value is available.

ARGUMENTS

message: A small (<= 60 chars) message to associate with the exit value. This is given in the DIAGNOSTICS section of the manpage.

RETURNS

exit_value: An exit value to use for this error type (in the range 0--255).

EXAMPLES

BUGS

REPORTING BUGS

Email the author.

AUTHOR

Martyn J. Pearce fluffy@cpan.org

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

CLASS CONSTANTS

FILE_SIZE_HUMAN

Option Types

Error Codes

CLASS COMPONENTS

CLASS HIGHER-LEVEL FUNCTIONS

CLASS HIGHER-LEVEL PROCEDURES

find_exec

ftime

commify

human_file_size

INSTANCE CONSTRUCTION

new

INSTANCE COMPONENTS

Scalar Components

List Components

Hash Components

Boolean Components

INSTANCE HIGHER-LEVEL FUNCTIONS

dry_run

run

output_fn

check_run

INSTANCE HIGHER-LEVEL PROCEDURES

new_exit_value

EXAMPLES

BUGS

REPORTING BUGS

AUTHOR

COPYRIGHT

SEE ALSO

Module Install Instructions