Mercurial > genshi > genshi-test

annotate doc/xpath.txt @ 938:a5a1c9a11135 tip

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