1Config::Model::InstanceU(s3e)r Contributed Perl DocumentaCtoinofnig::Model::Instance(3)
2
6 Config::Model::Instance - Instance of configuration tree
7
9 version 2.152
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_arg
80 Specify a backend argument that may be retrieved by some backend.
81 Instance is used as a relay and does not use this data.
82 check
84 Specify whether to check value while reading config files. Either:
85 yes Check value and throws an error for bad values.
87 skip
89 Check value and skip bad value.
90 no Do not check.
92 canonical
94 When true: write config data back using model order. By default,
95 write items back using the order found in the configuration file.
96 This feature is experimental and not supported by all backends.
97 on_change_cb
99 Call back this function whenever "notify_change" is called. Called
100 with arguments: "name => <root node element name>, index =>
101 <index_value>"
102 on_message_cb
104 Call back this function when show_message is called. By default,
105 messages are displayed on STDOUT.
106 error_paths
108 Returns a list of tree items that currently have an error.
109 error_messages
111 Returns a list of error messages from the tree content.
112 Note that the root directory specified within the configuration model
114 is overridden by "root_dir" parameter.
115 If you need to load configuration data that are not correct, you can
117 use "force_load => 1". Then, wrong data are discarded (equivalent to
118 "check => 'no'" ).
119
121 Manage configuration data
122 modify
123 Calls "load" and then "save".
124 Takes the same parameter as "load" plus:
126 "force_write"
128 Force saving configuration file even if no value was modified
129 (default is 0)
130 "quiet"
132 Do no display the changes brought by the modification steps
133 load
135 Load configuration tree with configuration data. See "load" in
136 Config::Model::Loader for parameters. Returns <$self>.
137 save
139 Save the content of the configuration tree to configuration files. (See
140 "write_back" for more details)
141 Use "force => 1" option to force saving configuration data.
143 config_root
145 Returns the root object of the configuration tree.
146 apply_fixes
148 Scan the tree and apply fixes that are attached to warning
149 specifications. See "warn_if_match" or "warn_unless_match" in "" in
150 Config::Model::Value.
151 deep_check
153 Scan the tree and deep check on all elements that support this.
154 Currently only hash or list element have this feature.
155 needs_save
157 Returns 1 (or more) if the instance contains data that needs to be
158 saved. I.e some change were done in the tree that needs to be saved.
159 has_changes
161 Returns true if the instance contains unsasved changes.
162 list_changes
164 In list context, returns a array ref of strings describing the changes.
165 In scalar context, returns a big string. Useful to print.
166 say_changes
168 Print all changes on STDOUT and return $self.
169 clear_changes
171 Clear list of changes. Note that changes pending in the configuration
172 tree is not affected. This clears only the list shown to user. Use only
173 for tests.
174 has_warning
176 Returns the number of warning found in the elements of this
177 configuration instance.
178 update
180 Parameters: "( quiet => (0|1), %args )"
181 Try to run update command on all nodes of the configuration tree. Node
183 without "update" method are ignored. "update" prints a message
184 otherwise (unless "quiet" is true).
185 grab
187 Use the steps parameter to retrieve and returns an object from the
188 configuration tree. Forwarded to "grab" in Config::Model::Role::Grab
189 grab_value
191 Use the steps parameter to retrieve and returns the value of a leaf
192 object from the configuration tree. Forwarded to "grab_value" in
193 Config::Model::Role::Grab
194 searcher
196 Returns an object dedicated to search an element in the configuration
197 model.
198 This method returns a Config::Model::Searcher object. See
200 Config::Model::Searcher for details on how to handle a search.
201 iterator
203 This method returns a Config::Model::Iterator object. See
204 Config::Model::Iterator for details.
205 Arguments are explained in Config::Model::Iterator constructor
207 arguments.
208 application
210 Returns the application name of the instance. (E.g "popcon", "dpkg"
211 ...)
212 wizard_helper
214 Deprecated. Call "iterator" instead.
215
217 name
218 Returns the instance name.
219 read_check
221 Returns which kind of check is performed while reading configuration
222 files. (see "check" parameter in "CONSTRUCTOR" section)
223 show_message
225 Parameters: "( string )"
226 Display the message on STDOUT unless a custom function was passed to
228 "on_message_cb" parameter.
229 reset_config
231 Destroy current configuration tree (with data) and returns a new tree
232 with data (and annotations) loaded from disk.
233 config_model
235 Returns the model (Config::Model object) of the configuration tree.
236 annotation_saver
238 Returns the object loading and saving annotations. See
239 Config::Model::Annotation for details.
240 preset_start
242 All values stored in preset mode are shown to the user as default
243 values. This feature is useful to enter configuration data entered by
244 an automatic process (like hardware scan)
245 preset_stop
247 Stop preset mode
248 preset
250 Get preset mode
251 preset_clear
253 Clear all preset values stored.
254 layered_start
256 All values stored in layered mode are shown to the user as default
257 values. This feature is useful to enter configuration data entered by
258 an automatic process (like hardware scan)
259 layered_stop
261 Stop layered mode
262 layered
264 Get layered mode
265 layered_clear
267 Clear all layered values stored.
268 get_data_mode
270 Returns 'normal' or 'preset' or 'layered'. Does not take into account
271 initial_load.
272 initial_load_start
274 Start initial_load mode. This mode tracks the first modifications of
275 the tree done with data read from the configuration file.
276 Instance is built with initial_load as 1. Read backend clears this
278 value once the first read is done.
279 Other modifications, when initial_load is zero, are assumed to be user
281 modifications.
282 initial_load_stop
284 Stop initial_load mode. Instance is built with initial_load as 1. Read
285 backend clears this value once the first read is done.
286 initial_load
288 Get initial_load mode
289 data
291 This method provides a way to store some arbitrary data in the instance
292 object.
293 E.g:
295 $instance->data(foo => 'bar');
297 Later:
299 my $foo = $instance->data('foo'); # $foo contains 'bar'
301
303 Usually, a program based on config model must first create the
304 configuration model, then load all configuration data.
305 This feature enables you to declare with the model a way to load
307 configuration data (and to write it back). See
308 Config::Model::BackendMgr for details.
309 backend_arg
311 Get cme command line argument that may be used by the backend to get
312 the configuration file. These method is typically used in the read and
313 write method of a backend to know where is the configuration file to
314 edit.
315 root_dir
317 Returns a Path::Tiny object for the root directory where configuration
318 data is read from or written to.
319 root_path
321 Same as "root_dir"
322 register_write_back
324 Parameters: "( node_location )"
325 Register a node path that is called back with "write_back" method.
327 notify_change
329 Notify that some data has changed in the tree. See "notify_change" in
330 Config::Model::AnyThing for more details.
331 write_back
333 In summary, save the content of the configuration tree to configuration
334 files.
335 In more details, "write_back" tries to run all subroutines registered
337 with "register_write_back" to write the configuration information.
338 (See Config::Model::BackendMgr for details).
339 You can specify here another config directory to write configuration
341 data back with "config_dir" parameter. This overrides the model
342 specifications.
343 "write_back" croaks if no write call-back are known.
345 Use "force => 1" option to force saving configuration data. This is
347 useful to write back a file even no change are done at semantic level,
348 i.e. to reformat a file or remove unnecessary data.
349
351 Dominique Dumont, (ddumont at cpan dot org)
352
354 Config::Model, Config::Model::Node, Config::Model::Loader,
355 Config::Model::Searcher, Config::Model::Value,
356
358 Dominique Dumont
359
361 This software is Copyright (c) 2005-2022 by Dominique Dumont.
362 This is free software, licensed under:
364 The GNU Lesser General Public License, Version 2.1, February 1999
366perl v5.36.0 2022-08-10 Config::Model::Instance(3)