Provided by: libgetopt-argvfile-perl_1.11-3_all 
NAME
Getopt::ArgvFile - interpolates script options from files into @ARGV or another array
VERSION
This manual describes version 1.11.
SYNOPSIS
One line invocation - option hints are processed while the module is loaded:
# load module and process option file hints in @ARGV
use Getopt::ArgvFile default=>1;
# load another module to evaluate the options, e.g.:
use Getopt::Long;
...
# evaluate options, e.g. this common way:
GetOptions(\%options, 'any'); # this function is defined in Getopt::Long
Or suppress option hint processing when the module is loaded, to perform it later on:
# load module, do *not* process option file hints
use Getopt::ArgvFile justload=>1;
# load another module to evaluate the options, e.g.:
use Getopt::Long;
...
# *now*, solve option file hints
Getopt::ArgvFile::argvFile(default=>1);
# evaluate options, e.g. this common way:
GetOptions(\%options, 'any'); # this function is defined in Getopt::Long
Or use the traditional two step invocation of module loading with symbol import and
explicit option file handling:
# Load the module and import the &argvFile symbol
# - this will *not* process option hints.
# Use *this* syntax to do so, *exactly*.
use Getopt::ArgvFile qw(argvFile);
# load another module to evaluate the options, e.g.:
use Getopt::Long;
...
# *now*, solve option file hints
argvFile(default=>1);
# evaluate options, e.g. this common way:
GetOptions(\%options, 'any'); # this function is defined in Getopt::Long
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 the options stored in the files
argvFile(array=>\@options);
In case you do not like the "@" prefix it is possible to define an option to be used
instead:
# prepare target array
my @options=('-options', 'options1', '-options', 'options2');
...
# replace file hints by the options stored in the files
argvFile(fileOption=>'options', array=>\@options);
DESCRIPTION
This module simply interpolates option file hints in @ARGV by the contents of the pointed
files. This enables option reading from files instead of or additional to the usual
reading from the command line.
Alternatively, you can process any array instead of @ARGV which is used by default and
mentioned mostly in this manual.
The interpolated @ARGV could be subsequently processed by the usual option handling, e.g.
by a Getopt::xxx module. Getopt::ArgvFile does not perform any option handling itself, it
only prepares the array @ARGV.
Option files can significantly simplify the call of a script. Imagine the following:
Breaking command line limits
A script may offer a lot of options, with possibly a few of them even taking
parameters. If these options and their parameters are passed onto the program call
directly, the number of characters accepted by your shells command line may be
exceeded.
Perl itself does not limit the number of characters passed to a script by parameters,
but the shell or command interpreter often sets a limit here. The same problem may
occur if you want to store a long call in a system file like crontab.
If such a limit restricts you, options and parameters may be moved into option files,
which will result in a shorter command line call.
Script calls prepared by scripts
Sometimes a script calls another script. The options passed onto the nested script
could depend on variable situations, such as a users input or the detected
environment. In such a case, it can be easier to generate an intermediate option file
which is then passed to the nested script.
Or imagine two cron jobs one preparing the other: the first may generate an option
file which is then used by the second.
Simple access to typical calling scenarios
If several options need to be set, but in certain circumstances are always the same,
it could become slightly nerveracking to type them in again and again. With an option
file, they can be stored once and recalled easily as often as necessary.
Further more, option files may be used to group options. Several settings may set up
one certain behaviour of the program, while others influence another. Or a certain set
of options may be useful in one typical situation, while another one should be used
elsewhere. Or there is a common set of options which has to be used in every call,
while other options are added depending on the current needs. Or there are a few user
groups with different but typical ways to call your script. In all these cases,
option files may collect options belonging together, and may be combined by the script
users to set up a certain call. In conjunction with the possibility to nest such
collections, this is perhaps the most powerful feature provided by this method.
Individual and installationwide default options
The module allows the programmer to enable user setups of default options; for both
individual users or generally all callers of a script. This is especially useful for
administrators who can configure the default behaviour of a script by setting up its
installationwide startup option file. All script users are free then to completely
forget every already configured setup option. And if one of them regularly adds
certain options to every call, he could store them in his individual startup option
file.
For example, I use this feature to make my scripts both flexible and usable. I have
several scripts accessing a database via DBI. The database account parameters as well
as the DBI startup settings should not be coded inside the scripts because this is not
very flexible, so I implemented them by options. But on the other hand, there should
be no need for a normal user to pass all these settings to every script call. My
solution for this is to use default option files set up and maintained by an
administrator. This is very transparent, most of the users know nothing of these
(documented ;-) configuration settings ... and if anything changes, only the option
files have to be adapted.
EXPORTS
No symbol is exported by default, but you may explicitly import the "argvFile()" function
using the exact syntax of the following example:
use Getopt::ArgvFile qw(argvFile);
Please note that this interface is provided for backwards compatibility with versions up
to 1.06. By loading the module this way, the traditional import mechanisms take affect and
"argvFile()" is not called implicitly.
This means that while option file hints are usually processed implicitly when
"Getopt::ArgvFile" is loaded, the syntax
use Getopt::ArgvFile qw(argvFile);
requires an extra call of argvFile() to process option files.
FUNCTIONS
There is only one function, argvFile(), which does all the work of option file hint
processing.
Please note that with version 1.07 and above "argvFile()" is called implicitly when the
module is loaded, except this is done in one of the following ways:
# the traditional interface - provided for
# backwards compatibility - this loads the
# module and imports the &argvFile symbol
use Getopt::ArgvFile qw(argvFile);
--
# option file processing is explicitly suppressed
use Getopt::ArgvFile justload=>1;
Except for the traditional loading, the complete interface of "argvFile()" is available
via "use", but in the typical "use" syntax without parentheses.
# implicit call of argvFile(default=>1, home=>1)
use Getopt::ArgvFile default=>1, home=>1;
See ONE LINE INVOCATION for further details.
argvFile()
Scans the command line parameters (stored in @ARGV or an alternatively passed array) for
option file hints (see Basics below), reads the pointed files and makes their contents
part of the source array (@ARGV by default) replacing the hints.
Because the function was intentionally designed to work on @ARGV and this is still the
default behaviour, this manual mostly speaks about @ARGV. Please note that it is possible
to process any other array as well.
Basics
An option file hint is simply the filename preceded by (at least) one "@" character:
> script -optA argA -optB @optionFile -optC argC
This will cause argvFile() to scan "optionFile" for options. The element "@optionFile"
will be removed from the @ARGV array and will be replaced by the options found.
Note: you can choose another prefix by using the "prefix" parameter, see below.
An option file which cannot be found is quietly skipped.
Well, what is within an option file? It is intended to store command line arguments which
should be passed to the called script. They can be stored exactly as they would be written
in the command line, but may be spread to multiple lines. To make the file more readable,
space and comment lines (starting with a "#") are allowed additionally. POD comments are
supported as well. For example, the call
> script -optA argA -optB -optC cArg par1 par2
could be transformed into
> script @scriptOptions par1 par2
where the file "scriptOptions" may look like this:
# option a
-optA argA
""
=pod
option b
=cut
-optB
""
# option c
-optC cArg
Nested option files
Option files can be nested. Recursion is avoided globally, that means that every file will
be opened only once (the first time argvFile() finds a hint pointing to it). This is the
simplest implementation, indeed, but should be suitable. (Unfortunately, there are
LIMITS.)
By using this feature, you may combine groups of typical options into a top level option
file, e.g.:
File ab:
""
# option a
-optA argA
# option b
-optB
""
File c:
""
# option c
-optC cArg
""
File abc:
""
# combine ab and c
@ab @c
If anyone provides these files, a user can use a very short call:
> script @abc
and argvFile() will recursively move all the filed program parameters into @ARGV.
Relative paths
Paths in option files might be relative, as in
-file ../file @../../configs/nested
If written with the (prepared) start directory in mind, that will work, but it can fail
when it was written relatively to the option file location because by default those paths
will not be resolved when written from an option file.
Use parameter "resolveRelativePathes" to switch to path resolution:
argvFile(resolveRelativePathes=>1);
will cause "argvFile()" to expand those paths, both in standard strings and nested option
files.
With resolveRelativePathes, both paths
will be resolved:
-file ../file @../../configs/nested
A path is resolved relative to the option file it is found in.
Environment variables
Similar to relative paths, environment variables are handled differently depending if the
option is specified at the commandline or from an option file, due to bypassed shell
processing. By default, "argvFile()" does not resolve environment variables. But if
required it can be commanded to do so via parameter "resolveEnvVars".
argvFile(resolveEnvVars=>1);
Startup support
By setting several named parameters, you can enable automatic processing of startup option
files. There are three of them:
The default option file is searched in the installation path of the calling script, the
home option file is searched in the users home (evaluated via environment variable
"HOME"), and the current option script is searched in the current directory.
By default, all startup option files are expected to be named like the script, preceded by
a dot, but this can be adapted to individual needs if preferred, see below.
Examples:
If a script located in "/path/script" is invoked in directory
/the/current/dir by a user "user" whoms "HOME" variable points
to "/homes/user", the following happens:
""
argvFile() # ignores all startup option files;
argvFile(default=>1) # searches and expands "/path/.script",
# if available (the "default" settings);
argvFile(home=>1) # searches and expands "/homes/user/.script",
# if available (the "home" settings);
argvFile(current=>1) # searches and expands "/the/current/dir/.script",
# if available (the "current" settings);
argvFile(
default => 1,
home => 1,
current => 1
) # tries to handle all startups.
Any true value will activate the setting it is assigned to.
In case the ".script" name rule does not meet your needs or does not fit into a certain
policy, the expected startup filenames can be set up by an option "startupFilename". The
option value may be a scalar used as the expected filename, or a reference to an array of
accepted choices, or a reference to code returning the name - plainly or as a reference to
an array of names. Such callback code will be called once and will receive the name of the
script.
# use ".config"
argvFile(startupFilename => '.config');
# use ".config" or "config"
argvFile(startupFilename => [qw(.config config)]);
# emulate the default behaviour,
# but use an extra dot postfix
my $nameBuilder=sub {join('', '.', basename($_[0]), '.');};
argvFile(startupFilename => $nameBuilder);
# use .(script)rc or .(script)/config
my $nameBuilder=sub
{
my $sname=basename($_[0]);
[".${sname}rc", ".${sname}/config"];
};
argvFile(startupFilename => $nameBuilder);
Note that the list variants will use the first matching filename in each possible startup-
file path. For example if your array is "['.scriptrc', '.script.config']" and you have
both a ".scriptrc" and a ".script.config" file in (say) your current directory, only the
".scriptrc" file will be used, as it is the first found.
The contents found in a startup file is placed before all explicitly set command line
arguments. This enables to overwrite a default setting by an explicit option. If all
startup files are read, current startup files can overwrite home files which have
preceedence over default ones, so that the default startups are most common. In other
words, if the module would not support startup files, you could get the same result with
"script @/path/.script @/homes/user/.script @/the/current/dir/.script".
Note: There is one certain case when overwriting will not work completely because
duplicates are sorted out: if all three types of startup files are used and the script is
started in the installation directory, the default file will be identical to the current
file. The default file is processed, but the current file is skipped as a duplicate later
on and will not overwrite settings made caused by the intermediately processed home file.
If started in another directory, it will overwrite the home settings. But the alternative
seems to be even more confusing: the script would behave differently if just started in
its installation path. Because a user might be more aware of configuration editing then of
the current path, I choose the current implementation, but this preceedence might become
configurable in a future version.
If there is no HOME environment variable, the home setting takes no effect to avoid
trouble accessing the root directory.
Cascades
The function supports multi-level (or so called cascaded) option files. If a filename in
an option file hint starts with a "@" again, this complete name is the resolution written
back to @ARGV - assuming there will be another utility reading option files.
Examples:
@rfile rfile will be opened, its contents is
made part of @ARGV.
@@rfile cascade: "@rfile" is written back to
@ARGV assuming that there is a subsequent
tool called by the script to which this
hint will be passed to solve it by an own
call of argvFile().
The number of cascaded hints is unlimited.
Processing an alternative array
Although the function was designed to process @ARGV, it is possible to process another
array as well if you prefer. To do this, simply pass a reference to this array by
parameter array.
Examples:
argvFile() # processes @ARGV;
argvFile(array=>\@options); # processes @options;
Choosing an alternative hint prefix
By default, "@" is the prefix used to mark an option file. This can be changed by using
the optional parameter prefix:
Examples:
argvFile(); # use "@";
argvFile(prefix=>'~'); # use "~";
Note that the strings "#", "=", "-" and "+" are reserved and cannot be chosen here because
they are used to start plain or POD comments or are typically option prefixes.
Using an option instead of a hint prefix
People not familiar with option files might be confused by file prefixes. This can be
avoided by offering an option that can be used instead of a prefix, using the optional
parameter fileOption:
# install a file option
# (all lines are equivalent)
argvFile(fileOption=>'options');
argvFile(fileOption=>'-options');
argvFile(fileOption=>'+options');
argvFile(fileOption=>'--options');
The name of the option can be specified with or without the usual option prefixes "-",
"--" and "+".
Once an option is declared, it can replace a prefix. (Prefixes remain in action as well.)
# with -options declared to be a file option,
# these sequences are equivalent
@file
-options file
# five equivalent cascades
@@@@file
-options @@@file
-options -options @@file
-options -options -options @file
-options -options -options -options file
Please note that prefixes are attached to the filename with no spaces in between, while
the option declared via -fileOption is separated from the filename by whitespace, as for
normal options.
ONE LINE INVOCATION
The traditional two line sequence
# load the module
use Getopt::ArgvFile qw(argvFile);
...
# solve option files
argvFile(default=>1);
can be reduced to one line - just pass the parameters of "argvFile()" to "use()":
# load module and process option file hints in @ARGV
use Getopt::ArgvFile default=>1;
Please note that in this case option file hints are processed at compile time. This means
that if you want to process alternative arrays, these arrays have to be prepared before,
usually in a "BEGIN" block.
In versions 1.07 and above, implicit option file handling is the default and only
suppressed for the traditional
use Getopt::ArgvFile qw(argvFile);
loading, for reasons of backwards compatibility. A simple loading like
use Getopt::ArgvFile;
will process option hints! If you want to suppress this, use the "justload" switch:
use Getopt::ArgvFile justload=>1;
See FUNCTIONS for additional information.
NOTES
If a script calling "argvFile()" with the "default" switch is invoked using a relative
path, it is strongly recommended to perform the call of "argvFile()" in the startup
directory because "argvFile()" then uses the relative script path as well.
LIMITS
If an option file does not exist, argvFile() simply ignores it. No message will be
displayed, no special return code will be set.
AUTHOR
Jochen Stenzel <mailto:perl@jochen-stenzel.de>
LICENSE
Copyright (c) 1993-2007 Jochen Stenzel. All rights reserved.
This program 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.