/ 
Getopt-EX-3.05
⭐ Starred 1 / Getopt::EX::Long

NAME

Getopt::EX::Long - Getopt::Long compatible extended module

SYNOPSIS

use Getopt::EX::Long;
GetOptions("file=s" => \my $file);

or using the object-oriented interface:

use Getopt::EX::Long;
my $parser = Getopt::EX::Long::Parser->new(
    config   => [ qw(posix_default no_ignore_case) ],
    exconfig => [ BASECLASS => 'App::example' ],
);
$parser->getoptions("file=s" => \my $file);

DESCRIPTION

Getopt::EX::Long is almost fully compatible with Getopt::Long. You can replace the module declaration, and it should work the same as before (see "INCOMPATIBILITY").

In addition to standard Getopt::Long functionality, users can define their own option aliases and write dynamically loaded extension modules. If the command name is example, the file

~/.examplerc

is loaded by default. In this rc file, users can define option aliases with macro processing. This is useful when the command takes complex arguments.

Special options starting with -M load the corresponding Perl module. The module is assumed to be under a specific base class. For example:

% example -Mfoo

loads the App::example::foo module by default.

Since extension modules are normal Perl modules, users can write any code they need. If the module is specified with an initial function call, that function is called when the module is loaded:

% example -Mfoo::bar(buz=100)

This loads module foo and calls function bar with the parameter buz set to 100.

If the module includes a __DATA__ section, it is interpreted as an rc file. Combined with the startup function call, this allows module behavior to be controlled through user-defined options.

For details about rc files and module specification, see Getopt::EX::Module.

CONFIG OPTIONS

Config options are set by ExConfigure or the exconfig parameter for the Getopt::EX::Long::Parser::new method.

AUTO_DEFAULT

Config options RCFILE and BASECLASS are automatically set based on the name of the command executable. If you don't want this behavior, set AUTO_DEFAULT to 0.

USER_SETTINGS

Whether to read the startup rc file of the program, ~/.progrc or the file given by RCFILE. Defaults to 1. When set to 0, the rc file is not read. Modules loaded with -M and their default options are not affected. The environment variable GETOPTEX_NO_USER_SETTINGS sets it to 0 from outside of the program (see "ENVIRONMENT").

A program which takes default options from somewhere else than the rc file can skip them as well; see config_option.

PROGRAM

Not a config option itself, but names the program whose config options are set by this ExConfigure call. Default is the current program, the basename of $0.

This is for a program which calls another program as a function in the same process, as Command::Run does in its nofork mode: the callee reads its own rc file, because its config options are kept apart from those of the caller (see "PROGRAM STATE"). The rc file holds the settings of the user for the callee run from the command line, and the output of the caller should not depend on them. The caller turns them off for the callee by name, before the first GetOptions call of the callee:

ExConfigure(PROGRAM => 'ansicolumn', USER_SETTINGS => 0);

Other options including RCFILE and BASECLASS are passed to Getopt::EX::Loader. Read its documentation for details.

FUNCTIONS

ExConfigure

Set config options. See "CONFIG OPTIONS".

ExReset

Reset the internal loader and configuration to their default state. This is useful when you need to reinitialize the module state, for example after forking a child process.

Note that ExConfigure and GetOptionsFromArray automatically detect forked processes and reset internally, so explicit calls to ExReset are usually unnecessary.

config_option [ program ]

Return the hash reference to the config options of the current program, or of the named one.

Some programs take default options from an environment variable as well, as greple does with GREPLEOPTS. This module does not handle such variables, but the program can read USER_SETTINGS through this function and skip them when it is 0, along with the rc file:

if (Getopt::EX::Long::config_option()->{USER_SETTINGS}) {
    unshift @ARGV, shellwords($ENV{GREPLEOPTS} // '');
}

ENVIRONMENT

GETOPTEX_NO_USER_SETTINGS

Set USER_SETTINGS to 0 for the programs named in it, separated by spaces or commas, or for every program when it is 1 or *, as far as the programs read their rc file through this module. Use it to run programs without the settings of the user, in tests or in a container, and to reach programs which are started as separate processes. It is read when the config options of a program are first used, so it has to be set before that.

PROGRAM STATE

The config options and the loader (which holds the rc file and the modules loaded) belong to the program, whose name $0 determines the default rc file and base class. They are kept for each program name, the basename of $0: when $0 is changed, as Command::Run does to call a program as a function without forking, ExConfigure and GetOptions work on the state of that program, and the rc file of one program is not applied to another.

The state of a program is created when it is first used, and the loader is created at its first GetOptions call and kept. Config options given for a program afterwards, with PROGRAM or through the environment, do not change the loader which has already read the rc file. When the process is forked, the state is reset in the child, so a caller should set the config options of the callee right before calling it.

INCOMPATIBILITY

The subroutine GetOptionsFromString is not supported.

SEE ALSO

Getopt::EX, Getopt::EX::Module, Getopt::EX::Loader