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