1Config::Model::InstanceU(s3e)r Contributed Perl DocumentaCtoinofnig::Model::Instance(3)
2
3
4

NAME

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

VERSION

9       version 2.150
10

SYNOPSIS

12        use Config::Model;
13        use File::Path ;
14
15        # setup a dummy popcon conf file
16        my $wr_dir = '/tmp/etc/';
17        my $conf_file = "$wr_dir/popularity-contest.conf" ;
18
19        unless (-d $wr_dir) {
20            mkpath($wr_dir, { mode => 0755 })
21              || die "can't mkpath $wr_dir: $!";
22        }
23        open(my $conf,"> $conf_file" ) || die "can't open $conf_file: $!";
24        $conf->print( qq!MY_HOSTID="aaaaaaaaaaaaaaaaaaaa"\n!,
25          qq!PARTICIPATE="yes"\n!,
26          qq!USEHTTP="yes" # always http\n!,
27          qq!DAY="6"\n!);
28        $conf->close ;
29
30        my $model = Config::Model->new;
31
32        # PopCon model is provided. Create a new Config::Model::Instance object
33        my $inst = $model->instance (root_class_name   => 'PopCon',
34                                     root_dir          => '/tmp',
35                                    );
36        my $root = $inst -> config_root ;
37
38        print $root->describe;
39

DESCRIPTION

41       This module provides an object that holds a configuration tree.
42

CONSTRUCTOR

44       An instance object is created by calling instance method on an existing
45       model. This model can be specified by its application name:
46
47        my $inst = $model->instance (
48          # run 'cme list' to get list of applications
49          application => 'foo',
50          # optional
51          instance_name => 'test1'
52        );
53
54        my $inst = $model->instance (
55          root_class_name => 'SomeRootClass',
56          instance_name => 'test1'
57        );
58
59       The directory (or directories) holding configuration files is specified
60       within the configuration model. For test purpose you can change the
61       "root" directory with "root_dir" parameter.
62
63       Constructor parameters are:
64
65       root_dir
66           Pseudo root directory where to read and write configuration files
67           (Path::Tiny object or string). Configuration directory specified in
68           model or with "config_dir" option is appended to this root
69           directory
70
71       root_path
72           Path::Tiny object created with "root_dir" value or with current
73           directory if "root_dir" is empty.
74
75       config_dir
76           Directory to read or write configuration file. This parameter must
77           be supplied if not provided by the configuration model. (string)
78
79       backend
80           Specify which backend to use. See "write_back" for details
81
82       backend_arg
83           Specify a backend argument that may be retrieved by some backend.
84           Instance is used as a relay and does not use this data.
85
86       check
87           Specify whether to check value while reading config files. Either:
88
89           yes Check value and throws an error for bad values.
90
91           skip
92               Check value and skip bad value.
93
94           no  Do not check.
95
96       canonical
97           When true: write config data back using model order. By default,
98           write items back using the order found in the configuration file.
99           This feature is experimental and not supported by all backends.
100
101       on_change_cb
102           Call back this function whenever "notify_change" is called. Called
103           with arguments: "name => <root node element name>, index =>
104           <index_value>"
105
106       on_message_cb
107           Call back this function when show_message is called. By default,
108           messages are displayed on STDOUT.
109
110       error_paths
111           Returns a list of tree items that currently have an error.
112
113       error_messages
114           Returns a list of error messages from the tree content.
115
116       Note that the root directory specified within the configuration model
117       is overridden by "root_dir" parameter.
118
119       If you need to load configuration data that are not correct, you can
120       use "force_load => 1". Then, wrong data are discarded (equivalent to
121       "check => 'no'" ).
122

METHODS

124   Manage configuration data
125   modify
126       Calls "load" and then "save".
127
128       Takes the same parameter as "load" plus:
129
130       "force_write"
131           Force saving configuration file even if no value was modified
132           (default is 0)
133
134       "quiet"
135           Do no display the changes brought by the modification steps
136
137   load
138       Load configuration tree with configuration data. See "load" in
139       Config::Model::Loader for parameters.  Returns <$self>.
140
141   save
142       Save the content of the configuration tree to configuration files. (See
143       "write_back" for more details)
144
145       Use "force => 1" option to force saving configuration data.
146
147   config_root
148       Returns the root object of the configuration tree.
149
150   apply_fixes
151       Scan the tree and apply fixes that are attached to warning
152       specifications.  See "warn_if_match" or "warn_unless_match" in "" in
153       Config::Model::Value.
154
155   deep_check
156       Scan the tree and deep check on all elements that support this.
157       Currently only hash or list element have this feature.
158
159   needs_save
160       Returns 1 (or more) if the instance contains data that needs to be
161       saved. I.e some change were done in the tree that needs to be saved.
162
163   has_changes
164       Returns true if the instance contains unsasved changes.
165
166   list_changes
167       In list context, returns a array ref of strings describing the changes.
168       In scalar context, returns a big string. Useful to print.
169
170   say_changes
171       Print all changes on STDOUT and return $self.
172
173   clear_changes
174       Clear list of changes. Note that changes pending in the configuration
175       tree is not affected. This clears only the list shown to user. Use only
176       for tests.
177
178   has_warning
179       Returns the number of warning found in the elements of this
180       configuration instance.
181
182   update
183       Parameters: "( quiet => (0|1), %args )"
184
185       Try to run update command on all nodes of the configuration tree. Node
186       without "update" method are ignored. "update" prints a message
187       otherwise (unless "quiet" is true).
188
189   grab
190       Use the steps parameter to retrieve and returns an object from the
191       configuration tree.  Forwarded to "grab" in Config::Model::Role::Grab
192
193   grab_value
194       Use the steps parameter to retrieve and returns the value of a leaf
195       object from the configuration tree.  Forwarded to "grab_value" in
196       Config::Model::Role::Grab
197
198   searcher
199       Returns an object dedicated to search an element in the configuration
200       model.
201
202       This method returns a Config::Model::Searcher object. See
203       Config::Model::Searcher for details on how to handle a search.
204
205   iterator
206       This method returns a Config::Model::Iterator object. See
207       Config::Model::Iterator for details.
208
209       Arguments are explained in  Config::Model::Iterator constructor
210       arguments.
211
212   application
213       Returns the application name of the instance. (E.g "popcon", "dpkg"
214       ...)
215
216   wizard_helper
217       Deprecated. Call "iterator" instead.
218

Internal methods

220   name
221       Returns the instance name.
222
223   read_check
224       Returns which kind of check is performed while reading configuration
225       files. (see "check" parameter in "CONSTRUCTOR" section)
226
227   show_message
228       Parameters: "( string )"
229
230       Display the message on STDOUT unless a custom function was passed to
231       "on_message_cb" parameter.
232
233   reset_config
234       Destroy current configuration tree (with data) and returns a new tree
235       with data (and annotations) loaded from disk.
236
237   config_model
238       Returns the model (Config::Model object) of the configuration tree.
239
240   annotation_saver
241       Returns the object loading and saving annotations. See
242       Config::Model::Annotation for details.
243
244   preset_start
245       All values stored in preset mode are shown to the user as default
246       values. This feature is useful to enter configuration data entered by
247       an automatic process (like hardware scan)
248
249   preset_stop
250       Stop preset mode
251
252   preset
253       Get preset mode
254
255   preset_clear
256       Clear all preset values stored.
257
258   layered_start
259       All values stored in layered mode are shown to the user as default
260       values. This feature is useful to enter configuration data entered by
261       an automatic process (like hardware scan)
262
263   layered_stop
264       Stop layered mode
265
266   layered
267       Get layered mode
268
269   layered_clear
270       Clear all layered values stored.
271
272   get_data_mode
273       Returns 'normal' or 'preset' or 'layered'. Does not take into account
274       initial_load.
275
276   initial_load_start
277       Start initial_load mode. This mode tracks the first modifications of
278       the tree done with data read from the configuration file.
279
280       Instance is built with initial_load as 1. Read backend clears this
281       value once the first read is done.
282
283       Other modifications, when initial_load is zero, are assumed to be user
284       modifications.
285
286   initial_load_stop
287       Stop initial_load mode. Instance is built with initial_load as 1. Read
288       backend clears this value once the first read is done.
289
290   initial_load
291       Get initial_load mode
292
293   data
294       This method provides a way to store some arbitrary data in the instance
295       object.
296
297       E.g:
298
299         $instance->data(foo => 'bar');
300
301       Later:
302
303         my $foo = $instance->data('foo'); # $foo contains 'bar'
304

Read and write backend features

306       Usually, a program based on config model must first create the
307       configuration model, then load all configuration data.
308
309       This feature enables you to declare with the model a way to load
310       configuration data (and to write it back). See
311       Config::Model::BackendMgr for details.
312
313   backend
314       Get the preferred backend method for this instance (as passed to the
315       constructor).
316
317   backend_arg
318       Get cme command line argument that may be used by the backend to get
319       the configuration file. These method is typically used in the read and
320       write method of a backend to know where is the configuration file to
321       edit.
322
323   root_dir
324       Returns a Path::Tiny object for the root directory where configuration
325       data is read from or written to.
326
327   root_path
328       Same as "root_dir"
329
330   register_write_back
331       Parameters: "( node_location )"
332
333       Register a node path that is called back with "write_back" method.
334
335   notify_change
336       Notify that some data has changed in the tree. See "notify_change" in
337       Config::Model::AnyThing for more details.
338
339   write_back
340       In summary, save the content of the configuration tree to configuration
341       files.
342
343       In more details, "write_back" trie to run all subroutines registered
344       with "register_write_back" to write the configuration information.
345       (See Config::Model::BackendMgr for details).
346
347       You can specify here another config directory to write configuration
348       data back with "config_dir" parameter. This overrides the model
349       specifications.
350
351       "write_back" croaks if no write call-back are known.
352
353       Use "force => 1" option to force saving configuration data. This is
354       useful to write back a file even no change are done at semantic level,
355       i.e. to reformat a file or remove unnecessary data.
356

AUTHOR

358       Dominique Dumont, (ddumont at cpan dot org)
359

SEE ALSO

361       Config::Model, Config::Model::Node, Config::Model::Loader,
362       Config::Model::Searcher, Config::Model::Value,
363

AUTHOR

365       Dominique Dumont
366
368       This software is Copyright (c) 2005-2022 by Dominique Dumont.
369
370       This is free software, licensed under:
371
372         The GNU Lesser General Public License, Version 2.1, February 1999
373
374
375
376perl v5.34.1                      2022-05-09        Config::Model::Instance(3)
Impressum