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

FreeBSD Manual Pages

  
 
  

home | help
Config::Parser::Ini(3)User Contributed Perl DocumentatioConfig::Parser::Ini(3)

NAME
       Config::Parser::Ini - configuration file	parser for ini-style files

SYNOPSIS
       $cfg = new Config::Parser::Ini($filename);

       $val = $cfg->get('dir', 'tmp');

       print $val->value;

       print $val->locus;

       $val = $cfg->tree->Dir->Tmp;

DESCRIPTION
       An ini-style configuration file is a textual file consisting of
       settings	grouped	into one or more sections.  A setting has the form

	 KEYWORD = VALUE

       where KEYWORD is	the setting name and VALUE is its value.
       Syntactically, VALUE is anything	to the right of	the equals sign	and up
       to the linefeed character terminating the line (ASCII 10), not
       including the leading and trailing whitespace characters.

       Each setting occupies one line.	Very long lines	can be split over
       several physical	lines by ending	each line fragment except the last
       with a backslash	character appearing right before the linefeed
       character.

       A section begins	with a section declaration in the following form:

	 [NAME NAME...]

       Here, square brackets form part of the syntax.  Any number of NAMEs can
       be present inside the square brackets.  The first NAME must follow the
       usual rules for a valid identifier name.	 Rest of NAMEs can contain any
       characters, provided that any NAME that includes	non-alphanumeric
       characters is enclosed in a pair	of double-quotes.  Any double-quotes
       and backslash characters	appearing within the quoted string must	be
       escaped by prefixing them with a	single backslash.

       The Config::Parser::Ini module is a framework for parsing such files.

       In the simplest case, the usage of this module is as simple as in the
       following fragment:

	 use Config::Parser::Ini;
	 my $cf	= new Config::Parser::Ini(filename => "config.ini");

       On success, this	returns	a valid	Config::Parser::Ini object.  On	error,
       the diagnostic message is issued	using the error	method (see the
       description of the method in Config::AST(3)) and	the module croaks.

       This usage, although simple, has	one major drawback - no	checking is
       performed on the	input file, except for the syntax check.  To fix this,
       you can supply a	dictionary (or lexicon)	of allowed keywords along with
       their values.  Such a dictionary	is itself a valid ini file, where the
       value of	each keyword describes its properties.	The dictionary is
       placed in the __DATA__ section of the source file which invokes the
       Config::Parser::Ini constructor.

       Expanding the example above:

	 use Config::Parser::Ini;
	 my $cf	= new Config::Parser::Ini(filename => "config.ini");

	 __DATA__
	 [core]
	    root = STRING :default /
	    umask = OCTAL
	 [user]
	    uid	= NUMBER
	    gid	= NUMBER

       This code specifies that	the configuration file can contain at most two
       sections: "[core]" and "[user]".	Two keywords are defined within	each
       section.	 Data types are	specified for each keyword, so the parser will
       bail out	in case	of type	mismatches. If the core.root setting is	not
       present in the configuration, the default one will be created with the
       value "/".

       It is often advisable to	create a subclass of Config::Parser::Ini and
       use it for parsing.  For	instance:

	 package App::MyConf;
	 use Config::Parser::Ini;
	 1;
	 __DATA__
	 [core]
	    root = STRING :default /
	    umask = OCTAL
	 [user]
	    uid	= NUMBER
	    gid	= NUMBER

       Then, to	parse the configuration	file, it will suffice to do:

	 $cf = my App::MyConf(filename => "config.ini");

       One advantage of	this approach is that it will allow you	to install
       additional validation for the configuration statements using the	:check
       option.	The argument to	this option is the name	of a method which will
       be invoked after	parsing	the statement in order to verify its value.
       It is described in detail below (see the	section	SYNTAX DEFINITION in
       the documentation of Config::Parser).  For example, if you wish to
       ensure that the value of	the "root" setting in "core" section points to
       an existing directory, you would	do:

	 package App::MyConf;
	 use Config::Parser::Ini;

	 sub dir_exists	{
	     my	($self,	$valref, $prev_value, $locus) =	@_;

	     unless (-d	$$valref) {
		 $self->error("$$valref: directory does	not exist",
			      locus => $locus);
		 return	0;
	     }
	     return 1;
	 }
	 1;
	 __DATA__
	 [core]
	    root = STRING :default / :check=dir_exists
	    umask = OCTAL
	 [user]
	    uid	= NUMBER
	    gid	= NUMBER

CONSTRUCTOR
	   $cfg	= new Config::Parser::Ini(%opts)

       Creates a new parser object.  Keyword arguments are:

       filename
	   Name	of the file to parse.  If not supplied,	you will have to call
	   the $cfg->parse method explicitly after you are returned a valid
	   $cfg.

       line
	   Optional line where the configuration starts	in filename.  It is
	   used	to keep	track of statement location in the file	for correct
	   diagnostics.	 If not	supplied, 1 is assumed.

       fh  File	handle to read from.  If it is not supplied, new handle	will
	   be created by using open on the supplied filename.

       lexicon
	   Dictionary of allowed configuration statements in the file.	You
	   will	not need this parameter.  It is	listed here for	completeness
	   sake.  Refer	to the Config::AST constructor for details.

METHODS
       All methods are inherited from Config::Parser.  Please see its
       documentation for details.

SEE ALSO
       Config::Parser(3), Config::AST(3).

perl v5.32.0			  2019-08-29		Config::Parser::Ini(3)

NAME | SYNOPSIS | DESCRIPTION | CONSTRUCTOR | METHODS | SEE ALSO

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

home | help