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.
type
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
The input time, formatted as days/hours/minutes/seconds (larger exponents produced only as needed)
print commify 1_535_343; # 1,535,343 print commify 1_535_343.45459845; # 1,535,343.454,598,45
number to commify.
The input number, with commas between groups 3 digits.
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
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
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.
gunzip
gzip
Optional A one-line summary of the purpose of the script; suitable for the header (NAME) line of a man page.
NAME
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.
__CYEARS__
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].
arg_name
output_suffix
(jim, kate)
output_fns
[blibble.foo.jim, blibble.foo.kate]
Optional An arrayref of copyright years. This is required if the copyright option contains the text __CYEARS__.
copyright
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.
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:
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.
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.
linkage
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.
must
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.
linkages
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.
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.
Optional If true, the option is not documented. This is intended for developer-only options.
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.
$rse->die
This differs from initialize in that it runs in every mode.
initialize
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.
main
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.
check
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.
Optional This is very much like finalize, but is run in all modes, even if one of these previous stages failed.
finalize
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.
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.
--dry-run
The dry_run method will error if called on an instance that is does not have this option set.
dry_run
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.
'hidden'
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
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.
parse command-line options
run check
select mode, and therefore initialize, main & finalize.
mode
run initialize
check number of arguments
run main with each argument (or with undef, if permissable and no arguments provided)
run finalize
run end
end
exit with the appropriate error code
Name 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. 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.
IPC::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).
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
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.
1 POD Error
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head2'
To install Getopt::Plus, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Getopt::Plus
CPAN shell
perl -MCPAN -e shell install Getopt::Plus
For more information on module installation, please visit the detailed CPAN module installation guide.