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

FreeBSD Manual Pages

  
 
  

home | help
Config::Std(3)	      User Contributed Perl Documentation	Config::Std(3)

NAME
       Config::Std - Load and save configuration files in a standard format

VERSION
       This document describes Config::Std version 0.903

SYNOPSIS
	   use Config::Std;

	   # Load named	config file into specified hash...
	   read_config 'demo2.cfg' => my %config;

	   # Extract the value of a key/value pair from	a specified section...
	   $config_value = $config{Section_label}{key};

	   # Change (or	create)	the value of a key/value pair...
	   $config{Other_section_label}{other_key} = $new_val;

	   # Update the	config file from which this hash was loaded...
	   write_config	%config;

	   # Write the config information to another file as well...
	   write_config	%config, $other_file_name;

DESCRIPTION
       This module implements yet another damn configuration-file system.

       The configuration language is deliberately simple and limited, and the
       module works hard to preserve as	much information (section order,
       comments, etc.) as possible when	a configuration	file is	updated.

       The whole point of Config::Std is to encourage use of one standard
       layout and syntax in config files. Damian says "I could have gotten
       away with it, I would have only allowed one separator. But it proved
       impossible to choose between ":"	and "="	(half the people I asked
       wanted one, half	wanted the other)."  Providing round-trip file re-
       write is	the spoonful of	sugar to help the medicine go down.  The
       supported syntax	is within the general INI file family

       See Chapter 19 of "Perl Best Practices" (O'Reilly, 2005)	for more
       detail on the rationale for this	approach.

   Configuration language
       The configuration language is a slight extension	of the Windows INI
       format.

       Comments

       A comment starts	with a "#" character (Perl-style) or a ";" character
       (INI-style), and	runs to	the end	of the same line:

	   # This is a comment

	   ; Ywis, eke hight thilke

       Comments	can be placed almost anywhere in a configuration file, except
       inside a	section	label, or in the key or	value of a configuration
       variable:

	   # Valid comment
	   [ # Not a comment, just a weird section label ]

	   ; Valid comment
	   key:	value  ; Not a comment,	just part of the value

       NOTE BENE -- that last is a BAD EXAMPLE of what is NOT supported.  This
       module supports full-line comments only,	not on same line with semantic
       content.

       Sections

       A configuration file consists of	one or more sections, each of which is
       introduced by a label in	square brackets:

	   [SECTION1]	     # Almost anything is a valid section label

	   [SECTION 2]	     # Internal	whitespace is allowed (except newlines)

	   [%^$%^&!!!]	     # The label doesn't have to be alphanumeric

	   [ETC. ETC. AS MANY AS YOU WANT]

       The only	restriction on section labels is that they must	be by
       themselves on a single line (except for any surrounding whitespace or
       trailing	comments), and they cannot contain the character "]".

       Every line after	a given	section	label until the	next section label (or
       the end of the config file) belongs to the given	section	label. If no
       section label is	currently in effect, the current section has an	empty
       label. In other words, there is an implicit:

	   []		     # Label is	the empty string

       at the start of each config file.

       Configuration variables

       Each non-empty line within a section must consist of the	specification
       of a configuration variable. Each such variable consists	of a key and a
       string value. For example:

	   name: George
	    age: 47

	   his weight! : 185

       The key consists	of every character (including internal whitespace)
       from the	start of the line until	the key/value separator. So, the
       previous	example	declares three keys: 'name', 'age', and	'his weight!'.

       Note that whitespace before and after the key is	removed. This makes it
       easier to format	keys cleanly:

		  name : George
		   age : 47
	   his weight! : 185

       The key/value separator can be either a colon (as above)	or an equals
       sign, like so:

		  name=	George
		   age=	 47
	   his weight! = 185

       Both types of separators	can be used in the same	file, but neither can
       be used as part of a key. Newlines are not allowed in keys either.

       When writing out	a config file, Config::Std tries to preserve whichever
       separator was used in the original data (if that	data was read in). New
       data (created by	code not parsed	by "read_config") is written back with
       a colon as its default separator, unless	you specify the	only other
       separator value '=' when	the module is loaded:

	   use Config::Std { def_sep =>	'=' };

       Note that this does not change read-in parsing, does not	change
       punctuation for values that were	parsed,	and will not allow values
       other than '=' or ':'.

       Everything from the first non-whitespace	character after	the separator,
       up to the end of	the line, is treated as	the value for the config
       variable.  So all of the	above examples define the same three values:
       'George', '47', and '185'.

       In other	words, any whitespace immediately surrounding the separator
       character is part of the	separator, not part of the key or value.

       Note that you can't put a comment on the	same line as a configuration
       variable. The "#	etc." is simply	considered part	of the value:

	   [Delimiters]

	   block delims:    { }
	   string delims:   " "
	   comment delims:  # \n

       You can comment a config	var on the preceding or	succeeding line:

	   [Delimiters]

	   # Use braces	to delimit blocks...
	   block delims:    { }

	   # Use double	quotes to delimit strings

	   string delims:   " "

	   # Use octothorpe/newline to delimit comments
	   comment delims:  # \n

       Multi-line configuration	values

       A single	value can be continued over two	or more	lines. If the line
       immediately after a configuration variable starts with the separator
       character used in the variable's	definition, then the value of the
       variable	continues on that line.	For example:

	   address: 742	Evergreen Terrace
		  : Springfield
		  : USA

       The newlines then form part of the value, so the	value specified	in the
       previous	example	is: "742A EvergreenA Terrace\nSpringfield\nUSA"

       Note that the second and	subsequent lines of a continued	value are
       considered to start where the whitespace	after the original separator
       finished, not where the whitespace after	their own separator finishes.
       For example, if the previous example had	been:

	   address: 742	Evergreen Terrace
		  :   Springfield
		  :	USA

       then the	value would be:

	   "742	Evergreen Terrace\n  Springfield\n    USA"

       If a continuation line has less leading whitespace that the first line:

	   address:   742 Evergreen Terrace
		  :  Springfield
		  : USA

       it's treated as having no leading whitespace:

	   "742	Evergreen Terrace\nSpringfield\nUSA"

       Multi-part configuration	values

       If the particular key appears more than once in the same	section, it is
       considered to be	part of	the same configuration variable. The value of
       that configuration value	is then	a list,	containing all the individual
       values for each instance	of the key. For	example, given the definition:

	   cast: Homer
	   cast: Marge
	   cast: Lisa
	   cast: Bart
	   cast: Maggie

       the corresponding value of the 'cast' configuration variable is:
       "['Homer',A 'Marge',A 'Lisa',A 'Bart',A 'Maggie']"

       Individual values in a multi-part list can also be multi-line (see
       above). For example, given:

	   extras: Moe
		 : (the	bartender)

	   extras: Smithers
		 : (the	dogsbody)

       the value for the 'extras' config variable is:
       "["Moe\n(theA bartender)",A "Smithers\n(theA dogsbody)"]"

   Internal representation
       Each section label in a configuration file becomes a top-level hash key
       whe the configuration file is read in. The corresponding	value is a
       nested hash reference.

       Each configuration variable's key becomes a key in that nested hash
       reference.  Each	configuration variable's value becomes the
       corresponding value in that nested hash reference.

       Single-line and multi-line values become	strings. Multi-part values
       become references to arrays of strings.

       For example, the	following configuration	file:

	   # A simple key (just	an identifier)...
	   simple : simple value

	   # A more complex key	(with whitespace)...
	   more	complex	key : more complex value

	   # A new section...
	   [MULTI-WHATEVERS]

	   # A value spread over several lines...
	   multi-line :	this is	line 1
		      :	this is	line 2
		      :	this is	line 3

	   # Several values for	the same key...
	   multi-value:	this is	value 1
	   multi-value:	this is	value 2
	   multi-value:	this is	value 3

       would be	read into a hash whose internal	structure looked like this:

	   {
	      #	Default	section...
	      '' => {
		 'simple'	    => 'simple value',
		 'more complex key' => 'more complex value',
	      },

	      #	Named section...
	      'MULTI-WHATEVERS'	=> {
		   'multi-line'	 => "this is line 1\nthis is line 2\nthis is line 3",

		   'multi-value' => [ 'this is value 1',
				      'this is value 2',
				      'this is value 3'
				    ],
	       }
	   }

INTERFACE
       The following subroutines are exported automatically whenever the
       module is loaded...

       "read_config($filename => %config_hash)"
       "read_config($filename => $config_hash_ref)"
       "read_config($string_ref	=> %config_hash_or_ref)"
	   The "read_config()" subroutine takes	two arguments: the filename of
	   a configuration file, and a variable	into which the contents	of
	   that	configuration file are to be loaded.

	   If the variable is a	hash, then the configuration sections and
	   their key/value pairs are loaded into nested	subhashes of the hash.

	   If the variable is a	scalar with an undefined value,	a reference to
	   an anonymous	hash is	first assigned to that scalar, and that	hash
	   is then filled as described above.

	   The subroutine returns true on success, and throws an exception on
	   failure.

	   If you pass a reference to the string as the	first argument to
	   "read_config()" it uses that	string as the source of	the config
	   info.  For example:

		   use Config::Std;

		   # here we load the config text to a scalar
		   my $cfg = q{
		   [Section 1]
		   attr1 = at
		   attr2 = bat

		   [Section 2]
		   attr3 = cat
		   };

		   # here we parse the config from that	scalar by passing a reference to it.
		   read_config(	\$cfg, my %config );

		   use Data::Dumper 'Dumper';
		   warn	Dumper [ \%config ];

       "write_config(%config_hash => $filename)"
       "write_config($config_hash_ref => $filename)"
       "write_config(%config_hash)"
       "write_config($config_hash_ref)"
	   The "write_config()"	subroutine takes two arguments:	the hash or
	   hash	reference containing the configuration data to be written out
	   to disk, and	an optional filename specifying	which file it is to be
	   written to.

	   The data hash must conform to the two-level structure described
	   earlier: with top-level keys	naming sections	and their values being
	   references to second-level hashes that store	the keys and values of
	   the configuartion variables.	If the structure of the	hash differs
	   from	this, an exception is thrown.

	   If a	filename is also specified, the	subroutine opens that file and
	   writes to it. It no filename	is specified, the subroutine uses the
	   name	of the file from which the hash	was originally loaded using
	   "read_config()". It no filename is specified	and the	hash wasn't
	   originally loaded using "read_config()", an exception is thrown.

	   The subroutine returns true on success and throws and exception on
	   failure.

       If necessary (typically to avoid	conflicts with other modules), you can
       have the	module export its two subroutines with different names by
       loading it with the appropriate options:

	   use Config::Std { read_config => 'get_ini', write_config => 'update_ini' };

	   # and later...

	   get_ini($filename =>	%config_hash);

	   # and later still...

	   update_ini(%config_hash);

       You can also control how	much spacing the module	puts between single-
       line values when	they are first written to a file, by using the
       "def_gap" option:

	   # No	empty line between single-line config values...
	   use Config::Std { def_gap =>	0 };

	   # An	empty line between all single-line config values...
	   use Config::Std { def_gap =>	1 };

       Regardless of the value passed for "def_gap", new multi-line values are
       always written with an empty line above and below them. Likewise,
       values that were	previously read	in from	a file are always written back
       with whatever spacing they originally had.

DIAGNOSTICS
       Can't open config file '%s' (%s)
	   You tried to	read in	a configuration	file, but the file you
	   specified didn't exist. Perhaps the filepath	you specified was
	   wrong. Or maybe your	application didn't have	permission to access
	   the file you	specified.

       Can't read from locked config file '$filename'
	   You tried to	read in	a configuration	file, but the file you
	   specified was being written by someone else (they had a file	lock
	   active on it).  Either try again later, or work out who else	is
	   using the file.

       Scalar second argument to 'read_config' must be empty
	   You passed a	scalar variable	as the destination into
	   "read_config()" was supposed	to load	a configuration	file, but that
	   variable already had	a defined value, so "read_config()" couldn't
	   autovivify a	new hash for you. Did you mean to pass the subroutine
	   a hash instead of a scalar?

       Can't save %s value for key '%s'	(only scalars or array refs)
	   You called "write_config" and passed	it a hash containing a
	   configuration variable whose	value wasn't a single string, or a
	   list	of strings. The	configuration file format supported by this
	   module only supports	those two data types as	values.	If you really
	   need	to store other kinds of	data in	a configuration	file, you
	   should consider using "Data::Dumper"	or "YAML" instead.

       Missing filename	in call	to write_config()
	   You tried to	calll "write_config()" with only a configuration hash,
	   but that hash wasn't	originally loaded using	"read_config()", so
	   "write_config()" has	no idea	where to write it to. Either make sure
	   the hash you're trying to save was originally loaded	using
	   "read_config()", or else provide an explicit	filename as the	second
	   argument to "write_config()".

       Can't open config file '%s' for writing (%s)
	   You tried to	update or create a configuration file, but the file
	   you specified could not be opened for writing (for the reason given
	   in the parentheses).	This is	often caused by	incorrect filepaths or
	   lack	of write permissions on	a directory.

       Can't write to locked config file '%s'
	   You tried to	update or create a configuration file, but the file
	   you specified was being written at the time by someone else (they
	   had a file lock active on it). Either try again later, or work out
	   who else is using the file.

CONFIGURATION AND ENVIRONMENT
       Config::Std requires no configuration files or environment variables.
       (To do so would be disturbingly recursive.)

DEPENDENCIES
       This module requires the	Class::Std module (available from the CPAN)

INCOMPATIBILITIES
       Those variants of INI file dialect supporting partial-line comment are
       incompatible.  (This is the price of keeping comments when re-writing.)

BUGS AND LIMITATIONS
       Memory leak re-reading
	   A daemon re-reading its config file has reported a memory leak.

       Parallel	testing	not safe
	   This	is a config file module. Tests written before "TAP" got
	   parallel testing are	unsafe with parallel testing, surprise!
	   Settings are	now included to	force serial testing (until we
	   refactor all	tests to use temp dirs?).

	   If using an older Perl < 5.21.1, and	Module.PL, and getting out-of-
	   sequence test failures installing this module, either update
	   Test::Harness~'>= 3.31' or export HARNESS_OPTIONS=j1	(or
	   force/no-test, or use Build.PL and/or perl-5.22.0 or	newer
	   instead).

       Loading on demand
	   If you attempt to load "read_config()" and "write_config()" at
	   runtime with	"require", you can not rely upon the prototype to
	   convert a regular hash to a reference. To work around this, you
	   must	explicitly pass	a reference to the config hash.

	       require Config::Std;
	       Config::Std->import;

	       my %config;
	       read_config($file, \%config);
	       write_config(\%config, $file);

       Windows line endings on Unix/Linux (RT#21547/23550)
	   If the config file being read contains carriage returns and line
	   feeds at the	end of each line rather	than just line feeds (i.e. the
	   standard Windows file format, when read on a	machine	expecting
	   POSIX file format), Config::Std emits an error with embedded
	   newline.

	   Workaround is match file line-endings to locale.

	   This	will be	fixed in 1.000.

       leading comment vanishes	(RT#24597,)
	   A comment before the	first section is not always retained on	write-
	   back, if the	'' default section is empty.

       Please report any bugs or feature requests to
       "bug-config-std@rt.cpan.org", or	through	the web	interface at
       <http://rt.cpan.org>.

AUTHOR
       Damian Conway  "<DCONWAY@cpan.org>" Maintainers Bill Ricker
       "<BRICKER@cpan.org>" Tom	Metro	   "<tmetro@cpan.org>"

LICENCE	AND COPYRIGHT
       Copyright (c) 2005, Damian Conway "<DCONWAY@cpan.org>".	Copyright (c)
       2011,2014,2017, D.Conway, W.Ricker "<BRICKER@cpan.org>" All rights
       reserved.

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

DISCLAIMER OF WARRANTY
       BECAUSE THIS SOFTWARE IS	LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
       FOR THE SOFTWARE, TO THE	EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
       WHEN OTHERWISE STATED IN	WRITING	THE COPYRIGHT HOLDERS AND/OR OTHER
       PARTIES PROVIDE THE SOFTWARE "AS	IS" WITHOUT WARRANTY OF	ANY KIND,
       EITHER EXPRESSED	OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
       ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF	THE SOFTWARE IS	WITH
       YOU. SHOULD THE SOFTWARE	PROVE DEFECTIVE, YOU ASSUME THE	COST OF	ALL
       NECESSARY SERVICING, REPAIR, OR CORRECTION.

       IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR	AGREED TO IN WRITING
       WILL ANY	COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
       REDISTRIBUTE THE	SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
       TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
       CONSEQUENTIAL DAMAGES ARISING OUT OF THE	USE OR INABILITY TO USE	THE
       SOFTWARE	(INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
       RENDERED	INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
       FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
       SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
       DAMAGES.

perl v5.32.0			  2017-10-07			Config::Std(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | INTERFACE | DIAGNOSTICS | CONFIGURATION AND ENVIRONMENT | DEPENDENCIES | INCOMPATIBILITIES | BUGS AND LIMITATIONS | AUTHOR | LICENCE AND COPYRIGHT | DISCLAIMER OF WARRANTY

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

home | help