Changeset 437

Timestamp:

05/26/07 09:06:03 (2 years ago)

Author:

athomas

Message:

cly: Documentation updates, added anonymous method to builder.

Files:

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

cly/trunk/cly/builder.py

@@ -374 +374 @@
-        return not self.traversals or context.traversed(self) < self.traversals
-
+    def _get_anonymous(self):
+        """Is this node anonymous?"""
+        return self.name.startswith('__anonymous_')
+
+    anonymous = property(_get_anonymous, doc=_get_anonymous.__doc__)
+
-    def __repr__(self):
-        return '<%s:%s>' % (self.__class__.__name__, self.path() or '<root>')

cly/trunk/doc/developers-guide.rst

@@ -9 +9 @@
-
-It offers a simple syntax for defining grammars and a powerful interactive
-
+,
-help.
-
@@ -27 +27 @@
-.. code-block:: python
-
-  
-  
-  
-  
-  
-  
-  
-  
+
+
+
+
+
+
+
+
-
-This CLY grammar is equivalent to the following EBNF-style grammar::
-
-  
-  
-  
-  
+
+
+
+
-
-
-
+
+
+
+
-
+Context
+~~~~~~~
+Each command is parsed in a new context. The context stores state like
+variables collected, number of traversals of nodes, etc. Mostly, it can be
+ignored but is mentioned here for reference.
+
+Types of Nodes
+~~~~~~~~~~~~~~
+CLY includes a whole set of builtin node types, which can be broken down into
+the following groups:
+
+``Node``
+    The base grammar node. These nodes in the grammar are purely for
+    routing the grammar to other nodes. They have no side-effects.
+
+``Grammar``
+    The root of the grammar. Contains all other nodes.
+
+``Group``
+    A convenience class used to group its child nodes together visually.
+    Equivalent to setting each nodes ``group`` attribute.
+
+``Alias``
+    Allow branches of the grammar to be included in other locations. The only
+    argument to ``Alias`` is the relative or absolute path of the branch to be
+    included. This path can take the form of a glob in order to include
+    multiple nodes. Use this to create optional arguments.
+
+``Variable``
+    Variable nodes insert their matching input into the ``vars`` of the
+    ``Context``, after being parsed by the ``parse()`` method. If the attribute
+    ``traversals != 1``, values are collected into a list rather than a scalar.
+    CLY includes a number of potentially useful ``Variable`` subclasses such as
+    ``URI``, ``Integer``, ``Float``, etc.
+
+``Action``
+    An action matches the end of a line and is used to execute a callback. It
+    passes any ``vars`` parsed by previous ``Variable`` nodes through to the
+    callback as arguments.
+
+Node Attributes and Constructor Arguments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Each node has a set of attributes that define its behaviour, from the regular
+expression used to match input, through to the number of times the node can
+be traversed in a parse context.
+
+These attributes can be set in three ways:
+
+  - As keyword arguments passed to the node constructor:
+
+    .. code-block:: python
+
+        Node('Help', pattern=r'.+')
+
+  - As keyword arguments passed to the node when it is "called":
+
+    .. code-block:: python
+
+        Node('Help')(pattern=r'.+')
+
+  - By subclassing the node and defining the attribute as a class attribute:
+
+    .. code-block:: python
+
+        class Any(Node):
+          pattern = r'.+'
+
+For details on what attributes are available for each node class, refer to the
+API documentation.
+
+Optional Branches
+~~~~~~~~~~~~~~~~~
+As mentioned above, the ``Alias`` node allows inclusion of other parts of the
+grammar at the current location. This is useful in a couple of situations, the
+most common of which is simply allowing optional nodes:
+
+.. code-block:: python
+
+  def add_host(hostname, ip, comment=''):
+    ...
+
+  # add <hostname> <ip> [<comment>]
+  add=Node('Add a host')(
+      hostname=Variable('Host name')(
+          ip=IP('IP address')(
+              action=Action('Add host', add_host),
+              # Optional comment
+              comment=Variable('Comment', pattern=r'.+')(
+                  Alias('../../action'),
+              )
+          )
+      ),
+  )
+
+A second useful situation is aliasing another entire block of the grammar at
+the current location:
+
+.. code-block:: python
+
+