1Config::Model::InstanceU(s3e)r Contributed Perl DocumentaCtoinofnig::Model::Instance(3)
2
6 Config::Model::Instance - Instance of configuration tree
7
9 version 2.129
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.
137 (alias to "write_back")
138 config_root
140 Returns the root object of the configuration tree.
141 apply_fixes
143 Scan the tree and apply fixes that are attached to warning
144 specifications. See "warn_if_match" or "warn_unless_match" in "" in
145 Config::Model::Value.
146 deep_check
148 Scan the tree and deep check on all elements that support this.
149 Currently only hash or list element have this feature.
150 needs_save
152 Returns 1 (or more) if the instance contains data that needs to be
153 saved. I.e some change were done in the tree that needs to be saved.
154 list_changes
156 In list context, returns a array ref of strings describing the changes.
157 In scalar context, returns a big string. Useful to print.
158 say_changes
160 Print all changes on STDOUT and return the list of changes.
161 clear_changes
163 Clear list of changes. Note that changes pending in the configuration
164 tree is not affected. This clears only the list shown to user. Use only
165 for tests.
166 has_warning
168 Returns the number of warning found in the elements of this
169 configuration instance.
170 update
172 Parameters: "( quiet => (0|1), %args )"
173 Try to run update command on all nodes of the configuration tree. Node
175 without "update" method are ignored. "update" prints a message
176 otherwise (unless "quiet" is true).
177 grab
179 Use the steps parameter to retrieve and returns an object from the
180 configuration tree. Forwarded to "grab" in Config::Model::Role::Grab
181 grab_value
183 Use the steps parameter to retrieve and returns the value of a leaf
184 object from the configuration tree. Forwarded to "grab_value" in
185 Config::Model::Role::Grab
186 searcher
188 Returns an object dedicated to search an element in the configuration
189 model (respecting privilege level).
190 This method returns a Config::Model::Searcher object. See
192 Config::Model::Searcher for details on how to handle a search.
193 iterator
195 This method returns a Config::Model::Iterator object. See
196 Config::Model::Iterator for details.
197 Arguments are explained in Config::Model::Iterator constructor
199 arguments.
200 application
202 Returns the application name of the instance. (E.g "popcon", "dpkg"
203 ...)
204 wizard_helper
206 Deprecated. Call "iterator" instead.
207
209 name
210 Returns the instance name.
211 read_check
213 Returns which kind of check is performed while reading configuration
214 files. (see "check" parameter in "CONSTRUCTOR" section)
215 show_message
217 Parameters: "( string )"
218 Display the message on STDOUT unless a custom function was passed to
220 "on_message_cb" parameter.
221 reset_config
223 Destroy current configuration tree (with data) and returns a new tree
224 with data (and annotations) loaded from disk.
225 config_model
227 Returns the model (Config::Model object) of the configuration tree.
228 annotation_saver
230 Returns the object loading and saving annotations. See
231 Config::Model::Annotation for details.
232 preset_start
234 All values stored in preset mode are shown to the user as default
235 values. This feature is useful to enter configuration data entered by
236 an automatic process (like hardware scan)
237 preset_stop
239 Stop preset mode
240 preset
242 Get preset mode
243 preset_clear
245 Clear all preset values stored.
246 layered_start
248 All values stored in layered mode are shown to the user as default
249 values. This feature is useful to enter configuration data entered by
250 an automatic process (like hardware scan)
251 layered_stop
253 Stop layered mode
254 layered
256 Get layered mode
257 layered_clear
259 Clear all layered values stored.
260 get_data_mode
262 Returns 'normal' or 'preset' or 'layered'. Does not take into account
263 initial_load.
264 initial_load_start
266 Start initial_load mode. This mode tracks the first modifications of
267 the tree done with data read from the configuration file.
268 Instance is built with initial_load as 1. Read backend clears this
270 value once the first read is done.
271 Other modifications, when initial_load is zero, are assumed to be user
273 modifications.
274 initial_load_stop
276 Stop initial_load mode. Instance is built with initial_load as 1. Read
277 backend clears this value once the first read is done.
278 initial_load
280 Get initial_load mode
281 data
283 This method provides a way to store some arbitrary data in the instance
284 object.
285 E.g:
287 $instance->data(foo => 'bar');
289 Later:
291 my $foo = $instance->data('foo'); # $foo contains 'bar'
293
295 Usually, a program based on config model must first create the
296 configuration model, then load all configuration data.
297 This feature enables you to declare with the model a way to load
299 configuration data (and to write it back). See
300 Config::Model::BackendMgr for details.
301 backend
303 Get the preferred backend method for this instance (as passed to the
304 constructor).
305 backend_arg
307 Get cme command line argument that may be used by the backend to get
308 the configuration file. These method is typically used in the read and
309 write method of a backend to know where is the configuration file to
310 edit.
311 root_dir
313 Returns a Path::Tiny object for the root directory where configuration
314 data is read from or written to.
315 root_path
317 Same as "root_dir"
318 register_write_back
320 Parameters: "( node_location )"
321 Register a node path that is called back with "write_back" method.
323 notify_change
325 Notify that some data has changed in the tree. See "notify_change" in
326 Config::Model::AnyThing for more details.
327 write_back
329 In summary, save the content of the configuration tree to configuration
330 files.
331 In more details, "write_back" trie to run all subroutines registered
333 with "register_write_back" to write the configuration information.
334 (See Config::Model::BackendMgr for details).
335 You can specify here another config directory to write configuration
337 data back with "config_dir" parameter. This overrides the model
338 specifications.
339 "write_back" croaks if no write call-back are known.
341
343 Dominique Dumont, (ddumont at cpan dot org)
344
346 Config::Model, Config::Model::Node, Config::Model::Loader,
347 Config::Model::Searcher, Config::Model::Value,
348
350 Dominique Dumont
351
353 This software is Copyright (c) 2005-2018 by Dominique Dumont.
354 This is free software, licensed under:
356 The GNU Lesser General Public License, Version 2.1, February 1999
358perl v5.28.1 2018-12-07 Config::Model::Instance(3)