--- name: "Config::Model::Instance" section: "3pm" platform: "linux" package: "libconfig-model-perl" version: "2.155-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Config::Model::Instance" --- # Config::Model::Instance(3pm) Instance of configuration tree ## NAME Config::Model::Instance - Instance of configuration tree ## VERSION version 2.155 ## 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\_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 => , index => "` - 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" Force saving configuration file even if no value was modified (default is 0) - "quiet" Do no display the changes brought by the modification steps ### 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. ### has\_changes Returns true if the instance contains unsasved changes. ### 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 `$self`. ### 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\_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"` tries 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-2022 by Dominique Dumont. This is free software, licensed under: ``` The GNU Lesser General Public License, Version 2.1, February 1999 ```