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

NAME

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

VERSION

version 2.012

SYNOPSIS

use Config::Model;
use Log::Log4perl qw(:easy);
use File::Path ;
Log::Log4perl->easy_init($WARN);

# 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

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>

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.

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::AutoRead for details.

read_root_dir()

Returns root directory where configuration data is read from.

backend()

Get the preferred backend method for this instance (as passed to the constructor).

write_root_dir()

Returns root directory where configuration data is 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.

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

AUTHOR

Dominique Dumont, (ddumont at cpan dot org)

SEE ALSO

Config::Model, Config::Model::Node, Config::Model::Loader, Config::Model::Searcher, Config::Model::Value,