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

FreeBSD Manual Pages

  
 
  

home | help
Config::Model::InstancUser Contributed Perl DocumentConfig::Model::Instance(3)

NAME
       Config::Model::Instance - Instance of configuration tree

VERSION
       version 2.140

SYNOPSIS
	use Config::Model;
	use File::Path ;

	# setup	a dummy	popcon conf file
	my $wr_dir = '/tmp/etc/';
	my $conf_file =	"$wr_dir/popularity-contest.conf" ;

	unless (-d $wr_dir) {
	    mkpath($wr_dir, { mode => 0755 })
	      || die "can't mkpath $wr_dir: $!";
	}
	open(my	$conf,"> $conf_file" ) || die "can't open $conf_file: $!";
	$conf->print( qq!MY_HOSTID="aaaaaaaaaaaaaaaaaaaa"\n!,
	  qq!PARTICIPATE="yes"\n!,
	  qq!USEHTTP="yes" # always http\n!,
	  qq!DAY="6"\n!);
	$conf->close ;

	my $model = Config::Model->new;

	# PopCon model is provided. Create a new Config::Model::Instance object
	my $inst = $model->instance (root_class_name   => 'PopCon',
				     root_dir	       => '/tmp',
				    );
	my $root = $inst -> config_root	;

	print $root->describe;

DESCRIPTION
       This module provides an object that holds a configuration tree.

CONSTRUCTOR
       An instance object is created by	calling	instance method	on an existing
       model. This model can be	specified by its application name:

	my $inst = $model->instance (
	  # run	'cme list' to get list of applications
	  application => 'foo',
	  # optional
	  instance_name	=> 'test1'
	);

	my $inst = $model->instance (
	  root_class_name => 'SomeRootClass',
	  instance_name	=> 'test1'
	);

       The directory (or directories) holding configuration files is specified
       within the configuration	model. For test	purpose	you can	change the
       "root" directory	with "root_dir"	parameter.

       Constructor parameters are:

       root_dir
	   Pseudo root directory where to read and write configuration files
	   (Path::Tiny object or string). Configuration	directory specified in
	   model or with "config_dir" option is	appended to this root
	   directory

       root_path
	   Path::Tiny object created with "root_dir" value or with current
	   directory if	"root_dir" is empty.

       config_dir
	   Directory to	read or	write configuration file. This parameter must
	   be supplied if not provided by the configuration model. (string)

       backend
	   Specify which backend to use. See "write_back" for details

       backend_arg
	   Specify a backend argument that may be retrieved by some backend.
	   Instance is used as a relay and does	not use	this data.

       check
	   Specify whether to check value while	reading	config files. Either:

	   yes Check value and throws an error for bad values.

	   skip
	       Check value and skip bad	value.

	   no  Do not check.

       canonical
	   When	true: write config data	back using model order.	By default,
	   write items back using the order found in the configuration file.
	   This	feature	is experimental	and not	supported by all backends.

       on_change_cb
	   Call	back this function whenever "notify_change" is called. Called
	   with	arguments: "name => <root node element name>, index =>
	   <index_value>"

       on_message_cb
	   Call	back this function when	show_message is	called.	By default,
	   messages are	displayed on STDOUT.

       error_paths
	   Returns a list of tree items	that currently have an error.

       error_messages
	   Returns a list of error messages from the tree content.

       Note that the root directory specified within the configuration model
       is overridden by	"root_dir" parameter.

       If you need to load configuration data that are not correct, you	can
       use "force_load => 1". Then, wrong data are discarded (equivalent to
       "check => 'no'" ).

METHODS
   Manage configuration	data
   modify
       Calls "load" and	then "save".

       Takes the same parameter	as "load" plus "force_write" to	force saving
       configuration file even if no value was modified	(default is 0)

   load
       Load configuration tree with configuration data.	See "load" in
       Config::Model::Loader for parameters.  Returns <$self>.

   save
       Save the	content	of the configuration tree to configuration files. (See
       "write_back" for	more details)

       Use "force => 1"	option to force	saving configuration data.

   config_root
       Returns the root	object of the configuration tree.

   apply_fixes
       Scan the	tree and apply fixes that are attached to warning
       specifications.	See "warn_if_match" or "warn_unless_match" in "" in
       Config::Model::Value.

   deep_check
       Scan the	tree and deep check on all elements that support this.
       Currently only hash or list element have	this feature.

   needs_save
       Returns 1 (or more) if the instance contains data that needs to be
       saved. I.e some change were done	in the tree that needs to be saved.

   list_changes
       In list context,	returns	a array	ref of strings describing the changes.
       In scalar context, returns a big	string.	Useful to print.

   say_changes
       Print all changes on STDOUT and return the list of changes.

   clear_changes
       Clear list of changes. Note that	changes	pending	in the configuration
       tree is not affected. This clears only the list shown to	user. Use only
       for tests.

   has_warning
       Returns the number of warning found in the elements of this
       configuration instance.

   update
       Parameters: "( quiet => (0|1), %args )"

       Try to run update command on all	nodes of the configuration tree. Node
       without "update"	method are ignored. "update" prints a message
       otherwise (unless "quiet" is true).

   grab
       Use the steps parameter to retrieve and returns an object from the
       configuration tree.  Forwarded to "grab"	in Config::Model::Role::Grab

   grab_value
       Use the steps parameter to retrieve and returns the value of a leaf
       object from the configuration tree.  Forwarded to "grab_value" in
       Config::Model::Role::Grab

   searcher
       Returns an object dedicated to search an	element	in the configuration
       model.

       This method returns a Config::Model::Searcher object. See
       Config::Model::Searcher for details on how to handle a search.

   iterator
       This method returns a Config::Model::Iterator object. See
       Config::Model::Iterator for details.

       Arguments are explained in  Config::Model::Iterator constructor
       arguments.

   application
       Returns the application name of the instance. (E.g "popcon", "dpkg"
       ...)

   wizard_helper
       Deprecated. Call	"iterator" instead.

Internal methods
   name
       Returns the instance name.

   read_check
       Returns which kind of check is performed	while reading configuration
       files. (see "check" parameter in	"CONSTRUCTOR" section)

   show_message
       Parameters: "( string )"

       Display the message on STDOUT unless a custom function was passed to
       "on_message_cb" parameter.

   reset_config
       Destroy current configuration tree (with	data) and returns a new	tree
       with data (and annotations) loaded from disk.

   config_model
       Returns the model (Config::Model	object)	of the configuration tree.

   annotation_saver
       Returns the object loading and saving annotations. See
       Config::Model::Annotation for details.

   preset_start
       All values stored in preset mode	are shown to the user as default
       values. This feature is useful to enter configuration data entered by
       an automatic process (like hardware scan)

   preset_stop
       Stop preset mode

   preset
       Get preset mode

   preset_clear
       Clear all preset	values stored.

   layered_start
       All values stored in layered mode are shown to the user as default
       values. This feature is useful to enter configuration data entered by
       an automatic process (like hardware scan)

   layered_stop
       Stop layered mode

   layered
       Get layered mode

   layered_clear
       Clear all layered values	stored.

   get_data_mode
       Returns 'normal'	or 'preset' or 'layered'. Does not take	into account
       initial_load.

   initial_load_start
       Start initial_load mode.	This mode tracks the first modifications of
       the tree	done with data read from the configuration file.

       Instance	is built with initial_load as 1. Read backend clears this
       value once the first read is done.

       Other modifications, when initial_load is zero, are assumed to be user
       modifications.

   initial_load_stop
       Stop initial_load mode. Instance	is built with initial_load as 1. Read
       backend clears this value once the first	read is	done.

   initial_load
       Get initial_load	mode

   data
       This method provides a way to store some	arbitrary data in the instance
       object.

       E.g:

	 $instance->data(foo =>	'bar');

       Later:

	 my $foo = $instance->data('foo'); # $foo contains 'bar'

Read and write backend features
       Usually,	a program based	on config model	must first create the
       configuration model, then load all configuration	data.

       This feature enables you	to declare with	the model a way	to load
       configuration data (and to write	it back). See
       Config::Model::BackendMgr for details.

   backend
       Get the preferred backend method	for this instance (as passed to	the
       constructor).

   backend_arg
       Get cme command line argument that may be used by the backend to	get
       the configuration file. These method is typically used in the read and
       write method of a backend to know where is the configuration file to
       edit.

   root_dir
       Returns a Path::Tiny object for the root	directory where	configuration
       data is read from or written to.

   root_path
       Same as "root_dir"

   register_write_back
       Parameters: "( node_location )"

       Register	a node path that is called back	with "write_back" method.

   notify_change
       Notify that some	data has changed in the	tree. See "notify_change" in
       Config::Model::AnyThing for more	details.

   write_back
       In summary, save	the content of the configuration tree to configuration
       files.

       In more details,	"write_back" trie to run all subroutines registered
       with "register_write_back" to write the configuration information.
       (See Config::Model::BackendMgr for details).

       You can specify here another config directory to	write configuration
       data back with "config_dir" parameter. This overrides the model
       specifications.

       "write_back" croaks if no write call-back are known.

       Use "force => 1"	option to force	saving configuration data. This	is
       useful to write back a file even	no change are done at semantic level,
       i.e. to reformat	a file or remove unnecessary data.

AUTHOR
       Dominique Dumont, (ddumont at cpan dot org)

SEE ALSO
       Config::Model, Config::Model::Node, Config::Model::Loader,
       Config::Model::Searcher,	Config::Model::Value,

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-28	    Config::Model::Instance(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | CONSTRUCTOR | METHODS | Internal methods | Read and write backend features | 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::Instance&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help