1Config::Model::Loader(3U)ser Contributed Perl DocumentatiCoonnfig::Model::Loader(3)
2
3
4

NAME

6       Config::Model::Loader - Load serialized data into config tree
7

VERSION

9       version 2.140
10

SYNOPSIS

12        use Config::Model;
13
14        # 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
26        $model ->create_config_class (
27           name => "MyClass",
28
29           element => [
30
31               [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
52        my $inst = $model->instance(root_class_name => 'MyClass' );
53
54        my $root = $inst->config_root ;
55
56        # 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
63        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
71
72        # delete some data
73        $root->load( steps => 'lista~2' );
74
75        print $root->describe(element => 'lista'),"\n" ;
76        # name         value        type         comment
77        # lista        foo,bar      list
78
79        # append some data
80        $root->load( steps => q!hash_of_nodes:en foo.=" world"! );
81
82        print $root->grab('hash_of_nodes:en')->describe(element => 'foo'),"\n" ;
83        # name         value        type         comment
84        # foo          "hello world" string
85

DESCRIPTION

87       This module is used directly by Config::Model::Node to load serialized
88       configuration data into the configuration tree.
89
90       Serialized data can be written by the user or produced by
91       Config::Model::Dumper while dumping data from a configuration tree.
92

CONSTRUCTOR

94   new
95       The constructor should be used only by Config::Model::Node.
96
97       Parameters:
98
99       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

load string syntax

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
107       ·   navigation: moving up and down the configuration tree.
108
109       ·   list and hash operation: select, add or delete hash or list item
110           (also known as "id" items)
111
112       ·   leaf operation: select, modify or delecte leaf value
113
114       ·   annotation: modify or delete configuration annotation (aka comment)
115
116   navigation
117       -       Go up one node
118
119       !       Go to the root node of the configuration tree.
120
121       xxx     Go down using "xxx" element. (For "node" type element)
122
123       /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
127   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
133       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
137           For instance, with "OpenSsh" model, you could do
138
139            Host:~"/.*.debian.org/" user='foo-guest'
140
141           to set "foo-user" users for all your debian accounts.
142
143           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
146           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
151            std_id:~/^\w+$/ DX=Bv int_v=9
152
153           In the examples below only "DX=BV" is executed by the loop:
154
155            std_id:~/^\w+$/ DX=Bv - int_v=9
156            std_id:~/^\w+$/ DX=Bv ! int_v=9
157
158           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
161       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
167       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
171       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
175       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
179       xxx:<yy or xxx:.push(yy)
180           Push "yy" value on "xxx" list
181
182       xxx:>yy or xxx:.unshift(yy)
183           Unshift "yy" value on "xxx" list
184
185       xxx:@ or xxx:.sort
186           Sort the list
187
188       xxx:.insert_at(yy,zz)
189           Insert "zz" value on "xxx" list before index "yy".
190
191       xxx:.insert_before(yy,zz)
192           Insert "zz" value on "xxx" list before value "yy".
193
194       xxx:.insert_before(/yy/,zz)
195           Insert "zz" value on "xxx" list before value matching "yy".
196
197       xxx:.insort(zz)
198           Insert "zz" value on "xxx" list so that existing alphanumeric order
199           is preserved.
200
201       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
209       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
217       xxx:=z1,z2,z3
218           Set list element "xxx" to list "z1,z2,z3". Use ",," for undef
219           values, and "" for empty values.
220
221           I.e, for a list "('a',undef,'','c')", use "a,,"",c".
222
223       xxx:yy=zz
224           For "hash" element containing "leaf" cargo_type. Set the leaf
225           identified by key "yy" to value "zz".
226
227           Using "xxx:~/yy/=zz" is also possible.
228
229       xxx:.copy(yy,zz)
230           copy item "yy" in "zz" (hash or list).
231
232       xxx:.clear
233           Clear the hash or list.
234
235   leaf operation
236       xxx=zz
237           Set element "xxx" to value "yy". load also accepts to set elements
238           with a quoted string. (For "leaf" element) Literal "\n" are
239           replaced by real "\n" (LF in Unix). Literal "\\" are replaced by
240           "\".
241
242           For instance "foo="a quoted string"" or "foo="\"bar\" and
243           \"baz\""".
244
245       xxx=~s/foo/bar/
246           Apply the substitution to the value of xxx. "s/foo/bar/" is the
247           standard Perl "s" substitution pattern.
248
249           Patterns with white spaces must be surrounded by quotes:
250
251             xxx=~"s/foo bar/bar baz/"
252
253           Perl pattern modifiers are accepted
254
255             xxx=~s/FOO/bar/i
256
257       xxx~
258           Undef element "xxx"
259
260       xxx.=zzz
261           Appends "zzz" value to current value (valid for "leaf" elements).
262
263       xxx=.file(yyy)
264           Store the content of file "yyy" in element "xxx".
265
266           Store STDIn in value xxx when "yyy" is '-'.
267
268       xxx=.env(yyy)
269           Store the content of environment variable "yyy" in element "xxx".
270
271   annotation
272       xxx#zzz or xxx:yyy#zzz
273           Element annotation. Can be quoted or not quoted. Note that
274           annotations are always placed at the end of an action item.
275
276           I.e. "foo#comment", "foo:bar#comment" or "foo:bar=baz#comment" are
277           valid.  "foo#comment:bar" is not valid.
278
279   Quotes
280       You can surround indexes and values with double quotes. E.g.:
281
282         a_string="\"foo\" and \"bar\""
283

Examples

285       You can use cme to modify configuration with "cme modify" command.
286
287       For instance, if Config::Model::Ssh is installed, you can run:
288
289        cme modify ssh 'ControlMaster=auto ControlPath="~/.ssh/master-%r@%n:%p"'
290
291       To delete "Host *" entry:
292
293        cme modify ssh 'Host:-"*"'
294
295       To specify 2 "Host" with a single command:
296
297        cme modify ssh 'Host:"foo* bar*" ForwardX11=yes HostName="foo.com" - Host:baz HostName="baz.com"'
298
299       Note the '"-"' used to go up one node before ""Host:baz"". In this
300       case, "up one node" leads to the "root node", so ""!"" could also be
301       used instead of ""-"":
302
303        cme modify ssh 'Host:"foo* bar*" ForwardX11=yes HostName="foo.com" ! Host:baz HostName="baz.com"'
304
305       Let's modify now the host name of using a ".org" domain instead of
306       ".com". The ":~" operator uses a regexp to loop over several Host
307       entries:
308
309        cme modify ssh 'Host:~/ba[rz]/ HostName=~s/.com$/.org/'
310
311       Now that ssh config is mucked up with dummy entries, let's clean up:
312
313        cme modify ssh 'Host:-"baz" Host:-"foo* bar*"'
314

Methods

316   load
317       Load data into the node tree (from the node passed with "node") and
318       fill values as we go following the instructions passed with "steps".
319       ("steps" can also be an array ref).
320
321       Parameters are:
322
323       steps (or step)
324           A string or an array ref containing the steps to load. See "load
325           string syntax" in above for a description of the string.
326
327       check
328           Whether to check values while loading. Either "yes" (default), "no"
329           or "skip".  Bad values are discarded when "check" is set to "skip".
330
331       caller_is_root
332           Change the target of the "!" command: when set, the "!" command go
333           to caller node instead of going to root node. (default is false)
334

AUTHOR

336       Dominique Dumont, (ddumont at cpan dot org)
337

SEE ALSO

339       Config::Model,Config::Model::Node,Config::Model::Dumper
340

AUTHOR

342       Dominique Dumont
343
345       This software is Copyright (c) 2005-2020 by Dominique Dumont.
346
347       This is free software, licensed under:
348
349         The GNU Lesser General Public License, Version 2.1, February 1999
350
351
352
353perl v5.32.0                      2020-08-02          Config::Model::Loader(3)
Impressum