NAME

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

SYNOPSIS

DESCRIPTION

CLASS CONSTANTS

Option Types

Permissable values to the type field of an option specifier.

OPT_FLOAT

OPT_INT

OPT_STRING

OPT_FDLEVEL

OPT_BOOLEAN

CLASS COMPONENTS

CLASS HIGHER-LEVEL FUNCTIONS

CLASS HIGHER-LEVEL PROCEDURES

INSTANCE CONSTRUCTION

new

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

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.

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. 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 code is not called in requisites mode.

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 code is not called in requisites mode.

Default: an empty coderef.

end

Optional This is very much like finalize, but is run in all modes.

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

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).

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.

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 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

cpanm Getopt::Plus

perl -MCPAN -e shell
install Getopt::Plus