Provided by: libconfig-model-perl_2.152-1_all 
NAME
Config::Model::Instance - Instance of configuration tree
VERSION
version 2.152
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_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"
Force saving configuration file even if no value was modified (default is 0)
"quiet"
Do no display the changes brought by the modification steps
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.
has_changes
Returns true if the instance contains unsasved changes.
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 $self.
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_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" tries 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-2022 by Dominique Dumont.
This is free software, licensed under:
The GNU Lesser General Public License, Version 2.1, February 1999