Config::Model::Instance(3pm)

User Contributed Perl Documentation

Config::Model::Instance(3pm)

NAME¶

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

VERSION¶

version 2.105

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:

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
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.

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( 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 (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( 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 clears 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.

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 )¶

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 a pseudo root directory or another config directory to write configuration data back with "root" and "config_dir" parameters. This overrides 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" croaks if no write call-back are known.

AUTHOR¶

Dominique Dumont, (ddumont at cpan dot org)

AUTHOR¶

Dominique Dumont

COPYRIGHT AND LICENSE¶

This is free software, licensed under:

  The GNU Lesser General Public License, Version 2.1, February 1999

2017-06-09

perl v5.24.1

Source file:	Config::Model::Instance.3pm.en.gz (from libconfig-model-perl )
Source last updated:	2017-06-09T19:40:40Z
Converted to HTML:	2022-09-07T21:03:58Z

NAME¶

VERSION¶

SYNOPSIS¶

DESCRIPTION¶

CONSTRUCTOR¶

METHODS¶

Manage configuration data¶

modify ( ... )¶

load ( ... )¶

save ( ... )¶

config_root()¶

apply_fixes¶

deep_check¶

needs_save¶

list_changes¶

say_changes¶

clear_changes¶

has_warning¶

update( quiet => (0|1), %args )¶

grab¶

grab_value¶

searcher ( )¶

iterator¶

application¶

wizard_helper ( ... )¶

Internal methods¶

name()¶

read_check()¶

show_message( string )¶

reset_config¶

config_model()¶

annotation_saver()¶

preset_start ()¶

preset_stop ()¶

preset ()¶

preset_clear()¶

layered_start ()¶

layered_stop ()¶

layered ()¶

layered_clear()¶

get_data_mode¶

initial_load_stop ()¶

initial_load ()¶

data( kind, [data] )¶

Auto read and write feature¶

backend()¶

root_dir()¶

register_write_back ( node_location )¶

notify_change¶

write_back ( ... )¶

AUTHOR¶

SEE ALSO¶

AUTHOR¶

COPYRIGHT AND LICENSE¶