Debian Codegraph @

README

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