1Config::Model::Loader(3Upsme)r Contributed Perl DocumentaCtoinofnig::Model::Loader(3pm)
2
6 Config::Model::Loader - Load serialized data into config tree
7
9 version 2.153
10
12 use Config::Model;
13 # define configuration tree object
15 my $model = Config::Model->new;
16 $model->create_config_class(
17 name => "Foo",
18 element => [
19 [qw/foo bar/] => {
20 type => 'leaf',
21 value_type => 'string'
22 },
23 ]
24 );
25 $model ->create_config_class (
27 name => "MyClass",
28 element => [
30 [qw/foo bar/] => {
32 type => 'leaf',
33 value_type => 'string'
34 },
35 hash_of_nodes => {
36 type => 'hash', # hash id
37 index_type => 'string',
38 cargo => {
39 type => 'node',
40 config_class_name => 'Foo'
41 },
42 },
43 [qw/lista listb/] => {
44 type => 'list',
45 cargo => {type => 'leaf',
46 value_type => 'string'
47 }
48 },
49 ],
50 ) ;
51 my $inst = $model->instance(root_class_name => 'MyClass' );
53 my $root = $inst->config_root ;
55 # put data
57 my $steps = 'foo=FOO hash_of_nodes:fr foo=bonjour -
58 hash_of_nodes:en foo=hello
59 ! lista=foo,bar lista:2=baz
60 listb:0=foo listb:1=baz';
61 $root->load( steps => $steps );
62 my $s = $root->fetch_element_value('foo'); # => is 'FOO'
64 $s = $root->grab_value('hash_of_nodes:en foo'); # => is 'hello'
65 $s = $root->grab_value('lista:1'); # => is 'bar'
66 $s = $root->grab_value('lista:2'); # => is 'baz'
67 # delete some data
69 $root->load( steps => 'lista~2' );
70 $s = $root->grab_value('lista:2'); # => is undef
72 # append some data
74 $root->load( steps => q!hash_of_nodes:en foo.=" world"! );
75 $s = $root->grab_value('hash_of_nodes:en foo'); # => is 'hello world'
77
79 This module is used directly by Config::Model::Node to load serialized
80 configuration data into the configuration tree.
81 Serialized data can be written by the user or produced by
83 Config::Model::Dumper while dumping data from a configuration tree.
84
86 new
87 The constructor should be used only by Config::Model::Node.
88 Parameters:
90 start_node
92 node ref of the root of the tree (of sub-root) to start the load
93 from. Stored as a weak reference.
94
96 The string is made of the following items (also called "actions")
97 separated by spaces. These actions can be divided in 4 groups:
98 • navigation: moving up and down the configuration tree.
100 • list and hash operation: select, add or delete hash or list item
102 (also known as "id" items)
103 • leaf operation: select, modify or delecte leaf value
105 • annotation: modify or delete configuration annotation (aka comment)
107 navigation
109 - Go up one node
110 ! Go to the root node of the configuration tree.
112 xxx Go down using "xxx" element. (For "node" type element)
114 /xxx Go up until the element "xxx" is found. This search can be
116 combined with one of the command specified below, e.g
117 "/a_string="foo bar""
118 list and hash operation
120 xxx:yy
121 Go down using "xxx" element and id "yy" (For "hash" or "list"
122 element with "node" cargo_type). Literal "\n" are replaced by real
123 "\n" (LF in Unix).
124 xxx:.foreach_match(yy) or xxx:~yy
126 Go down using "xxx" element and loop over the ids that match the
127 regex specified by "yy". (For "hash").
128 For instance, with "OpenSsh" model, you could do
130 Host:~"/.*.debian.org/" user='foo-guest'
132 to set "foo-user" users for all your debian accounts.
134 The leading and trailing '/' may be omitted. Be sure to surround
136 the regexp with double quote if space are embedded in the regex.
137 Note that the loop ends when the load command goes above the
139 element where the loop is executed. For instance, the instruction
140 below tries to execute "DX=BV" and "int_v=9" for all elements of
141 "std_id" hash:
142 std_id:~/^\w+$/ DX=Bv int_v=9
144 In the examples below only "DX=BV" is executed by the loop:
146 std_id:~/^\w+$/ DX=Bv - int_v=9
148 std_id:~/^\w+$/ DX=Bv ! int_v=9
149 The loop is done on all elements of the hash when no value is
151 passed after "":~"" (mnemonic: an empty regexp matches any value).
152 xxx:.rm(yy) or xxx:-yy
154 Delete item referenced by "xxx" element and id "yy". For a list,
155 this is equivalent to "splice xxx,yy,1". This command does not go
156 down in the tree (since it has just deleted the element). I.e. a
157 '"-"' is generally not needed afterwards.
158 xxx:.rm_value(yy) or xxx:-=yy
160 Remove the element whose value is "yy". For list or hash of leaves.
161 Does not not complain if the value to delete is not found.
162 xxx:..rm_match(yy) or xxx:-~/yy/
164 Remove the element whose value matches "yy". For list or hash of
165 leaves. Does not not complain if no value were deleted.
166 xxx:.substitute(/yy/zz/) or xxx:=~s/yy/zz/
168 Substitute a value with another. Perl switches can be used(e.g.
169 "xxx:=~s/yy/zz/gi")
170 xxx:<yy or xxx:.push(yy)
172 Push "yy" value on "xxx" list
173 xxx:>yy or xxx:.unshift(yy)
175 Unshift "yy" value on "xxx" list
176 xxx:@ or xxx:.sort
178 Sort the list
179 xxx:.insert_at(yy,zz)
181 Insert "zz" value on "xxx" list before index "yy".
182 xxx:.insert_before(yy,zz)
184 Insert "zz" value on "xxx" list before value "yy".
185 xxx:.insert_before(/yy/,zz)
187 Insert "zz" value on "xxx" list before value matching "yy".
188 xxx:.insort(zz)
190 Insert "zz" value on "xxx" list so that existing alphanumeric order
191 is preserved.
192 xxx:.insort(zz)
194 For hash element containing nodes: creates a new hash element with
195 "zz" key on "xxx" hash so that existing alphanumeric order of keys
196 is preserved. Note that all keys are sorted once this instruction
197 is called. Following instructions are applied on the created
198 element. I.e. putting key order aside, "xxx:.insort(zz)" has the
199 same effect as "xxx:zz" instruction.
200 xxx:.insort(zz,vv)
202 For hash element containing leaves: creates a new hash element with
203 "zz" key and assing value "vv" so that existing alphanumeric order
204 of keys is preserved. Note that all keys are sorted once this
205 instruction is called. Putting key order aside,
206 "xxx:.insort(zz,vv)" has the same effect as "xxx:zz=vv"
207 instruction.
208 xxx:.ensure(zz)
210 Ensure that list "xxx" contains value "zz". If value "zz" is
211 already stored in "xxx" list, this function does nothing. In the
212 other case, value "zz" is inserted in alphabetical order.
213 xxx:=z1,z2,z3
215 Set list element "xxx" to list "z1,z2,z3". Use ",," for undef
216 values, and "" for empty values.
217 I.e, for a list "('a',undef,'','c')", use "a,,"",c".
219 xxx:yy=zz
221 For "hash" element containing "leaf" cargo_type. Set the leaf
222 identified by key "yy" to value "zz".
223 Using "xxx:~/yy/=zz" is also possible.
225 xxx:.copy(yy,zz)
227 copy item "yy" in "zz" (hash or list).
228 xxx:.json("path/to/file.json/foo/bar")
230 Store "bar" content in array or hash. This should be used to store
231 hash or list of values.
232 You may store deep data structure. In this case, make sure that the
234 structure of the loaded data matches the structure of the model.
235 This won't happen by chance.
236 xxx:.clear
238 Clear the hash or list.
239 leaf operation
241 xxx=zz
242 Set element "xxx" to value "yy". load also accepts to set elements
243 with a quoted string. (For "leaf" element) Literal "\n" are
244 replaced by real "\n" (LF in Unix). Literal "\\" are replaced by
245 "\".
246 For instance "foo="a quoted string"" or "foo="\"bar\" and
248 \"baz\""".
249 xxx=~s/foo/bar/
251 Apply the substitution to the value of xxx. "s/foo/bar/" is the
252 standard Perl "s" substitution pattern.
253 Patterns with white spaces must be surrounded by quotes:
255 xxx=~"s/foo bar/bar baz/"
257 Perl pattern modifiers are accepted
259 xxx=~s/FOO/bar/i
261 xxx~
263 Undef element "xxx"
264 xxx.=zzz
266 Appends "zzz" value to current value (valid for "leaf" elements).
267 xxx=.file(yyy)
269 Store the content of file "yyy" in element "xxx".
270 Store STDIn in value xxx when "yyy" is '-'.
272 xxx=.json(path/to/data.json/foo/bar)
274 Open file "data.json" and store value from JSON data extracted with
275 "foo/bar" subpath.
276 For instance, if "data.json" contains:
278 {
280 "foo": {
281 "bar": 42
282 }
283 }
284 The instruction "baz=.json(data.json/foo/bar)" stores 42 in "baz"
286 element.
287 xxx=.yaml(path/to/data.yaml/0/foo/bar)
289 Open file "data.yaml" and store value from YAML data extracted with
290 "0/foo/bar" subpath.
291 Since a YAML file can contain several documents (separated by "---"
293 lines, the subpath must begin with a number to select the document
294 containing the required value.
295 For instance, if "data.yaml" contains:
297 ---
299 foo:
300 bar: 42
301 The instruction "baz=.yaml(data.yaml/0/foo/bar)" stores 42 in "baz"
303 element.
304 xxx=.env(yyy)
306 Store the content of environment variable "yyy" in element "xxx".
307 annotation
309 xxx#zzz or xxx:yyy#zzz
310 Element annotation. Can be quoted or not quoted. Note that
311 annotations are always placed at the end of an action item.
312 I.e. "foo#comment", "foo:bar#comment" or "foo:bar=baz#comment" are
314 valid. "foo#comment:bar" is not valid.
315 Quotes
317 You can surround indexes and values with single or double quotes. E.g.:
318 a_string='"foo" and "bar"'
320 Single quotes were added in version 2.153.
322
324 You can use cme to modify configuration with "cme modify" command.
325 For instance, if Config::Model::Ssh is installed, you can run:
327 cme modify ssh 'ControlMaster=auto ControlPath="~/.ssh/master-%r@%n:%p"'
329 To delete "Host *" entry:
331 cme modify ssh 'Host:-"*"'
333 To specify 2 "Host" with a single command:
335 cme modify ssh 'Host:"foo* bar*" ForwardX11=yes HostName="foo.com" - Host:baz HostName="baz.com"'
337 Note the '"-"' used to go up one node before ""Host:baz"". In this
339 case, "up one node" leads to the "root node", so ""!"" could also be
340 used instead of ""-"":
341 cme modify ssh 'Host:"foo* bar*" ForwardX11=yes HostName="foo.com" ! Host:baz HostName="baz.com"'
343 Let's modify now the host name of using a ".org" domain instead of
345 ".com". The ":~" operator uses a regexp to loop over several Host
346 entries:
347 cme modify ssh 'Host:~/ba[rz]/ HostName=~s/.com$/.org/'
349 Now that ssh config is mucked up with dummy entries, let's clean up:
351 cme modify ssh 'Host:-"baz" Host:-"foo* bar*"'
353
355 load
356 Load data into the node tree (from the node passed with "node") and
357 fill values as we go following the instructions passed with "steps".
358 ("steps" can also be an array ref).
359 Parameters are:
361 steps (or step)
363 A string or an array ref containing the steps to load. See "load
364 string syntax" in above for a description of the string.
365 check
367 Whether to check values while loading. Either "yes" (default), "no"
368 or "skip". Bad values are discarded when "check" is set to "skip".
369 caller_is_root
371 Change the target of the "!" command: when set, the "!" command go
372 to caller node instead of going to root node. (default is false)
373
375 Dominique Dumont, (ddumont at cpan dot org)
376
378 Config::Model,Config::Model::Node,Config::Model::Dumper
379
381 Dominique Dumont
382
384 This software is Copyright (c) 2005-2022 by Dominique Dumont.
385 This is free software, licensed under:
387 The GNU Lesser General Public License, Version 2.1, February 1999
389perl v5.38.0 2023-07-25 Config::Model::Loader(3pm)