Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ArgvFile(3)	      User Contributed Perl Documentation	   ArgvFile(3)

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.24.1			  2007-04-21			   ArgvFile(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | EXPORTS | FUNCTIONS | ONE LINE INVOCATION | NOTES | LIMITS | AUTHOR | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Getopt::ArgvFile&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help