Filewatcher File Search File Search
Catalog
Content Search
» » » » » libgetopt-argvfile-perl_1.11-1_all.deb » Content »
pkg://libgetopt-argvfile-perl_1.11-1_all.deb:31542/usr/share/man/man3/  info  control  downloads

libgetopt-argvfile-perl - Perl module for reading script options and parameters from files…  more info»

Getopt::ArgvFile.3pm.gz

ArgvFile(3pm)    User Contributed Perl Documentation   ArgvFile(3pm)



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
           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 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 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 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 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.

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 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-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.



perl v5.10.0                 2007-04-21                ArgvFile(3pm)
Results 1 - 1 of 1
Help - FTP Sites List - Software Dir.
Search over 15 billion files
© 1997-2017 FileWatcher.com