1ArgvFile(3) User Contributed Perl Documentation ArgvFile(3)
2
6 Getopt::ArgvFile - interpolates script options from files into @ARGV or
7 another array
8
10 This manual describes version 1.11.
11
13 One line invocation - option hints are processed while the module is
14 loaded:
15 # load module and process option file hints in @ARGV
17 use Getopt::ArgvFile default=>1;
18 # load another module to evaluate the options, e.g.:
20 use Getopt::Long;
21 ...
22 # evaluate options, e.g. this common way:
24 GetOptions(\%options, 'any'); # this function is defined in Getopt::Long
25 Or suppress option hint processing when the module is loaded, to
27 perform it later on:
28 # load module, do *not* process option file hints
30 use Getopt::ArgvFile justload=>1;
31 # load another module to evaluate the options, e.g.:
33 use Getopt::Long;
34 ...
35 # *now*, solve option file hints
37 Getopt::ArgvFile::argvFile(default=>1);
38 # evaluate options, e.g. this common way:
40 GetOptions(\%options, 'any'); # this function is defined in Getopt::Long
41 Or use the traditional two step invocation of module loading with
43 symbol import and explicit option file handling:
44 # Load the module and import the &argvFile symbol
46 # - this will *not* process option hints.
47 # Use *this* syntax to do so, *exactly*.
48 use Getopt::ArgvFile qw(argvFile);
49 # load another module to evaluate the options, e.g.:
51 use Getopt::Long;
52 ...
53 # *now*, solve option file hints
55 argvFile(default=>1);
56 # evaluate options, e.g. this common way:
58 GetOptions(\%options, 'any'); # this function is defined in Getopt::Long
59 If options should be processed into another array, this can be done
61 this way:
62 # prepare target array
64 my @options=('@options1', '@options2', '@options3');
65 ...
67 # replace file hints by the options stored in the files
69 argvFile(array=>\@options);
70 In case you do not like the "@" prefix it is possible to define an
72 option to be used instead:
73 # prepare target array
75 my @options=('-options', 'options1', '-options', 'options2');
76 ...
78 # replace file hints by the options stored in the files
80 argvFile(fileOption=>'options', array=>\@options);
81
83 This module simply interpolates option file hints in @ARGV by the
84 contents of the pointed files. This enables option reading from files
85 instead of or additional to the usual reading from the command line.
86 Alternatively, you can process any array instead of @ARGV which is used
88 by default and mentioned mostly in this manual.
89 The interpolated @ARGV could be subsequently processed by the usual
91 option handling, e.g. by a Getopt::xxx module. Getopt::ArgvFile does
92 not perform any option handling itself, it only prepares the array
93 @ARGV.
94 Option files can significantly simplify the call of a script. Imagine
96 the following:
97 Breaking command line limits
99 A script may offer a lot of options, with possibly a few of them
100 even taking parameters. If these options and their parameters are
101 passed onto the program call directly, the number of characters
102 accepted by your shells command line may be exceeded.
103 Perl itself does not limit the number of characters passed to a
105 script by parameters, but the shell or command interpreter often
106 sets a limit here. The same problem may occur if you want to store
107 a long call in a system file like crontab.
108 If such a limit restricts you, options and parameters may be moved
110 into option files, which will result in a shorter command line
111 call.
112 Script calls prepared by scripts
114 Sometimes a script calls another script. The options passed onto
115 the nested script could depend on variable situations, such as a
116 users input or the detected environment. In such a case, it can be
117 easier to generate an intermediate option file which is then passed
118 to the nested script.
119 Or imagine two cron jobs one preparing the other: the first may
121 generate an option file which is then used by the second.
122 Simple access to typical calling scenarios
124 If several options need to be set, but in certain circumstances are
125 always the same, it could become sligthly nerveracking to type them
126 in again and again. With an option file, they can be stored once
127 and recalled easily as often as necessary.
128 Further more, option files may be used to group options. Several
130 settings may set up one certain behaviour of the program, while
131 others influence another. Or a certain set of options may be useful
132 in one typical situation, while another one should be used
133 elsewhere. Or there is a common set of options which has to be used
134 in every call, while other options are added depending on the
135 current needs. Or there are a few user groups with different but
136 typical ways to call your script. In all these cases, option files
137 may collect options belonging together, and may be combined by the
138 script users to set up a certain call. In conjunction with the
139 possiblity to nest such collections, this is perhaps the most
140 powerful feature provided by this method.
141 Individual and installationwide default options
143 The module allows the programmer to enable user setups of default
144 options; for both individual users or generally all callers of a
145 script. This is especially useful for administrators who can
146 configure the default behaviour of a script by setting up its
147 installationwide startup option file. All script users are free
148 then to completely forget every already configured setup option.
149 And if one of them regularly adds certain options to every call, he
150 could store them in his individual startup option file.
151 For example, I use this feature to make my scripts both flexible
153 and usable. I have several scripts accessing a database via DBI.
154 The database account parameters as well as the DBI startup settings
155 should not be coded inside the scripts because this is not very
156 flexible, so I implemented them by options. But on the other hand,
157 there should be no need for a normal user to pass all these
158 settings to every script call. My solution for this is to use
159 default option files set up and maintained by an administrator.
160 This is very transparent, most of the users know nothing of these
161 (documented ;-) configuration settings ... and if anything changes,
162 only the option files have to be adapted.
163
165 No symbol is exported by default, but you may explicitly import the
166 "argvFile()" function using the exact syntax of the following example:
167 use Getopt::ArgvFile qw(argvFile);
169 Please note that this interface is provided for backwards compatibility
171 with versions up to 1.06. By loading the module this way, the
172 traditional import mechanisms take affect and "argvFile()" is not
173 called implicitly.
174 This means that while option file hints are usually processed
176 implicitly when "Getopt::ArgvFile" is loaded, the syntax
177 use Getopt::ArgvFile qw(argvFile);
179 requires an extra call of argvFile() to process option files.
181
183 There is only one function, argvFile(), which does all the work of
184 option file hint processing.
185 Please note that with version 1.07 and above "argvFile()" is called
187 implicitly when the module is loaded, except this is done in one of the
188 following ways:
189 # the traditional interface - provided for
191 # backwards compatibility - this loads the
192 # module and imports the &argvFile symbol
193 use Getopt::ArgvFile qw(argvFile);
194 --
196 # option file processing is explicitly suppressed
198 use Getopt::ArgvFile justload=>1;
199 Except for the traditional loading, the complete interface of
201 "argvFile()" is available via "use", but in the typical "use" syntax
202 without parantheses.
203 # implicit call of argvFile(default=>1, home=>1)
205 use Getopt::ArgvFile default=>1, home=>1;
206 See ONE LINE INVOCATION for further details.
208 argvFile()
210 Scans the command line parameters (stored in @ARGV or an alternatively
211 passed array) for option file hints (see Basics below), reads the
212 pointed files and makes their contents part of the source array (@ARGV
213 by default) replacing the hints.
214 Because the function was intentionally designed to work on @ARGV and
216 this is still the default behaviour, this manual mostly speaks about
217 @ARGV. Please note that it is possible to process any other array as
218 well.
219 Basics
221 An option file hint is simply the filename preceeded by (at least) one
223 "@" character:
224 > script -optA argA -optB @optionFile -optC argC
226 This will cause argvFile() to scan "optionFile" for options. The
228 element "@optionFile" will be removed from the @ARGV array and will be
229 replaced by the options found.
230 Note: you can choose another prefix by using the "prefix" parameter,
232 see below.
233 An option file which cannot be found is quietly skipped.
235 Well, what is within an option file? It is intended to store command
237 line arguments which should be passed to the called script. They can be
238 stored exactly as they would be written in the command line, but may be
239 spread to multiple lines. To make the file more readable, space and
240 comment lines (starting with a "#") are allowed additionally. POD
241 comments are supported as well. For example, the call
242 > script -optA argA -optB -optC cArg par1 par2
244 could be transformed into
246 > script @scriptOptions par1 par2
248 where the file "scriptOptions" may look like this:
250 # option a
252 -optA argA
253 ""
255 =pod
257 option b
258 =cut
259 -optB
260 ""
262 # option c
264 -optC cArg
265 Nested option files
267 Option files can be nested. Recursion is avoided globally, that means
269 that every file will be opened only once (the first time argvFile()
270 finds a hint pointing to it). This is the simplest implementation,
271 indeed, but should be suitable. (Unfortunately, there are LIMITS.)
272 By using this feature, you may combine groups of typical options into a
274 top level option file, e.g.:
275 File ab:
277 ""
279 # option a
281 -optA argA
282 # option b
283 -optB
284 ""
286 File c:
288 ""
290 # option c
292 -optC cArg
293 ""
295 File abc:
297 ""
299 # combine ab and c
301 @ab @c
302 If anyone provides these files, a user can use a very short call:
304 > script @abc
306 and argvFile() will recursively move all the filed program parameters
308 into @ARGV.
309 Relative pathes
311 Pathes in option files might be relative, as in
313 -file ../file @../../configs/nested
315 If written with the (prepared) start directory in mind, that will work,
317 but it can fail when it was written relatively to the option file
318 location because by default those pathes will not be resolved when
319 written from an option file.
320 Use parameter "resolveRelativePathes" to switch to path resolution:
322 argvFile(resolveRelativePathes=>1);
324 will cause "argvFile()" to expand those pathes, both in standard
326 strings and nested option files.
327 With resolveRelativePathes, both pathes
329 will be resolved:
330 -file ../file @../../configs/nested
332 A path is resolved relative to the option file it is found in.
334 Environment variables
336 Similar to relative pathes, environment variables are handled
338 differently depending if the option is specified at the commandline or
339 from an option file, due to bypassed shell processing. By default,
340 "argvFile()" does not resolve environment variables. But if required it
341 can be commanded to do so via parameter "resolveEnvVars".
342 argvFile(resolveEnvVars=>1);
344 Startup support
346 By setting several named parameters, you can enable automatic
348 processing of startup option files. There are three of them:
349 The default option file is searched in the installation path of the
351 calling script, the home option file is searched in the users home
352 (evaluated via environment variable "HOME"), and the current option
353 script is searched in the current directory.
354 By default, all startup option files are expected to be named like the
356 script, preceeded by a dot, but this can be adapted to individual needs
357 if preferred, see below.
358 Examples:
360 If a script located in "/path/script" is invoked in directory
361 /the/current/dir by a user "user" whoms "HOME" variable points
362 to "/homes/user", the following happens:
363 ""
365 argvFile() # ignores all startup option files;
367 argvFile(default=>1) # searches and expands "/path/.script",
368 # if available (the "default" settings);
369 argvFile(home=>1) # searches and expands "/homes/user/.script",
370 # if available (the "home" settings);
371 argvFile(current=>1) # searches and expands "/the/current/dir/.script",
372 # if available (the "current" settings);
373 argvFile(
374 default => 1,
375 home => 1,
376 current => 1
377 ) # tries to handle all startups.
378 Any true value will activate the setting it is assigned to.
380 In case the ".script" name rule does not meet your needs or does not
382 fit into a certain policy, the expected startup filenames can be set up
383 by an option "startupFilename". The option value may be a scalar used
384 as the expected filename, or a reference to an array of accepted
385 choices, or a reference to code returning the name - plainly or as a
386 reference to an array of names. Such callback code will be called once
387 and will receive the name of the script.
388 # use ".config"
390 argvFile(startupFilename => '.config');
391 # use ".config" or "config"
393 argvFile(startupFilename => [qw(.config config)]);
394 # emulate the default behaviour,
396 # but use an extra dot postfix
397 my $nameBuilder=sub {join('', '.', basename($_[0]), '.');};
398 argvFile(startupFilename => $nameBuilder);
399 # use .(script)rc or .(script)/config
401 my $nameBuilder=sub
402 {
403 my $sname=basename($_[0]);
404 [".${sname}rc", ".${sname}/config"];
405 };
406 argvFile(startupFilename => $nameBuilder);
407 Note that the list variants will use the first matching filename in
409 each possible startup-file path. For example if your array is
410 "['.scriptrc', '.script.config']" and you have both a ".scriptrc" and a
411 ".script.config" file in (say) your current directory, only the
412 ".scriptrc" file will be used, as it is the first found.
413 The contents found in a startup file is placed before all explicitly
415 set command line arguments. This enables to overwrite a default setting
416 by an explicit option. If all startup files are read, current startup
417 files can overwrite home files which have preceedence over default
418 ones, so that the default startups are most common. In other words, if
419 the module would not support startup files, you could get the same
420 result with "script @/path/.script @/homes/user/.script
421 @/the/current/dir/.script".
422 Note: There is one certain case when overwriting will not work
424 completely because duplicates are sorted out: if all three types of
425 startup files are used and the script is started in the installation
426 directory, the default file will be identical to the current file. The
427 default file is processed, but the current file is skipped as a
428 duplicate later on and will not overwrite settings made caused by the
429 intermediately processed home file. If started in another directory,
430 it will overwrite the home settings. But the alternative seems to be
431 even more confusing: the script would behave differently if just
432 started in its installation path. Because a user might be more aware of
433 configuration editing then of the current path, I choose the current
434 implementation, but this preceedence might become configurable in a
435 future version.
436 If there is no HOME environment variable, the home setting takes no
438 effect to avoid trouble accessing the root directory.
439 Cascades
441 The function supports multi-level (or so called cascaded) option files.
443 If a filename in an option file hint starts with a "@" again, this
444 complete name is the resolution written back to @ARGV - assuming there
445 will be another utility reading option files.
446 Examples:
448 @rfile rfile will be opened, its contents is
449 made part of @ARGV.
450 @@rfile cascade: "@rfile" is written back to
451 @ARGV assuming that there is a subsequent
452 tool called by the script to which this
453 hint will be passed to solve it by an own
454 call of argvFile().
455 The number of cascaded hints is unlimited.
457 Processing an alternative array
459 Although the function was designed to process @ARGV, it is possible to
461 process another array as well if you prefer. To do this, simply pass a
462 reference to this array by parameter array.
463 Examples:
465 argvFile() # processes @ARGV;
466 argvFile(array=>\@options); # processes @options;
467 Choosing an alternative hint prefix
469 By default, "@" is the prefix used to mark an option file. This can be
471 changed by using the optional parameter prefix:
472 Examples:
474 argvFile(); # use "@";
475 argvFile(prefix=>'~'); # use "~";
476 Note that the strings "#", "=", "-" and "+" are reserved and cannot be
478 chosen here because they are used to start plain or POD comments or are
479 typically option prefixes.
480 Using an option instead of a hint prefix
482 People not familiar with option files might be confused by file
484 prefixes. This can be avoided by offering an option that can be used
485 instead of a prefix, using the optional parameter fileOption:
486 # install a file option
488 # (all lines are equivalent)
489 argvFile(fileOption=>'options');
490 argvFile(fileOption=>'-options');
491 argvFile(fileOption=>'+options');
492 argvFile(fileOption=>'--options');
493 The name of the option can be specified with or without the usual
495 option prefixes "-", "--" and "+".
496 Once an option is declared, it can replace a prefix. (Prefixes remain
498 in action as well.)
499 # with -options declared to be a file option,
501 # these sequences are equivalent
502 @file
503 -options file
504 # five equivalent cascades
506 @@@@file
507 -options @@@file
508 -options -options @@file
509 -options -options -options @file
510 -options -options -options -options file
511 Please note that prefixes are attached to the filename with no spaces
513 in between, while the option declared via -fileOption is separated from
514 the filename by whitespace, as for normal options.
515
517 The traditional two line sequence
518 # load the module
520 use Getopt::ArgvFile qw(argvFile);
521 ...
523 # solve option files
525 argvFile(default=>1);
526 can be reduced to one line - just pass the parameters of "argvFile()"
528 to "use()":
529 # load module and process option file hints in @ARGV
531 use Getopt::ArgvFile default=>1;
532 Please note that in this case option file hints are processed at
534 compile time. This means that if you want to process alternative
535 arrays, these arrays have to be prepared before, usually in a "BEGIN"
536 block.
537 In versions 1.07 and above, implicit option file handling is the
539 default and only suppressed for the traditional
540 use Getopt::ArgvFile qw(argvFile);
542 loading, for reasons of backwards compatibility. A simple loading like
544 use Getopt::ArgvFile;
546 will process option hints! If you want to suppress this, use the
548 "justload" switch:
549 use Getopt::ArgvFile justload=>1;
551 See FUNCTIONS for additional informations.
553
555 If a script calling "argvFile()" with the "default" switch is invoked
556 using a relative path, it is strongly recommended to perform the call
557 of "argvFile()" in the startup directory because "argvFile()" then uses
558 the relative script path as well.
559
561 If an option file does not exist, argvFile() simply ignores it. No
562 message will be displayed, no special return code will be set.
563
565 Jochen Stenzel <mailto:perl@jochen-stenzel.de>
566
568 Copyright (c) 1993-2007 Jochen Stenzel. All rights reserved.
569 This program is free software, you can redistribute it and/or modify it
571 under the terms of the Artistic License distributed with Perl version
572 5.003 or (at your option) any later version. Please refer to the
573 Artistic License that came with your Perl distribution for more
574 details.
575perl v5.12.0 2007-04-21 ArgvFile(3)