/ 
Getopt-EX-2.2.1
River stage two • 10 direct dependents • 19 total dependents
/ Getopt::EX

NAME

Getopt::EX - Getopt Extender

VERSION

Version 2.2.1

DESCRIPTION

Getopt::EX extends basic function of Getopt family to support user-definable option aliases, and dynamic module which works together with a script through option interface.

INTERFACES

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

Easy one is Getopt::Long compatible module, Getopt::EX::Long. You can simply replace module declaration and get the benefit of this module to some extent. It allows user to make start up rc file in their home directory, which provide user-defined option aliases.

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

Another module Getopt::EX::Colormap is made to produce colored text on ANSI terminal, and to provide easy way to maintain labeled colormap table 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, user can define their own option with macro processing. This is useful when the command takes complicated arguments. User can also define default option which is used always. For example,

option default -n

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

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

Also, special command option preceded by -M is taken and corresponding perl module is loaded. For example,

% example -Mfoo

will load App::example::foo module.

This module is normal perl module, so user can write anything they want. If the module option come with 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 __DATA__ section, it is interpreted just same as rc file. So you can define arbitrary option there. Combined with startup function call described above, it is possible to control module behavior by user defined option.

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");

And process command line options:

$loader->deal_with(\@ARGV);

Finally gives built-in function declared in dynamically loaded modules to 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 to communicate with user-defined subroutines, use Getopt::EX::Func module, which provide parse_func interface. If your script has --begin option which tells the script to call 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 so tightly coupled with other modules in Getopt::EX. It provides concise way to specify ANSI terminal colors with various effects, and produce terminal sequences by color specification or label parameter.

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, user can change these colors from command line option like this:

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

or call arbitrary perl function like:

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

Above example produces uppercase version of provided string instead of ANSI color sequence.

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

Getopt::EX::LabeledParam

This is super-class of Getopt::EX::Colormap. Getopt::Long support parameter handling within 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

Parse number parameter description and produces number range list or number sequence. Number format is composed by 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

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

Getopt::EX::Hashed

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

Getopt::EX::i18n

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

Getopt::EX::termcolor

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

Getopt::EX::RPN

Getopt::EX::RPN provides a RPN (Reverse Polish Notation) calculation interface for command line arguments. This is convenient when you want to define parameter 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-2024 Kazumasa Utashiro

LICENSE

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