1Config::Model::Loader(3U)ser Contributed Perl DocumentatiCoonnfig::Model::Loader(3)
2
6 Config::Model::Loader - Load serialized data into config tree
7
9 version 2.141
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 print $root->describe,"\n" ;
64 # name value type comment
65 # foo FOO string
66 # bar [undef] string
67 # hash_of_nodes <Foo> node hash keys: "en" "fr"
68 # lista foo,bar,baz list
69 # listb foo,baz list
70 # delete some data
73 $root->load( steps => 'lista~2' );
74 print $root->describe(element => 'lista'),"\n" ;
76 # name value type comment
77 # lista foo,bar list
78 # append some data
80 $root->load( steps => q!hash_of_nodes:en foo.=" world"! );
81 print $root->grab('hash_of_nodes:en')->describe(element => 'foo'),"\n" ;
83 # name value type comment
84 # foo "hello world" string
85
87 This module is used directly by Config::Model::Node to load serialized
88 configuration data into the configuration tree.
89 Serialized data can be written by the user or produced by
91 Config::Model::Dumper while dumping data from a configuration tree.
92
94 new
95 The constructor should be used only by Config::Model::Node.
96 Parameters:
98 start_node
100 node ref of the root of the tree (of sub-root) to start the load
101 from. Stored as a weak reference.
102
104 The string is made of the following items (also called "actions")
105 separated by spaces. These actions can be divided in 4 groups:
106 • navigation: moving up and down the configuration tree.
108 • list and hash operation: select, add or delete hash or list item
110 (also known as "id" items)
111 • leaf operation: select, modify or delecte leaf value
113 • annotation: modify or delete configuration annotation (aka comment)
115 navigation
117 - Go up one node
118 ! Go to the root node of the configuration tree.
120 xxx Go down using "xxx" element. (For "node" type element)
122 /xxx Go up until the element "xxx" is found. This search can be
124 combined with one of the command specified below, e.g
125 "/a_string="foo bar""
126 list and hash operation
128 xxx:yy
129 Go down using "xxx" element and id "yy" (For "hash" or "list"
130 element with "node" cargo_type). Literal "\n" are replaced by real
131 "\n" (LF in Unix).
132 xxx:.foreach_match(yy) or xxx:~yy
134 Go down using "xxx" element and loop over the ids that match the
135 regex specified by "yy". (For "hash").
136 For instance, with "OpenSsh" model, you could do
138 Host:~"/.*.debian.org/" user='foo-guest'
140 to set "foo-user" users for all your debian accounts.
142 The leading and trailing '/' may be omitted. Be sure to surround
144 the regexp with double quote if space are embedded in the regex.
145 Note that the loop ends when the load command goes above the
147 element where the loop is executed. For instance, the instruction
148 below tries to execute "DX=BV" and "int_v=9" for all elements of
149 "std_id" hash:
150 std_id:~/^\w+$/ DX=Bv int_v=9
152 In the examples below only "DX=BV" is executed by the loop:
154 std_id:~/^\w+$/ DX=Bv - int_v=9
156 std_id:~/^\w+$/ DX=Bv ! int_v=9
157 The loop is done on all elements of the hash when no value is
159 passed after "":~"" (mnemonic: an empty regexp matches any value).
160 xxx:.rm(yy) or xxx:-yy
162 Delete item referenced by "xxx" element and id "yy". For a list,
163 this is equivalent to "splice xxx,yy,1". This command does not go
164 down in the tree (since it has just deleted the element). I.e. a
165 '"-"' is generally not needed afterwards.
166 xxx:.rm_value(yy) or xxx:-=yy
168 Remove the element whose value is "yy". For list or hash of leaves.
169 Does not not complain if the value to delete is not found.
170 xxx:..rm_match(yy) or xxx:-~/yy/
172 Remove the element whose value matches "yy". For list or hash of
173 leaves. Does not not complain if no value were deleted.
174 xxx:.substitute(/yy/zz/) or xxx:=~s/yy/zz/
176 Substitute a value with another. Perl switches can be used(e.g.
177 "xxx:=~s/yy/zz/gi")
178 xxx:<yy or xxx:.push(yy)
180 Push "yy" value on "xxx" list
181 xxx:>yy or xxx:.unshift(yy)
183 Unshift "yy" value on "xxx" list
184 xxx:@ or xxx:.sort
186 Sort the list
187 xxx:.insert_at(yy,zz)
189 Insert "zz" value on "xxx" list before index "yy".
190 xxx:.insert_before(yy,zz)
192 Insert "zz" value on "xxx" list before value "yy".
193 xxx:.insert_before(/yy/,zz)
195 Insert "zz" value on "xxx" list before value matching "yy".
196 xxx:.insort(zz)
198 Insert "zz" value on "xxx" list so that existing alphanumeric order
199 is preserved.
200 xxx:.insort(zz)
202 For hash element containing nodes: creates a new hash element with
203 "zz" key on "xxx" hash so that existing alphanumeric order of keys
204 is preserved. Note that all keys are sorted once this instruction
205 is called. Following instructions are applied on the created
206 element. I.e. putting key order aside, "xxx:.insort(zz)" has the
207 same effect as "xxx:zz" instruction.
208 xxx:.insort(zz,vv)
210 For hash element containing leaves: creates a new hash element with
211 "zz" key and assing value "vv" so that existing alphanumeric order
212 of keys is preserved. Note that all keys are sorted once this
213 instruction is called. Putting key order aside,
214 "xxx:.insort(zz,vv)" has the same effect as "xxx:zz=vv"
215 instruction.
216 xxx:=z1,z2,z3
218 Set list element "xxx" to list "z1,z2,z3". Use ",," for undef
219 values, and "" for empty values.
220 I.e, for a list "('a',undef,'','c')", use "a,,"",c".
222 xxx:yy=zz
224 For "hash" element containing "leaf" cargo_type. Set the leaf
225 identified by key "yy" to value "zz".
226 Using "xxx:~/yy/=zz" is also possible.
228 xxx:.copy(yy,zz)
230 copy item "yy" in "zz" (hash or list).
231 xxx:.json("path/to/file.json/foo/bar")
233 Store "bar" content in array or hash. This should be used to store
234 hash or list of values.
235 You may store deep data structure. In this case, make sure that the
237 structure of the loaded data matches the structure of the model.
238 This won't happen by chance.
239 xxx:.clear
241 Clear the hash or list.
242 leaf operation
244 xxx=zz
245 Set element "xxx" to value "yy". load also accepts to set elements
246 with a quoted string. (For "leaf" element) Literal "\n" are
247 replaced by real "\n" (LF in Unix). Literal "\\" are replaced by
248 "\".
249 For instance "foo="a quoted string"" or "foo="\"bar\" and
251 \"baz\""".
252 xxx=~s/foo/bar/
254 Apply the substitution to the value of xxx. "s/foo/bar/" is the
255 standard Perl "s" substitution pattern.
256 Patterns with white spaces must be surrounded by quotes:
258 xxx=~"s/foo bar/bar baz/"
260 Perl pattern modifiers are accepted
262 xxx=~s/FOO/bar/i
264 xxx~
266 Undef element "xxx"
267 xxx.=zzz
269 Appends "zzz" value to current value (valid for "leaf" elements).
270 xxx=.file(yyy)
272 Store the content of file "yyy" in element "xxx".
273 Store STDIn in value xxx when "yyy" is '-'.
275 xxx=.json(path/to/data.json/foo/bar)
277 Open file "data.json" and store value from JSON data extracted with
278 "foo/bar" subpath.
279 For instance, if "data.json" contains:
281 {
283 "foo": {
284 "bar": 42
285 }
286 }
287 The instruction "baz=.json(data.json/foo/bar)" stores 42 in "baz"
289 element.
290 xxx=.yaml(path/to/data.yaml/0/foo/bar)
292 Open file "data.yaml" and store value from YAML data extracted with
293 "0/foo/bar" subpath.
294 Since a YAML file can contain several documents (separated by "---"
296 lines, the subpath must begin with a number to select the document
297 containing the required value.
298 For instance, if "data.yaml" contains:
300 ---
302 foo:
303 bar: 42
304 The instruction "baz=.yaml(data.yaml/0/foo/bar)" stores 42 in "baz"
306 element.
307 xxx=.env(yyy)
309 Store the content of environment variable "yyy" in element "xxx".
310 annotation
312 xxx#zzz or xxx:yyy#zzz
313 Element annotation. Can be quoted or not quoted. Note that
314 annotations are always placed at the end of an action item.
315 I.e. "foo#comment", "foo:bar#comment" or "foo:bar=baz#comment" are
317 valid. "foo#comment:bar" is not valid.
318 Quotes
320 You can surround indexes and values with double quotes. E.g.:
321 a_string="\"foo\" and \"bar\""
323
325 You can use cme to modify configuration with "cme modify" command.
326 For instance, if Config::Model::Ssh is installed, you can run:
328 cme modify ssh 'ControlMaster=auto ControlPath="~/.ssh/master-%r@%n:%p"'
330 To delete "Host *" entry:
332 cme modify ssh 'Host:-"*"'
334 To specify 2 "Host" with a single command:
336 cme modify ssh 'Host:"foo* bar*" ForwardX11=yes HostName="foo.com" - Host:baz HostName="baz.com"'
338 Note the '"-"' used to go up one node before ""Host:baz"". In this
340 case, "up one node" leads to the "root node", so ""!"" could also be
341 used instead of ""-"":
342 cme modify ssh 'Host:"foo* bar*" ForwardX11=yes HostName="foo.com" ! Host:baz HostName="baz.com"'
344 Let's modify now the host name of using a ".org" domain instead of
346 ".com". The ":~" operator uses a regexp to loop over several Host
347 entries:
348 cme modify ssh 'Host:~/ba[rz]/ HostName=~s/.com$/.org/'
350 Now that ssh config is mucked up with dummy entries, let's clean up:
352 cme modify ssh 'Host:-"baz" Host:-"foo* bar*"'
354
356 load
357 Load data into the node tree (from the node passed with "node") and
358 fill values as we go following the instructions passed with "steps".
359 ("steps" can also be an array ref).
360 Parameters are:
362 steps (or step)
364 A string or an array ref containing the steps to load. See "load
365 string syntax" in above for a description of the string.
366 check
368 Whether to check values while loading. Either "yes" (default), "no"
369 or "skip". Bad values are discarded when "check" is set to "skip".
370 caller_is_root
372 Change the target of the "!" command: when set, the "!" command go
373 to caller node instead of going to root node. (default is false)
374
376 Dominique Dumont, (ddumont at cpan dot org)
377
379 Config::Model,Config::Model::Node,Config::Model::Dumper
380
382 Dominique Dumont
383
385 This software is Copyright (c) 2005-2021 by Dominique Dumont.
386 This is free software, licensed under:
388 The GNU Lesser General Public License, Version 2.1, February 1999
390perl v5.32.1 2021-01-27 Config::Model::Loader(3)