DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH
 

ArgvFile(3)





NAME

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


VERSION

       This manual describes version 1.10.


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');

       Or suppress option hint processing when the module is loaded, to per-
       form 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');

       Or use the traditional two step invocation of module loading with sym-
       bol 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');

       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=>'option', array=>\@options);


DESCRIPTION

       This module simply interpolates option file hints in @ARGV by the con-
       tents 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 sligthly 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 else-
           where. 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 nest such collections, this is perhaps the most pow-
           erful 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 con-
           figure the default behaviour of a script by setting up its instal-
           lationwide 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 set-
           tings 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 (docu-
           mented ;-) 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 tradi-
       tional import mechanisms take affect and "argvFile()" is not called
       implicitly.

       This means that while option file hints are usually processed implic-
       itly 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 "argv-
       File()" is available via "use", but in the typical "use" syntax without
       parantheses.

         # 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 preceeded by (at least) one
       "@" character:

         > script -optA argA -optB @optionFile -optC argC

       This will cause argvFile() to scan "optionFile" for options.  The ele-
       ment "@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 com-
       ments 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 loca-
       tion 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.

       Envrionment variables

       Similar to relative pathes, environment variables are handled differ-
       ently depending if the option is specified at the commandline or from
       an option file, due to bypassed shell processing. By default, "argv-
       File()" 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 process-
       ing 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/cur-
       rent/dir/.script".

       Note: There is one certain case when overwriting will not work com-
       pletely 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 dupli-
       cate later on and will not overwrite settings made caused by the inter-
       mediately 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 configura-
       tion editing then of the current path, I choose the current implementa-
       tion, but this preceedence might become configurable in a future ver-
       sion.

       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 com-
       plete 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

       However 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 pre-
       fixes.  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 com-
       pile 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 "just-
       load" switch:

         use Getopt::ArgvFile justload=>1;

       See FUNCTIONS for additional informations.


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-2005 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 Artis-
       tic License that came with your Perl distribution for more details.

perl v5.8.8                       2005-02-06                       ArgvFile(3)
See also Getopt::Long(3)

Man(1) output converted with man2html