1Config::Model::BackendMUgsre(r3)Contributed Perl DocumenCtoantfiiogn::Model::BackendMgr(3)
2
6 Config::Model::BackendMgr - Load configuration node on demand
7
9 version 2.152
10
12 # Use BackendMgr to write data in Yaml file
13 # This example requires Config::Model::Backend::Yaml which is now
14 # shipped outside of Config::Model. Please get it on CPAN
15 use Config::Model;
16 # define configuration tree object
18 my $model = Config::Model->new;
19 $model->create_config_class(
20 name => "Foo",
21 element => [
22 [qw/foo bar/] => {
23 type => 'leaf',
24 value_type => 'string'
25 },
26 ]
27 );
28 $model->create_config_class(
30 name => "MyClass",
31 # rw_config spec is used by Config::Model::BackendMgr
33 rw_config => {
34 backend => 'yaml',
35 config_dir => '/tmp/',
36 file => 'my_class.yml',
37 auto_create => 1,
38 },
39 element => [
41 [qw/foo bar/] => {
42 type => 'leaf',
43 value_type => 'string'
44 },
45 hash_of_nodes => {
46 type => 'hash', # hash id
47 index_type => 'string',
48 cargo => {
49 type => 'node',
50 config_class_name => 'Foo'
51 },
52 },
53 ],
54 );
55 my $inst = $model->instance( root_class_name => 'MyClass' );
57 my $root = $inst->config_root;
59 # put data
61 my $steps = 'foo=FOO hash_of_nodes:fr foo=bonjour -
62 hash_of_nodes:en foo=hello ';
63 $root->load( steps => $steps );
64 $inst->write_back;
66 # now look at file /tmp/my_class.yml
68
70 This class provides a way to specify how to load or store configuration
71 data within the model.
72 With these specifications, all configuration information is read during
74 creation of a node (which triggers the creation of a backend manager
75 object) and written back when write_back method is called either on the
76 instance.
77 This load/store can be done with different backends:
79 • Any of the "Config::Model::Backend::*" classes available on your
81 system. For instance "Config::Model::Backend::Yaml".
82 • "cds_file": Config dump string (cds) in a file. I.e. a string that
84 describes the content of a configuration tree is loaded from or
85 saved in a text file. This format is defined by this project. See
86 "load string syntax" in Config::Model::Loader.
87 • "perl_file": Perl data structure (perl) in a file. See
89 Config::Model::DumpAsData for details on the data structure. Now
90 handled by Config::Model::Backend::PerlFile
91 When needed, "write_back" method can be called on the instance (See
93 Config::Model::Instance) to store back all configuration information.
94
96 The backend specification is provided as an attribute of a
97 Config::Model::Node specification. These attributes are optional: A
98 node without "rw_config" attribute must rely on another node to read or
99 save its data.
100 When needed (usually for the root node), the configuration class is
102 declared with a "rw_config" parameter which specifies the read/write
103 backend configuration.
104 Parameters available for all backends
106 The following parameters are accepted by all backends:
107 config_dir
109 Specify configuration directory. This parameter is optional as the
110 directory can be hardcoded in the backend class. "config_dir"
111 beginning with '"~"' is munged so "~" is replaced by
112 "File::HomeDir->my_data". See File::HomeDir for details.
113 file
115 Specify configuration file name (without the path). This parameter
116 is optional as the file name can be hardcoded in the backend class.
117 The configuration file name can be specified with &index keyword
119 when a backend is associated to a node contained in a hash. For
120 instance, with "file" set to "&index.conf":
121 service # hash element
123 foo # hash index
124 nodeA # values of nodeA are stored in foo.conf
125 bar # hash index
126 nodeB # values of nodeB are stored in bar.conf
127 Likewise, the keyword &element can be used to specify the file
129 name. For instance, with "file" set to "&element-&index.conf":
130 service # hash element
132 foo # hash index
133 nodeA # values of nodeA are stored in service.foo.conf
134 bar # hash index
135 nodeB # values of nodeB are stored in service.bar.conf
136 file_mode
138 "file_mode" parameter can be used to set the mode of the written
139 file(s). "file_mode" value can be in any form supported by "chmod"
140 in Path::Tiny. Example:
141 file_mode => 0664,
143 file_mode => '0664',
144 file_mode => 'g+w'
145 os_config_dir
147 Specify alternate location of a configuration directory depending
148 on the OS (as returned by $^O, see "PLATFORMS" in perlport). For
149 instance:
150 config_dir => '/etc/ssh',
152 os_config_dir => { darwin => '/etc' }
153 default_layer
155 Optional. Specifies where to find a global configuration file that
156 specifies default values. For instance, this is used by OpenSSH to
157 specify a global configuration file ("/etc/ssh/ssh_config") that is
158 overridden by user's file:
159 default_layer => {
161 os_config_dir => { 'darwin' => '/etc' },
162 config_dir => '/etc/ssh',
163 file => 'ssh_config'
164 }
165 Only the 3 above parameters can be specified in "default_layer".
167 auto_create
169 By default, an exception is thrown if no read was successful. This
170 behavior can be overridden by specifying "auto_create => 1" in one
171 of the backend specification. For instance:
172 rw_config => {
174 backend => 'IniFile',
175 config_dir => '/tmp',
176 file => 'foo.conf',
177 auto_create => 1
178 },
179 Setting "auto_create" to 1 is necessary to create a configuration
181 from scratch
182 auto_delete
184 Delete configuration files that contains no data. (default is to
185 leave an empty file)
186 Config::Model::Backend::* backends
188 Specify the backend name and the parameters of the backend defined in
189 their documentation.
190 For instance:
192 rw_config => {
194 backend => 'yaml',
195 config_dir => '/tmp/',
196 file => 'my_class.yml',
197 },
198 See Config::Model::Backend::Yaml for more details for this backend.
200 Your own backend
202 You can also write a dedicated backend. See How to write your own
203 backend for details.
204
206 By default, configurations files are read from the directory specified
207 by "config_dir" parameter specified in the model. You may override the
208 "root" directory for test.
209
211 support_annotation
212 Returns 1 if at least the backend supports read and write annotations
213 (aka comments) in the configuration file.
214
216 Dominique Dumont, (ddumont at cpan dot org)
217
219 Config::Model, Config::Model::Instance, Config::Model::Node,
220 Config::Model::Dumper
221
223 Dominique Dumont
224
226 This software is Copyright (c) 2005-2022 by Dominique Dumont.
227 This is free software, licensed under:
229 The GNU Lesser General Public License, Version 2.1, February 1999
231perl v5.36.0 2022-08-10 Config::Model::BackendMgr(3)