← Back to branch summary

~ubuntu-branches/ubuntu/jaunty/calibre/jaunty-backports

« back to all changes in this revision

Viewing changes to src/calibre/manual/xpath.rst

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2009-01-20 17:14:02 UTC
  • Revision ID: james.westby@ubuntu.com-20090120171402-8y3znf6nokwqe80k
Tags: upstream-0.4.125+dfsg
Import upstream version 0.4.125+dfsg

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/calibre/manual/xpath.rst
 
1
.. include:: global.rst
 
2
 
 
3
.. _xpath-tutorial:
 
4
 
 
5
XPath Tutorial
 
6
==============
 
7
 
 
8
In this tutorial, you will be given a gentle introduction to 
 
9
`XPath <http://en.wikipedia.org/wiki/XPath>`_, a query language that can be 
 
10
used to select arbitrary parts of `HTML <http://en.wikipedia.org/wiki/HTML>`_
 
11
documents in |app|. XPath is a widely
 
12
used standard, and googling it will yield a ton of information. This tutorial, 
 
13
however, focuses on using XPath for ebook related tasks like finding chapter 
 
14
headings in an unstructured HTML document.
 
15
 
 
16
.. contents:: Contents
 
17
  :depth: 1
 
18
  :local: 
 
19
 
 
20
Selecting by tagname
 
21
----------------------------------------
 
22
 
 
23
The simplest form of selection is to select tags by name. For example, 
 
24
suppose you want to select all the ``<h2>`` tags in a document. The XPath
 
25
query for this is simply::
 
26
 
 
27
    //h2        (Selects all <h2> tags)
 
28
 
 
29
The prefix `//` means *search at any level of the document*. Now suppose you
 
30
want to search for ``<span>`` tags that are inside ``<a>`` tags. That can be
 
31
achieved with::
 
32
 
 
33
    //a/span    (Selects <span> tags inside <a> tags)
 
34
 
 
35
If you want to search for tags at a particular level in the document, change
 
36
the prefix::
 
37
 
 
38
    /body/div/p (Selects <p> tags that are children of <div> tags that are
 
39
                 children of the <body> tag)
 
40
 
 
41
This will match only ``<p>A very short ebook to demonstrate the use of XPath.</p>`` 
 
42
in the `Sample ebook`_ but not any of the other ``<p>`` tags.
 
43
 
 
44
Now suppose you want to select both ``<h1>`` and ``<h2>`` tags. To do that,
 
45
we need a XPath construct called *predicate*. A :dfn:`predicate` is simply 
 
46
a test that is used to select tags. Tests can be arbitrarily powerful and as
 
47
this tutorial progresses, you will see more powerful examples. A predicate
 
48
is created by enclosing the test expression in square brackets::
 
49
 
 
50
//*[name()='h1' or name()='h2']
 
51
 
 
52
There are several new features in this XPath expression. The first is the use
 
53
of the wildcard ``*``. It means *match any tag*. Now look at the test expression
 
54
``name()='h1' or name()='h2'``. :term:`name()` is an example of a *built-in function*.
 
55
It simply evaluates to the name of the tag. So by using it, we can select tags
 
56
whose names are either `h1` or `h2`. XPath has several useful built-in functions.
 
57
A few more will be introduced in this tutorial.
 
58
 
 
59
Selecting by attributes
 
60
-----------------------
 
61
 
 
62
To select tags based on their attributes, the use of predicates is required::
 
63
 
 
64
    //*[@style]              (Select all tags that have a style attribute)
 
65
    //*[@class="chapter"]    (Select all tags that have class="chapter")
 
66
    //h1[@class="bookTitle"] (Select all h1 tags that have class="bookTitle")
 
67
 
 
68
Here, the ``@`` operator refers to the attributes of the tag. You can use some 
 
69
of the `XPath built-in functions`_ to perform more sophisticated
 
70
matching on attribute values.
 
71
 
 
72
 
 
73
Selecting by tag content
 
74
------------------------
 
75
 
 
76
Using XPath, you can even select tags based on the text they contain. The best way to do this is
 
77
to use the power of *regular expressions* via the built-in function :term:`re:test()`::
 
78
 
 
79
    //h2[re:test(., 'chapter|section', 'i')] (Selects <h2> tags that contain the words chapter or 
 
80
                                              section)
 
81
 
 
82
Here the ``.`` operator refers to the contents of the tag, just as the ``@`` operator referred
 
83
to its attributes.
 
84
 
 
85
 
 
86
Sample ebook
 
87
------------
 
88
 
 
89
.. literalinclude:: xpath.xhtml
 
90
    :language: html
 
91
 
 
92
XPath built-in functions
 
93
------------------------
 
94
 
 
95
.. glossary::
 
96
 
 
97
    name()
 
98
        The name of the current tag.
 
99
 
 
100
    contains()
 
101
        ``contains(s1, s2)`` returns `true` if s1 contains s2.
 
102
 
 
103
    re:test()
 
104
        ``re:test(src, pattern, flags)`` returns `true` if the string `src` matches the
 
105
        regular expression `pattern`. A particularly useful flag is ``i``, it makes matching
 
106
        case insensitive. A good primer on the syntax for regular expressions can be found
 
107
        at `regexp syntax <http://docs.python.org/lib/re-syntax.html>`_
 
108