Mercurial > genshi > mirror
annotate doc/xpath.txt @ 794:f9e23d472a6e trunk
Merged AST branch back into trunk. Most of this code was written by Marcin Kurczych for his Google Summer of Code 2008 project. The merge of this branch means that Genshi now uses the native `_ast` module on Python >= 2.5, and an emulation thereof on Python 2.4. This replaces the usage of the `compiler` package, which was deprecated in Python 2.6 and removed in Python 3.0. Another effect is that Genshi now runs on Google AppEngine (although performance is bad due to the lack of template caching).
| author | cmlenz |
|---|---|
| date | Tue, 16 Dec 2008 23:02:36 +0000 |
| parents | 317a7f4e3c69 |
| children | f33ecf3c319e |
| rev | line source |
|---|---|
| 226 | 1 .. -*- mode: rst; encoding: utf-8 -*- |
| 2 | |
| 3 ===================== | |
| 230 | 4 Using XPath in Genshi |
| 226 | 5 ===================== |
| 6 | |
| 230 | 7 Genshi provides basic XPath_ support for matching and querying event streams. |
| 226 | 8 |
| 9 .. _xpath: http://www.w3.org/TR/xpath | |
| 10 | |
| 11 | |
| 12 .. contents:: Contents | |
| 13 :depth: 2 | |
| 14 .. sectnum:: | |
| 15 | |
| 16 | |
| 17 ----------- | |
| 18 Limitations | |
| 19 ----------- | |
| 20 | |
| 230 | 21 Due to the streaming nature of the processing model, Genshi uses only a subset |
| 226 | 22 of the `XPath 1.0`_ language. |
| 23 | |
| 24 .. _`XPath 1.0`: http://www.w3.org/TR/xpath | |
| 25 | |
| 26 In particular, only the following axes are supported: | |
| 27 | |
| 28 * ``attribute`` | |
| 29 * ``child`` | |
| 30 * ``descendant`` | |
| 31 * ``descendant-or-self`` | |
| 32 * ``self`` | |
| 33 | |
| 230 | 34 This means you can't use the ``parent``, ancestor, or sibling axes in Genshi |
| 226 | 35 (the ``namespace`` axis isn't supported either, but what you'd ever need that |
| 36 for I don't know). Basically, any path expression that would require buffering | |
| 37 of the stream is not supported. | |
| 38 | |
| 394 | 39 Predicates are of course supported, but path expressions *inside* predicates |
| 226 | 40 are restricted to attribute lookups (again due to the lack of buffering). |
| 41 | |
| 42 Most of the XPath functions and operators are supported, however they | |
| 43 (currently) only work inside predicates. The following functions are **not** | |
| 44 supported: | |
| 45 | |
| 46 * ``count()`` | |
| 47 * ``id()`` | |
| 48 * ``lang()`` | |
| 49 * ``last()`` | |
| 50 * ``position()`` | |
| 51 * ``string()`` | |
| 52 * ``sum()`` | |
| 53 | |
| 54 The mathematical operators (``+``, ``-``, ``*``, ``div``, and ``mod``) are not | |
| 516 | 55 yet supported, whereas sub-expressions and the various comparison and logical |
| 56 operators should work as expected. | |
| 226 | 57 |
| 58 You can also use XPath variable references (``$var``) inside predicates. | |
| 59 | |
| 60 | |
| 61 ---------------- | |
| 62 Querying Streams | |
| 63 ---------------- | |
| 64 | |
|
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
394
diff
changeset
|
65 The ``Stream`` class provides a ``select(path)`` function that can be used to |
|
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
394
diff
changeset
|
66 retrieve subsets of the stream: |
| 226 | 67 |
|
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
394
diff
changeset
|
68 .. code-block:: pycon |
| 226 | 69 |
|
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
394
diff
changeset
|
70 >>> from genshi.input import XML |
| 516 | 71 |
|
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
394
diff
changeset
|
72 >>> doc = XML('''<doc> |
| 516 | 73 ... <items count="4"> |
| 74 ... <item status="new"> | |
| 75 ... <summary>Foo</summary> | |
| 76 ... </item> | |
| 77 ... <item status="closed"> | |
| 78 ... <summary>Bar</summary> | |
| 79 ... </item> | |
| 80 ... <item status="closed" resolution="invalid"> | |
| 81 ... <summary>Baz</summary> | |
| 82 ... </item> | |
| 83 ... <item status="closed" resolution="fixed"> | |
| 84 ... <summary>Waz</summary> | |
| 85 ... </item> | |
| 86 ... </items> | |
|
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
394
diff
changeset
|
87 ... </doc>''') |
| 516 | 88 |
| 89 >>> print doc.select('items/item[@status="closed" and ' | |
| 90 ... '(@resolution="invalid" or not(@resolution))]/summary/text()') | |
| 91 BarBaz | |
| 92 | |
| 226 | 93 |
| 94 | |
| 95 --------------------- | |
| 96 Matching in Templates | |
| 97 --------------------- | |
| 98 | |
| 99 See the directive ``py:match`` in the `XML Template Language Specification`_. | |
| 100 | |
| 101 .. _`XML Template Language Specification`: xml-templates.html |