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.150
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:.ensure(zz)
218 Ensure that list "xxx" contains value "zz". If value "zz" is
219 already stored in "xxx" list, this function does nothing. In the
220 other case, value "zz" is inserted in alphabetical order.
221 xxx:=z1,z2,z3
223 Set list element "xxx" to list "z1,z2,z3". Use ",," for undef
224 values, and "" for empty values.
225 I.e, for a list "('a',undef,'','c')", use "a,,"",c".
227 xxx:yy=zz
229 For "hash" element containing "leaf" cargo_type. Set the leaf
230 identified by key "yy" to value "zz".
231 Using "xxx:~/yy/=zz" is also possible.
233 xxx:.copy(yy,zz)
235 copy item "yy" in "zz" (hash or list).
236 xxx:.json("path/to/file.json/foo/bar")
238 Store "bar" content in array or hash. This should be used to store
239 hash or list of values.
240 You may store deep data structure. In this case, make sure that the
242 structure of the loaded data matches the structure of the model.
243 This won't happen by chance.
244 xxx:.clear
246 Clear the hash or list.
247 leaf operation
249 xxx=zz
250 Set element "xxx" to value "yy". load also accepts to set elements
251 with a quoted string. (For "leaf" element) Literal "\n" are
252 replaced by real "\n" (LF in Unix). Literal "\\" are replaced by
253 "\".
254 For instance "foo="a quoted string"" or "foo="\"bar\" and
256 \"baz\""".
257 xxx=~s/foo/bar/
259 Apply the substitution to the value of xxx. "s/foo/bar/" is the
260 standard Perl "s" substitution pattern.
261 Patterns with white spaces must be surrounded by quotes:
263 xxx=~"s/foo bar/bar baz/"
265 Perl pattern modifiers are accepted
267 xxx=~s/FOO/bar/i
269 xxx~
271 Undef element "xxx"
272 xxx.=zzz
274 Appends "zzz" value to current value (valid for "leaf" elements).
275 xxx=.file(yyy)
277 Store the content of file "yyy" in element "xxx".
278 Store STDIn in value xxx when "yyy" is '-'.
280 xxx=.json(path/to/data.json/foo/bar)
282 Open file "data.json" and store value from JSON data extracted with
283 "foo/bar" subpath.
284 For instance, if "data.json" contains:
286 {
288 "foo": {
289 "bar": 42
290 }
291 }
292 The instruction "baz=.json(data.json/foo/bar)" stores 42 in "baz"
294 element.
295 xxx=.yaml(path/to/data.yaml/0/foo/bar)
297 Open file "data.yaml" and store value from YAML data extracted with
298 "0/foo/bar" subpath.
299 Since a YAML file can contain several documents (separated by "---"
301 lines, the subpath must begin with a number to select the document
302 containing the required value.
303 For instance, if "data.yaml" contains:
305 ---
307 foo:
308 bar: 42
309 The instruction "baz=.yaml(data.yaml/0/foo/bar)" stores 42 in "baz"
311 element.
312 xxx=.env(yyy)
314 Store the content of environment variable "yyy" in element "xxx".
315 annotation
317 xxx#zzz or xxx:yyy#zzz
318 Element annotation. Can be quoted or not quoted. Note that
319 annotations are always placed at the end of an action item.
320 I.e. "foo#comment", "foo:bar#comment" or "foo:bar=baz#comment" are
322 valid. "foo#comment:bar" is not valid.
323 Quotes
325 You can surround indexes and values with double quotes. E.g.:
326 a_string="\"foo\" and \"bar\""
328
330 You can use cme to modify configuration with "cme modify" command.
331 For instance, if Config::Model::Ssh is installed, you can run:
333 cme modify ssh 'ControlMaster=auto ControlPath="~/.ssh/master-%r@%n:%p"'
335 To delete "Host *" entry:
337 cme modify ssh 'Host:-"*"'
339 To specify 2 "Host" with a single command:
341 cme modify ssh 'Host:"foo* bar*" ForwardX11=yes HostName="foo.com" - Host:baz HostName="baz.com"'
343 Note the '"-"' used to go up one node before ""Host:baz"". In this
345 case, "up one node" leads to the "root node", so ""!"" could also be
346 used instead of ""-"":
347 cme modify ssh 'Host:"foo* bar*" ForwardX11=yes HostName="foo.com" ! Host:baz HostName="baz.com"'
349 Let's modify now the host name of using a ".org" domain instead of
351 ".com". The ":~" operator uses a regexp to loop over several Host
352 entries:
353 cme modify ssh 'Host:~/ba[rz]/ HostName=~s/.com$/.org/'
355 Now that ssh config is mucked up with dummy entries, let's clean up:
357 cme modify ssh 'Host:-"baz" Host:-"foo* bar*"'
359
361 load
362 Load data into the node tree (from the node passed with "node") and
363 fill values as we go following the instructions passed with "steps".
364 ("steps" can also be an array ref).
365 Parameters are:
367 steps (or step)
369 A string or an array ref containing the steps to load. See "load
370 string syntax" in above for a description of the string.
371 check
373 Whether to check values while loading. Either "yes" (default), "no"
374 or "skip". Bad values are discarded when "check" is set to "skip".
375 caller_is_root
377 Change the target of the "!" command: when set, the "!" command go
378 to caller node instead of going to root node. (default is false)
379
381 Dominique Dumont, (ddumont at cpan dot org)
382
384 Config::Model,Config::Model::Node,Config::Model::Dumper
385
387 Dominique Dumont
388
390 This software is Copyright (c) 2005-2022 by Dominique Dumont.
391 This is free software, licensed under:
393 The GNU Lesser General Public License, Version 2.1, February 1999
395perl v5.34.1 2022-05-09 Config::Model::Loader(3)