1ArgvFile(3)           User Contributed Perl Documentation          ArgvFile(3)
2
3
4

NAME

6       Getopt::ArgvFile - interpolates script options from files into @ARGV or
7       another array
8

VERSION

10       This manual describes version 1.11.
11

SYNOPSIS

13       One line invocation - option hints are processed while the module is
14       loaded:
15
16         # load module and process option file hints in @ARGV
17         use Getopt::ArgvFile default=>1;
18
19         # load another module to evaluate the options, e.g.:
20         use Getopt::Long;
21         ...
22
23         # evaluate options, e.g. this common way:
24         GetOptions(\%options, 'any');    # this function is defined in Getopt::Long
25
26       Or suppress option hint processing when the module is loaded, to
27       perform it later on:
28
29         # load module, do *not* process option file hints
30         use Getopt::ArgvFile justload=>1;
31
32         # load another module to evaluate the options, e.g.:
33         use Getopt::Long;
34         ...
35
36         # *now*, solve option file hints
37         Getopt::ArgvFile::argvFile(default=>1);
38
39         # evaluate options, e.g. this common way:
40         GetOptions(\%options, 'any');    # this function is defined in Getopt::Long
41
42       Or use the traditional two step invocation of module loading with
43       symbol import and explicit option file handling:
44
45         # 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
50         # load another module to evaluate the options, e.g.:
51         use Getopt::Long;
52         ...
53
54         # *now*, solve option file hints
55         argvFile(default=>1);
56
57         # evaluate options, e.g. this common way:
58         GetOptions(\%options, 'any');    # this function is defined in Getopt::Long
59
60       If options should be processed into another array, this can be done
61       this way:
62
63         # prepare target array
64         my @options=('@options1', '@options2', '@options3');
65
66         ...
67
68         # replace file hints by the options stored in the files
69         argvFile(array=>\@options);
70
71       In case you do not like the "@" prefix it is possible to define an
72       option to be used instead:
73
74         # prepare target array
75         my @options=('-options', 'options1', '-options', 'options2');
76
77         ...
78
79         # replace file hints by the options stored in the files
80         argvFile(fileOption=>'options', array=>\@options);
81

DESCRIPTION

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
87       Alternatively, you can process any array instead of @ARGV which is used
88       by default and mentioned mostly in this manual.
89
90       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
95       Option files can significantly simplify the call of a script.  Imagine
96       the following:
97
98       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
104           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
109           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
113       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
120           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
123       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
129           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
142       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
152           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

EXPORTS

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
168         use Getopt::ArgvFile qw(argvFile);
169
170       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
175       This means that while option file hints are usually processed
176       implicitly when "Getopt::ArgvFile" is loaded, the syntax
177
178         use Getopt::ArgvFile qw(argvFile);
179
180       requires an extra call of argvFile() to process option files.
181

FUNCTIONS

183       There is only one function, argvFile(), which does all the work of
184       option file hint processing.
185
186       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
190         # 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
195         --
196
197         # option file processing is explicitly suppressed
198         use Getopt::ArgvFile justload=>1;
199
200       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
204         # implicit call of argvFile(default=>1, home=>1)
205         use Getopt::ArgvFile default=>1, home=>1;
206
207       See ONE LINE INVOCATION for further details.
208
209   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
215       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
220       Basics
221
222       An option file hint is simply the filename preceeded by (at least) one
223       "@" character:
224
225         > script -optA argA -optB @optionFile -optC argC
226
227       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
231       Note: you can choose another prefix by using the "prefix" parameter,
232       see below.
233
234       An option file which cannot be found is quietly skipped.
235
236       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
243         > script -optA argA -optB -optC cArg par1 par2
244
245       could be transformed into
246
247         > script @scriptOptions par1 par2
248
249       where the file "scriptOptions" may look like this:
250
251         # option a
252         -optA argA
253
254       ""
255
256         =pod
257         option b
258         =cut
259         -optB
260
261       ""
262
263         # option c
264         -optC cArg
265
266       Nested option files
267
268       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
273       By using this feature, you may combine groups of typical options into a
274       top level option file, e.g.:
275
276         File ab:
277
278       ""
279
280         # option a
281         -optA argA
282         # option b
283         -optB
284
285       ""
286
287         File c:
288
289       ""
290
291         # option c
292         -optC cArg
293
294       ""
295
296         File abc:
297
298       ""
299
300         # combine ab and c
301         @ab @c
302
303       If anyone provides these files, a user can use a very short call:
304
305         > script @abc
306
307       and argvFile() will recursively move all the filed program parameters
308       into @ARGV.
309
310       Relative pathes
311
312       Pathes in option files might be relative, as in
313
314         -file ../file @../../configs/nested
315
316       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
321       Use parameter "resolveRelativePathes" to switch to path resolution:
322
323          argvFile(resolveRelativePathes=>1);
324
325       will cause "argvFile()" to expand those pathes, both in standard
326       strings and nested option files.
327
328          With resolveRelativePathes, both pathes
329          will be resolved:
330
331          -file ../file @../../configs/nested
332
333       A path is resolved relative to the option file it is found in.
334
335       Environment variables
336
337       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
343         argvFile(resolveEnvVars=>1);
344
345       Startup support
346
347       By setting several named parameters, you can enable automatic
348       processing of startup option files. There are three of them:
349
350       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
355       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
359        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
364       ""
365
366         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
379       Any true value will activate the setting it is assigned to.
380
381       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
389         # use ".config"
390         argvFile(startupFilename => '.config');
391
392         # use ".config" or "config"
393         argvFile(startupFilename => [qw(.config config)]);
394
395         # emulate the default behaviour,
396         # but use an extra dot postfix
397         my $nameBuilder=sub {join('', '.', basename($_[0]), '.');};
398         argvFile(startupFilename => $nameBuilder);
399
400         # 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
408       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
414       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
423       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
437       If there is no HOME environment variable, the home setting takes no
438       effect to avoid trouble accessing the root directory.
439
440       Cascades
441
442       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
447        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
456       The number of cascaded hints is unlimited.
457
458       Processing an alternative array
459
460       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
464        Examples:
465         argvFile()                    # processes @ARGV;
466         argvFile(array=>\@options);   # processes @options;
467
468       Choosing an alternative hint prefix
469
470       By default, "@" is the prefix used to mark an option file. This can be
471       changed by using the optional parameter prefix:
472
473        Examples:
474         argvFile();                   # use "@";
475         argvFile(prefix=>'~');        # use "~";
476
477       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
481       Using an option instead of a hint prefix
482
483       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
487         # 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
494       The name of the option can be specified with or without the usual
495       option prefixes "-", "--" and "+".
496
497       Once an option is declared, it can replace a prefix. (Prefixes remain
498       in action as well.)
499
500          # with -options declared to be a file option,
501          # these sequences are equivalent
502          @file
503          -options file
504
505          # five equivalent cascades
506          @@@@file
507          -options @@@file
508          -options -options @@file
509          -options -options -options @file
510          -options -options -options -options file
511
512       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

ONE LINE INVOCATION

517       The traditional two line sequence
518
519         # load the module
520         use Getopt::ArgvFile qw(argvFile);
521
522         ...
523
524         # solve option files
525         argvFile(default=>1);
526
527       can be reduced to one line - just pass the parameters of "argvFile()"
528       to "use()":
529
530         # load module and process option file hints in @ARGV
531         use Getopt::ArgvFile default=>1;
532
533       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
538       In versions 1.07 and above, implicit option file handling is the
539       default and only suppressed for the traditional
540
541         use Getopt::ArgvFile qw(argvFile);
542
543       loading, for reasons of backwards compatibility. A simple loading like
544
545         use Getopt::ArgvFile;
546
547       will process option hints! If you want to suppress this, use the
548       "justload" switch:
549
550         use Getopt::ArgvFile justload=>1;
551
552       See FUNCTIONS for additional informations.
553

NOTES

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

LIMITS

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

AUTHOR

565       Jochen Stenzel <mailto:perl@jochen-stenzel.de>
566

LICENSE

568       Copyright (c) 1993-2007 Jochen Stenzel. All rights reserved.
569
570       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.
575
576
577
578perl v5.12.0                      2007-04-21                       ArgvFile(3)
Impressum