1Config::Model::InstanceU(s3e)r Contributed Perl DocumentaCtoinofnig::Model::Instance(3)
2
6 Config::Model::Instance - Instance of configuration tree
7
9 version 2.150
10
12 use Config::Model;
13 use File::Path ;
14 # setup a dummy popcon conf file
16 my $wr_dir = '/tmp/etc/';
17 my $conf_file = "$wr_dir/popularity-contest.conf" ;
18 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 my $model = Config::Model->new;
31 # 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 print $root->describe;
39
41 This module provides an object that holds a configuration tree.
42
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 my $inst = $model->instance (
48 # run 'cme list' to get list of applications
49 application => 'foo',
50 # optional
51 instance_name => 'test1'
52 );
53 my $inst = $model->instance (
55 root_class_name => 'SomeRootClass',
56 instance_name => 'test1'
57 );
58 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 Constructor parameters are:
64 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 root_path
72 Path::Tiny object created with "root_dir" value or with current
73 directory if "root_dir" is empty.
74 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 backend
80 Specify which backend to use. See "write_back" for details
81 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 check
87 Specify whether to check value while reading config files. Either:
88 yes Check value and throws an error for bad values.
90 skip
92 Check value and skip bad value.
93 no Do not check.
95 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 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 on_message_cb
107 Call back this function when show_message is called. By default,
108 messages are displayed on STDOUT.
109 error_paths
111 Returns a list of tree items that currently have an error.
112 error_messages
114 Returns a list of error messages from the tree content.
115 Note that the root directory specified within the configuration model
117 is overridden by "root_dir" parameter.
118 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
124 Manage configuration data
125 modify
126 Calls "load" and then "save".
127 Takes the same parameter as "load" plus:
129 "force_write"
131 Force saving configuration file even if no value was modified
132 (default is 0)
133 "quiet"
135 Do no display the changes brought by the modification steps
136 load
138 Load configuration tree with configuration data. See "load" in
139 Config::Model::Loader for parameters. Returns <$self>.
140 save
142 Save the content of the configuration tree to configuration files. (See
143 "write_back" for more details)
144 Use "force => 1" option to force saving configuration data.
146 config_root
148 Returns the root object of the configuration tree.
149 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 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 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 has_changes
164 Returns true if the instance contains unsasved changes.
165 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 say_changes
171 Print all changes on STDOUT and return $self.
172 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 has_warning
179 Returns the number of warning found in the elements of this
180 configuration instance.
181 update
183 Parameters: "( quiet => (0|1), %args )"
184 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 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 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 searcher
199 Returns an object dedicated to search an element in the configuration
200 model.
201 This method returns a Config::Model::Searcher object. See
203 Config::Model::Searcher for details on how to handle a search.
204 iterator
206 This method returns a Config::Model::Iterator object. See
207 Config::Model::Iterator for details.
208 Arguments are explained in Config::Model::Iterator constructor
210 arguments.
211 application
213 Returns the application name of the instance. (E.g "popcon", "dpkg"
214 ...)
215 wizard_helper
217 Deprecated. Call "iterator" instead.
218
220 name
221 Returns the instance name.
222 read_check
224 Returns which kind of check is performed while reading configuration
225 files. (see "check" parameter in "CONSTRUCTOR" section)
226 show_message
228 Parameters: "( string )"
229 Display the message on STDOUT unless a custom function was passed to
231 "on_message_cb" parameter.
232 reset_config
234 Destroy current configuration tree (with data) and returns a new tree
235 with data (and annotations) loaded from disk.
236 config_model
238 Returns the model (Config::Model object) of the configuration tree.
239 annotation_saver
241 Returns the object loading and saving annotations. See
242 Config::Model::Annotation for details.
243 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 preset_stop
250 Stop preset mode
251 preset
253 Get preset mode
254 preset_clear
256 Clear all preset values stored.
257 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 layered_stop
264 Stop layered mode
265 layered
267 Get layered mode
268 layered_clear
270 Clear all layered values stored.
271 get_data_mode
273 Returns 'normal' or 'preset' or 'layered'. Does not take into account
274 initial_load.
275 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 Instance is built with initial_load as 1. Read backend clears this
281 value once the first read is done.
282 Other modifications, when initial_load is zero, are assumed to be user
284 modifications.
285 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 initial_load
291 Get initial_load mode
292 data
294 This method provides a way to store some arbitrary data in the instance
295 object.
296 E.g:
298 $instance->data(foo => 'bar');
300 Later:
302 my $foo = $instance->data('foo'); # $foo contains 'bar'
304
306 Usually, a program based on config model must first create the
307 configuration model, then load all configuration data.
308 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 backend
314 Get the preferred backend method for this instance (as passed to the
315 constructor).
316 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 root_dir
324 Returns a Path::Tiny object for the root directory where configuration
325 data is read from or written to.
326 root_path
328 Same as "root_dir"
329 register_write_back
331 Parameters: "( node_location )"
332 Register a node path that is called back with "write_back" method.
334 notify_change
336 Notify that some data has changed in the tree. See "notify_change" in
337 Config::Model::AnyThing for more details.
338 write_back
340 In summary, save the content of the configuration tree to configuration
341 files.
342 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 You can specify here another config directory to write configuration
348 data back with "config_dir" parameter. This overrides the model
349 specifications.
350 "write_back" croaks if no write call-back are known.
352 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
358 Dominique Dumont, (ddumont at cpan dot org)
359
361 Config::Model, Config::Model::Node, Config::Model::Loader,
362 Config::Model::Searcher, Config::Model::Value,
363
365 Dominique Dumont
366
368 This software is Copyright (c) 2005-2022 by Dominique Dumont.
369 This is free software, licensed under:
371 The GNU Lesser General Public License, Version 2.1, February 1999
373perl v5.34.1 2022-05-09 Config::Model::Instance(3)