/ 
Config-Model-2.144
River stage two • 11 direct dependents • 11 total dependents
/ Config::Model::Instance

NAME

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

VERSION

version 2.144

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-2021 by Dominique Dumont.

This is free software, licensed under:

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