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

FreeBSD Manual Pages

  
 
  

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

NAME
       Config::General - Generic Config	Module

SYNOPSIS
	#
	# the OOP way
	use Config::General;
	$conf =	Config::General->new("rcfile");
	my %config = $conf->getall;

	#
	# the procedural way
	use Config::General qw(ParseConfig SaveConfig SaveConfigString);
	my %config = ParseConfig("rcfile");

DESCRIPTION
       This module opens a config file and parses its contents for you.	The
       new method requires one parameter which needs to	be a filename. The
       method getall returns a hash which contains all options and its
       associated values of your config	file.

       The format of config files supported by Config::General is inspired by
       the well	known Apache config format, in fact, this module is 100%
       compatible to Apache configs, but you can also just use simple
	name/value pairs in your config	files.

       In addition to the capabilities of an Apache config file	it supports
       some enhancements such as here-documents, C-style comments or multiline
       options.

SUBROUTINES/METHODS
       new()
	   Possible ways to call new():

	    $conf = Config::General->new("rcfile");

	    $conf = Config::General->new(\%somehash);

	    $conf = Config::General->new( %options ); #	see below for description of possible options

	   This	method returns a Config::General object	(a hash	blessed	into
	   "Config::General" namespace.	 All further methods must be used from
	   that	returned object. see below.

	   You can use the new style with hash parameters or the old style
	   which is of course still supported. Possible	parameters to new()
	   are:

	   * a filename	of a configfile, which will be opened and parsed by
	   the parser

	   or

	   * a hash reference, which will be used as the config.

	   An alternative way to call new() is supplying an option- hash with
	   one or more of the following	keys set:

	   -ConfigFile
	       A filename or a filehandle, i.e.:

		-ConfigFile => "rcfile"	or -ConfigFile => \$FileHandle

	   -ConfigHash
	       A hash reference, which will be used as the config, i.e.:

		-ConfigHash => \%somehash

	   -String
	       A string	which contains a whole config, or an arrayref
	       containing the whole config line	by line.  The parser will
	       parse the contents of the string	instead	of a file. i.e:

		-String	=> $complete_config

	       it is also possible to feed an array reference to -String:

		-String	=> \@config_lines

	   -AllowMultiOptions
	       If the value is "no", then multiple identical options are
	       disallowed.  The	default	is "yes".  i.e.:

		-AllowMultiOptions => "yes"

	       see IDENTICAL OPTIONS for details.

	   -LowerCaseNames
	       If set to a true	value, then all	options	found in the config
	       will be converted to lowercase. This allows you to provide
	       case-in-sensitive configs. The values of	the options will not
	       lowercased.

	   -UseApacheInclude
	       If set to a true	value, the parser will consider	"include ..."
	       as valid	include	statement (just	like the well known Apache
	       include statement).

	       It also supports	apache's "IncludeOptional" statement with the
	       same behavior, that is, if the include file doesn't exist no
	       error will be thrown.

	   -IncludeRelative
	       If set to a true	value, included	files with a relative path
	       (i.e. "cfg/blah.conf") will be opened from within the location
	       of the configfile instead from within the location of the
	       script($0). This	works only if the configfile has a absolute
	       pathname	(i.e. "/etc/main.conf").

	       If the variable -ConfigPath has been set	and if the file	to be
	       included	could not be found in the location relative to the
	       current config file, the	module will search within -ConfigPath
	       for the file. See the description of -ConfigPath	for more
	       details.

	   -IncludeDirectories
	       If set to a true	value, you may specify include a directory, in
	       which case all files inside the directory will be loaded	in
	       ASCII order.  Directory includes	will not recurse into
	       subdirectories.	This is	comparable to including	a directory in
	       Apache-style config files.

	   -IncludeGlob
	       If set to a true	value, you may specify a glob pattern for an
	       include to include all matching files (e.g. <<include
	       conf.d/*.conf>>).  Also note that as with standard file
	       patterns, * will	not match dot-files, so	<<include dir/*>> is
	       often more desirable than including a directory with
	       -IncludeDirectories.

	       An include option will not cause	a parser error if the glob
	       didn't return anything.

	   -IncludeAgain
	       If set to a true	value, you will	be able	to include a sub-
	       configfile multiple times.  With	the default, false, you	will
	       get a warning about duplicate includes and only the first
	       include will succeed.

	       Reincluding a configfile	can be useful if it contains data that
	       you want	to be present in multiple places in the	data tree.
	       See the example under "INCLUDES".

	       Note, however, that there is currently no check for include
	       recursion.

	   -ConfigPath
	       As mentioned above, you can use this variable to	specify	a
	       search path for relative	config files which have	to be
	       included. Config::General will search within this path for the
	       file if it cannot find the file at the location relative	to the
	       current config file.

	       To provide multiple search paths	you can	specify	an array
	       reference for the path.	For example:

		@path =	qw(/usr/lib/perl /nfs/apps/lib /home/lib);
		..
		-ConfigPath => \@path

	   -MergeDuplicateBlocks
	       If set to a true	value, then duplicate blocks, that means
	       blocks and named	blocks,	will be	merged into a single one (see
	       below for more details on this).	 The default behavior of
	       Config::General is to create an array if	some junk in a config
	       appears more than once.

	   -MergeDuplicateOptions
	       If set to a true	value, then duplicate options will be merged.
	       That means, if the same option occurs more than once, the last
	       one will	be used	in the resulting config	hash.

	       Setting this option implies -AllowMultiOptions == false unless
	       you set -AllowMultiOptions explicit to 'true'. In this case
	       duplicate blocks	are allowed and	put into an array but
	       duplicate options will be merged.

	   -AutoLaunder
	       If set to a true	value, then all	values in your config file
	       will be laundered to allow them to be used under	a -T taint
	       flag.  This could be regarded as	circumventing the purpose of
	       the -T flag, however, if	the bad	guys can mess with your	config
	       file, you have problems that -T will not	be able	to stop.
	       AutoLaunder will	only handle a config file being	read from
	       -ConfigFile.

	   -AutoTrue
	       If set to a true	value, then options in your config file, whose
	       values are set to true or false values, will be normalised to 1
	       or 0 respectively.

	       The following values will be considered as true:

		yes, on, 1, true

	       The following values will be considered as false:

		no, off, 0, false

	       This effect is case-insensitive,	i.e. both "Yes"	or "No"	will
	       result in 1.

	   -FlagBits
	       This option takes one required parameter, which must be a hash
	       reference.

	       The supplied hash reference needs to define variables for which
	       you want	to preset values. Each variable	you have defined in
	       this hash-ref and which occurs in your config file, will	cause
	       this variable being set to the preset values to which the value
	       in the config file refers to.

	       Multiple	flags can be used, separated by	the pipe character |.

	       Well, an	example	will clarify things:

		my $conf = Config::General->new(
			-ConfigFile => "rcfile",
			-FlagBits => {
			     Mode => {
				CLEAR	 => 1,
				STRONG	 => 1,
				UNSECURE => "32bit" }
			}
		);

	       In this example we are defining a variable named	"Mode" which
	       may contain one or more of "CLEAR", "STRONG" and	"UNSECURE" as
	       value.

	       The appropriate config entry may	look like this:

		# rcfile
		Mode = CLEAR | UNSECURE

	       The parser will create a	hash which will	be the value of	the
	       key "Mode". This	hash will contain all flags which you have
	       pre-defined, but	only those which were set in the config	will
	       contain the pre-defined value, the other	ones will be
	       undefined.

	       The resulting config structure would look like this after
	       parsing:

		%config	= (
			    Mode => {
				      CLEAR    => 1,
				      UNSECURE => "32bit",
				      STRONG   => undef,
				    }
			  );

	       This method allows the user (or,	the "maintainer" of the
	       configfile for your application)	to set multiple	pre-defined
	       values for one option.

	       Please beware, that all occurrences of those variables will be
	       handled this way, there is no way to distinguish	between
	       variables in different scopes.  That means, if "Mode" would
	       also occur inside a named block,	it would also parsed this way.

	       Values which are	not defined in the hash-ref supplied to	the
	       parameter -FlagBits and used in the corresponding variable in
	       the config will be ignored.

	       Example:

		# rcfile
		Mode = BLAH | CLEAR

	       would result in this hash structure:

		 %config = (
			    Mode => {
				      CLEAR    => 1,
				      UNSECURE => undef,
				      STRONG   => undef,
				    }
			  );

	       "BLAH" will be ignored silently.

	   -DefaultConfig
	       This can	be a hash reference or a simple	scalar (string)	of a
	       config. This causes the module to preset	the resulting config
	       hash with the given values, which allows	you to set default
	       values for particular config options directly.

	       Note that you probably want to use this with
	       -MergeDuplicateOptions, otherwise a default value already in
	       the configuration file will produce an array of two values.

	   -Tie
	       -Tie takes the name of a	Tie class as argument that each	new
	       hash should be based off	of.

	       This hash will be used as the 'backing hash' instead of a
	       standard	Perl hash, which allows	you to affect the way,
	       variable	storing	will be	done. You could, for example supply a
	       tied hash, say Tie::DxHash, which preserves ordering of the
	       keys in the config (which a standard Perl hash won't do). Or,
	       you could supply	a hash tied to a DBM file to save the parsed
	       variables to disk.

	       There are many more things to do	in tie-land, see tie to	get
	       some interesting	ideas.

	       If you want to use the -Tie feature together with
	       -DefaultConfig make sure	that the hash supplied to
	       -DefaultConfig must be tied to the same Tie class.

	       Make sure that the hash which receives the generated hash
	       structure (e.g. which you are using in the assignment: %hash =
	       $config->getall()) must be tied to the same Tie class.

	       Example:

		use Config::General qw(ParseConfig);
		use Tie::IxHash;
		tie my %hash, "Tie::IxHash";
		%hash =	ParseConfig(
			  -ConfigFile => shift(),
			  -Tie => "Tie::IxHash"
			);

	   -InterPolateVars
	       If set to a true	value, variable	interpolation will be done on
	       your config input. See Config::General::Interpolated for	more
	       information.

	   -InterPolateEnv
	       If set to a true	value, environment variables can be used in
	       configs.

	       This implies -InterPolateVars.

	   -AllowSingleQuoteInterpolation
	       By default variables inside single quotes will not be
	       interpolated. If	you turn on this option, they will be
	       interpolated as well.

	   -ExtendedAccess
	       If set to a true	value, you can use object oriented (extended)
	       methods to access the parsed config. See
	       Config::General::Extended for more information.

	   -StrictObjects
	       By default this is turned on, which causes Config::General to
	       croak with an error if you try to access	a non-existent key
	       using the OOP-way (-ExtendedAcess enabled). If you turn
	       -StrictObjects off (by setting to 0 or "no") it will just
	       return an empty object/hash/scalar. This	is valid for OOP-
	       access 8via AUTOLOAD and	for the	methods	obj(), hash() and
	       value().

	   -StrictVars
	       By default this is turned on, which causes Config::General to
	       croak with an error if an undefined variable with
	       InterPolateVars turned on occurs	in a config. Set to false
	       (i.e. 0)	to avoid such error messages.

	   -SplitPolicy
	       You can influence the way how Config::General decides which
	       part of a line in a config file is the key and which one	is the
	       value. By default it tries its best to guess. That means	you
	       can mix equalsign assignments and whitespace assignments.

	       However,	sometime you may wish to make it more strictly for
	       some reason. In this case you can set -SplitPolicy. The
	       possible	values are: 'guess' which is the default, 'whitespace'
	       which causes the	module to split	by whitespace, 'equalsign'
	       which causes it to split	strictly by equal sign,	or 'custom'.
	       In the latter case you must also	set -SplitDelimiter to some
	       regular expression of your choice. For example:

		-SplitDelimiter	=> '\s*:\s*'

	       will cause the module to	split by colon while whitespace	which
	       surrounds the delimiter will be removed.

	       Please note that	the delimiter used when	saving a config
	       (save_file() or save_string()) will be chosen according to the
	       current -SplitPolicy. If	-SplitPolicy is	set to 'guess' or
	       'whitespace', 3 spaces will be used to delimit saved options.
	       If 'custom' is set, then	you need to set	-StoreDelimiter.

	   -SplitDelimiter
	       Set this	to any arbitrary regular expression which will be used
	       for option/value	splitting. -SplitPolicy	must be	set to
	       'custom'	to make	this work.

	   -StoreDelimiter
	       You can use this	parameter to specify a custom delimiter	to use
	       when saving configs to a	file or	string.	You only need to set
	       it if you want to store the config back to disk and if you have
	       -SplitPolicy set	to 'custom'.

	       However,	this parameter takes precedence	over whatever is set
	       for -SplitPolicy.

	       Be very careful with this parameter.

	   -CComments
	       Config::General is able to notice c-style comments (see section
	       COMMENTS).  But for some	reason you might no need this. In this
	       case you	can turn this feature off by setting -CComments	to a
	       false value('no', 0, 'off').

	       By default -CComments is	turned on.

	   -BackslashEscape
	       Deprecated Option.

	   -SlashIsDirectory
	       If you turn on this parameter, a	single slash as	the last
	       character of a named block will be considered as	a directory
	       name.

	       By default this flag is turned off, which makes the module
	       somewhat	incompatible to	Apache configs,	since such a setup
	       will be normally	considered as an explicit empty	block, just as
	       XML defines it.

	       For example, if you have	the following config:

		<Directory />
		  Index	index.awk
		</Directory>

	       you will	get such an error message from the parser:

		EndBlock "</Directory>"	has no StartBlock statement (level: 1, chunk 10)!

	       This is caused by the fact that the config chunk	below will be
	       internally converted to:

		<Directory></Directory>
		  Index	index.awk
		</Directory>

	       Now there is one	'</Directory>' too much. The proper solution
	       is to use quotation to circumvent this error:

		<Directory "/">
		  Index	index.awk
		</Directory>

	       However,	a raw apache config comes without such quotes. In this
	       case you	may consider to	turn on	-SlashIsDirectory.

	       Please note that	this is	a new option (incorporated in version
	       2.30), it may lead to various unexpected	side effects or	other
	       failures.  You've been warned.

	   -UseApacheIfDefine
	       Enables support for Apache <IfDefine> ... </IfDefine>. See
	       -Define.

	   -Define
	       Defines the symbols to be used for conditional configuration
	       files.  Allowed arguments: scalar, scalar ref, array ref	or
	       hash ref.

	       Examples:

		-Define	=> 'TEST'
		-Define	=> \$testOrProduction
		-Define	=> [qw(TEST VERBOSE)]
		-Define	=> {TEST => 1, VERBOSE => 1}

	       Sample configuration:

		 <Logging>
		   <IfDefine TEST>
		      Level Debug
		      include test/*.cfg
		   </IfDef>
		   <IfDefine !TEST>
		     Level Notice
		      include production/*.cfg
		   </IfDefine>
		 </Logging>

	   -ApacheCompatible
	       Over the	past years a lot of options has	been incorporated into
	       Config::General to be able to parse real	Apache configs.

	       The new -ApacheCompatible option	now makes it possible to tweak
	       all options in a	way that Apache	configs	can be parsed.

	       This is called "apache compatibility mode" - if you will	ever
	       have problems with parsing Apache configs without this option
	       being set, you'll get no	help by	me. Thanks :)

	       The following options will be set:

		UseApacheInclude   = 1
		IncludeRelative	   = 1
		IncludeDirectories = 1
		IncludeGlob	   = 1
		SlashIsDirectory   = 1
		SplitPolicy	   = 'whitespace'
		CComments	   = 0
		UseApacheIfDefine  = 1

	       Take a look into	the particular documentation sections what
	       those options are doing.

	       Beside setting some options it also turns off support for
	       explicit	empty blocks.

	   -UTF8
	       If turned on, all files will be opened in utf8 mode. This may
	       not work	properly with older versions of	Perl.

	   -SaveSorted
	       If you want to save configs in a	sorted manner, turn this
	       parameter on. It	is not enabled by default.

	   -NoEscape
	       If you want to use the data ( scalar or final leaf ) without
	       escaping	special	character, turn	this parameter on. It is not
	       enabled by default.

	   -NormalizeBlock
	       Takes a subroutine reference as parameter and gets the current
	       block or	blockname passed as parameter and is expected to
	       return it in some altered way as	a scalar string. The sub will
	       be called before	anything else will be done by the module
	       itself (e.g. interpolation).

	       Example:

		-NormalizeBlock	=> sub { my $x = shift;	$x =~ s/\s*$//;	$x; }

	       This removes trailing whitespaces of block names.

	   -NormalizeOption
	       Same as -NormalizeBlock but applied on options only.

	   -NormalizeValue
	       Same as -NormalizeBlock but applied on values only.

       getall()
	   Returns a hash structure which represents the whole config.

       files()
	   Returns a list of all files read in.

       save_file()
	   Writes the config hash back to the hard disk. This method takes one
	   or two parameters. The first	parameter must be the filename where
	   the config should be	written	to. The	second parameter is optional,
	   it must be a	reference to a hash structure, if you set it. If you
	   do not supply this second parameter then the	internal config	hash,
	   which has already been parsed, will be used.

	   Please note that any	occurrence of comments will be ignored by
	   getall() and	thus be	lost after you call this method.

	   You need also to know that named blocks will	be converted to	nested
	   blocks (which is the	same from the perl point of view). An example:

	    <user hans>
	      id 13
	    </user>

	   will	become the following after saving:

	    <user>
	      <hans>
		 id 13
	      </hans>
	    </user>

	   Example:

	    $conf_obj->save_file("newrcfile", \%config);

	   or, if the config has already been parsed, or if it didn't change:

	    $conf_obj->save_file("newrcfile");

       save_string()
	   This	method is equivalent to	the previous save_file(), but it does
	   not store the generated config to a file. Instead it	returns	it as
	   a string, which you can save	yourself afterwards.

	   It takes one	optional parameter, which must be a reference to a
	   hash	structure.  If you omit	this parameter,	the internal config
	   hash, which has already been	parsed,	will be	used.

	   Example:

	    my $content	= $conf_obj->save_string(\%config);

	   or:

	    my $content	= $conf_obj->save_string();

CONFIG FILE FORMAT
       Lines beginning with # and empty	lines will be ignored. (see section
       COMMENTS!)  Spaces at the beginning and the end of a line will also be
       ignored as well as tabulators.  If you need spaces at the end or	the
       beginning of a value you	can surround it	with double quotes.  An	option
       line starts with	its name followed by a value. An equal sign is
       optional.  Some possible	examples:

	user	max
	user  =	max
	user		max

       If there	are more than one statements with the same name, it will
       create an array instead of a scalar. See	the example below.

       The method getall returns a hash	of all values.

BLOCKS
       You can define a	block of options. A block looks	much like a block in
       the wellknown Apache config format. It starts with <blockname> and ends
       with </blockname>.

       A block start and end cannot be on the same line.

       An example:

	<database>
	 host	= muli
	 user	= moare
	 dbname	= modb
	 dbpass	= D4r_9Iu
	</database>

       Blocks can also be nested. Here is a more complicated example:

	user   = hans
	server = mc200
	db     = maxis
	passwd = D3rf$
	<jonas>
	 user	 = tom
	 db	 = unknown
	 host	 = mila
	 <tablestructure>
	  index	  int(100000)
	  name	  char(100)
	  prename char(100)
	  city	  char(100)
	  status  int(10)
	  allowed moses
	  allowed ingram
	  allowed joice
	 </tablestructure>
	</jonas>

       The hash	which the method getall	returns	look like that:

	 print Data::Dumper(\%hash);
	 $VAR1 = {
		  'passwd' => 'D3rf$',
		  'jonas'  => {
			       'tablestructure'	=> {
						    'prename' => 'char(100)',
						    'index'   => 'int(100000)',
						    'city'    => 'char(100)',
						    'name'    => 'char(100)',
						    'status'  => 'int(10)',
						    'allowed' => [
								  'moses',
								  'ingram',
								  'joice',
								 ]
						   },
			       'host'		=> 'mila',
			       'db'		=> 'unknown',
			       'user'		=> 'tom'
			      },
		  'db'	   => 'maxis',
		  'server' => 'mc200',
		  'user'   => 'hans'
		 };

       If you have turned on -LowerCaseNames (see new()) then blocks as	in the
       following example:

	<Dir>
	 <AttriBUTES>
	  Owner	 root
	 </attributes>
	</dir>

       would produce the following hash	structure:

	 $VAR1 = {
		  'dir'	=> {
			    'attributes' => {
					     'owner'  => "root",
					    }
			   }
		 };

       As you can see, the keys	inside the config hash are normalized.

       Please note, that the above config block	would result in	a valid	hash
       structure, even if -LowerCaseNames is not set!  This is because
       Config::General does not	use the	block names to check if	a block	ends,
       instead it uses an internal state counter, which	indicates a block end.

       If the module cannot find an end-block statement, then this block will
       be ignored.

NAMED BLOCKS
       If you need multiple blocks of the same name, then you have to name
       every block.  This works	much like Apache config. If the	module finds a
       named block, it will create a hashref with the left part	of the named
       block as	the key	containing one or more hashrefs	with the right part of
       the block as key	containing everything inside the block(which may again
       be nested!). As examples	says more than words:

       # given the following sample
	<Directory /usr/frisco>
	 Limit Deny
	 Options ExecCgi Index
	</Directory>
	<Directory /usr/frik>
	 Limit DenyAll
	 Options None
	</Directory>

       # you will get:

	 $VAR1 = {
		  'Directory' => {
				  '/usr/frik' => {
						  'Options' => 'None',
						  'Limit' => 'DenyAll'
						 },
				  '/usr/frisco'	=> {
						    'Options' => 'ExecCgi Index',
						    'Limit' => 'Deny'
						   }
				 }
		 };

       You cannot have more than one named block with the same name because it
       will be stored in a hashref and therefore be overwritten	if a block
       occurs once more.

WHITESPACE IN BLOCKS
       The normal behavior of Config::General is to look for whitespace	in
       block names to decide if	it's a named block or just a simple block.

       Sometimes you may need blocknames which have whitespace in their	names.

       With named blocks this is no problem, as	the module only	looks for the
       first whitespace:

	<person	hugo gera>
	</person>

       would be	parsed to:

	 $VAR1 = {
		  'person' => {
			       'hugo gera' => {
					      },
			      }
		 };

       The problem occurs, if you want to have a simple	block containing
       whitespace:

	<hugo gera>
	</hugo gera>

       This would be parsed as a named block, which is not what	you wanted. In
       this very case you may use quotation marks to indicate that it is not a
       named block:

	<"hugo gera">
	</"hugo	gera">

       The save() method of the	module inserts automatically quotation marks
       in such cases.

EXPLICIT EMPTY BLOCKS
       Beside the notation of blocks mentioned above it	is possible to use
       explicit	empty blocks.

       Normally	you would write	this in	your config to define an empty block:

	<driver	Apache>
	</driver>

       To save writing you can also write:

	<driver	Apache/>

       which is	the very same as above.	This works for normal blocks and for
       named blocks.

IDENTICAL OPTIONS (ARRAYS)
       You may have more than one line of the same option with different
       values.	Example:

	log  log1
	log  log2
	log  log2

       You will	get a scalar if	the option occurred only once or an array if
       it occurred more	than once. If you expect multiple identical options,
       then you	may need to check if an	option occurred	more than once:

	 $allowed = $hash{jonas}->{tablestructure}->{allowed};
	 if (ref($allowed) eq "ARRAY") {
	   @ALLOWED = @{$allowed};
	   else	{
	     @ALLOWED =	($allowed);
	   }
	 }

       The same	applies	to blocks and named blocks too (they are described in
       more detail below). For example,	if you have the	following config:

	<dir blah>
	 user max
	</dir>
	<dir blah>
	 user hannes
	</dir>

       then you	would end up with a data structure like	this:

	 $VAR1 = {
		  'dir'	=> {
			    'blah' => [
				       {
					'user' => 'max'
				       },
				       {
					'user' => 'hannes'
				       }
				      ]
			   }
		 };

       As you can see, the two identical blocks	are stored in a	hash which
       contains	an array(-reference) of	hashes.

       Under some rare conditions you might not	want this behavior with	blocks
       (and named blocks too). If you want to get one single hash with the
       contents	of both	identical blocks, then you need	to turn	the new()
       parameter -MergeDuplicateBlocks on (see above). The parsed structure of
       the example above would then look like this:

	 $VAR1 = {
		  'dir'	=> {
			    'blah' => {
				       'user' => [
						  'max',
						  'hannes'
						 ]
				      }
			   }
		 };

       As you can see, there is	only one hash "dir->{blah}" containing
       multiple	"user" entries.	As you can also	see, turning on
       -MergeDuplicateBlocks does not affect scalar options (i.e. "option =
       value").	In fact	you can	tune merging of	duplicate blocks and options
       independent from	each other.

       If you don't want to allow more than one	identical options, you may
       turn it off by setting the flag AllowMultiOptions in the	new() method
       to "no".	 If turned off,	Config::General	will complain about multiple
       occurring options with identical	names!

   FORCE SINGLE	VALUE ARRAYS
       You may also force a single config line to get parsed into an array by
       turning on the option -ForceArray and by	surrounding the	value of the
       config entry by []. Example:

	hostlist = [ foo.bar ]

       Will be a singlevalue array entry if the	option is turned on. If	you
       want it to remain to be an array	you have to turn on -ForceArray	during
       save too.

LONG LINES
       If you have a config value, which is too	long and would take more than
       one line, you can break it into multiple	lines by using the backslash
       character at the	end of the line. The Config::General module will
       concatenate those lines to one single-value.

       Example:

	command	= cat /var/log/secure/tripwire | \
	mail C<-s> "report from	tripwire" \
	honey@myotherhost.nl

       command will become: "cat /var/log/secure/tripwire | mail "-s" 'report
       from twire' honey@myotherhost.nl"

HERE DOCUMENTS
       You can also define a config value as a so called "here-document". You
       must tell the module an identifier which	indicates the end of a here
       document. An identifier must follow a "<<".

       Example:

	message	<<EOF
	 we want to
	 remove	the
	 homedir of
	 root.
	EOF

       Everything between the two "EOF"	strings	will be	in the option message.

       There is	a special feature which	allows you to use indentation with
       here documents.	You can	have any amount	of whitespace or tabulators in
       front of	the end	identifier. If the module finds	spaces or tabs then it
       will remove exactly those amount	of spaces from every line inside the
       here-document.

       Example:

	message	<<EOF
	   we want to
	   remove the
	   homedir of
	   root.
	   EOF

       After parsing, message will become:

	we want	to
	remove the
	homedir	of
	root.

       because there were the string "	   " in	front of EOF, which were cut
       from every line inside the here-document.

INCLUDES
       You can include an external file	at any position	in your	config file
       using the following statement in	your config file:

	<<include externalconfig.rc>>

       If you turned on	-UseApacheInclude (see new()), then you	can also use
       the following statement to include an external file:

	include	externalconfig.rc

       This file will be inserted at the position where	it was found as	if the
       contents	of this	file were directly at this position.

       You can also recursively	include	files, so an included file may include
       another one and so on.  Beware that you do not recursively load the
       same file, you will end with an error message like "too many open files
       in system!".

       By default included files with a	relative pathname will be opened from
       within the current working directory. Under some	circumstances it maybe
       possible	to open	included files from the	directory, where the
       configfile resides. You need to turn on the option -IncludeRelative
       (see new()) if you want that. An	example:

	my $conf = Config::General(
	 -ConfigFile =>	"/etc/crypt.d/server.cfg"
	 -IncludeRelative => 1
	);

       /etc/crypt.d/server.cfg:

	<<include acl.cfg>>

       In this example Config::General will try	to include acl.cfg from
       /etc/crypt.d:

	/etc/crypt.d/acl.cfg

       The default behavior (if	-IncludeRelative is not	set!) will be to open
       just acl.cfg, wherever it is, i.e. if you did a
       chdir("/usr/local/etc"),	then Config::General will include:

	/usr/local/etc/acl.cfg

       Include statements can be case insensitive (added in version 1.25).

       Include statements will be ignored within C-Comments and	here-
       documents.

       By default, a config file will only be included the first time it is
       referenced.  If you wish	to include a file in multiple places, set
       /-IncludeAgain to true. But be warned: this may lead to infinite	loops,
       so make sure, you're not	including the same file	from within itself!

       Example:

	# main.cfg
	<object	billy>
	 class=Some::Class
	<printers>
	 include printers.cfg
	</printers>
	# ...
	</object>
	 <object bob>
	  class=Another::Class
	 <printers>
	 include printers.cfg
	 </printers>
	 # ...
	</object>

       Now "printers.cfg" will be include in both the "billy" and "bob"
       objects.

       You will	have to	be careful to not recursively include a	file.
       Behaviour in this case is undefined.

COMMENTS
       A comment starts	with the number	sign #,	there can be any number	of
       spaces and/or tab stops in front	of the #.

       A comment can also occur	after a	config statement. Example:

	username = max	# this is the comment

       If you want to comment out a large block	you can	use C-style comments.
       A /* signals the	begin of a comment block and the */ signals the	end of
       the comment block.  Example:

	user  =	max # valid option
	db    =	tothemax
	/*
	user  =	andors
	db    =	toand
	*/

       In this example the second options of user and db will be ignored.
       Please beware of	the fact, if the Module	finds a	/* string which	is the
       start of	a comment block, but no	matching end block, it will ignore the
       whole rest of the config	file!

       NOTE: If	you require the	# character (number sign) to remain in the
       option value, then you can use a	backslash in front of it, to escape
       it. Example:

	bgcolor	= \#ffffcc

       In this example the value of $config{bgcolor} will be "#ffffcc",
       Config::General will not	treat the number sign as the begin of a
       comment because of the leading backslash.

       Inside here-documents escaping of number	signs is NOT required!

PARSER PLUGINS
       You can alter the behavior of the parser	by supplying closures which
       will be called on certain hooks during config file processing and
       parsing.

       The general aproach works like this:

	 sub ck	{
	   my($file, $base) = @_;
	   print "_open() tries	$file ... ";
	   if ($file =~	/blah/)	{
	     print "ignored\n";
	     return (0);
	   } else {
	     print "allowed\n";
	     return (1,	@_);
	   }
	 }

	 my %c = ParseConfig(
			     -IncludeGlob      => 1,
			     -UseApacheInclude => 1,
			     -ConfigFile       => shift,
			     -Plug	       => { pre_open =>	*ck }
			    );

       Output:

	_open()	tries cfg ... allowed
	_open()	tries x/*.conf ... allowed
	_open()	tries x/1.conf ... allowed
	_open()	tries x/2.conf ... allowed
	_open()	tries x/blah.conf ... ignored

       As you can see, we wrote	a little sub which takes a filename and	a base
       directory as parameters.	We tell	Config::General	via the	Plug parameter
       of new()	to call	this sub everytime before it attempts to open a	file.

       General processing continues as usual if	the first value	of the
       returned	array is true. The second value	of that	array depends on the
       kind of hook being called.

       The following hooks are available so far:

       pre_open
	   Takes two parameters: filename and basedirectory.

	   Has to return an array consisting of	3 values:

	    - 1	or 0 (continue processing or not)
	    - filename
	    - base directory

       pre_read
	   Takes two parameters: the filehandle	of the file to be read and an
	   array containing the	raw contents of	said file.

	   This	hook will be applied in	_read(). File contents are already
	   available at	this stage, comments will be removed, here-docs
	   normalized and the like. This hook gets the unaltered, original
	   contents.

	   Has to return an array of 3 values:

	    - 1	or 0 (continue processing or not)
	    - the filehandle
	    - an array of strings

	   You can use this hook to apply your own normalizations or whatever.

	   Be careful when returning the abort value (1st value	of returned
	   array 0), since in this case	nothing	else would be done on the
	   contents. If	it still contains comments or something, they will be
	   parsed as legal config options.

       post_read
	   Takes one parameter:	a reference to an array	containing the
	   prepared config lines (after	being processed	by _read()).

	   This	hook will be applied in	_read()	when everything	else has been
	   done.

	   Has to return an array of 2 values:

	    - 1	or 0 (continue processing or not) [Ignored for post hooks]
	    - a	reference to an	array containing the config lines

       pre_parse_value
	   Takes 2 parameters: an option name and its value.

	   This	hook will be applied in	_parse_value() before any processing.

	   Has to return an array of 3 values:

	    - 1	or 0 (continue processing or not)
	    - option name
	    - value of the option

       post_parse_value
	   Almost identical to pre_parse_value,	but will be applied after
	   _parse_value() is finished and all usual processing and
	   normalization is done.

       Not implemented yet: hooks for variable interpolation and block
       parsing.

OBJECT ORIENTED	INTERFACE
       There is	a way to access	a parsed config	the OO-way.  Use the module
       Config::General::Extended, which	is supplied with the Config::General
       distribution.

VARIABLE INTERPOLATION
       You can use variables inside your config	files if you like. To do that
       you have	to use the module Config::General::Interpolated, which is
       supplied	with the Config::General distribution.

EXPORTED FUNCTIONS
       Config::General exports some functions too, which makes it somewhat
       easier to use it, if you	like this.

       How to import the functions:

	use Config::General qw(ParseConfig SaveConfig SaveConfigString);

       ParseConfig()
	   This	function takes exactly all those parameters, which are allowed
	   to the new()	method of the standard interface.

	   Example:

	    use	Config::General	qw(ParseConfig);
	    my %config = ParseConfig(-ConfigFile => "rcfile", -AutoTrue	=> 1);

       SaveConfig()
	   This	function requires two arguments, a filename and	a reference to
	   a hash structure.

	   Example:

	    use	Config::General	qw(SaveConfig);
	    ..
	    SaveConfig("rcfile", \%some_hash);

       SaveConfigString()
	   This	function requires a reference to a config hash as parameter.
	   It generates	a configuration	based on this hash as the object-
	   interface method save_string() does.

	   Example:

	    use	Config::General	qw(ParseConfig SaveConfigString);
	    my %config = ParseConfig(-ConfigFile => "rcfile");
	    .. # change	%config	something
	    my $content	= SaveConfigString(\%config);

CONFIGURATION AND ENVIRONMENT
       No environment variables	will be	used.

SEE ALSO
       I recommend you to read the following documents,	which are supplied
       with Perl:

	perlreftut		       Perl references short introduction
	perlref			       Perl references,	the rest of the	story
	perldsc			       Perl data structures intro
	perllol			       Perl data structures: arrays of arrays

	Config::General::Extended      Object oriented interface to parsed configs
	Config::General::Interpolated  Allows one to use variables inside config files

LICENSE	AND COPYRIGHT
       Copyright (c) 2000-2016 Thomas Linden

       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

BUGS AND LIMITATIONS
       See rt.cpan.org for current bugs, if any.

INCOMPATIBILITIES
       None known.

DIAGNOSTICS
       To debug	Config::General	use the	Perl debugger, see perldebug.

DEPENDENCIES
       Config::General depends on the modules FileHandle,
       File::Spec::Functions, File::Glob, which	all are	shipped	with Perl.

AUTHOR
       Thomas Linden <tlinden |AT| cpan.org>

VERSION
       2.63

perl v5.24.1			  2016-07-29			    General(3)

NAME | SYNOPSIS | DESCRIPTION | SUBROUTINES/METHODS | CONFIG FILE FORMAT | BLOCKS | NAMED BLOCKS | WHITESPACE IN BLOCKS | EXPLICIT EMPTY BLOCKS | IDENTICAL OPTIONS (ARRAYS) | LONG LINES | HERE DOCUMENTS | INCLUDES | COMMENTS | PARSER PLUGINS | OBJECT ORIENTED INTERFACE | VARIABLE INTERPOLATION | EXPORTED FUNCTIONS | CONFIGURATION AND ENVIRONMENT | SEE ALSO | LICENSE AND COPYRIGHT | BUGS AND LIMITATIONS | INCOMPATIBILITIES | DIAGNOSTICS | DEPENDENCIES | AUTHOR | VERSION

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

home | help