Mercurial > genshi > genshi-test
diff doc/xpath.txt @ 226:09f869a98149
Add reStructuredText documentation files.
author | cmlenz |
---|---|
date | Fri, 08 Sep 2006 08:44:31 +0000 |
parents | |
children | 24757b771651 |
line wrap: on
line diff
new file mode 100644 --- /dev/null +++ b/doc/xpath.txt @@ -0,0 +1,92 @@ +.. -*- mode: rst; encoding: utf-8 -*- + +===================== +Using XPath in Markup +===================== + +Markup provides basic XPath_ support for matching and querying event streams. + +.. _xpath: http://www.w3.org/TR/xpath + + +.. contents:: Contents + :depth: 2 +.. sectnum:: + + +----------- +Limitations +----------- + +Due to the streaming nature of the processing model, Markup uses only a subset +of the `XPath 1.0`_ language. + +.. _`XPath 1.0`: http://www.w3.org/TR/xpath + +In particular, only the following axes are supported: + +* ``attribute`` +* ``child`` +* ``descendant`` +* ``descendant-or-self`` +* ``self`` + +This means you can't use the ``parent``, ancestor, or sibling axes in Markup +(the ``namespace`` axis isn't supported either, but what you'd ever need that +for I don't know). Basically, any path expression that would require buffering +of the stream is not supported. + +Predicates are of course supported, but Path expressions *inside* predicates +are restricted to attribute lookups (again due to the lack of buffering). + +Most of the XPath functions and operators are supported, however they +(currently) only work inside predicates. The following functions are **not** +supported: + +* ``count()`` +* ``id()`` +* ``lang()`` +* ``last()`` +* ``position()`` +* ``string()`` +* ``sum()`` + +The mathematical operators (``+``, ``-``, ``*``, ``div``, and ``mod``) are not +yet supported, whereas the various comparison and logical operators should work +as expected. + +You can also use XPath variable references (``$var``) inside predicates. + + +---------------- +Querying Streams +---------------- + +:: + + from markup.input import XML + + doc = XML('''<doc> + <items count="2"> + <item status="new"> + <summary>Foo</summary> + </item> + <item status="closed"> + <summary>Bar</summary> + </item> + </items> + </doc>''') + print doc.select('items/item[@status="closed"]/summary/text()') + +This would result in the following output:: + + Bar + + +--------------------- +Matching in Templates +--------------------- + +See the directive ``py:match`` in the `XML Template Language Specification`_. + +.. _`XML Template Language Specification`: xml-templates.html