1Config::Model::InstanceU(s3e)r Contributed Perl DocumentaCtoinofnig::Model::Instance(3)
2
6 Config::Model::Instance - Instance of configuration tree
7
9 version 2.141
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 "force_write" to force saving
129 configuration file even if no value was modified (default is 0)
130 load
132 Load configuration tree with configuration data. See "load" in
133 Config::Model::Loader for parameters. Returns <$self>.
134 save
136 Save the content of the configuration tree to configuration files. (See
137 "write_back" for more details)
138 Use "force => 1" option to force saving configuration data.
140 config_root
142 Returns the root object of the configuration tree.
143 apply_fixes
145 Scan the tree and apply fixes that are attached to warning
146 specifications. See "warn_if_match" or "warn_unless_match" in "" in
147 Config::Model::Value.
148 deep_check
150 Scan the tree and deep check on all elements that support this.
151 Currently only hash or list element have this feature.
152 needs_save
154 Returns 1 (or more) if the instance contains data that needs to be
155 saved. I.e some change were done in the tree that needs to be saved.
156 list_changes
158 In list context, returns a array ref of strings describing the changes.
159 In scalar context, returns a big string. Useful to print.
160 say_changes
162 Print all changes on STDOUT and return the list of changes.
163 clear_changes
165 Clear list of changes. Note that changes pending in the configuration
166 tree is not affected. This clears only the list shown to user. Use only
167 for tests.
168 has_warning
170 Returns the number of warning found in the elements of this
171 configuration instance.
172 update
174 Parameters: "( quiet => (0|1), %args )"
175 Try to run update command on all nodes of the configuration tree. Node
177 without "update" method are ignored. "update" prints a message
178 otherwise (unless "quiet" is true).
179 grab
181 Use the steps parameter to retrieve and returns an object from the
182 configuration tree. Forwarded to "grab" in Config::Model::Role::Grab
183 grab_value
185 Use the steps parameter to retrieve and returns the value of a leaf
186 object from the configuration tree. Forwarded to "grab_value" in
187 Config::Model::Role::Grab
188 searcher
190 Returns an object dedicated to search an element in the configuration
191 model.
192 This method returns a Config::Model::Searcher object. See
194 Config::Model::Searcher for details on how to handle a search.
195 iterator
197 This method returns a Config::Model::Iterator object. See
198 Config::Model::Iterator for details.
199 Arguments are explained in Config::Model::Iterator constructor
201 arguments.
202 application
204 Returns the application name of the instance. (E.g "popcon", "dpkg"
205 ...)
206 wizard_helper
208 Deprecated. Call "iterator" instead.
209
211 name
212 Returns the instance name.
213 read_check
215 Returns which kind of check is performed while reading configuration
216 files. (see "check" parameter in "CONSTRUCTOR" section)
217 show_message
219 Parameters: "( string )"
220 Display the message on STDOUT unless a custom function was passed to
222 "on_message_cb" parameter.
223 reset_config
225 Destroy current configuration tree (with data) and returns a new tree
226 with data (and annotations) loaded from disk.
227 config_model
229 Returns the model (Config::Model object) of the configuration tree.
230 annotation_saver
232 Returns the object loading and saving annotations. See
233 Config::Model::Annotation for details.
234 preset_start
236 All values stored in preset mode are shown to the user as default
237 values. This feature is useful to enter configuration data entered by
238 an automatic process (like hardware scan)
239 preset_stop
241 Stop preset mode
242 preset
244 Get preset mode
245 preset_clear
247 Clear all preset values stored.
248 layered_start
250 All values stored in layered mode are shown to the user as default
251 values. This feature is useful to enter configuration data entered by
252 an automatic process (like hardware scan)
253 layered_stop
255 Stop layered mode
256 layered
258 Get layered mode
259 layered_clear
261 Clear all layered values stored.
262 get_data_mode
264 Returns 'normal' or 'preset' or 'layered'. Does not take into account
265 initial_load.
266 initial_load_start
268 Start initial_load mode. This mode tracks the first modifications of
269 the tree done with data read from the configuration file.
270 Instance is built with initial_load as 1. Read backend clears this
272 value once the first read is done.
273 Other modifications, when initial_load is zero, are assumed to be user
275 modifications.
276 initial_load_stop
278 Stop initial_load mode. Instance is built with initial_load as 1. Read
279 backend clears this value once the first read is done.
280 initial_load
282 Get initial_load mode
283 data
285 This method provides a way to store some arbitrary data in the instance
286 object.
287 E.g:
289 $instance->data(foo => 'bar');
291 Later:
293 my $foo = $instance->data('foo'); # $foo contains 'bar'
295
297 Usually, a program based on config model must first create the
298 configuration model, then load all configuration data.
299 This feature enables you to declare with the model a way to load
301 configuration data (and to write it back). See
302 Config::Model::BackendMgr for details.
303 backend
305 Get the preferred backend method for this instance (as passed to the
306 constructor).
307 backend_arg
309 Get cme command line argument that may be used by the backend to get
310 the configuration file. These method is typically used in the read and
311 write method of a backend to know where is the configuration file to
312 edit.
313 root_dir
315 Returns a Path::Tiny object for the root directory where configuration
316 data is read from or written to.
317 root_path
319 Same as "root_dir"
320 register_write_back
322 Parameters: "( node_location )"
323 Register a node path that is called back with "write_back" method.
325 notify_change
327 Notify that some data has changed in the tree. See "notify_change" in
328 Config::Model::AnyThing for more details.
329 write_back
331 In summary, save the content of the configuration tree to configuration
332 files.
333 In more details, "write_back" trie to run all subroutines registered
335 with "register_write_back" to write the configuration information.
336 (See Config::Model::BackendMgr for details).
337 You can specify here another config directory to write configuration
339 data back with "config_dir" parameter. This overrides the model
340 specifications.
341 "write_back" croaks if no write call-back are known.
343 Use "force => 1" option to force saving configuration data. This is
345 useful to write back a file even no change are done at semantic level,
346 i.e. to reformat a file or remove unnecessary data.
347
349 Dominique Dumont, (ddumont at cpan dot org)
350
352 Config::Model, Config::Model::Node, Config::Model::Loader,
353 Config::Model::Searcher, Config::Model::Value,
354
356 Dominique Dumont
357
359 This software is Copyright (c) 2005-2021 by Dominique Dumont.
360 This is free software, licensed under:
362 The GNU Lesser General Public License, Version 2.1, February 1999
364perl v5.32.1 2021-01-27 Config::Model::Instance(3)