Mercurial > genshi > mirror

annotate doc/xpath.txt @ 974:740bc7646c28 trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Update ChangeLog with changes for 0.6.1.
author hodgestar
date Sun, 30 Dec 2012 14:13:27 +0000
parents f33ecf3c319e
children
rev   line source
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
1 .. -*- mode: rst; encoding: utf-8 -*-
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
2
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
3 =====================
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
4 Using XPath in Genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
5 =====================
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
6
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
7 Genshi provides basic XPath_ support for matching and querying event streams.
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
8
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
9 .. _xpath: http://www.w3.org/TR/xpath
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
10
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
11
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
12 .. contents:: Contents
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
13 :depth: 2
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
14 .. sectnum::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
15
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
16
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
17 -----------
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
18 Limitations
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
19 -----------
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
20
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
21 Due to the streaming nature of the processing model, Genshi uses only a subset
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
22 of the `XPath 1.0`_ language.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
23
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
24 .. _`XPath 1.0`: http://www.w3.org/TR/xpath
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
25
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
26 In particular, only the following axes are supported:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
27
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
28 * ``attribute``
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
29 * ``child``
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
30 * ``descendant``
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
31 * ``descendant-or-self``
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
32 * ``self``
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
33
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
34 This means you can't use the ``parent``, ancestor, or sibling axes in Genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
35 (the ``namespace`` axis isn't supported either, but what you'd ever need that
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
36 for I don't know). Basically, any path expression that would require buffering
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
37 of the stream is not supported.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
38
394
cab6b0256019 Minor doc fixes.
cmlenz
parents: 230
diff changeset
39 Predicates are of course supported, but path expressions *inside* predicates
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
40 are restricted to attribute lookups (again due to the lack of buffering).
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
41
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
42 Most of the XPath functions and operators are supported, however they
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
43 (currently) only work inside predicates. The following functions are **not**
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
44 supported:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
45
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
46 * ``count()``
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
47 * ``id()``
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
48 * ``lang()``
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
49 * ``last()``
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
50 * ``position()``
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
51 * ``string()``
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
52 * ``sum()``
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
53
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
54 The mathematical operators (``+``, ``-``, ``*``, ``div``, and ``mod``) are not
516
317a7f4e3c69 Implemented XPath sub-expressions.
athomas
parents: 510
diff changeset
55 yet supported, whereas sub-expressions and the various comparison and logical
317a7f4e3c69 Implemented XPath sub-expressions.
athomas
parents: 510
diff changeset
56 operators should work as expected.
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
57
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
58 You can also use XPath variable references (``$var``) inside predicates.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
59
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
60
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
61 ----------------
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
62 Querying Streams
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
63 ----------------
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
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
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
67
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 394
diff changeset
68 .. code-block:: pycon
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
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
317a7f4e3c69 Implemented XPath sub-expressions.
athomas
parents: 510
diff changeset
71
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 394
diff changeset
72 >>> doc = XML('''<doc>
516
317a7f4e3c69 Implemented XPath sub-expressions.
athomas
parents: 510
diff changeset
73 ... <items count="4">
317a7f4e3c69 Implemented XPath sub-expressions.
athomas
parents: 510
diff changeset
74 ... <item status="new">
317a7f4e3c69 Implemented XPath sub-expressions.
athomas
parents: 510
diff changeset
75 ... <summary>Foo</summary>
317a7f4e3c69 Implemented XPath sub-expressions.
athomas
parents: 510
diff changeset
76 ... </item>
317a7f4e3c69 Implemented XPath sub-expressions.
athomas
parents: 510
diff changeset
77 ... <item status="closed">
317a7f4e3c69 Implemented XPath sub-expressions.
athomas
parents: 510
diff changeset
78 ... <summary>Bar</summary>
317a7f4e3c69 Implemented XPath sub-expressions.
athomas
parents: 510
diff changeset
79 ... </item>
317a7f4e3c69 Implemented XPath sub-expressions.
athomas
parents: 510
diff changeset
80 ... <item status="closed" resolution="invalid">
317a7f4e3c69 Implemented XPath sub-expressions.
athomas
parents: 510
diff changeset
81 ... <summary>Baz</summary>
317a7f4e3c69 Implemented XPath sub-expressions.
athomas
parents: 510
diff changeset
82 ... </item>
317a7f4e3c69 Implemented XPath sub-expressions.
athomas
parents: 510
diff changeset
83 ... <item status="closed" resolution="fixed">
317a7f4e3c69 Implemented XPath sub-expressions.
athomas
parents: 510
diff changeset
84 ... <summary>Waz</summary>
317a7f4e3c69 Implemented XPath sub-expressions.
athomas
parents: 510
diff changeset
85 ... </item>
317a7f4e3c69 Implemented XPath sub-expressions.
athomas
parents: 510
diff changeset
86 ... </items>
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 394
diff changeset
87 ... </doc>''')
516
317a7f4e3c69 Implemented XPath sub-expressions.
athomas
parents: 510
diff changeset
88
853
f33ecf3c319e Convert a bunch of print statements to py3k compatible syntax.
cmlenz
parents: 516
diff changeset
89 >>> print(doc.select('items/item[@status="closed" and '
f33ecf3c319e Convert a bunch of print statements to py3k compatible syntax.
cmlenz
parents: 516
diff changeset
90 ... '(@resolution="invalid" or not(@resolution))]/summary/text()'))
516
317a7f4e3c69 Implemented XPath sub-expressions.
athomas
parents: 510
diff changeset
91 BarBaz
317a7f4e3c69 Implemented XPath sub-expressions.
athomas
parents: 510
diff changeset
92
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
93
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
94
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
95 ---------------------
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
96 Matching in Templates
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
97 ---------------------
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
98
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
99 See the directive ``py:match`` in the `XML Template Language Specification`_.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
100
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
101 .. _`XML Template Language Specification`: xml-templates.html
Copyright (C) 2012-2017 Edgewall Software