Current File : //usr/local/share/man/man3/Getopt::ArgvFile.3

.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.30)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ArgvFile 3"
.TH ArgvFile 3 "2007-04-22" "perl v5.20.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Getopt::ArgvFile \- interpolates script options from files into @ARGV or another array
.SH "VERSION"
.IX Header "VERSION"
This manual describes version \fB1.11\fR.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
One line invocation \- option hints are processed while the module is loaded:
.PP
.Vb 2
\&  # 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(\e%options, \*(Aqany\*(Aq);    # this function is defined in Getopt::Long
.Ve
.PP
Or suppress option hint processing when the module is loaded, to
perform it later on:
.PP
.Vb 2
\&  # 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(\e%options, \*(Aqany\*(Aq);    # this function is defined in Getopt::Long
.Ve
.PP
Or use the traditional two step invocation of module loading with
\&\fIsymbol import\fR and \fIexplicit\fR option file handling:
.PP
.Vb 4
\&  # 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(\e%options, \*(Aqany\*(Aq);    # this function is defined in Getopt::Long
.Ve
.PP
If options should be processed into another array, this can be done this way:
.PP
.Vb 2
\&  # prepare target array
\&  my @options=(\*(Aq@options1\*(Aq, \*(Aq@options2\*(Aq, \*(Aq@options3\*(Aq);
\&
\&  ...
\&
\&  # replace file hints by the options stored in the files
\&  argvFile(array=>\e@options);
.Ve
.PP
In case you do not like the \*(L"@\*(R" prefix it is possible to define an option to
be used instead:
.PP
.Vb 2
\&  # prepare target array
\&  my @options=(\*(Aq\-options\*(Aq, \*(Aqoptions1\*(Aq, \*(Aq\-options\*(Aq, \*(Aqoptions2\*(Aq);
\&
\&  ...
\&
\&  # replace file hints by the options stored in the files
\&  argvFile(fileOption=>\*(Aqoptions\*(Aq, array=>\e@options);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module simply interpolates option file hints in \f(CW@ARGV\fR
by the contents of the pointed files. This enables option
reading from \fIfiles\fR instead of or additional to the usual
reading from the command line.
.PP
Alternatively, you can process any array instead of \f(CW@ARGV\fR
which is used by default and mentioned mostly in this manual.
.PP
The interpolated \f(CW@ARGV\fR could be subsequently processed by
the usual option handling, e.g. by a Getopt::xxx module.
Getopt::ArgvFile does \fInot\fR perform any option handling itself,
it only prepares the array \f(CW@ARGV\fR.
.PP
Option files can significantly simplify the call of a script.
Imagine the following:
.IP "Breaking command line limits" 4
.IX Item "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.
.Sp
Perl itself does \fInot\fR limit the number of characters passed to a
script by parameters, but the shell or command interpreter often
\&\fIsets\fR a limit here. The same problem may occur if you want to
store a long call in a system file like crontab.
.Sp
If such a limit restricts you, options and parameters may be moved into
option files, which will result in a shorter command line call.
.IP "Script calls prepared by scripts" 4
.IX Item "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 \fIcan\fR be easier
to generate an intermediate option file which is then passed to
the nested script.
.Sp
Or imagine two cron jobs one preparing the other: the first may generate
an option file which is then used by the second.
.IP "Simple access to typical calling scenarios" 4
.IX Item "Simple access to typical calling scenarios"
If several options need to be set, but in certain circumstances
are always the same, it could become sligthly nerveracking to type
them in again and again. With an option file, they can be stored
\&\fIonce\fR and recalled easily as often as necessary.
.Sp
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 possiblity to \fInest\fR such collections, this is
perhaps the most powerful feature provided by this method.
.IP "Individual and installationwide default options" 4
.IX Item "Individual and installationwide default options"
The module allows the programmer to enable user setups of default options;
for both individual users or generally \fIall\fR callers of a script.
This is especially useful for administrators who can configure the
\&\fIdefault\fR 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 \fIindividual\fR
startup option file.
.Sp
For example, I use this feature to make my scripts both flexible \fIand\fR
usable. I have several scripts accessing a database via \s-1DBI.\s0 The database
account parameters as well as the \s-1DBI\s0 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 \fIdefault\fR 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.
.SH "EXPORTS"
.IX Header "EXPORTS"
No symbol is exported by default, but you may explicitly import
the \*(L"\fIargvFile()\fR\*(R" function \fIusing the exact syntax of the following example\fR:
.PP
.Vb 1
\&  use Getopt::ArgvFile qw(argvFile);
.Ve
.PP
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 \fI\f(CI\*(C`argvFile()\*(C'\fI is not called implicitly\fR.
.PP
This means that while option file hints are usually processed implicitly when
\&\f(CW\*(C`Getopt::ArgvFile\*(C'\fR is loaded, the syntax
.PP
.Vb 1
\&  use Getopt::ArgvFile qw(argvFile);
.Ve
.PP
requires an \fIextra\fR call of \fI\fIargvFile()\fI\fR to process option files.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
There is only one function, \fI\fIargvFile()\fI\fR, which does all the work of
option file hint processing.
.PP
Please note that with version 1.07 and above \f(CW\*(C`argvFile()\*(C'\fR is called
\&\fIimplicitly\fR when the module is loaded, except this is done in one of
the following ways:
.PP
.Vb 4
\&  # 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;
.Ve
.PP
Except for the traditional loading, the complete interface of \f(CW\*(C`argvFile()\*(C'\fR
is available via \f(CW\*(C`use\*(C'\fR, but in the typical \f(CW\*(C`use\*(C'\fR syntax without
parantheses.
.PP
.Vb 2
\&  # implicit call of argvFile(default=>1, home=>1)
\&  use Getopt::ArgvFile default=>1, home=>1;
.Ve
.PP
See \fI\s-1ONE LINE INVOCATION\s0\fR for further details.
.SS "\fIargvFile()\fP"
.IX Subsection "argvFile()"
Scans the command line parameters (stored in \f(CW@ARGV\fR or an alternatively
passed array) for option file hints (see \fIBasics\fR below), reads the
pointed files and makes their contents part of the source array
(@ARGV by default) replacing the hints.
.PP
Because the function was intentionally designed to work on \f(CW@ARGV\fR
and this is still the default behaviour, this manual mostly speaks about
\&\f(CW@ARGV\fR. Please note that it is possible to process \fIany\fR other array
as well.
.PP
\&\fBBasics\fR
.PP
An option file hint is simply the filename preceeded by (at least) one
\&\*(L"@\*(R" character:
.PP
.Vb 1
\&  > script \-optA argA \-optB @optionFile \-optC argC
.Ve
.PP
This will cause \fIargvFile()\fR to scan \*(L"optionFile\*(R" for options.
The element \*(L"@optionFile\*(R" will be removed from the \f(CW@ARGV\fR array and
will be replaced by the options found.
.PP
Note: you can choose another prefix by using the \*(L"prefix\*(R" parameter,
see below.
.PP
An option file which cannot be found is quietly skipped.
.PP
Well, what is \fIwithin\fR an option file? It is intended to
store \fIcommand line arguments\fR 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 \*(L"#\*(R")
are allowed additionally. \s-1POD\s0 comments are supported as well.
For example, the call
.PP
.Vb 1
\&  > script \-optA argA \-optB \-optC cArg par1 par2
.Ve
.PP
could be transformed into
.PP
.Vb 1
\&  > script @scriptOptions par1 par2
.Ve
.PP
where the file \*(L"scriptOptions\*(R" may look like this:
.PP
.Vb 2
\&  # option a
\&  \-optA argA
.Ve
.PP
\&\f(CW\*(C`\*(C'\fR
.PP
.Vb 4
\&  =pod
\&  option b
\&  =cut
\&  \-optB
.Ve
.PP
\&\f(CW\*(C`\*(C'\fR
.PP
.Vb 2
\&  # option c
\&  \-optC cArg
.Ve
.PP
\&\fBNested option files\fR
.PP
Option files can be nested. Recursion is avoided globally, that means
that every file will be opened only \fIonce\fR (the first time \fIargvFile()\fR finds
a hint pointing to it). This is the simplest implementation, indeed, but
should be suitable. (Unfortunately, there are \fI\s-1LIMITS\s0\fR.)
.PP
By using this feature, you may combine groups of typical options into
a top level option file, e.g.:
.PP
.Vb 1
\&  File ab:
.Ve
.PP
\&\f(CW\*(C`\*(C'\fR
.PP
.Vb 4
\&  # option a
\&  \-optA argA
\&  # option b
\&  \-optB
.Ve
.PP
\&\f(CW\*(C`\*(C'\fR
.PP
.Vb 1
\&  File c:
.Ve
.PP
\&\f(CW\*(C`\*(C'\fR
.PP
.Vb 2
\&  # option c
\&  \-optC cArg
.Ve
.PP
\&\f(CW\*(C`\*(C'\fR
.PP
.Vb 1
\&  File abc:
.Ve
.PP
\&\f(CW\*(C`\*(C'\fR
.PP
.Vb 2
\&  # combine ab and c
\&  @ab @c
.Ve
.PP
If anyone provides these files, a user can use a very short call:
.PP
.Vb 1
\&  > script @abc
.Ve
.PP
and \fIargvFile()\fR will recursively move all the filed program parameters
into \f(CW@ARGV\fR.
.PP
\&\fBRelative pathes\fR
.PP
Pathes in option files might be relative, as in
.PP
.Vb 1
\&  \-file ../file @../../configs/nested
.Ve
.PP
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 pathes will not be resolved when written from
an option file.
.PP
Use parameter \f(CW\*(C`resolveRelativePathes\*(C'\fR to switch to path resolution:
.PP
.Vb 1
\&   argvFile(resolveRelativePathes=>1);
.Ve
.PP
will cause \f(CW\*(C`argvFile()\*(C'\fR to expand those pathes, both in standard strings
and nested option files.
.PP
.Vb 2
\&   With resolveRelativePathes, both pathes
\&   will be resolved:
\&
\&   \-file ../file @../../configs/nested
.Ve
.PP
A path is resolved \fIrelative to the option file\fR it is found in.
.PP
\&\fBEnvironment variables\fR
.PP
Similar to relative pathes, 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, \f(CW\*(C`argvFile()\*(C'\fR does
not resolve environment variables. But if required it can be commanded
to do so via parameter \f(CW\*(C`resolveEnvVars\*(C'\fR.
.PP
.Vb 1
\&  argvFile(resolveEnvVars=>1);
.Ve
.PP
\&\fBStartup support\fR
.PP
By setting several named parameters, you can enable automatic processing
of \fIstartup option files\fR. There are three of them:
.PP
The \fIdefault option file\fR is searched in the installation path
of the calling script, the \fIhome option file\fR is searched in the
users home (evaluated via environment variable \*(L"\s-1HOME\*(R"\s0), and the
\&\fIcurrent option script\fR is searched in the current directory.
.PP
By default, all startup option files are expected to be named like
the script, preceeded by a dot, but this can be adapted to individual
needs if preferred, see below.
.PP
.Vb 4
\& 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:
.Ve
.PP
\&\f(CW\*(C`\*(C'\fR
.PP
.Vb 12
\&  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.
.Ve
.PP
Any true value will activate the setting it is assigned to.
.PP
In case the \*(L".script\*(R" 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 \f(CW\*(C`startupFilename\*(C'\fR. 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 \fIonce\fR and will
receive the name of the script.
.PP
.Vb 2
\&  # use ".config"
\&  argvFile(startupFilename => \*(Aq.config\*(Aq);
\&
\&  # use ".config" or "config"
\&  argvFile(startupFilename => [qw(.config config)]);
\&
\&  # emulate the default behaviour,
\&  # but use an extra dot postfix
\&  my $nameBuilder=sub {join(\*(Aq\*(Aq, \*(Aq.\*(Aq, basename($_[0]), \*(Aq.\*(Aq);};
\&  argvFile(startupFilename => $nameBuilder);
\&
\&  # use .(script)rc or .(script)/config
\&  my $nameBuilder=sub
\&                   {
\&                    my $sname=basename($_[0]);
\&                    [".${sname}rc", ".${sname}/config"];
\&                   };
\&  argvFile(startupFilename => $nameBuilder);
.Ve
.PP
Note that the list variants will use the first matching filename in each
possible startup-file path. For example if your array is \f(CW\*(C`[\*(Aq.scriptrc\*(Aq,
\&\*(Aq.script.config\*(Aq]\*(C'\fR and you have both a \f(CW\*(C`.scriptrc\*(C'\fR and a \f(CW\*(C`.script.config\*(C'\fR
file in (say) your current directory, only the \f(CW\*(C`.scriptrc\*(C'\fR file will be
used, as it is the first found.
.PP
The contents found in a startup file is placed \fIbefore\fR all explicitly
set command line arguments. This enables to overwrite a default setting
by an explicit option. If all startup files are read, \fIcurrent\fR startup
files can overwrite \fIhome\fR files which have preceedence over \fIdefault\fR
ones, so that the \fIdefault\fR startups are most common. In other words,
if the module would not support startup files, you could get the same
result with \*(L"script @/path/.script @/homes/user/.script @/the/current/dir/.script\*(R".
.PP
Note: There is one certain case when overwriting will \fInot\fR 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
\&\fInot\fR overwrite settings made caused by the intermediately processed home file.
If started in another directory, it \fIwill\fR 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.
.PP
If there is no \fI\s-1HOME\s0\fR environment variable, the \fIhome\fR setting takes no effect
to avoid trouble accessing the root directory.
.PP
\&\fBCascades\fR
.PP
The function supports multi-level (or so called \fIcascaded\fR) option files.
If a filename in an option file hint starts with a \*(L"@\*(R" again, this complete
name is the resolution written back to \f(CW@ARGV\fR \- assuming there will be
another utility reading option files.
.PP
.Vb 8
\& 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().
.Ve
.PP
The number of cascaded hints is unlimited.
.PP
\&\fBProcessing an alternative array\fR
.PP
Although the function was designed to process \f(CW@ARGV\fR, it is possible to
process another array as well if you prefer. To do this, simply pass
a \fIreference\fR to this array by parameter \fBarray\fR.
.PP
.Vb 3
\& Examples:
\&  argvFile()                    # processes @ARGV;
\&  argvFile(array=>\e@options);   # processes @options;
.Ve
.PP
\&\fBChoosing an alternative hint prefix\fR
.PP
By default, \*(L"@\*(R" is the prefix used to mark an option file. This can
be changed by using the optional parameter \fBprefix\fR:
.PP
.Vb 3
\& Examples:
\&  argvFile();                   # use "@";
\&  argvFile(prefix=>\*(Aq~\*(Aq);        # use "~";
.Ve
.PP
Note that the strings \*(L"#\*(R", \*(L"=\*(R", \*(L"\-\*(R" and \*(L"+\*(R" are reserved and \fIcannot\fR
be chosen here because they are used to start plain or \s-1POD\s0 comments or
are typically option prefixes.
.PP
\&\fBUsing an option instead of a hint prefix\fR
.PP
People not familiar with option files might be confused by file prefixes.
This can be avoided by offering an \fIoption\fR that can be used instead
of a prefix, using the optional parameter \fBfileOption\fR:
.PP
.Vb 6
\&  # install a file option
\&  # (all lines are equivalent)
\&  argvFile(fileOption=>\*(Aqoptions\*(Aq);
\&  argvFile(fileOption=>\*(Aq\-options\*(Aq);
\&  argvFile(fileOption=>\*(Aq+options\*(Aq);
\&  argvFile(fileOption=>\*(Aq\-\-options\*(Aq);
.Ve
.PP
The name of the option can be specified with or without the usual option
prefixes \f(CW\*(C`\-\*(C'\fR, \f(CW\*(C`\-\-\*(C'\fR and \f(CW\*(C`+\*(C'\fR.
.PP
Once an option is declared, it \fIcan\fR replace a prefix. (Prefixes remain
in action as well.)
.PP
.Vb 4
\&   # 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
.Ve
.PP
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.
.SH "ONE LINE INVOCATION"
.IX Header "ONE LINE INVOCATION"
The traditional two line sequence
.PP
.Vb 2
\&  # load the module
\&  use Getopt::ArgvFile qw(argvFile);
\&
\&  ...
\&
\&  # solve option files
\&  argvFile(default=>1);
.Ve
.PP
can be reduced to one line \- just pass the parameters of \f(CW\*(C`argvFile()\*(C'\fR
to \f(CW\*(C`use()\*(C'\fR:
.PP
.Vb 2
\&  # load module and process option file hints in @ARGV
\&  use Getopt::ArgvFile default=>1;
.Ve
.PP
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 \f(CW\*(C`BEGIN\*(C'\fR block.
.PP
In versions 1.07 and above, implicit option file handling is the \fIdefault\fR
and only suppressed for the traditional
.PP
.Vb 1
\&  use Getopt::ArgvFile qw(argvFile);
.Ve
.PP
loading, for reasons of backwards compatibility. A simple loading like
.PP
.Vb 1
\&  use Getopt::ArgvFile;
.Ve
.PP
\&\fIwill\fR process option hints! If you want to suppress this, use the
\&\fB\f(CB\*(C`justload\*(C'\fB\fR switch:
.PP
.Vb 1
\&  use Getopt::ArgvFile justload=>1;
.Ve
.PP
See \fI\s-1FUNCTIONS\s0\fR for additional informations.
.SH "NOTES"
.IX Header "NOTES"
If a script calling \f(CW\*(C`argvFile()\*(C'\fR with the \f(CW\*(C`default\*(C'\fR switch is
invoked using a relative path, it is strongly recommended to
perform the call of \f(CW\*(C`argvFile()\*(C'\fR in the startup directory
because \f(CW\*(C`argvFile()\*(C'\fR then uses the \fIrelative\fR script path as
well.
.SH "LIMITS"
.IX Header "LIMITS"
If an option file does not exist, \fIargvFile()\fR simply ignores it.
No message will be displayed, no special return code will be set.
.SH "AUTHOR"
.IX Header "AUTHOR"
Jochen Stenzel <mailto:perl@jochen\-stenzel.de>
.SH "LICENSE"
.IX Header "LICENSE"
Copyright (c) 1993\-2007 Jochen Stenzel. All rights reserved.
.PP
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.