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

Provided by: libconfig-model-perl_2.117-1_all

NAME

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

VERSION

       version 2.117

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

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( 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_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( kind, [data] )
       The data method provide a way to store some arbitrary data in the instance object.

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

   root_dir()
       Returns root directory where configuration data is read from or written to.

   root_path()
       Returns a Path::Tiny object for the root directory where configuration data is read from or written to.

   register_write_back ( 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)

AUTHOR

       Dominique Dumont

COPYRIGHT 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

perl v5.26.1                                       2018-02-19                       Config::Model::Instance(3pm)

NAME

VERSION

SYNOPSIS

DESCRIPTION

CONSTRUCTOR

METHODS

Internal methods

Read and write backend features

AUTHOR

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE