Martyn J. Pearce > Getopt-Plus-0.98 > Getopt::Plus

Download:
Getopt-Plus-0.98.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.98   Source   Latest Release: Getopt-Plus-0.99

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.

  1. parse command-line options
  2. run check
  3. select mode, and therefore initialize, main & finalize.
  4. run initialize
  5. check number of arguments
  6. run main with each argument (or with undef, if permissable and no arguments provided)
  7. run finalize
  8. run end
  9. 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 ^

Copyright (c) 2002, 2003, 2004, 2005 Martyn J. Pearce.

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

SEE ALSO ^

syntax highlighting: