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


line stmt bran cond sub pod time code
1             package Getopt::EX;
2 1     1   789 use 5.014;
  1         3  
3 1     1   434 use version; our $VERSION = version->declare("2.1.3");
  1         2271  
  1         7  
4              
5             1;
6              
7             =head1 NAME
8              
9             Getopt::EX - Getopt Extender
10              
11              
12             =head1 VERSION
13              
14             Version 2.1.3
15              
16              
17             =head1 DESCRIPTION
18              
19             L extends basic function of L family to support
20             user-definable option aliases, and dynamic module which works together
21             with a script through option interface.
22              
23             =head1 INTERFACES
24              
25             There are two major interfaces to use L modules.
26              
27             Easy one is L compatible module, L.
28             You can simply replace module declaration and get the benefit of this
29             module to some extent. It allows user to make start up I file in
30             their home directory, which provide user-defined option aliases.
31              
32             Use L to get full capabilities. Then the user of
33             your script can make their own extension module which work together
34             with original command through command option interface.
35              
36             Another module L is made to produce colored text
37             on ANSI terminal, and to provide easy way to maintain labeled colormap
38             table and option handling.
39              
40             =head2 L
41              
42             This is the easiest way to get started with L. This
43             module is almost compatible with L and drop-in
44             replaceable.
45              
46             In addition, if the command name is I,
47              
48             ~/.examplerc
49              
50             file is loaded by default. In this rc file, user can define their own
51             option with macro processing. This is useful when the command takes
52             complicated arguments. User can also define default option which is
53             used always. For example,
54              
55             option default -n
56              
57             gives option I<-n> always when the script executed. See
58             L document what you can do in this file.
59              
60             If the rc file includes a section start with C<__PERL__>, it is
61             evaluated as a perl program. User can define any kind of functions
62             there, which can be invoked from command line option if the script is
63             aware of them. At this time, module object is assigned to variable
64             C<$MODULE>, and you can access module API through it.
65              
66             Also, special command option preceded by B<-M> is taken and
67             corresponding perl module is loaded. For example,
68              
69             % example -Mfoo
70              
71             will load C module.
72              
73             This module is normal perl module, so user can write anything they
74             want. If the module option come with initial function call, it is
75             called at the beginning of command execution. Suppose that the module
76             I is specified like this:
77              
78             % example -Mfoo::bar(buz=100) ...
79              
80             Then, after the module B is loaded, function I is called
81             with the parameter I with value 100.
82              
83             If the module includes C<__DATA__> section, it is interpreted just
84             same as rc file. So you can define arbitrary option there. Combined
85             with startup function call described above, it is possible to control
86             module behavior by user defined option.
87              
88             =head2 L
89              
90             This module provides more primitive access to the underlying modules.
91             You should create loader object first:
92              
93             use Getopt::EX::Loader;
94             my $loader = Getopt::EX::Loader->new(
95             BASECLASS => 'App::example',
96             );
97              
98             Then load rc file:
99              
100             $loader->load_file("$ENV{HOME}/.examplerc");
101              
102             And process command line options:
103              
104             $loader->deal_with(\@ARGV);
105              
106             Finally gives built-in function declared in dynamically loaded modules
107             to option parser.
108              
109             my $parser = Getopt::Long::Parser->new;
110             $parser->getoptions( ... , $loader->builtins )
111              
112             Actually, this is what L module is doing
113             internally.
114              
115             =head2 L
116              
117             To make your script to communicate with user-defined subroutines, use
118             L module, which provide C interface. If
119             your script has B<--begin> option which tells the script to call
120             specific function at the beginning of execution. Write something
121             like:
122              
123             use Getopt::EX::Func qw(parse_func);
124             GetOptions("begin:s" => \my $opt_begin);
125             my $func = parse_func($opt_begin);
126             $func->call;
127              
128             Then the script can be invoked like this:
129              
130             % example -Mfoo --begin 'repeat(debug,msg=hello,count=2)'
131              
132             See L for more detail.
133              
134             =head2 L
135              
136             This module is not so tightly coupled with other modules in
137             L. It provides concise way to specify ANSI terminal
138             colors with various effects, and produce terminal sequences by color
139             specification or label parameter.
140              
141             You can use this module with normal L:
142              
143             my @opt_colormap;
144             use Getopt::Long;
145             GetOptions("colormap|cm=s" => \@opt_colormap);
146            
147             my %colormap = ( # default color map
148             FILE => 'R',
149             LINE => 'G',
150             TEXT => 'B',
151             );
152             my @colors;
153            
154             require Getopt::EX::Colormap;
155             my $handler = Getopt::EX::Colormap->new(
156             HASH => \%colormap,
157             LIST => \@colors,
158             );
159            
160             $handler->load_params(@opt_colormap);
161              
162             and then get colored string as follows.
163              
164             print $handler->color("FILE", "FILE in Red\n");
165             print $handler->color("LINE", "LINE in Blue\n");
166             print $handler->color("TEXT", "TEXT in Green\n");
167              
168             In this example, user can change these colors from command line option
169             like this:
170              
171             % example --colormap FILE=C,LINE=M,TEXT=Y
172              
173             or call arbitrary perl function like:
174              
175             % example --colormap FILE='sub{uc}'
176              
177             Above example produces uppercase version of provided string instead of
178             ANSI color sequence.
179              
180             If you want to use just coloring function, use backend module
181             L.
182              
183             =head2 L
184              
185             This is super-class of L. L
186             support parameter handling within hash,
187              
188             my %defines;
189             GetOptions ("define=s" => \%defines);
190              
191             and the parameter can be given in C format.
192              
193             --define os=linux --define vendor=redhat
194              
195             Using L, this can be written as:
196              
197             my @defines;
198             my %defines;
199             GetOptions ("defines=s" => \@defines);
200             Getopt::EX::LabeledParam
201             ->new(HASH => \%defines)
202             ->load_params (@defines);
203              
204             and the parameter can be given mixed together.
205              
206             --define os=linux,vendor=redhat
207              
208             =head2 L
209              
210             Parse number parameter description and produces number range list or
211             number sequence. Number format is composed by four elements: C,
212             C, C and C, like this:
213              
214             1 1
215             1:3 1,2,3
216             1:20:5 1, 6, 11, 16
217             1:20:5:3 1,2,3, 6,7,8, 11,12,13, 16,17,18
218              
219             =head1 SEE ALSO
220              
221             =head2 L
222              
223             Coloring capability of L is now implemented in
224             this module.
225              
226             =head2 L
227              
228             B is a module to automate a hash object to store
229             command line option values for B and compatible modules
230             including B.
231              
232             =head2 L
233              
234             L provides an easy way to set locale environment
235             before executing command.
236              
237             =head2 L
238              
239             L is a common module to manipulate system
240             dependent terminal color.
241              
242             =head2 L
243              
244             L provides a RPN (Reverse Polish Notation)
245             calculation interface for command line arguments. This is convenient
246             when you want to define parameter based on terminal height or width.
247              
248             =head1 AUTHOR
249              
250             Kazumasa Utashiro
251              
252             =head1 COPYRIGHT
253              
254             The following copyright notice applies to all the files provided in
255             this distribution, including binary files, unless explicitly noted
256             otherwise.
257              
258             Copyright 2015-2023 Kazumasa Utashiro
259              
260             =head1 LICENSE
261              
262             This library is free software; you can redistribute it and/or modify
263             it under the same terms as Perl itself.
264              
265             =cut
266              
267             # LocalWords: Getopt colormap perl foo bar buz colorize BASECLASS
268             # LocalWords: rc examplerc ENV ARGV getoptions builtins func linux
269             # LocalWords: GetOptions redhat Kazumasa Utashiro RPN