EX.pm

filter: Statementstmt 100% 4 / 4 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 1 / 1 Podpod n/a totaltotal 100% 5 / 5 CC 1 SCAR 0.0
CC
1
Cov
100%
BEGIN
1.0
CRAP 1.0
« EX/Long.pm ↑ Summary
1 package Getopt::EX;
2 1 ▶use 5.014;
Subroutine BEGIN: called CC=1 SCAR=0.0
3  
4 1 our $VERSION = "3.05";
5  
6 1 1;
7  
8 =head1 NAME
9  
10 Getopt::EX - Getopt Extender
11  
12  
13 =head1 VERSION
14  
15 Version 3.05
16  
17  
18 =head1 DESCRIPTION
19  
20 L<Getopt::EX> extends the basic functionality of L<Getopt::Long> to
21 support user-definable option aliases and dynamic extension modules
22 that integrate with scripts through the option interface.
23  
24 =head1 INTERFACES
25  
26 There are two major interfaces for using L<Getopt::EX> modules.
27  
28 The simpler one is the L<Getopt::Long>-compatible module,
29 L<Getopt::EX::Long>. You can simply replace the module declaration to
30 get the benefits of this module. It allows users to create a startup
31 I<rc> file in their home directory to define option aliases.
32  
33 For full capabilities, use L<Getopt::EX::Loader>. This allows users
34 of your script to create their own extension modules that work
35 together with the original command through the option interface.
36  
37 Another module, L<Getopt::EX::Colormap>, is designed to produce
38 colored text on ANSI terminals and provides an easy way to maintain
39 labeled colormap tables with option handling.
40  
41 =head2 L<Getopt::EX::Long>
42  
43 This is the easiest way to get started with L<Getopt::EX>. This
44 module is almost fully compatible with L<Getopt::Long> and can be used
45 as a drop-in replacement.
46  
47 If the command name is I<example>, the file
48  
49 ~/.examplerc
50  
51 is loaded by default. In this rc file, users can define their own
52 option aliases with macro processing. This is useful when a command
53 takes complex arguments. Users can also define default options that
54 are always applied. For example:
55  
56 option default -n
57  
58 ensures that the I<-n> option is always used when the script runs.
59 See L<Getopt::EX::Module> for full details on rc file format.
60  
61 If the rc file includes a section starting with C<__PERL__> or
62 C<__PERL5__>, it is evaluated as Perl code. Users can define
63 functions there, which can be invoked from command line options if the
64 script supports them. The module object is available through the
65 C<$MODULE> variable.
66  
67 Special command options starting with B<-M> load the corresponding
68 Perl module. For example:
69  
70 % example -Mfoo
71  
72 loads the C<App::example::foo> module.
73  
74 Since extension modules are normal Perl modules, users can write any
75 code they need. If the module option includes an initial function
76 call, that function is called when the module is loaded. For example:
77  
78 % example -Mfoo::bar(buz=100)
79  
80 loads module B<foo> and calls function I<bar> with the parameter
81 I<buz> set to 100. The C<=> form is also supported:
82  
83 % example -Mfoo::bar=buz=100
84  
85 If the module includes a C<__DATA__> section, it is interpreted as an
86 rc file. Combined with the startup function call, this allows module
87 behavior to be controlled through user-defined options.
88  
89 =head2 L<Getopt::EX::Loader>
90  
91 This module provides lower-level access to the underlying
92 functionality. First create a loader object:
93  
94 use Getopt::EX::Loader;
95 my $loader = Getopt::EX::Loader->new(
96 BASECLASS => 'App::example',
97 );
98  
99 Then load the rc file:
100  
101 $loader->load_file("$ENV{HOME}/.examplerc");
102  
103 Process command line options:
104  
105 $loader->deal_with(\@ARGV);
106  
107 Finally, pass the built-in options declared in dynamically loaded
108 modules to the option parser:
109  
110 my $parser = Getopt::Long::Parser->new;
111 $parser->getoptions( ... , $loader->builtins );
112  
113 This is essentially what L<Getopt::EX::Long> does internally.
114  
115 =head2 L<Getopt::EX::Func>
116  
117 This module provides the C<parse_func> interface for communicating
118 with user-defined subroutines. If your script has a B<--begin> option
119 that specifies a function to call at the beginning of execution:
120  
121 use Getopt::EX::Func qw(parse_func);
122 GetOptions("begin:s" => \my $opt_begin);
123 my $func = parse_func($opt_begin);
124 $func->call;
125  
126 The user can then invoke the script like this:
127  
128 % example -Mfoo --begin 'repeat(debug,msg=hello,count=2)'
129  
130 To include commas in parameter values, use C<*=> to take the rest of
131 the string, or C</=> with a delimiter:
132  
133 func(pattern*=a,b,c)
134 func(pattern/=|a,b,c|)
135  
136 Both pass C<a,b,c> as the value of C<pattern>. The C</=> form allows
137 multiple parameters with commas:
138  
139 func(pat1/=|a,b|,pat2/=|c,d|)
140  
141 See L<Getopt::EX::Func> for more details.
142  
143 =head2 L<Getopt::EX::Colormap>
144  
145 This module is not tightly coupled with other L<Getopt::EX> modules.
146 It provides a concise way to specify ANSI terminal colors with various
147 effects, producing terminal escape sequences from color specifications
148 or label parameters.
149  
150 You can use this module with standard L<Getopt::Long>:
151  
152 my @opt_colormap;
153 use Getopt::Long;
154 GetOptions("colormap|cm=s" => \@opt_colormap);
155  
156 my %colormap = ( # default color map
157 FILE => 'R',
158 LINE => 'G',
159 TEXT => 'B',
160 );
161 my @colors;
162  
163 require Getopt::EX::Colormap;
164 my $handler = Getopt::EX::Colormap->new(
165 HASH => \%colormap,
166 LIST => \@colors,
167 );
168  
169 $handler->load_params(@opt_colormap);
170  
171 Then get colored strings:
172  
173 print $handler->color("FILE", "FILE in Red\n");
174 print $handler->color("LINE", "LINE in Green\n");
175 print $handler->color("TEXT", "TEXT in Blue\n");
176  
177 Users can change these colors from the command line:
178  
179 % example --colormap FILE=C,LINE=M,TEXT=Y
180  
181 or call an arbitrary Perl function:
182  
183 % example --colormap FILE='sub{uc}'
184  
185 The above produces an uppercase version of the string instead of a
186 color sequence.
187  
188 For just the coloring functionality, use the backend module
189 L<Term::ANSIColor::Concise>.
190  
191 =head2 L<Getopt::EX::LabeledParam>
192  
193 This is the superclass of L<Getopt::EX::Colormap>. L<Getopt::Long>
194 supports parameter handling with a hash:
195  
196 my %defines;
197 GetOptions("define=s" => \%defines);
198  
199 Parameters can be given in C<key=value> format:
200  
201 --define os=linux --define vendor=redhat
202  
203 Using L<Getopt::EX::LabeledParam>, this can be written as:
204  
205 my @defines;
206 my %defines;
207 GetOptions("define=s" => \@defines);
208 Getopt::EX::LabeledParam
209 ->new(HASH => \%defines)
210 ->load_params(@defines);
211  
212 allowing parameters to be combined:
213  
214 --define os=linux,vendor=redhat
215  
216 =head2 L<Getopt::EX::Numbers>
217  
218 Parses number parameter descriptions and produces number range lists
219 or sequences. The format consists of four elements: C<start>,
220 C<end>, C<step>, and C<length>:
221  
222 1 1
223 1:3 1,2,3
224 1:20:5 1, 6, 11, 16
225 1:20:5:3 1,2,3, 6,7,8, 11,12,13, 16,17,18
226  
227 =head1 SEE ALSO
228  
229 =over 4
230  
231 =item L<Term::ANSIColor::Concise>
232  
233 The coloring capability of L<Getopt::EX::Colormap> is implemented in
234 this module.
235  
236 =item L<Getopt::EX::Hashed>
237  
238 Automates a hash object to store command line option values for
239 L<Getopt::Long> and compatible modules including L<Getopt::EX::Long>.
240  
241 =item L<Getopt::EX::Config>
242  
243 Provides an interface to define configuration information for
244 L<Getopt::EX> modules, including module-specific options.
245  
246 =item L<Getopt::EX::i18n>
247  
248 Provides an easy way to set the locale environment before executing a
249 command.
250  
251 =item L<Getopt::EX::termcolor>
252  
253 A common module to handle system-dependent terminal colors.
254  
255 =item L<Getopt::EX::RPN>
256  
257 Provides an RPN (Reverse Polish Notation) calculation interface for
258 command line arguments, useful for defining parameters based on
259 terminal dimensions.
260  
261 =back
262  
263 =head1 AUTHOR
264  
265 Kazumasa Utashiro
266  
267 =head1 COPYRIGHT
268  
269 The following copyright notice applies to all the files provided in
270 this distribution, including binary files, unless explicitly noted
271 otherwise.
272  
273 Copyright 2015-2025 Kazumasa Utashiro
274  
275 =head1 LICENSE
276  
277 This library is free software; you can redistribute it and/or modify
278 it under the same terms as Perl itself.
279  
280 =cut
281  
282 # LocalWords: Getopt colormap perl foo bar buz colorize BASECLASS
283 # LocalWords: rc examplerc ENV ARGV getoptions builtins func linux
284 # LocalWords: GetOptions redhat Kazumasa Utashiro RPN
« EX/Long.pm ↑ Summary