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

FreeBSD Manual Pages

  
 
  

home | help
Config::Model::BackendUseryContributed Perl DocuConfig::Model::Backend::Any(3)

NAME
       Config::Model::Backend::Any - Virtual class for other backends

VERSION
       version 2.140

SYNOPSIS
	package	Config::Model::Backend::Foo ;
	use Mouse ;

	extends	'Config::Model::Backend::Any';

	# mandatory
	sub read {
	   my $self = shift ;
	   my %args = @_ ;

	   # args are:
	   # root	=> './my_test',	 # fake	root directory,	used for tests
	   # config_dir	=> /etc/foo',	 # absolute path
	   # file	=> 'foo.conf',	 # file	name
	   # file_path	=> Path::Tiny object for './my_test/etc/foo/foo.conf'
	   # check	=> yes|no|skip

	   return 0 unless $args{file_path}->exists ; #	or die,	your choice

	   # read the file line	by line
	   # we	assume the file	contain	lines like 'key=value'
	   foreach ($args{file_path}->lines_utf8) {
	       chomp ;	 # remove trailing \n
	       s/#.*// ; # remove any comment
	       next unless /\S/; # skip	blank line

	       # $data is 'foo=bar' which is compatible	with load
	       $self->node->load(steps => $_, check => $args{check} ) ;
	   }
	   return 1 ;
	}

	# mandatory
	sub write {
	   my $self = shift ;
	   my %args = @_ ;

	   # args are:
	   # root	=> './my_test',	 # fake	root directory,	used for tests
	   # config_dir	=> /etc/foo',	 # absolute path
	   # file	=> 'foo.conf',	 # file	name
	   # file_path	=> Path::Tiny object for './my_test/etc/foo/foo.conf'
	   # check	=> yes|no|skip

	   # read the content of the configuration tree
	   my @lines;
	   foreach my $elt ($self->node->children) {
	       # read the value	from element $elt
	       my $v = $self->node->grab_value($elt) ;

	       # write value in	file
	       push @lines,qq!$elt="$v"\n! if defined $v ;
	   }

	   $args{file_path}->spew_utf8(@lines);
	   return 1;
	}

DESCRIPTION
       Some application	have configuration files with a	syntax which is	not
       supported by existing "Config::Model::Backend::*" classes.

       In this case a new backend must be written.
       "Config::Model::Backend::Any" was created to facilitate this task.

       The new backend class must use Mouse and	must extends (inherit)
       "Config::Model::Backend::Any".

How to write your own backend
   Declare the new backend in a	node of	the model
       As explained in "Backend	specification" in Config::Model::BackendMgr,
       the new backend must be declared	as an attribute	of a
       Config::Model::Node specification.

       Let's say your new backend is "Config::Model::Backend::Foo". This new
       backend can be specified	with:

	rw_config  => {
	   backend    => 'Foo' , # can also be 'foo'
	   config_dir => '/etc/cfg_dir'
	   file	      => 'foo.conf', # optional
	}

       (The backend class name is constructed with "ucfirst($backend_name)")

       "rw_config" can also have custom	parameters that	are passed verbatim to
       "Config::Model::Backend::Foo" methods:

	rw_config  => {
	   backend    => 'Foo' , # can also be 'foo'
	   config_dir => '/etc/cfg_dir'
	   file	      => 'foo.conf', # optional
	   my_param   => 'my_value',
	}

       "Config::Model::Backend::Foo" class must	inherit	(extend)
       Config::Model::Backend::Any and is expected to provide the following
       methods:

       read
	   "read" is called with the following parameters:

	    %custom_parameters,	      #	e.g. my_param	=> 'my_value' in the example above
	    object     => $obj,		# Config::Model::Node object
	    root       => $root_dir,  #	fake root directory, used for tests
	    backend    => $backend,   #	backend	name
	    config_dir => $read_dir,  #	path below root
	    file       => 'foo.conf', #	file name
	    file_path  => $full_name, #	Path::Tiny object
	    check      => [yes|no|skip]

	   The IO::File	object is undef	if the file cannot be read.

	   This	method must return 1 if	the read was successful, 0 otherwise.

	   Following the "my_param" example above, %custom_parameters contains
	   " ( 'my_param' , 'my_value' ) ", so "read()"	is called with "root",
	   "config_dir", "file_path" and "my_param   =>	'my_value'".

       write
	   "write" is called with the following	parameters:

	    %$custom_parameters,	 # e.g.	my_param   => 'my_value' in the	example	above
	    object	=> $obj,	 # Config::Model::Node object
	    root	=> $root_dir,	 # fake	root directory,	used for tests
	    auto_create	=> $auto_create, # boolean specified in	backend	declaration
	    auto_delete	=> $auto_delete, # boolean specified in	backend	declaration
	    backend	=> $backend,	 # backend name
	    config_dir	=> $write_dir,	 # override from instance
	    file	=> 'foo.conf',	 # file	name
	    file_path	=> $full_name, # full file name	(root+path+file)
	    write	=> 1,		 # always
	    check	=> [ yes|no|skip] ,
	    backup	=> [ undef || '' || suffix ] # backup strategy required	by user

	   The IO::File	object is undef	if the file cannot be written to.

	   This	method must return 1 if	the write was successful, 0 otherwise

   How to test your new	backend
       Using Config::Model::Tester, you	can test your model with your backend
       following the instructions given	in Config::Model::Tester.

       You can also test your backend with a minimal model (and
       Config::Model::Tester). In this case, you need to specify a small model
       to test in a "*-test-conf.pl" file.  See	the IniFile backend test
       <https://github.com/dod38fr/config-
       model/blob/master/t/model_tests.d/backend-ini-test-conf.pl> for an
       example and its examples	files <https://github.com/dod38fr/config-
       model/tree/master/t/model_tests.d/backend-ini-examples>.

CONSTRUCTOR
   new
       The constructor should be used only by Config::Model::Node.

       Parameter:

       node
	   Calling node	object.	Node ref is weakened,

       name
	   Backend name

       auto_create
	   Boolean. Set	to true	to create the configuration file if this one
	   is missing (default 0)

       auto_delete
	   Boolean. Set	to true	to remove the configuration file if this one
	   no longer contain configuration information.	(default 0)

Methods	to override
   annotation
       Whether the backend supports reading and	writing	annotation (a.k.a
       comments). Default is 0.	Override this method to	return 1 if your
       backend supports	annotations.

   read
       Read the	configuration file. This method	must be	overridden.

   write
       Write the configuration file. This method must be overridden.

Methods
   node
       Return the node (a Config::Model::Node) holding this backend.

   instance
       Return the instance (a Config::Model::Instance) holding this
       configuration.

   show_message
       Parameters: "( string )"

       Show a message to STDOUT	(unless	overridden).  Delegated	to
       "show_message" in Config::Model::Instance.

   read_global_comments
       Parameters:

       o   array ref of	string containing the lines to be parsed

       o   A string to specify how a comment is	started. Each character	is
	   recognized as a comment starter (e.g	'"#;"' allow a comment to
	   begin with '"#"' or '";"')

       Read the	global comments	(i.e. the first	block of comments until	the
       first blank or non comment line)	and store them as root node
       annotation. Note	that the global	comment	must be	separated from the
       first data line by a blank line.

       Example:

	$self->read_global_comments( \@lines, ';');
	$self->read_global_comments( \@lines, '#;');

   associates_comments_with_data
       Parameters:

       o   array ref of	string containing the lines to be parsed

       o   A string to specify how a comment is	started. Each character	is
	   recognized as a comment starter (e.g	'"#;"' allow a comment to
	   begin with '"#"' or '";"')

       This method extracts comments from the passed lines and associate them
       with actual data	found in the file lines. Data is associated with
       comments	preceding or on	the same line as the data. Returns a list of [
       data, comment ].

       Example:

	 my @lines = (
	   '# Foo comments',
	   'foo= 1',
	   'Baz	= 0 # Baz comments'
	 );
	 my @res = $self->associates_comments_with_data( \@lines, '#')
	 # @res	is:
	 # ( [ 'foo= 1', 'Foo comments'	] , [ 'Baz = 0'	, 'Baz comments' ] )

   write_global_comments
       Return a	string containing global comments using	data from
       configuration root annotation.

       Requires	one parameter: comment_char (e.g "#" or	'//' )

       Example:

	 my $str = $self->write_global_comments('#')

   write_data_and_comments
       Returns a string	containing comments (stored in annotation) and
       corresponding data. Comments are	written	before the data. If a data is
       undef, the comment is written on	its own	line.

       Positional parameters are "( comment_char , data1, comment1, data2,
       comment2	...)"

       Example:

	print $self->write_data_and_comments('#', 'foo', 'foo comment',	undef, 'lone comment','bar')
	# returns "# foo comment\nfoo\n#lon

       Use "undef" as comment char if comments are not supported by the	syntax
       of the configuration file. Comments will	then be	dropped.

Replacing a custom backend
       Custom backend are now deprecated and must be replaced with a class
       inheriting this module.

       Please:

       o   Rename your class to	begin with "Config::Model::Backend::"

       o   Add "use Mouse ;" and "extends 'Config::Model::Backend::Any';" in
	   the header of your custom class.

       o   Add "my $self = shift;" as the beginning of "read" and "write"
	   functions...	well...	methods.

       Here's an example of such a change <https://github.com/dod38fr/config-
       model/commit/c3b7007ad386cb2356c5ac1499fe51bdf492b19a>.

AUTHOR
       Dominique Dumont, (ddumont at cpan dot org)

SEE ALSO
       Config::Model, Config::Model::BackendMgr, Config::Model::Node,

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.1			  2021-03-01	Config::Model::Backend::Any(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | How to write your own backend | CONSTRUCTOR | Methods to override | Methods | Replacing a custom backend | 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::Any&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help