Config::Model::Instance(3pm) | User Contributed Perl Documentation | Config::Model::Instance(3pm) |
NAME¶
Config::Model::Instance - Instance of configuration treeVERSION¶
version 2.133SYNOPSIS¶
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. (alias to "write_back")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::Grabgrab_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::Grabsearcher¶
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.
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 modepreset¶
Get preset modepreset_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 modelayered¶
Get layered modelayered_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 modedata¶
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.
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 DumontCOPYRIGHT AND LICENSE¶
This software is Copyright (c) 2005-2018 by Dominique Dumont.This is free software, licensed under:
The GNU Lesser General Public License, Version 2.1, February 1999
2019-01-15 | perl v5.28.1 |