Debian Codegraph @

README

raw
1 ######################################################################
2 ## File: $Id: README 3442 2005-05-14 14:14:01Z spadkins $
3 ######################################################################
4
5 1. What is the App-Options distribution?
6
7 You might say App-Options distribution is "yet another command line
8 option processor." However, it was created for maximum ease of use
9 with the needs of the Perl 5 Enterprise Environment in mind
10 (more on that later).
11
12 The distribution consists of one Perl module and one shell script.
13
14 App::Options - a perl module which combines command line parameters,
15 environment variables, and configuration files to produce
16 a hash of option values.
17
18 prefix - a shell script which works for ksh (Korn shell) or
19 bash (Bourne Again Shell) which allows you to change
20 a family of environment variables (PATH, LD_LIBRARY_PATH,
21 MANPATH, etc.) necessary for running programs out of a
22 directory in which software has been installed.
23 (This script is useful but not necessary, and non-Unix users
24 may safely ignore it.)
25
26 2. What are the features?
27
28 FEATURES OF App::Options
29
30 o Flexible command line syntax
31 Parse long (--whatever) and short (-w) command line options
32 (with [--verbose=3] or without [--verbose] arguments)
33 and just put the values in %App::options (or some other hash
34 that you may specify).
35 o Automatic boolean command line switches
36 An option like "--help" is equivalent to "--help=1".
37 o Combines options with Environment Variables
38 The --whatever=value option can be supplied with the
39 APP_WHATEVER environment variable.
40 o Combines options with variables in global and local config files
41 The --whatever=value option can be supplied in config files with
42 the "whatever = value" statement. Initialization searches
43 "$HOME/.app/$prog.conf", "$HOME/.app/app.conf",
44 "$progdir/$prog.conf", "$progdir/app.conf",
45 "$prefix/etc/app/$prog.conf", "$prefix/etc/app/app.conf", and
46 "/etc/app.conf" in order to find the option values.
47 o Import other files with "import = filename" statement
48 Config files can, in essence, include other config files.
49 o Stop importing other files with "flush_imports = 1" statement
50 A config file can use this statement to tell the program
51 to stop searching for other config files it was planning
52 on searching.
53 o Option values undergo variable expansion
54 This means that some values may rely on other values.
55 i.e. "prefix = /usr/mycompany/3.2.1" and "logdir = ${prefix}/log"
56 o Config files can have conditional sections
57 A section specifier "[cleanup]" begins a section only valid
58 for the program "cleanup" (or "cleanup.exe" or cleanup.pl, etc.).
59 A section specifier "[ALL]" (or just "[]") begins another
60 unconditional section. In fact, "[cleanup]" is just a synonym
61 for "[app=cleanup]". Sections can be made conditional on the
62 current values of any variables. i.e. "[country=US;city=LAX]"
63 would begin a section of variables only valid if the two
64 specified variables have the required values.
65 o Config files can have conditional lines
66 Any section specifier can apply only to a single line by
67 putting a statement after it. "[city=LAX] state = CA"
68 o Modify @INC variable with the "perlinc = path1,path2" statement
69 This allows the person deploying the software to set up the Perl
70 include path so that a particular version of the software
71 installed on the system is used. Subsequent uses of "use" and
72 "require" will load modules from the configured locations.
73 o Validate that "required" options are provided
74 Certain options can be identified as required. Otherwise the
75 program will not run.
76 o Validate option values against types
77 Certain options can be identified as to their type or pattern
78 (integer, int, float, number, date, datetime, string, regexp).
79 If the option value is provided and it does not match the
80 type or pattern, the program will not run.
81 o Provide automatic "-?" and "--help" messages
82 Adds user-friendliness to programs with no extra effort.
83
84 3. What were the design goals that make this distribution unique?
85
86 #1 Support multiple installations of a complex suite of software.
87 This is useful for development and deployment of large systems,
88 where multiple versions may be in varying states of development,
89 testing, or production.
90
91 #2 Support a suite of programs all using a common set of configuration
92 files. Large systems have many programs. We don't want to
93 repeat the database name, username, and password in a separate
94 config file for each program.
95
96 #3 Make it so easy to use that a developer would be silly not to
97 use it in even his smallest and simplest of scripts. However,
98 it should be powerful enough to support advanced features as
99 the developer needs them.
100
101 #4 Support conditions where the environment variables are not
102 easy to control. i.e. CGI programs or cron jobs.
103
104 These were important design goals to support the App-Context variant
105 of the Perl 5 Enterprise Environment (P5EE). See the P5EE website
106 (http://www.officevision.com/pub/p5ee) for more details.
107
108 4. Why another module? Why not use Getopt::Long or others?
109
110 There are many configuration modules on CPAN. See
111
112 http://search.cpan.org/modlist/Option_Parameter_Config_Processing
113
114 The most important feature was to be able to run it within a
115 BEGIN block to modify the Perl include path (@INC). This is
116 most of design goal #1. This means very few dependencies and
117 only on core modules.
118
119 I started by writing a few lines of code in a BEGIN block.
120 Then it got to be a lot of lines of code in a BEGIN block.
121 Then I moved it out to a module so I could reuse it easily.
122 Then it grew into a full-fledged command line, environment
123 variable, and config file value option processor.
124
125 I did try Getopt::Long, but it wasn't that easy to use, you had
126 to code your own "--help" feature, and it didn't incorporate
127 environment variables or config files. I wanted something
128 more high-level and full-featured, so I wrote App::Options.
129
130 The description of the AppConfig distribution sounds similar
131 to what is described here. However, the following are the key
132 differences.
133
134 * App::Options does its option processing in the BEGIN block.
135 This allows for the @INC variable to be modified in time
136 for subsequent "use" and "require" statements.
137 This met design goal #1.
138
139 * App::Options consults a cascading set of option files.
140 These files include those which are system global, project
141 global, and user private. This allows for system
142 administrators, project developers, and in individual
143 users to all have complementary roles on defining
144 the configuration values. This met design goal #2.
145
146 * App::Options "sections" (i.e. "[cleanup]") are conditional.
147 It is conditional in App::Options, allowing you to use one
148 set of option files to configure an entire suite of programs
149 and scripts. In AppConfig, the section name is simply a
150 prefix which gets prepended to subsequest option names.
151 This also helped to meet design goal #2.
152
153 * App::Options is not a toolkit but a standardized way of
154 doing option processing. With AppConfig, you still have
155 to decide where to put config files, you still have to
156 code the "--help" feature, etc. With App::Options, you simply
157 "use App::Options;" and all the hard work is done.
158 Advanced options can be added later as necessary as args
159 to the "use" statement. This met design goal #3.
160
161 Design goal #4 required the autodetection of the ${prefix}
162 variable. Thus, the App::Options module can be integrated with
163 the discipline of choosing a root directory for your
164 software installation (i.e. PREFIX=/usr/mycompany/2.0.12).
165
166 5. You say it's so easy. Show me.
167
168 #!/usr/bin/perl
169 use App::Options;
170 # now use the %App::options hash
171 print "yada yada\n" if ($App::options{verbose});
172
173 It's that easy.
174
175 And it automatically has "-?" and "--help" support without
176 you having to code a thing.
177
178 Read the man page (or the code) if you want more power.
179
180 6. How do I install it?
181
182 To install this module, cd to the directory that contains this README
183 file and type the following (as usual).
184
185 perl Makefile.PL
186 make
187 make test
188 make install
189