Use distutils instead of my own installation script.
[confparser-old] / confparser.txt
1 *** ConfParser ***
2
3 [[TableOfContents]]
4
5 = Arch repository =
6
7 | Archive  | `frederic@jolliton.com--2005-private` |
8 | Location | `http://arch-intra.tuxee.net/2005`    |
9 | Version  | `confparser--main--0.1`               |
10 | ArchZoom | [Web interface http://arch.intra.tuxee.net/archzoom.cgi/frederic@jolliton.com--2005-private/confparser--main--0.1] |
11
12 = Summary =
13
14 This python module allow to parse configuration file with a simple
15 syntax.
16
17 Example of configuration:
18
19 -=-=-
20 conf = '''
21 options {
22   default {
23     allow-snmp-trap true ;
24   }
25 }
26 server samba-test1 {
27   created '2005-09-19T02:43:30Z' ;
28   monitoring {
29     priority auto ;
30     service web {
31       name 'Apache' ;
32       port 80 443 ;
33     }
34     service mail {
35       name 'Sendmail' ;
36       port 25 ;
37     }
38   }
39   network {
40     nic eth0 {
41       ip '192.168.1.10/24' '192.168.1.11/24' ;
42       speed 100 ;
43       duplex full ;
44     }
45     nic eth1 {
46       comment 'Admin NIC' ;
47       ip '192.168.250.10/24' ;
48       speed auto ;
49       duplex auto ;
50     }
51   }
52 }
53 '''
54 -=-=-
55
56 The `confparser` provide the function `parser` to transform such text
57 into a particular tree.
58
59 -=-=-
60 >>> import pprint
61 >>> import confparser
62 >>> conf = ''' <text above> '''
63 >>> example = confparser.parse( conf )
64 >>> pprint.pprint( example )
65 ('__root__',
66  None,
67  [('options',
68    [],
69    [('default',
70      [],
71      [('allow-snmp-trap', ['true'], [], (3, 5, None))],
72      (2, 3, None))],
73    (1, 1, None)),
74   ('server',
75    ['samba-test1'],
76    [('created', ['2005-09-19T02:43:30Z'], [], (7, 3, None)),
77     ('monitoring',
78      [],
79      [('priority', ['auto'], [], (9, 5, None)),
80 ...)
81 >>>
82 -=-=-
83
84 Notice that an artificial root node called `__root__` is added to hold
85 all the top elements of the configuration.
86
87 But it's not practical to work with such structure.
88
89 A recent addition to confparser allow to get an object tree (made of
90 `NodeSet`/`Node` objects) instead of this raw structure (which is made of
91 list, tuple, string and integer.) The function `parseExt` do that.
92
93 -=-=-
94 [continuing previous session]
95 >>> ns = confparser.parseExt( conf )
96 >>> print ns
97 <NodeSet with 1 elements>
98 >>>
99 -=-=-
100
101 `NodeSet` provide a method `pstr` (pretty string) which convert back
102 this object structure into a text that look like the original.
103
104 -=-=-
105 >>> print ns.pstr()
106 __root__ {
107   options {
108     default {
109       allow-snmp-trap true ;
110     }
111   }
112   server samba-test1 {
113     created "2005-09-19T02:43:30Z" ;
114     monitoring {
115       priority auto ;
116 ...
117 }
118 >>>
119 -=-=-
120
121 One of the main advantage of the `NodeSet` object is that it provide
122 support to find certain nodes inside it, a la XPath. For that you have
123 to specify a path as argument to "index" `NodeSet` like in the following
124 example to find the `server` node:
125
126 -=-=-
127 >>> ns[ 'server' ]
128 <NodeSet with 1 elements>
129 -=-=-
130
131 To find the `created` node inside this node, we can either look in the
132 previous `NodeSet`:
133
134 -=-=-
135 >>> ns[ 'server' ][ 'created' ]
136 <NodeSet with 1 elements>
137 >>> print ns[ 'server' ][ 'created' ].pstr()
138 created "2005-09-19T02:43:30Z" ;
139 -=-=-
140
141 or combine path:
142
143 -=-=-
144 >>> print ns[ 'server/created' ].pstr()
145 created "2005-09-19T02:43:30Z" ;
146 -=-=-
147
148 To extract the values following the `created` keyword, we can
149 use the special path element `?` which give them:
150
151 -=-=-
152 >>> ns[ 'server/created/?' ]
153 '2005-09-19T02:43:30Z'
154 -=-=-
155
156 To find a node with a particular name, append `:` to node name followed
157 by the value to match. To find the `nic` with values `eth0`:
158
159 -=-=-
160 >>> print ns[ 'server/network/nic:eth0' ].pstr()
161 nic eth0 {
162   ip "192.168.1.10/24" "192.168.1.11/24" ;
163   speed 100 ;
164   duplex full ;
165 }
166 -=-=-
167
168 To find the IPs of this node:
169
170 -=-=-
171 >>> ns[ 'server/network/nic:eth0/ip/?' ]
172 '192.168.1.10/24 192.168.1.11/24'
173 -=-=-
174
175 Notice that this result is a single string.
176
177 To find the list of IP, use `@` or `@@` instead of `?`.
178
179 -=-=-
180 >>> ns[ 'server/network/nic:eth0/ip/@' ]
181 ('192.168.1.10/24', '192.168.1.11/24')
182 -=-=-
183
184 The difference between `@` and `@@` is that the later return a set of
185 tuple for each matching line instead of returning a flat list like '@'
186 do. It's also possible to extend `@@` further by including also the
187 node name by using `@@@` instead.
188
189 To find a node at any depth use an empty path element, like in this
190 example to find all nodes named `ip`:
191
192 -=-=-
193 >>> ns[ '//ip' ]
194 <NodeSet with 2 elements>
195 >>> ns[ '//ip/@' ]
196 ('192.168.1.10/24', '192.168.1.11/24', '192.168.250.10/24')
197 >>> ns[ '//ip/@@' ]
198 [('192.168.1.10/24', '192.168.1.11/24'), ('192.168.250.10/24',)]
199 >>> ns[ '//ip/@@@' ]
200 [('ip', '192.168.1.10/24', '192.168.1.11/24'), ('ip', '192.168.250.10/24')]
201 -=-=-
202
203 To match any node use `*`.
204
205 -=-=-
206 >>> ns[ '*' ]
207 <NodeSet with 2 elements>
208 >>> ns[ '*/@@' ]
209 [(), ('samba-test1',)]
210 -=-=-
211
212 (Note: this last result extract the name of the node `options` which
213 have no values hence the empty list, and the name of the `server`
214 node.)
215
216 By default `*` match any node with any values.
217
218 To match particular values, specify them using `:` as separator, like
219 in this example:
220
221 -=-=-
222 >>> ns[ '//nic:eth0/ip/@' ]
223 ('192.168.1.10/24', '192.168.1.11/24')
224 -=-=-
225
226 You can use wildcard for values:
227
228 -=-=-
229 >>> ns[ '//nic:*' ]
230 <NodeSet with 2 elements>
231 -=-=-
232
233 Notice that `nic` and `nic:*` don't match the same thing. The former
234 match a node named `nic` with any number of values, while the later
235 match a node named `nic` with only one value (not even zero.)
236
237 Wildcard can also be used to match substring. To find all `nic` node
238 with value ending with `1`:
239
240 -=-=-
241 >>> ns[ '//nic:*1/?' ]
242 'eth1'
243 -=-=-
244
245 To find all the node in the tree, and extract all the values:
246
247 -=-=-
248 >>> ns[ '//*' ]
249 <NodeSet with 23 elements>
250 >>> ns[ '//*/?' ]
251 'true samba-test1 2005-09-19T02:43:30Z auto web Apache 80\
252  443 mail Sendmail 25 eth0 192.168.1.10/24 192.168.1.11/24\
253  100 full eth1 Admin NIC 192.168.250.10/24 auto auto'
254 >>> ns[ '//*/@@@' ]
255 [('options',), ('default',), ('allow-snmp-trap', 'true'),
256  ('server', 'samba-test1'), ('created', '2005-09-19T02:43:30Z'),
257  ('monitoring',), ('priority', 'auto'), ('service', 'web'),
258  ('name', 'Apache'), ('port', 80, 443), ('service', 'mail'),
259  ('name', 'Sendmail'), ('port', 25), ('network',), ('nic', 'eth0'),
260  ('ip', '192.168.1.10/24', '192.168.1.11/24'), ('speed', 100),
261  ('duplex', 'full'), ('nic', 'eth1'), ('comment', 'Admin NIC'),
262  ('ip', '192.168.250.10/24'), ('speed', 'auto'), ('duplex', 'auto')]
263 -=-=-
264
265 More examples:
266
267 -=-=-
268 >>> ns[ '/@@@' ]
269 [('__root__',)]
270 >>> ns[ '/*/@@@' ]
271 [('options',), ('server', 'samba-test1')]
272 >>> ns[ '/*/*/@@@' ]
273 [('default',), ('created', '2005-09-19T02:43:30Z'), ('monitoring',), ('network',)]
274 -=-=-
275
276 To find any nodes at depth 4:
277
278 -=-=-
279 >>> print ns[ '/*/*/*/*' ].pstr()
280 name Apache ;
281 port 80 443 ;
282 name Sendmail ;
283 port 25 ;
284 ip "192.168.1.10/24" "192.168.1.11/24" ;
285 speed 100 ;
286 duplex full ;
287 comment "Admin NIC" ;
288 ip "192.168.250.10/24" ;
289 speed auto ;
290 duplex auto ;
291 -=-=-