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

FreeBSD Manual Pages

  
 
  

home | help
Config::Model::BackendUseriContributed Perl Config::Model::Backend::IniFile(3)

NAME
       Config::Model::Backend::IniFile - Read and write	config as a INI	file

VERSION
       version 2.140

SYNOPSIS
	use Config::Model;

	my $model = Config::Model->new;
	$model->create_config_class (
	   name	   => "IniClass",
	   element => [
	       [qw/foo bar/] =>	{
		   type	=> 'list',
		   cargo => {qw/type leaf value_type string/}
	       }
	   ]
	);

	# model	for free INI class name	and constrained	class parameters
	$model->create_config_class(
	   name	=> "MyClass",

	   element => [
	       ini_class => {
		   type	  => 'hash',
		   index_type => 'string',
		   cargo => {
		       type => 'node',
		       config_class_name => 'IniClass'
		   },
	       },
	   ],

	  rw_config  =>	{
	    backend => 'IniFile',
	    config_dir => '/tmp',
	    file  => 'foo.conf',
	    store_class_in_hash	=> 'ini_class',
	    auto_create	=> 1,
	  }
	);

	my $inst = $model->instance(root_class_name => 'MyClass' );
	my $root = $inst->config_root ;

	$root->load('ini_class:ONE foo=FOO1 bar=BAR1 -
		     ini_class:TWO foo=FOO2' );

	$inst->write_back ;

       Now "/tmp/foo.conf" contains:

	## file	written	by Config::Model
	[ONE]
	foo=FOO1

	bar=BAR1

	[TWO]
	foo=FOO2

DESCRIPTION
       This module is used directly by Config::Model to	read or	write the
       content of a configuration tree written with INI	syntax in
       "Config::Model" configuration tree.

       This INI	file can have arbitrary	comment	delimiter. See the example in
       the SYNOPSIS that sets a	semi-column as comment delimiter.  By default
       the comment delimiter is	'#' like in Shell or Perl.

       Note that undefined values are skipped for list element.	I.e. when a
       list element contains "('a',undef,'b')",	the data structure contains
       'a','b'.

Limitations
   Structure
       Structure of the	Config::Model must be very simple. Either:

       o   A single class with hash of leaves elements.

       o   2 levels of classes.	The top	level has nodes	elements. All other
	   classes have	only leaf elements.

Comments in Ini	file
       This backend tries to read and write comments from configuration	file.
       The comments are	stored as annotation within the	configuration tree.
       Comments	extraction is based on best estimation as to which parameter
       the comment may apply. Wrong estimations	are possible.

CONSTRUCTOR
   new
       Parameters: "( node => $node_obj, name => 'inifile' )"

       Inherited from Config::Model::Backend::Any. The constructor is called
       by Config::Model::BackendMgr.

Parameters
       Optional	parameters declared in the model:

       comment_delimiter
	   Change the character	that starts comments in	the INI	file. Default
	   is '"#"'.

	   Some	Ini files allows comments to begin with	several	characters
	   (e.g. "#" or	";"). In this case, set	"comment_delimiter" to the
	   possible characters (e.g ""#;""). The first character is used to
	   write back comments.	(In the	example	above, comment "; blah"	is
	   written back	as "# blah".

       store_class_in_hash
	   See "Arbitrary class	name"

       section_map
	   Is a	kind of	exception of the above rule. See also "Arbitrary class
	   name"

       force_lc_section
	   Boolean. When set, sections names are converted to lowercase.

       force_lc_key
	   Idem	for key	name

       force_lc_value
	   Idem	for all	values.

       split_list_value
	   Some	INI values are in fact a list of items separated by a space or
	   a comma.  This parameter specifies the regex	 to use	to split the
	   value into a	list. This applies only	to "list" elements.

       join_list_value
	   Conversely, the list	element	split with "split_list_value" needs to
	   be written back with	a string to join them. Specify this string
	   (usually ' '	or ', ') with "join_list_value".

       split_check_list_value
	   Some	INI values are in fact a check list of items separated by a
	   space or a comma.  This parameter specifies the regex to use	to
	   split the value read	from the file into a list of items to check.
	   This	applies	only to	"check_list" elements.

       join_check_list_value
	   Conversely, the check_list element split with "split_list_value"
	   needs to be written back with a string to join them.	Specify	this
	   string (usually ' ' or ', ')	with "join_check_list_value".

       write_boolean_as
	   Array ref. Reserved for boolean value. Specify how to write a
	   boolean value.  Default is "[0,1]" which may	not be the most
	   readable. "write_boolean_as"	can be specified as "['false','true']"
	   or "['no','yes']".

       assign_char
	   Character used to assign value in INI file. Default is "=".

       assign_with
	   String used write assignment	in INI file. Default is	"" = "".

Mapping	between	INI structure and model
       INI file	typically have the same	structure with 2 different
       conventions.  The class names can be imposed by the application or may
       be chosen by user.

   Imposed class name
       In this case, the class names must match	what is	expected by the
       application.  The elements of each class	can be different. For
       instance:

	 foo = foo_v
	 [ A ]
	 bar = bar_v
	 [ B ]
	 baz = baz_v

       In this case, class "A" and class "B" do	not use	the same configuration
       class.

       The model has this structure:

	Root class
	|- leaf	element	foo
	|- node	element	A of class_A
	|  \- leaf element bar
	\- node	element	B of class_B
	   \-  leaf element baz

   Arbitrary class name
       In this case, the class names can be chosen by the end user. Each class
       has the same elements. For instance:

	 foo = foo_v
	 [ A ]
	 bar = bar_v1
	 [ B ]
	 bar = bar_v2

       In this case, class "A" and class "B" do	not use	the same configuration
       class.  The model has this structure:

	Root class
	|- leaf	foo
	\- hash	element	my_class_holder
	   |- key A (value is node of class_A)
	   |  \- element-bar
	   \- key B (value is node of class_A)
	      \- element-bar

       In this case, the "my_class_holder" name	is specified in	"rw_config"
       with "store_class_in_hash" parameter:

	   rw_config  => {
	     backend =>	'IniFile',
	     config_dir	=> '/tmp',
	     file  => 'foo.ini',
	     store_class_in_hash => 'my_class_holder',
	   }

       Of course they are exceptions. For instance, in "Multistrap", the
       "[General]" INI class must be mapped to a specific node object. This
       can be specified	with the "section_map" parameter:

	   rw_config  => }
	      backend => 'IniFile',
	      config_dir => '/tmp',
	      file  => 'foo.ini',
	      store_class_in_hash => 'my_class_holder',
	      section_map => {
		  General => 'general_node',
	      }
	   }

       "section_map" can also map an INI class to the root node:

	   rw_config =>	{
	     backend =>	'ini_file',
	     store_class_in_hash => 'sections',
	     section_map => {
		 General => '!'
	     },
	   }

Handle key value files
       This backend is able to handle simple configuration files where the
       values are written as key value pairs like:

	foo = bar

       or

	foo: bar

       The option "assign_char"	is used	to specify which character is used to
       assign a	value in the file (white spaces	are ignored).  "assign_char"
       is ""=""	(the default) in the first example, and	"":"" in the second.

       The "assign_with" is used to control how	the file is written back. E.g:

	foo=bar	  # the	default
	foo= bar  # assign_with	is "= "
	foo = bar # assign_with	is " = "
	foo:bar	  # assign_char	is ':',	assign_with is the default
	foo: bar  # assign_char	is ':',	assign_with is ": "
	foo : bar # assign_char	is ':',	assign_with is " : "

Methods
   read
       Of all parameters passed	to this	read call-back,	only "file_path" is
       used. This parameter must be Path::Tiny object.

       It can also be undef. In	this case, "read" returns 0.

       When a file is read, "read" returns 1.

   write
       Of all parameters passed	to this	write call-back, only "file_path" is
       used. This parameter must be a Path::Tiny object.

       "write" returns 1.

AUTHOR
       Dominique Dumont, (ddumont at cpan dot org); Krzysztof Tyszecki,
       (krzysztof.tyszecki at gmail dot	com)

SEE ALSO
       Config::Model, Config::Model::BackendMgr, Config::Model::Backend::Any,

AUTHOR
       Dominique Dumont

COPYRIGHT AND LICENSE
       This software is	Copyright (c) 2005-2020	by Dominique Dumont.

       This is free software, licensed under:

	 The GNU Lesser	General	Public License,	Version	2.1, February 1999

perl v5.32.0			  2020-08-28Config::Model::Backend::IniFile(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | Limitations | Comments in Ini file | CONSTRUCTOR | Parameters | Mapping between INI structure and model | Handle key value files | Methods | AUTHOR | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

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

home | help