Mercurial > genshi > mirror

annotate doc/xpath.txt @ 379:e1d659c87ddf trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
The builder API now accepts streams as children of elements and fragments.
author cmlenz
date Thu, 23 Nov 2006 17:48:17 +0000
parents 84168828b074
children cab6b0256019
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
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
39 Predicates are of course supported, but Path expressions *inside* predicates
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
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
55 yet supported, whereas the various comparison and logical operators should work
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
56 as expected.
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
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
65 ::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
66
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
67 from genshi.input import XML
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
68
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
69 doc = XML('''<doc>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
70 <items count="2">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
71 <item status="new">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
72 <summary>Foo</summary>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
73 </item>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
74 <item status="closed">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
75 <summary>Bar</summary>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
76 </item>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
77 </items>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
78 </doc>''')
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
79 print doc.select('items/item[@status="closed"]/summary/text()')
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
80
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
81 This would result in the following output::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
82
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
83 Bar
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
84
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
85
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
86 ---------------------
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
87 Matching in Templates
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
88 ---------------------
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
89
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
90 See the directive ``py:match`` in the `XML Template Language Specification`_.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
91
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
92 .. _`XML Template Language Specification`: xml-templates.html
Copyright (C) 2012-2017 Edgewall Software