Changeset 482

Timestamp:

12/09/07 05:21:56 (1 year ago)

Author:

athomas

Message:

cly: More developers guide documentation, specifically about the XML grammar.
Extending the nodes supported by the XML parser is now as simple as passing
them as a list to Grammar.from_xml().

Files:

• cly/trunk/cly/builder.py (modified) (2 diffs)
• cly/trunk/doc/developers-guide.rst (modified) (3 diffs)

cly/trunk/cly/builder.py

@@ -668 +668 @@
-            raise XMLParseError(str(e))
-
-{}
+[]
-
-        def boolean(v):
@@ -690 +690 @@
-
-        node_types = dict([(v.__name__.lower(), v)
-globals().values(
+(globals().values() + extra_nodes
-                          if isclass(v) and issubclass(v, Node)])
-
-        node_types.update(extra_nodes)
-
-        def parse(parent, xnode):

cly/trunk/doc/developers-guide.rst

@@ -7 +7 @@
---------
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-Matching Input
-~~~~~~~~~~~~~~
-
-
-
-
-
-
+
+
+
+
-
-.. code-block:: python
@@ -179 +198 @@
-  )
-
-
-
-
-callback as the first argument. Refer to `Creating a Parser
+ also has
+
+
+argument. Refer to `Passing User-defined Objects to Callbacks
-information about user contexts.
-
@@ -294 +313 @@
-already been collected.
-
+Defining a Grammar in XML
+-------------------------
+CLY XML grammars are simply a one-to-one mapping of XML elements to Python
+``cly.builder.Node`` objects. Attributes of each element are passed as arguments
+to the ``Node`` constructor.
+
+Here's a simple example of a grammar defining a single "echo" command:
+
+.. code-block:: xml
+
+  <?xml version="1.0"?>
+  <grammar xmlns="http://swapoff.org/cly/xml">
+    <node name="echo">
+      <variable name="text">
+        <action callback="echo" pattern=".+"/>
+      </variable>
+    </node>
+  </grammar>
+
+Parsing an XML Grammar
+~~~~~~~~~~~~~~~~~~~~~~
+
+Calling ``Grammar.from_xml()`` with an XML string as the first argument will
+build a new ``Grammar`` object from that XML. An optional second argument
+``extra_nodes`` can be used to pass a list of extra ``Node`` sub-classes to
+recognise as elements. All other keyword arguments will be treated as local
+symbols when evaluating attribute values in the XML grammar.
+
+Here's an example that uses the previously defined XML grammar to implement an
+"echo" command:
+
+.. code-block:: python
+
+  from cly import Grammar, interact
+
+  def echo(text):
+      print text
+
+  xml_grammar = open('example.xml').read()
+  grammar = Grammar.from_xml(xml_grammar, echo=echo)
+
+  interact(grammar)
+
+Here's a slightly more complex example with looping and grouping:
+
+.. code-block:: xml
+
+  <?xml version="1.0"?>
+  <grammar xmlns="http://swapoff.org/cly/xml">
+    <node name="echo">
+      <group traversals="0">
+        <variable name="text">
+          <alias target="/echo/*"/>
+          <action callback="echo"/>
+        </variable>
+      </group>
+    </node>
+  </grammar>
+
+The Python code is identical.
+
+XML Attribute Type Conversion
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+All ``Node`` constructor arguments that are not strings but are known to the
+``Parser`` will be evaluated as Python code, meaning integer arguments will be
+converted to integers, callback arguments may contain lambdas, etc. This
+evaluation can be forced by using the ``eval`` XML namespace:
+
+.. code-block:: xml
+
+  <?xml version="1.0"?>
+  <grammar xmlns="http://swapoff.org/cly/xml" xmlns:eval="http://swapoff.org/cly/xml-eval">
+    <node eval:help="'HELLO WORLD'.title()"/>
+      ...
+    </node>
+  </grammar>
+
+
-Parsing
--------
-
-
-
-
+
+
+
+
+
+
+
+
-
-Basic usage is: