cmlenz@226: .. -*- mode: rst; encoding: utf-8 -*-
cmlenz@226: 
cmlenz@226: =====================
cmlenz@230: Using XPath in Genshi
cmlenz@226: =====================
cmlenz@226: 
cmlenz@230: Genshi provides basic XPath_ support for matching and querying event streams.
cmlenz@226: 
cmlenz@226: .. _xpath: http://www.w3.org/TR/xpath
cmlenz@226: 
cmlenz@226: 
cmlenz@226: .. contents:: Contents
cmlenz@226:    :depth: 2
cmlenz@226: .. sectnum::
cmlenz@226: 
cmlenz@226: 
cmlenz@226: -----------
cmlenz@226: Limitations
cmlenz@226: -----------
cmlenz@226: 
cmlenz@230: Due to the streaming nature of the processing model, Genshi uses only a subset
cmlenz@226: of the `XPath 1.0`_ language.
cmlenz@226: 
cmlenz@226: .. _`XPath 1.0`: http://www.w3.org/TR/xpath
cmlenz@226: 
cmlenz@226: In particular, only the following axes are supported:
cmlenz@226: 
cmlenz@226: * ``attribute``
cmlenz@226: * ``child``
cmlenz@226: * ``descendant``
cmlenz@226: * ``descendant-or-self``
cmlenz@226: * ``self``
cmlenz@226: 
cmlenz@230: This means you can't use the ``parent``, ancestor, or sibling axes in Genshi
cmlenz@226: (the ``namespace`` axis isn't supported either, but what you'd ever need that
cmlenz@226: for I don't know). Basically, any path expression that would require buffering
cmlenz@226: of the stream is not supported.
cmlenz@226: 
cmlenz@394: Predicates are of course supported, but path expressions *inside* predicates
cmlenz@226: are restricted to attribute lookups (again due to the lack of buffering).
cmlenz@226: 
cmlenz@226: Most of the XPath functions and operators are supported, however they
cmlenz@226: (currently) only work inside predicates. The following functions are **not**
cmlenz@226: supported:
cmlenz@226: 
cmlenz@226: * ``count()``
cmlenz@226: * ``id()``
cmlenz@226: * ``lang()``
cmlenz@226: * ``last()``
cmlenz@226: * ``position()``
cmlenz@226: * ``string()``
cmlenz@226: * ``sum()``
cmlenz@226: 
cmlenz@226: The mathematical operators (``+``, ``-``, ``*``, ``div``, and ``mod``) are not
athomas@516: yet supported, whereas sub-expressions and the various comparison and logical
athomas@516: operators should work as expected.
cmlenz@226: 
cmlenz@226: You can also use XPath variable references (``$var``) inside predicates.
cmlenz@226: 
cmlenz@226: 
cmlenz@226: ----------------
cmlenz@226: Querying Streams
cmlenz@226: ----------------
cmlenz@226: 
cmlenz@510: The ``Stream`` class provides a ``select(path)`` function that can be used to
cmlenz@510: retrieve subsets of the stream:
cmlenz@226: 
cmlenz@510: .. code-block:: pycon
cmlenz@226: 
cmlenz@510:   >>> from genshi.input import XML
athomas@516: 
cmlenz@510:   >>> doc = XML('''<doc>
athomas@516:   ...  <items count="4">
athomas@516:   ...       <item status="new">
athomas@516:   ...         <summary>Foo</summary>
athomas@516:   ...       </item>
athomas@516:   ...       <item status="closed">
athomas@516:   ...         <summary>Bar</summary>
athomas@516:   ...       </item>
athomas@516:   ...       <item status="closed" resolution="invalid">
athomas@516:   ...         <summary>Baz</summary>
athomas@516:   ...       </item>
athomas@516:   ...       <item status="closed" resolution="fixed">
athomas@516:   ...         <summary>Waz</summary>
athomas@516:   ...       </item>
athomas@516:   ...   </items>
cmlenz@510:   ... </doc>''')
athomas@516: 
cmlenz@853:   >>> print(doc.select('items/item[@status="closed" and '
cmlenz@853:   ...     '(@resolution="invalid" or not(@resolution))]/summary/text()'))
athomas@516:   BarBaz
athomas@516: 
cmlenz@226: 
cmlenz@226: 
cmlenz@226: ---------------------
cmlenz@226: Matching in Templates
cmlenz@226: ---------------------
cmlenz@226: 
cmlenz@226: See the directive ``py:match`` in the `XML Template Language Specification`_.
cmlenz@226: 
cmlenz@226: .. _`XML Template Language Specification`: xml-templates.html