Getopt::Plus - Options wrapper with standard options, help system and more
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).
Permissable values to the type field of an option specifier.
Not an error at all. Hence the name.
Not so much an error as a non-erroneous circumstance worthy of signalling, e.g., grep finding no matches.
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.
The program was called wrong.
Some problem reading from disk or network (system read).
Some problem writing to disk or network (system write).
Some problem reading from db or similar (application read).
Some problem writing to db or similar (application write).
Some problem with an external application.
An internal logic error (the sort of thing that should never happen, but has been caught by an internal assertion or sanity check).
Some problem with the input file (which was read fine, but contains bad data).
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).
The name of the command to execute
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.
This function is exported upon request.
print ftime 86500; # 1d0h0m40s print ftime 357; # 5m57s
time (duration) to format, as a number of seconds
This function is exported upon request.
print commify 1_535_343; # 1,535,343 print commify 1_535_343.45459845; # 1,535,343.454,598,45
number to commify.
This function is exported upon request.
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
An integer being a number of bytes
Create & return a new thing.
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 are taken as key => value pairs. Recognized keys are:
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.
Optional A one-line summary of the purpose of the script; suitable for the header (NAME) line of a man page.
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.
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:
This instance of Getopt::Plus.
The ARGV item in question
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].
Optional An arrayref of copyright years. This is required if the copyright option contains the text __CYEARS__.
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.
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:
Optional
An arrayref of option specifications.
Each specification is a hashref, with the following keys:
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.
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)
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
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
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.
Optional A short summary of the meaning of the option. Keep it short (preferably 16 chars or less)
Default: the empty string
Optional A long description of the meaning of the option.
Default: the empty string
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
Optional If true, the option is not documented. This is intended for developer-only options.
Default: false
Default: empty list.
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.
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.
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.
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.
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'.
Optional The number of args permissable to this executable (after any option processing).
Valid values are:
It is an error to specify an arg_ary that is not '0' without also specifying an argtype.
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.
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.
The following components are implemented via Class::MethodMaker
The current mode in force. Defaults to undef. This needs to be selected in the check block to have effect.
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.
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
A coderef
A coderef
A coderef
Set this to true to prevent any main calls. Implemented to all callbacks from main to prevent further processing (without signalling an error).
This instance was created with the dry_run option set.
None
True if the program is in dry-run mode (the --dry-run option has been invoked).
Do the business.
checkmode, and therefore initialize, main & finalize.initializemain with each argument (or with undef, if permissable and no arguments provided)finalizeendName of the input file to construct an output file name from.
Name of the output file. Not defined if output_suffix is not set. May be multiple names if multiple output_suffixes are set.
The arguments are taken as key => value pairs. Like a hash. The recognized keys are:
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.)
Optional. A label for informational messages.
Optional. A scalar (filename) or scalar ref (ref to hold string) for std input.
Optional
Optional
Optional. The error code to expect. Defaults to zero. check_run will croak if an unexpected error_code occurs.
Optional. The error code to set in case of failure. Defaults to ERR_EXTERNAL.
A list of redirects (other than std(in|out|err)), in IPC::Run notation.
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).
Generate a new exit value for a given error type. An exception is thrown if no new exit value is available.
A small (<= 60 chars) message to associate with the exit value. This is given in the DIAGNOSTICS section of the manpage.
An exit value to use for this error type (in the range 0--255).
Email the author.
Martyn J. Pearce fluffy@cpan.org
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.
