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 preceeded 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 pathes

Pathes 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 pathes 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 pathes, both in standard strings and nested option files.

   With resolveRelativePathes, both pathes
   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 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, "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, preceeded 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.