Provided by: libconfig-model-perl_2.082-1_all 
NAME
Config::Model::Instance - Instance of configuration tree
VERSION
version 2.082
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:
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:
root_dir
Pseudo root directory where to read and write configuration files. Configuration
directory specified in model or with "config_dir" option is appended to this root
directory
config_dir
Directory to read or write configuration file. This parameter must be supplied if not
provided by the configuration model.
backend
Specify which backend to use. See "write_back ( ... )" for details
skip_read
When set, configuration files will not be read when creating configuration tree.
check
'yes', 'skip' or 'no'
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 will be
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 will be 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 will be discarded (equivalent to "check =" 'no'> ).
METHODS
name()
Returns the instance name.
config_root()
Returns the root object of the configuration tree.
read_check()
Returns how to check read files.
show_message( 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_stop ()
Stop initial_load mode. Instance is built with initial_load as 1. Read backend will clear
this value once the first read is done.
initial_load ()
Get initial_load mode
data( kind, [data] )
The data method provide a way to store some arbitrary data in the instance object.
load( "..." )
Load configuration tree with configuration data. See Config::Model::Loader for more
details
searcher ( )
Returns an object dedicated to search an element in the configuration model (respecting
privilege level).
This method returns a Config::Model::Searcher object. See Config::Model::Searcher for
details on how to handle a search.
wizard_helper ( ... )
Deprecated. Call "iterator" instead.
iterator
This method returns a Config::Model::Iterator object. See Config::Model::Iterator for
details.
Arguments are explained in Config::Model::Iterator constructor arguments.
Auto read and write feature
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).
root_dir()
Returns root directory where configuration data is read from or written to.
register_write_back ( node_location )
Register a node path that will be 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 ( ... )
Try to run all subroutines registered with "register_write_back" to write the
configuration information until one succeeds (returns true). (See
Config::Model::BackendMgr for details).
You can specify here a pseudo root directory or another config directory to write
configuration data back with "root" and "config_dir" parameters. This will override the
model specifications.
You can force to use a backend by specifying "backend => xxx". For instance, "backend =>
'augeas'" or "backend => 'custom'".
You can force to use all backend to write the files by specifying "backend => 'all'".
"write_back" will croak if no write call-back are known.
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.
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.
has_warning
Returns the number of warning found in the elements of this configuration instance.
update( quiet => (0|1), %args )
Try to run update command on all nodes of the configuration tree. Node without "update"
method are ignored. "update" will "say" a message otherwise (unless "quiet" is true).
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-2016 by Dominique Dumont.
This is free software, licensed under:
The GNU Lesser General Public License, Version 2.1, February 1999