/ 
Getopt-EX-2.3.1
River stage two • 11 direct dependents • 18 total dependents
⭐ Starred 1 GitHub stars
/ Getopt::EX

NAME

Getopt::EX - Getopt Extender

VERSION

Version 2.3.1

DESCRIPTION

Getopt::EX extends the basic functionality of the Getopt family to support user-definable option aliases, and dynamic modules which work together with a script through the option interface.

INTERFACES

There are two major interfaces to use Getopt::EX modules.

The easier one is Getopt::Long compatible module, Getopt::EX::Long. You can simply replace the module declaration and get the benefits of this module to some extent. It allows users to create a startup rc file in their home directory, which provides user-defined option aliases.

Use Getopt::EX::Loader to get full capabilities. Then the users of your script can create their own extension modules which work together with the original command through the command option interface.

Another module Getopt::EX::Colormap is designed to produce colored text on ANSI terminals, and to provide an easy way to maintain labeled colormap tables and option handling.

Getopt::EX::Long

This is the easiest way to get started with Getopt::EX. This module is almost compatible with Getopt::Long and drop-in replaceable.

In addition, if the command name is example,

~/.examplerc

file is loaded by default. In this rc file, users can define their own options with macro processing. This is useful when the command takes complicated arguments. Users can also define default options which are always used. For example,

option default -n

always gives the -n option when the script is executed. See the Getopt::EX::Module documentation for what you can do in this file.

If the rc file includes a section starting with __PERL__ or __PERL5__, it is evaluated as a Perl program. Users can define any kind of functions there, which can be invoked from command line options if the script is aware of them. At this time, the module object is assigned to the variable $MODULE, and you can access the module API through it.

Also, special command options preceded by -M are recognized and the corresponding Perl module is loaded. For example,

% example -Mfoo

will load App::example::foo module.

This module is a normal Perl module, so users can write anything they want. If the module option comes with an initial function call, it is called at the beginning of command execution. Suppose that the module foo is specified like this:

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

Then, after the module foo is loaded, function bar is called with the parameter buz with value 100.

If the module includes a __DATA__ section, it is interpreted just the same as an rc file. So you can define arbitrary options there. Combined with the startup function call described above, it is possible to control module behavior by user-defined options.

Getopt::EX::Loader

This module provides more primitive access to the underlying modules. You should create loader object first:

use Getopt::EX::Loader;
my $loader = Getopt::EX::Loader->new(
    BASECLASS => 'App::example',
    );

Then load rc file:

$loader->load_file("$ENV{HOME}/.examplerc");

Then process command line options:

$loader->deal_with(\@ARGV);

Finally, pass the built-in functions declared in dynamically loaded modules to the option parser.

my $parser = Getopt::Long::Parser->new;
$parser->getoptions( ... , $loader->builtins )

Actually, this is what Getopt::EX::Long module is doing internally.

Getopt::EX::Func

To make your script communicate with user-defined subroutines, use the Getopt::EX::Func module, which provides the parse_func interface. If your script has a --begin option which tells the script to call a specific function at the beginning of execution, write something like:

use Getopt::EX::Func qw(parse_func);
GetOptions("begin:s" => \my $opt_begin);
my $func = parse_func($opt_begin);
$func->call;

Then the script can be invoked like this:

% example -Mfoo --begin 'repeat(debug,msg=hello,count=2)'

See Getopt::EX::Func for more detail.

Getopt::EX::Colormap

This module is not tightly coupled with other modules in Getopt::EX. It provides a concise way to specify ANSI terminal colors with various effects, and produces terminal sequences by color specification or label parameters.

You can use this module with normal Getopt::Long:

my @opt_colormap;
use Getopt::Long;
GetOptions("colormap|cm=s" => \@opt_colormap);

my %colormap = ( # default color map
    FILE => 'R',
    LINE => 'G',
    TEXT => 'B',
    );
my @colors;

require Getopt::EX::Colormap;
my $handler = Getopt::EX::Colormap->new(
    HASH => \%colormap,
    LIST => \@colors,
    );

$handler->load_params(@opt_colormap);

and then get colored string as follows.

print $handler->color("FILE", "FILE in Red\n");
print $handler->color("LINE", "LINE in Blue\n");
print $handler->color("TEXT", "TEXT in Green\n");

In this example, users can change these colors from the command line option like this:

% example --colormap FILE=C,LINE=M,TEXT=Y

or call arbitrary perl function like:

% example --colormap FILE='sub{uc}'

The above example produces an uppercase version of the provided string instead of an ANSI color sequence.

If you want to use just coloring function, use backend module Term::ANSIColor::Concise.

Getopt::EX::LabeledParam

This is the super-class of Getopt::EX::Colormap. Getopt::Long supports parameter handling within a hash,

my %defines;
GetOptions ("define=s" => \%defines);

and the parameter can be given in key=value format.

--define os=linux --define vendor=redhat

Using Getopt::EX::LabeledParam, this can be written as:

my @defines;
my %defines;
GetOptions ("defines=s" => \@defines);
Getopt::EX::LabeledParam
    ->new(HASH => \%defines)
    ->load_params (@defines);

and the parameter can be given mixed together.

--define os=linux,vendor=redhat

Getopt::EX::Numbers

Parses number parameter descriptions and produces number range lists or number sequences. Number format is composed of four elements: start, end, step and length, like this:

1		1
1:3		1,2,3
1:20:5	1,     6,     11,       16
1:20:5:3	1,2,3, 6,7,8, 11,12,13, 16,17,18

SEE ALSO

Term::ANSIColor::Concise

The coloring capability of Getopt::EX::Colormap is now implemented in this module.

Getopt::EX::Hashed

Getopt::EX::Hashed is a module that automates a hash object to store command line option values for Getopt::Long and compatible modules including Getopt::EX::Long.

Getopt::EX::Config

Getopt::EX::Config provides an interface to define configuration information for Getopt::EX modules. Using this module, it is possible to define configuration information specific to the module and to define module-specific command options.

Getopt::EX::i18n

Getopt::EX::i18n provides an easy way to set the locale environment before executing a command.

Getopt::EX::termcolor

Getopt::EX::termcolor is a common module to manipulate system-dependent terminal colors.

Getopt::EX::RPN

Getopt::EX::RPN provides an RPN (Reverse Polish Notation) calculation interface for command line arguments. This is convenient when you want to define parameters based on terminal height or width.

AUTHOR

Kazumasa Utashiro

COPYRIGHT

The following copyright notice applies to all the files provided in this distribution, including binary files, unless explicitly noted otherwise.

Copyright 2015-2025 Kazumasa Utashiro

LICENSE

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