Crock-ified documentation.
authorFrederic Jolliton <frederic@jolliton.com>
Fri, 5 Aug 2005 17:13:19 +0000 (17:13 +0000)
committerFrederic Jolliton <frederic@jolliton.com>
Fri, 5 Aug 2005 17:13:19 +0000 (17:13 +0000)
* README converted to a Crock documentation (see Crock project.)

git-archimport-id: frederic@jolliton.com--2005-private/confparser--main--0.1--patch-18

README [deleted file]
confparser.txt [new file with mode: 0644]

diff --git a/README b/README
deleted file mode 100644 (file)
index c37ca20..0000000
--- a/README
+++ /dev/null
@@ -1,243 +0,0 @@
-ConfParser
-----------
-
-This python module allow to parse configuration file with a simple
-syntax.
-
-Example of configuration:
-
-conf = '''
-options {
-  default {
-    allow-snmp-trap true ;
-  }
-}
-server samba-test1 {
-  created '2005-09-19T02:43:30Z' ;
-  monitoring {
-    priority auto ;
-    service web {
-      name 'Apache' ;
-      port 80 443 ;
-    }
-    service mail {
-      name 'Sendmail' ;
-      port 25 ;
-    }
-  }
-  network {
-    nic eth0 {
-      ip '192.168.1.10/24' '192.168.1.11/24' ;
-      speed 100 ;
-      duplex full ;
-    }
-    nic eth1 {
-      comment 'Admin NIC' ;
-      ip '192.168.250.10/24' ;
-      speed auto ;
-      duplex auto ;
-    }
-  }
-}
-'''
-
-The confparser provide the function 'parser' to transform such text
-into a particular tree.
-
->>> import pprint
->>> import confparser
->>> conf = ''' <text above> '''
->>> example = confparser.parse( conf )
->>> pprint.pprint( example )
-('__root__',
- None,
- [('options',
-   [],
-   [('default',
-     [],
-     [('allow-snmp-trap', ['true'], [], (3, 5, None))],
-     (2, 3, None))],
-   (1, 1, None)),
-  ('server',
-   ['samba-test1'],
-   [('created', ['2005-09-19T02:43:30Z'], [], (7, 3, None)),
-    ('monitoring',
-     [],
-     [('priority', ['auto'], [], (9, 5, None)),
-...)
->>>
-
-Notice that an artificial root node called '__root__' is added to hold
-all the top elements of the configuration.
-
-But it's not practical to work with such structure.
-
-A recent addition to confparser allow to get an object tree (made of
-NodeSet/Node objects) instead of this raw structure (which is made of
-list, tuple, string and integer.) The function parseExt do that.
-
-[continuing previous session]
->>> ns = confparser.parseExt( conf )
->>> print ns
-<NodeSet with 1 elements>
->>>
-
-NodeSet provide a method pstr (pretty string) which convert back
-this object structure into a text that look like the original.
-
->>> print ns.pstr()
-__root__ {
-  options {
-    default {
-      allow-snmp-trap true ;
-    }
-  }
-  server samba-test1 {
-    created "2005-09-19T02:43:30Z" ;
-    monitoring {
-      priority auto ;
-...
-}
->>>
-
-One of the main advantage of the NodeSet object is that it provide
-support to find certain nodes inside it, a la XPath. For that you have
-to specify a path as argument to "index" NodeSet like in the following
-example to find the 'server' node:
-
->>> ns[ 'server' ]
-<NodeSet with 1 elements>
-
-To find the 'created' node inside this node, we can either look in the
-previous NodeSet:
-
->>> ns[ 'server' ][ 'created' ]
-<NodeSet with 1 elements>
->>> print ns[ 'server' ][ 'created' ].pstr()
-created "2005-09-19T02:43:30Z" ;
-
-or combine path:
-
->>> print ns[ 'server/created' ].pstr()
-created "2005-09-19T02:43:30Z" ;
-
-To extract the values following the 'created' keyword, we can
-use the special path element '?' which give them:
-
->>> ns[ 'server/created/?' ]
-'2005-09-19T02:43:30Z'
-
-To find a node with a particular name, append : to node name followed
-by the value to match. To find the 'nic' with values 'eth0':
-
->>> print ns[ 'server/network/nic:eth0' ].pstr()
-nic eth0 {
-  ip "192.168.1.10/24" "192.168.1.11/24" ;
-  speed 100 ;
-  duplex full ;
-}
-
-To find the IPs of this node:
-
->>> ns[ 'server/network/nic:eth0/ip/?' ]
-'192.168.1.10/24 192.168.1.11/24'
-
-Notice that this result is a single string.
-
-To find the list of IP, use '@' or '@@' instead of '?'.
-
->>> ns[ 'server/network/nic:eth0/ip/@' ]
-('192.168.1.10/24', '192.168.1.11/24')
-
-The difference between '@' and '@@' is that the later return a set of
-tuple for each matching line instead of returning a flat list like '@'
-do. It's also possible to extend '@@' further by including also the
-node name by using '@@@' instead.
-
-To find a node at any depth use an empty path element, like in this
-example to find all nodes named 'ip':
-
->>> ns[ '//ip' ]
-<NodeSet with 2 elements>
->>> ns[ '//ip/@' ]
-('192.168.1.10/24', '192.168.1.11/24', '192.168.250.10/24')
->>> ns[ '//ip/@@' ]
-[('192.168.1.10/24', '192.168.1.11/24'), ('192.168.250.10/24',)]
->>> ns[ '//ip/@@@' ]
-[('ip', '192.168.1.10/24', '192.168.1.11/24'), ('ip', '192.168.250.10/24')]
-
-To match any node use '*'.
-
->>> ns[ '*' ]
-<NodeSet with 2 elements>
->>> ns[ '*/@@' ]
-[(), ('samba-test1',)]
-
-(Note: this last result extract the name of the node 'options' which
-have no values hence the empty list, and the name of the 'server'
-node.)
-
-By default '*' match any node with any values.
-
-To match particular values, specify them using ':' as separator, like
-in this example:
-
->>> ns[ '//nic:eth0/ip/@' ]
-('192.168.1.10/24', '192.168.1.11/24')
-
-You can use wildcard for values:
-
->>> ns[ '//nic:*' ]
-<NodeSet with 2 elements>
-
-Notice that 'nic' and 'nic:*' don't match the same thing. The former
-match a node named 'nic' with any number of values, while the later
-match a node named 'nic' with only one value (not even zero.)
-
-Wildcard can also be used to match substring. To find all 'nic' node
-with value ending with '1':
-
->>> ns[ '//nic:*1/?' ]
-'eth1'
-
-To find all the node in the tree, and extract all the values:
-
->>> ns[ '//*' ]
-<NodeSet with 23 elements>
->>> ns[ '//*/?' ]
-'true samba-test1 2005-09-19T02:43:30Z auto web Apache 80\
- 443 mail Sendmail 25 eth0 192.168.1.10/24 192.168.1.11/24\
- 100 full eth1 Admin NIC 192.168.250.10/24 auto auto'
->>> ns[ '//*/@@@' ]
-[('options',), ('default',), ('allow-snmp-trap', 'true'),
- ('server', 'samba-test1'), ('created', '2005-09-19T02:43:30Z'),
- ('monitoring',), ('priority', 'auto'), ('service', 'web'),
- ('name', 'Apache'), ('port', 80, 443), ('service', 'mail'),
- ('name', 'Sendmail'), ('port', 25), ('network',), ('nic', 'eth0'),
- ('ip', '192.168.1.10/24', '192.168.1.11/24'), ('speed', 100),
- ('duplex', 'full'), ('nic', 'eth1'), ('comment', 'Admin NIC'),
- ('ip', '192.168.250.10/24'), ('speed', 'auto'), ('duplex', 'auto')]
-
-More examples:
-
->>> ns[ '/@@@' ]
-[('__root__',)]
->>> ns[ '/*/@@@' ]
-[('options',), ('server', 'samba-test1')]
->>> ns[ '/*/*/@@@' ]
-[('default',), ('created', '2005-09-19T02:43:30Z'), ('monitoring',), ('network',)]
-
-To find any nodes at depth 4:
-
->>> print ns[ '/*/*/*/*' ].pstr()
-name Apache ;
-port 80 443 ;
-name Sendmail ;
-port 25 ;
-ip "192.168.1.10/24" "192.168.1.11/24" ;
-speed 100 ;
-duplex full ;
-comment "Admin NIC" ;
-ip "192.168.250.10/24" ;
-speed auto ;
-duplex auto ;
diff --git a/confparser.txt b/confparser.txt
new file mode 100644 (file)
index 0000000..49deab8
--- /dev/null
@@ -0,0 +1,291 @@
+*** ConfParser ***
+
+[[TableOfContents]]
+
+= Arch repository =
+
+| Archive  | `frederic@jolliton.com--2005-private` |
+| Location | `http://arch-intra.tuxee.net/2005`    |
+| Version  | `confparser--main--0.1`               |
+| ArchZoom | [Web interface http://arch.intra.tuxee.net/archzoom.cgi/frederic@jolliton.com--2005-private/confparser--main--0.1] |
+
+= Summary =
+
+This python module allow to parse configuration file with a simple
+syntax.
+
+Example of configuration:
+
+-=-=-
+conf = '''
+options {
+  default {
+    allow-snmp-trap true ;
+  }
+}
+server samba-test1 {
+  created '2005-09-19T02:43:30Z' ;
+  monitoring {
+    priority auto ;
+    service web {
+      name 'Apache' ;
+      port 80 443 ;
+    }
+    service mail {
+      name 'Sendmail' ;
+      port 25 ;
+    }
+  }
+  network {
+    nic eth0 {
+      ip '192.168.1.10/24' '192.168.1.11/24' ;
+      speed 100 ;
+      duplex full ;
+    }
+    nic eth1 {
+      comment 'Admin NIC' ;
+      ip '192.168.250.10/24' ;
+      speed auto ;
+      duplex auto ;
+    }
+  }
+}
+'''
+-=-=-
+
+The `confparser` provide the function `parser` to transform such text
+into a particular tree.
+
+-=-=-
+>>> import pprint
+>>> import confparser
+>>> conf = ''' <text above> '''
+>>> example = confparser.parse( conf )
+>>> pprint.pprint( example )
+('__root__',
+ None,
+ [('options',
+   [],
+   [('default',
+     [],
+     [('allow-snmp-trap', ['true'], [], (3, 5, None))],
+     (2, 3, None))],
+   (1, 1, None)),
+  ('server',
+   ['samba-test1'],
+   [('created', ['2005-09-19T02:43:30Z'], [], (7, 3, None)),
+    ('monitoring',
+     [],
+     [('priority', ['auto'], [], (9, 5, None)),
+...)
+>>>
+-=-=-
+
+Notice that an artificial root node called `__root__` is added to hold
+all the top elements of the configuration.
+
+But it's not practical to work with such structure.
+
+A recent addition to confparser allow to get an object tree (made of
+`NodeSet`/`Node` objects) instead of this raw structure (which is made of
+list, tuple, string and integer.) The function `parseExt` do that.
+
+-=-=-
+[continuing previous session]
+>>> ns = confparser.parseExt( conf )
+>>> print ns
+<NodeSet with 1 elements>
+>>>
+-=-=-
+
+`NodeSet` provide a method `pstr` (pretty string) which convert back
+this object structure into a text that look like the original.
+
+-=-=-
+>>> print ns.pstr()
+__root__ {
+  options {
+    default {
+      allow-snmp-trap true ;
+    }
+  }
+  server samba-test1 {
+    created "2005-09-19T02:43:30Z" ;
+    monitoring {
+      priority auto ;
+...
+}
+>>>
+-=-=-
+
+One of the main advantage of the `NodeSet` object is that it provide
+support to find certain nodes inside it, a la XPath. For that you have
+to specify a path as argument to "index" `NodeSet` like in the following
+example to find the `server` node:
+
+-=-=-
+>>> ns[ 'server' ]
+<NodeSet with 1 elements>
+-=-=-
+
+To find the `created` node inside this node, we can either look in the
+previous `NodeSet`:
+
+-=-=-
+>>> ns[ 'server' ][ 'created' ]
+<NodeSet with 1 elements>
+>>> print ns[ 'server' ][ 'created' ].pstr()
+created "2005-09-19T02:43:30Z" ;
+-=-=-
+
+or combine path:
+
+-=-=-
+>>> print ns[ 'server/created' ].pstr()
+created "2005-09-19T02:43:30Z" ;
+-=-=-
+
+To extract the values following the `created` keyword, we can
+use the special path element `?` which give them:
+
+-=-=-
+>>> ns[ 'server/created/?' ]
+'2005-09-19T02:43:30Z'
+-=-=-
+
+To find a node with a particular name, append `:` to node name followed
+by the value to match. To find the `nic` with values `eth0`:
+
+-=-=-
+>>> print ns[ 'server/network/nic:eth0' ].pstr()
+nic eth0 {
+  ip "192.168.1.10/24" "192.168.1.11/24" ;
+  speed 100 ;
+  duplex full ;
+}
+-=-=-
+
+To find the IPs of this node:
+
+-=-=-
+>>> ns[ 'server/network/nic:eth0/ip/?' ]
+'192.168.1.10/24 192.168.1.11/24'
+-=-=-
+
+Notice that this result is a single string.
+
+To find the list of IP, use `@` or `@@` instead of `?`.
+
+-=-=-
+>>> ns[ 'server/network/nic:eth0/ip/@' ]
+('192.168.1.10/24', '192.168.1.11/24')
+-=-=-
+
+The difference between `@` and `@@` is that the later return a set of
+tuple for each matching line instead of returning a flat list like '@'
+do. It's also possible to extend `@@` further by including also the
+node name by using `@@@` instead.
+
+To find a node at any depth use an empty path element, like in this
+example to find all nodes named `ip`:
+
+-=-=-
+>>> ns[ '//ip' ]
+<NodeSet with 2 elements>
+>>> ns[ '//ip/@' ]
+('192.168.1.10/24', '192.168.1.11/24', '192.168.250.10/24')
+>>> ns[ '//ip/@@' ]
+[('192.168.1.10/24', '192.168.1.11/24'), ('192.168.250.10/24',)]
+>>> ns[ '//ip/@@@' ]
+[('ip', '192.168.1.10/24', '192.168.1.11/24'), ('ip', '192.168.250.10/24')]
+-=-=-
+
+To match any node use `*`.
+
+-=-=-
+>>> ns[ '*' ]
+<NodeSet with 2 elements>
+>>> ns[ '*/@@' ]
+[(), ('samba-test1',)]
+-=-=-
+
+(Note: this last result extract the name of the node `options` which
+have no values hence the empty list, and the name of the `server`
+node.)
+
+By default `*` match any node with any values.
+
+To match particular values, specify them using `:` as separator, like
+in this example:
+
+-=-=-
+>>> ns[ '//nic:eth0/ip/@' ]
+('192.168.1.10/24', '192.168.1.11/24')
+-=-=-
+
+You can use wildcard for values:
+
+-=-=-
+>>> ns[ '//nic:*' ]
+<NodeSet with 2 elements>
+-=-=-
+
+Notice that `nic` and `nic:*` don't match the same thing. The former
+match a node named `nic` with any number of values, while the later
+match a node named `nic` with only one value (not even zero.)
+
+Wildcard can also be used to match substring. To find all `nic` node
+with value ending with `1`:
+
+-=-=-
+>>> ns[ '//nic:*1/?' ]
+'eth1'
+-=-=-
+
+To find all the node in the tree, and extract all the values:
+
+-=-=-
+>>> ns[ '//*' ]
+<NodeSet with 23 elements>
+>>> ns[ '//*/?' ]
+'true samba-test1 2005-09-19T02:43:30Z auto web Apache 80\
+ 443 mail Sendmail 25 eth0 192.168.1.10/24 192.168.1.11/24\
+ 100 full eth1 Admin NIC 192.168.250.10/24 auto auto'
+>>> ns[ '//*/@@@' ]
+[('options',), ('default',), ('allow-snmp-trap', 'true'),
+ ('server', 'samba-test1'), ('created', '2005-09-19T02:43:30Z'),
+ ('monitoring',), ('priority', 'auto'), ('service', 'web'),
+ ('name', 'Apache'), ('port', 80, 443), ('service', 'mail'),
+ ('name', 'Sendmail'), ('port', 25), ('network',), ('nic', 'eth0'),
+ ('ip', '192.168.1.10/24', '192.168.1.11/24'), ('speed', 100),
+ ('duplex', 'full'), ('nic', 'eth1'), ('comment', 'Admin NIC'),
+ ('ip', '192.168.250.10/24'), ('speed', 'auto'), ('duplex', 'auto')]
+-=-=-
+
+More examples:
+
+-=-=-
+>>> ns[ '/@@@' ]
+[('__root__',)]
+>>> ns[ '/*/@@@' ]
+[('options',), ('server', 'samba-test1')]
+>>> ns[ '/*/*/@@@' ]
+[('default',), ('created', '2005-09-19T02:43:30Z'), ('monitoring',), ('network',)]
+-=-=-
+
+To find any nodes at depth 4:
+
+-=-=-
+>>> print ns[ '/*/*/*/*' ].pstr()
+name Apache ;
+port 80 443 ;
+name Sendmail ;
+port 25 ;
+ip "192.168.1.10/24" "192.168.1.11/24" ;
+speed 100 ;
+duplex full ;
+comment "Admin NIC" ;
+ip "192.168.250.10/24" ;
+speed auto ;
+duplex auto ;
+-=-=-