File Coverage

blib/lib/Getopt/EX.pm

Criterion	Covered	Total	%
statement	5	5	100.0
branch			n/a
condition			n/a
subroutine	2	2	100.0
pod			n/a
total	7	7	100.0

package Getopt::EX;
use 5.014;
use version; our $VERSION = version->declare("2.1.3");

1;

=head1 NAME

Getopt::EX - Getopt Extender


=head1 VERSION

Version 2.1.3


=head1 DESCRIPTION

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

=head1 INTERFACES

There are two major interfaces to use L modules.

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

Use L 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 L is made to produce colored text
on ANSI terminal, and to provide easy way to maintain labeled colormap
table and option handling.

=head2 L

This is the easiest way to get started with L.  This
module is almost compatible with L and drop-in
replaceable.

In addition, if the command name is I,

    ~/.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 I<-n> always when the script executed.  See
L document what you can do in this file.

If the rc file includes a section start with C<__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
C<$MODULE>, and you can access module API through it.

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

    % example -Mfoo

will load C 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
I is specified like this:

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

Then, after the module B is loaded, function I is called
with the parameter I with value 100.

If the module includes C<__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.

=head2 L

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 L module is doing
internally.

=head2 L

To make your script to communicate with user-defined subroutines, use
L module, which provide C interface.  If
your script has B<--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 L for more detail.

=head2 L

This module is not so tightly coupled with other modules in
L.  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 L:

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

=head2 L

This is super-class of L.  L
support parameter handling within hash,

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

and the parameter can be given in C format.

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

Using L, 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

=head2 L

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

=head1 SEE ALSO

=head2 L

Coloring capability of L is now implemented in
this module.

=head2 L

B is a module to automate a hash object to store
command line option values for B and compatible modules
including B.

=head2 L

L provides an easy way to set locale environment
before executing command.

=head2 L

L is a common module to manipulate system
dependent terminal color.

=head2 L

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

=head1 AUTHOR

Kazumasa Utashiro

=head1 COPYRIGHT

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

Copyright 2015-2023 Kazumasa Utashiro

=head1 LICENSE

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

=cut

#  LocalWords:  Getopt colormap perl foo bar buz colorize BASECLASS
#  LocalWords:  rc examplerc ENV ARGV getoptions builtins func linux
#  LocalWords:  GetOptions redhat Kazumasa Utashiro RPN