README.md
1# NAME
2
3Getopt::EX - Getopt Extender
4
5# VERSION
6
7Version v1.15.1
8
9# DESCRIPTION
10
11[Getopt::EX](https://metacpan.org/pod/Getopt::EX) extends the basic function of [Getopt](https://metacpan.org/pod/Getopt) family to
12support user-definable option aliases, and dynamic module which works
13together with the script through option interface.
14
15# INTERFACES
16
17There are two major interfaces to use [Getopt::EX](https://metacpan.org/pod/Getopt::EX) modules.
18
19Easy one is [Getopt::Long](https://metacpan.org/pod/Getopt::Long) compatible module, [Getopt::EX::Long](https://metacpan.org/pod/Getopt::EX::Long).
20You can simply replace module declaration and get the benefit of this
21module to some extent. It allows user to make start up _rc_ file in
22their home directory, which provide user-defined option aliases.
23
24Use [Getopt::EX::Loader](https://metacpan.org/pod/Getopt::EX::Loader) to get full capabilities. Then the user of
25your script can make their own extension module which work together
26with original command through command option interface.
27
28Another module [Getopt::EX::Colormap](https://metacpan.org/pod/Getopt::EX::Colormap) is made to produce colored text
29on ANSI terminal, and to provide easy way to maintain labeled colormap
30table and option handling. It can be used just like
31[Term::ANSIColor](https://metacpan.org/pod/Term::ANSIColor) but you'd better use standard module in that case.
32
33## [Getopt::EX::Long](https://metacpan.org/pod/Getopt::EX::Long)
34
35This is the easiest way to get started with [Getopt::EX](https://metacpan.org/pod/Getopt::EX). This
36module is almost compatible with [Getopt::Long](https://metacpan.org/pod/Getopt::Long) and replaceable.
37
38In addition, if the command name is _example_,
39
40 ~/.examplerc
41
42file is loaded by default. In this rc file, user can define their own
43option with macro processing. This is useful when the command takes
44complicated arguments. User can also define default option which is
45used always. For example,
46
47 option default -n
48
49gives option _-n_ always when the script executed. See
50[Getopt::EX::Module](https://metacpan.org/pod/Getopt::EX::Module) document what you can do in this file.
51
52If the rc file includes a section start with `__PERL__`, it is
53evaluated as a perl program. User can define any kind of functions
54there, which can be invoked from command line option if the script is
55aware of them.
56
57Also, special command option preceded by **-M** is taken and
58corresponding perl module is loaded. For example,
59
60 % example -Mfoo
61
62will load `App::example::foo` module.
63
64This module is normal perl module, so user can write anything they
65want. If the module option come with initial function call, it is
66called at the beginning of command execution. Suppose that the module
67_foo_ is specified like this:
68
69 % example -Mfoo::bar(buz=100) ...
70
71Then, after the module **foo** is loaded, function _bar_ is called
72with the parameter _baz_ with value 100.
73
74If the module includes `__DATA__` section, it is interpreted just
75same as rc file. So you can define arbitrary option there. Combined
76with startup function call described above, it is possible to control
77module behavior by user defined option.
78
79## [Getopt::EX::Loader](https://metacpan.org/pod/Getopt::EX::Loader)
80
81This module provides more primitive access to the underlying modules.
82You should create loader object first:
83
84 use Getopt::EX::Loader;
85 my $loader = new Getopt::EX::Loader
86 BASECLASS => 'App::example';
87
88Then load rc file:
89
90 $loader->load_file("$ENV{HOME}/.examplerc");
91
92And process command line options:
93
94 $loader->deal_with(\@ARGV);
95
96Finally gives built-in function declared in dynamically loaded modules
97to option parser.
98
99 my $parser = new Getopt::Long::Parser;
100 $parser->getoptions( ... , $loader->builtins )
101
102Actually, this is what [Getopt::EX::Long](https://metacpan.org/pod/Getopt::EX::Long) module is doing
103internally.
104
105To communicate with user-defined subroutines, use [Getopt::EX::Func](https://metacpan.org/pod/Getopt::EX::Func)
106module, which provide `parse_func` interface. If your script has
107**--begin** option which tells the script to call specific function at
108the beginning of execution. Write something like:
109
110 use Getopt::EX::Func qw(parse_func);
111 GetOptions("begin:s" => $opt_begin);
112 my $func = parse_func($opt_begin);
113 $func->call;
114
115Then the script can be invoked like this:
116
117 % example -Mfoo --begin 'repeat(debug,msg=hello,count=2)'
118
119See [Getopt::EX::Func](https://metacpan.org/pod/Getopt::EX::Func) for more detail.
120
121## [Getopt::EX::Colormap](https://metacpan.org/pod/Getopt::EX::Colormap)
122
123This module is not so tightly coupled with other modules in
124[Getopt::EX](https://metacpan.org/pod/Getopt::EX). It provides concise way to specify ANSI terminal 256
125colors with various effects, and produce terminal sequences by color
126specification or label parameter.
127
128You can use this with normal [Getopt::Long](https://metacpan.org/pod/Getopt::Long):
129
130 my @opt_colormap;
131 use Getopt::Long;
132 GetOptions("colormap|cm=s" => \@opt_colormap);
133
134 my %colormap = ( # default color map
135 FILE => 'R',
136 LINE => 'G',
137 TEXT => 'B',
138 );
139 my @colors;
140
141 require Getopt::EX::Colormap;
142 my $handler = new Getopt::EX::Colormap
143 HASH => \%colormap,
144 LIST => \@colors;
145
146 $handler->load_params(@opt_colormap);
147
148and then get colored string as follows.
149
150 print $handler->color("FILE", "FILE in Red\n");
151 print $handler->color("LINE", "LINE in Blue\n");
152 print $handler->color("TEXT", "TEXT in Green\n");
153
154In this example, user can change these colors from command line option
155like this:
156
157 % example --colormap FILE=C,LINE=M,TEXT=Y
158
159or call arbitrary perl function like:
160
161 % example --colormap FILE='sub{uc}'
162
163Above example produces uppercase version of provided string instead of
164ANSI color sequence.
165
166If you only use coloring function, it's more simple:
167
168 require Getopt::EX::Colormap;
169 my $handler = new Getopt::EX::Colormap;
170
171 print $handler->color("R", "FILE in Red\n");
172 print $handler->color("G", "LINE in Blue\n");
173 print $handler->color("B", "TEXT in Green\n");
174
175or even simpler non-oo interface:
176
177 use Getopt::EX::Colormap qw(colorize);
178
179 print colorize("R", "FILE in Red\n");
180 print colorize("G", "LINE in Blue\n");
181 print colorize("B", "TEXT in Green\n");
182
183## [Getopt::EX::Numbers](https://metacpan.org/pod/Getopt::EX::Numbers)
184
185Parse number parameter description and produces number range list or
186number sequence. Number format is composed by four elements: `start`,
187`end`, `step` and `length`, like this:
188
189 1 1
190 1:3 1,2,3
191 1:20:5 1, 6, 11, 16
192 1:20:5:3 1,2,3, 6,7,8, 11,12,13, 16,17,18
193
194# AUTHOR
195
196Kazumasa Utashiro
197
198# COPYRIGHT
199
200The following copyright notice applies to all the files provided in
201this distribution, including binary files, unless explicitly noted
202otherwise.
203
204Copyright (C) 2015-2019 Kazumasa Utashiro
205
206# LICENSE
207
208This library is free software; you can redistribute it and/or modify
209it under the same terms as Perl itself.
210