1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213
|
Release
=======
Getopt::ArgvFile 1.06.
Overview
========
This module is a simple supplement to other option handling modules.
It allows script options and parameters to be read from files
instead of from the command line by interpolating file contents
into @ARGV. This way it PREPARES the final option handling.
Getopt::ArgvFile does NOT perform any option processing itself, and
should work fine together with any other option handling module
(e.g. Getopt::Long) or even self coded option handling.
Well, the usual process can be illustrated by the following:
---------------
command -> @ARGV -> | Getopt::xxx |
line ---------------
Getopt::ArgvFile adds an additional interpolation of @ARGV, replacing
strings pointing to files with options by the contents of these files:
------------- ---------------
command -> @ARGV with -> | Getopt:: | -> @ARGV with -> | Getopt::xxx |
line file hints | ArgvFile | options only ---------------
-------------
| ^
v |
|
option files --------
For example, let's say your script accepts two mandatory options ("-first"
and "-second") each taking parameters, which have to be followed by three
script parameters, the usual call would be anything like
yourScript -first 1stPar -second 2ndPar par1 par2 par3
If a user finds out that the options and their parameters are almost
always the same for him, and if you use Getopt::ArgvFile in your script,
he could store the stable part of this call in a file like
# always pass 1stPar to -first
-first 1stPar
# as well as 2ndPar to -second
-second 2ndPar
If this file is named "opts", subsequent calls may be shortened to
yourScript @opts par1 par2 par3
What your script will see in @ARGV after a call of
Getopt::ArgvFile::argvFile() will be exactly the same as in the initial
call showed above, so that the script can process the command line as
usual then. But from the USERS point of view, the call was simpler indeed.
More, if even the script parameters do not change from call to call,
they may be stored in a second file "pars", and the call would become
yourScript @opts @pars
The use of Getopt::ArgvFile can simplify periodical script calls as well
as increase the handability of multi option scripts. (As an example,
imagine a cronjob set up with option files which could be completely
maintained outside the crontab.)
The module can process an alternative array instead of @ARGV if one prefers.
Further more, Getopt::ArgvFile supports both option file nesting and
cascading as well as automatically read "default option files". Please
see the documentation for details. It also contains several usage examples.
Synopsis
========
To offer support of option files, simply add something like the following
to your script:
# load module
use Getopt::ArgvFile qw(argvFile);
# solve option files, if any
argvFile();
Now the command line can be processed as usual, e.g. by
Getopt::Long::GetOptions(...);
If options should be processed into another array, this can be done this way:
# prepare target array
my @options=('@options1', '@options2', '@options3');
# replace file hints by file contents
argvFile(array=>\@options);
Requirements
============
Getopt::ArgvFile is tested with Perl versions 5.005 and 5.6.x.
(Versions prior 1.04 were tested with 5.00[34], too.)
It should run under later versions as well.
Text::ParseWords 3.1 is required.
Installation
============
This module can be installed as usual by
perl Makefile.PL
make
make test
make install
What's new?
===========
1.06 argvFile() takes a new option "startupFilename"
to let users specify what scheme should be used
to find startup files (thanks to Helmut Steinbach
for the initial idea). Names may be specified
directly or by a reference to a function which
will then be invoked with the scriptname to
provide the filename dynamically.
1.05 Using File::Spec::Functions to build filenames
more portable.
Using Cwd::abs_path() now to check if several
startup file locations are identical.
Added support for startup files in the *current*
directory (thanks to Helmut Steinbach for this
suggestion).
Switched to Test::More (for installation checks).
1.04 fixed a bug: if the script directory was identical
to the users home and both default and home setting
were used, the default options were read twice
(thanks to Manfred Kuegler for the report).
1.03 introduced new parameter "prefix".
POD comments in option files are supported now
(according to an idea of Joe Pepin).
1.02 introduced new parameter "array".
1.01 came with an updated README to reflect that the
required module Text::ParseWords 3.1 is available
on CPAN now.
Problems?
=========
If you run into trouble with this module, feel free
to contact me at perl@jochen-stenzel.de.
Author, Copyright, License
==========================
Copyright (c) 1993-2002 Jochen Stenzel. All rights reserved.
This module is free software, you can redistribute it and/or modify it
under the terms of the Artistic License distributed with Perl version
5.003 or (at your option) any later version. Please refer to the
Artistic License that came with your Perl distribution for more
details.
The Artistic License should have been included in your distribution of
Perl. It resides in the file named "Artistic" at the top-level of the
Perl source tree (where Perl was downloaded/unpacked - ask your
system administrator if you dont know where this is). Alternatively,
the current version of the Artistic License distributed with Perl can
be viewed on-line on the World-Wide Web (WWW) from the following URL:
http://www.perl.com/perl/misc/Artistic.html
Disclaimer
==========
This software is distributed in the hope that it will be useful, but
is provided "AS IS" WITHOUT WARRANTY OF ANY KIND, either expressed or
implied, INCLUDING, without limitation, the implied warranties of
MERCHANTABILITY and FITNESS FOR A PARTICULAR PURPOSE.
The ENTIRE RISK as to the quality and performance of the software
IS WITH YOU (the holder of the software). Should the software prove
defective, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR
CORRECTION.
IN NO EVENT WILL ANY COPYRIGHT HOLDER OR ANY OTHER PARTY WHO MAY CREATE,
MODIFY, OR DISTRIBUTE THE SOFTWARE BE LIABLE OR RESPONSIBLE TO YOU OR TO
ANY OTHER ENTITY FOR ANY KIND OF DAMAGES (no matter how awful - not even
if they arise from known or unknown flaws in the software).
Please refer to the Artistic License that came with your Perl
distribution for more details.
|