A point is simply a location in a document — a location between two characters of interest. Like a point in plane geometry, a point in XPointer has no dimension at all: a single point “contains” nothing at all, not even a single character. There’s also a point at the start of the string-value and at its end (and, as you will see, before and after each node in the document).

Note that points are found not only in text nodes, but in any string-value. An attribute’s value, a comment, a PI, indeed the root node itself — all have string-values as well and are thus potential targets in which to locate points.

Each point has two properties, a container node and an index. The container node, obviously, is the point’s parent — the context in which the point is located. The index is a positive integer ranging from 0 through the number of points (less 1) in that container node.

Consider the following fragment:

<storage>disk</storage>

The storage element’s string-value — its text node child — consists of four characters; within the text node, the interstice between each pair of characters (d and i, i and s, and s and k) is one point, and there’s also a point before the d and after the k — a total of five points. The container node for the points (indexes 0 through 4) before and after each character is the text node; the container node for the two points (indexes 0 and 1) before and after the text node is the storage element. Figure 9-3 illustrates.

Figure 9-3. Point locations in an element with a text-node child

An important implication of Figure 9-3 is that the node tree as understood by XPath is not the same as the “location tree” as understood by XPointer (although naturally there are overlaps). See Figure 9-4.

Figure 9-4. A “location tree” view of Figure 9-3

As you can see, the storage element now has not just one child (the text node), but three children (the text node plus the points before and after it). Furthermore, while a text node can have no children from XPath’s perspective, it does from XPointer’s; the number of child points always equals the length of the text node, plus 1.

One effect of a point’s being defined by its container and its index within that container is that there are no identical points in a document, at least within a given container. However, there will be points indistinguishable from one another. For instance, in the above example, point P0 within the storage element is indistinguishable from the “separate” point P0 within the text node.

This might seem disconcerting at first. It makes sense, though, when you remember that XPath, too, often provides several ways of locating a given “thing”; a given node might be visible along more than one axis, for example.

<media>
   <storage>microform</storage>
   <storage>CD-ROM</storage>
   <storage>DVD</storage>
   <storage>disk</storage>
</media>

xpointer(//storage[1]/point(  )[1])

<!DOCTYPE gadget [
<!ENTITY R "Ronco" >
]>
<gadget>
   <name>Veg-O-Matic</name>
   <company>&R;</company>
</gadget>

A range, as you might expect, is whatever lies in a given document between any two given points, not surprisingly referred to as the start and end points. The start and end points may be equal (in which case the range is called a collapsed range); if they are not equal, the end point must follow the start point, in document order.

A reminder: I’m using the term “document” loosely in the preceding sentence. In this sense, it comprises not only well-formed XML documents, but also non-well-formed external parsed entities. The spec asserts that the start and end point must be within the same document or external parsed entity; nonetheless, it’s safe to assume that a document containing a reference to an external parsed entity may have ranges that overlap the “border” between document and entity. Consider the case of the following document:

<!DOCTYPE speechinfo [
<!ENTITY getty SYSTEM "gettysburg.xml">
]>
<speechinfo>
   <speaker>Abraham Lincoln</speaker>
   <text>&getty;</text>
</speechinfo>

where the gettysburg.xml document contains the text (marked up or otherwise) of Lincoln’s famous address.

A start point/end point for a legitimate range might be, respectively, the point just before the L in Lincoln (in the main document) and following the o in and seven years ago (in the external parsed entity). As I discussed at the end of the section about points, for all intents and purposes, an entity reference can be assumed to have been expanded by the time the XPointer application sees a document. What the spec really means by restricting the start and end point to the same document or external parsed entity is, for example, that you can’t set the start point to just before the L in Lincoln and the end point in some other document (or in some unreferenced external parsed entity).

XPath?</h1><!-- Intro paragraph --><p>After you've worked

XPath?</h1><!-- Intro paragraph --><p>After you've worked

xpointer(//range(  )[4])

<front_matter>
   <epigraph id="GIRA001">
                        <author born="1882-10-29" died="1944-01-31">Giraudoux, Jean</author>
                        <source year="1942">The Apollo of Bellac</source>
                        <text>When you see a woman who can go nowhere without 
                        a staff of admirers, it is not so much because they think 
                        she is beautiful, it is because she has told them they 
                        are handsome.</text>
   </epigraph>
</front_matter>

GIRA0011882-10-291944-01-31Giradoux, Jean1942The Apollo of BellacWhen you see a woman 
who can [...] handsome.

Giradoux, JeanThe Apollo of BellacWhen you see a woman who can [...] handsome.

<?xml-stylesheet type="text/xsl" href="maginfo.xsl"?>
<mag:magazine id="NY"
   xmlns:mag="http://www.example.com/magml">
   <mag:name>The New Yorker</mag:name>
   <!-- Update: Brown hasn't been the editor for years. -->
   <mag:editor>Brown, Tina</mag:editor>
</mag:magazine>

Let’s look at how these extensions to XPath’s definition of document order work in practice. I won’t reconsider the node-versus-node case (corresponding to the first row in Table 9-4); if you need a refresher, refer back to Chapter 2.

Here is a brief sample document from which I’ll pick arbitrary locations and show how to apply Table 9-4 to a real-world example.

<dictionary source="Welsh" target="English">
   <word>
      <in>ffwlbart</in>
      <out>polecat</out>
   </word>
   <word>
      <in>rhaglaw</in>
      <out>governor</out>
      <out>lieutenant</out>
   </word>
   <word>
      <in>ymyl</in>
      <out>edge</out>
      <out>border</out>
   </word>
</dictionary>

Here are the locations to be considered:

Table 9-5 illustrates how an XPointer processor would interpret the document order of various combinations of these locations.

Similar logic applies for any combination of nodes, points, and ranges.

Exactly how the start-point( ) function behaves varies according to the type of each location in locset.

Not very surprisingly, if a given location is a point or range, start-point( ) returns that point or the range’s start point, respectively. If a given location is the root location, an element, text, comment, or PI, the point returned is the one whose index is 0 within that container.

Surprisingly (to me, anyway), if a given location is an attribute or namespace location, “the pointer part in which the function appears fails.” What this probably refers to is just that you can’t identify the start point of an attribute or namespace location; still, it seems to fly in the face of examples elsewhere in the spec, which assert (for example) that a substring of an attribute value can constitute a range.

Here’s a document fragment as an example:

<transaction type="deposit">
   <account>1234-0987-65</account>
   <amount currency="USD">1009.46</amount>
   <source>cash</source>
</transaction>

We could construct an XPointer into this source such as the following:

xpointer(start-point(//account))

This XPointer locates the point within the account element whose index is 0 — that is, the node point immediately preceding the text node whose value is “1234-0987-65.” We could also pass to the start-point( ) function a multimember location-set, as in:

xpointer(start-point(/transaction/*))

The value returned would be a series of points, representing the start points of each child of the root transaction element. Because there are three such children — the account, amount, and source elements — we’d get back a location-set, in this case, of three node points: the points immediately following each child element’s start tag. On the other hand:

xpointer(start-point(/transaction))

locates the node point between the transaction and account element’s start tags.

As you might expect, the end-point( ) function is the flip-side of start-point( ), returning — for each location in the passed location-set — an end point determined according to the location’s type.

For point and range locations, the function returns that point or the range’s end point, respectively. For attribute and namespace locations, as with start-point( ), the XPointer part containing the function call fails. How end-point( ) treats the other location types, though, is a little less generic.

Referring back to the previous XML code example, this XPointer:

xpointer(end-point(/))

locates the node point following the root transaction element’s end tag. (The container is the root node. The 0-index point within that container is the node point preceding transaction’s start tag; there’s only one child of the root location, which is the transaction element, therefore the index of the point returned by end-point( ) is 1.)

Similarly:

xpointer(end-point(//text(  )))

returns a location-set consisting of three points: the character point at the very end of each of the source’s three text locations. For example, the first text location’s string-value is 1234-0987-65, 12 characters long; the point within that text location whose index is 12 is the character point following the digit 5.

To understand how this function works, you need to understand the start-point( ) and end-point( ) functions as well. (If you’re not sure about them, check the descriptions above.) Its behavior also depends on the context location at the point of the call to range-to( ). The function returns a range whose start point is calculated as if you’d passed the context location to start-point( ), and whose end point is calculated as if you’d passed the locset argument to end-point( ). The effect, therefore, is to locate everything from the context location through that end point, inclusively.

Returning to the banking-transaction document, consider this XPointer:

xpointer(//account/range-to(account))

At the time of the call to range-to( ), the context location is the account element. Its start point (as if calculated using start-point(//account)) is the node point immediately following that element’s start tag (just before the digit 1). Thus, this XPointer returns everything between that start point and the end point of the amount element — that is, the node point just before amount’s end tag. The result is a location-set (containing a single range) whose string-value is the concatenated string-values of the account and amount elements:

1234-0987-651009.46

As the spec points out, the range-to( ) function puts an additional spin on XPath’s definition of a location step. XPath says that a location step can consist of either the full or abbreviated form of the axis-node test-predicate combination. In the XPointer universe, this definition is broadened to include one or more optional calls to range-to( ), each perhaps with a predicate of its own. Thus, with XPointer we may now see location paths such as the one highlighted here:

xpointer(//lawn[@type = 'zoysia']/sowing[@time = 'earliest']/range-to(following-
sibling::sowing[@time = 'latest']))

The location steps preceding the call to range-to( ) locate a node-set restricted to all sowing elements with a time attribute of “earliest” that are children of lawn elements with a type of “zoysia”; this node-set thus establishes the context for the call to range-to( ) (which establishes a range from the “earliest” sowing through the “latest”). This call to range-to( ) thus excludes from the final range any text within the selected lawn element except the text that appears in that range of its child sowing elements.

This odd-looking beast of a function searches all locations passed as the first argument; each location’s string-value is matched against the second argument, and if a match is found, a location-set consisting of a number of ranges is returned, one range for each discrete match for the string argument found within the range’s string-values. By default, a range starts just before the matched string, and ends just after it, so the string-value of each range returned is the matched string, wherever they occur within the location-set. However, you can override these defaults using the optional third and fourth arguments. The number1 argument fixes the start point of the range (offset from the first character in the match); the number2 argument specifies the length of the returned range, in characters.

For instance, given a document such as this:

<people>
   <person>
      <name>Simpson,John</name>
   </person>
   <person>
      <name>Kirby,John</name>
   </person>
   <person>
      <name>Simpson,Mike</name>
   </person>
</people>

You could use the string-range( ) function as in the following XPointer to return just those name elements whose string-values contained the string “Simpson”:

xpointer(string-range(//name[contains(., "Simpson")], "Simpson")

This locates two ranges; both ranges consist of the string “Simpson” because by default — in the absence of the third and fourth arguments — the range(s) returned match the sought-for string exactly. You could also include the optional third and fourth arguments to return (for example) ranges consisting of the four characters following the comma:

xpointer(string-range(//name[contains(., "Simpson")], "Simpson", 8, 4))

This returns two ranges, comprising the strings “John” and “Mike.”

Use the range( ) function when you want not a location-set of ranges per se, but of their covering ranges. For each location in locset, the function returns its covering range. Refer back to Section 9.2.2.4 to see how covering ranges are determined for the various location types.

The range-inside( ) function works similarly to the range( ) function, in that it may return a range for each location in locset. But range-inside( ) may also return non-range-type locations. Table 9-7 summarizes.

As always, this behavior will be easier to understand using a concrete example. So consider the following:

<neighborhood>
   <street>
      <name>Post Avenue</name>
      <address>101</address>
      <address>103</address>
      <address>109</address>
   </street>
   <street>
      <name>Mercy Lane</name>
      <address>1424A</address>
      <address>1424B</address>
   </street>
</neighborhood>

And now consider the following XPointer:

xpointer(range-inside(//address))

Because the location-set passed to the function includes five members — the address elements — each of which is neither a point nor a range, we should expect this function to return a set of five range-type locations. The container for each of these locations is an address element, and the start point of each location within its container is at index 0 (that is, immediately following the element’s start tag). The end point is the length of the corresponding address element’s string-value — immediately following the 1, 3, 9, A, and B characters in the address elements. Thus, the function call returns the five ranges with the following string-values:

101
103
109
1424A
1424B

Now let’s look at a different XPointer that uses range-inside( ):

xpointer(range-inside(//street[2]))

Only one location is passed to range-inside( ) here — the second street element — so we’ll get back a single range. The container for the range is that street element itself, and the start point is set at index 0 (the node point immediately following the second street element’s start tag). The end point of this street element location is a node point — the one preceding that street element’s end tag. Therefore, the index of the returned range’s end point is set to the number of children of the street element, or 3 (one name element and two address elements) — setting the end point to the node point immediately preceding the second street element’s end tag. Thus, the returned range is:

<name>Mercy Lane</name>
<address>1424A</address>
<address>1424B</address>

The here( ) function provides a convenient means to refer to the XML document or external parsed entity in which the XPointer itself appears. The location-set returned by the function has a single member, determined as follows:

Here’s a sample XML document using two XPointers:

<code>
   <navel-gazing>xpointer(here(  )/..)</navel-gazing>
   <looking-elsewhere xlink:href="xpointer(here(  )/..)"/>
</code>

The first XPointer, of course, appears in an element node — as the text node contained by the navel-gazing element. Therefore, the first XPointer locates the code element. The second XPointer occurs in the xlink:href attribute of the looking-elsewhere element; thus, this XPointer locates the parent of that attribute, or the looking-elsewhere element.

The only application in which you’ll make use of the origin( ) function is when constructing an XPointer in an XLink context — specifically, when you need to identify the location at which a particular XLink’s traversal begins. Complete coverage of XLink lies well outside this book’s scope. In general, though, XLink provides for so-called “third party” and inbound links, in addition to the more familiar outbound-only links (such as XHTML’s a elements with href attributes).

The particular problem that the origin( ) function addresses has to do with a series of XLinks in which succeeding links need to be relative to preceding ones. Without getting into the details of how the XLinks themselves are effected (syntactically or conceptually), an example of such a situation might be depicted something like the following pseudocode:

XLinkToChapter(xpointer([XPointer to a resource in some other document]))
XLinkToChapter(xpointer(origin(  )/following-sibling::*))

Again, I stress that this is not the way these XLinks are actually constructed. The point is that the second link (the one with the call to the origin( ) function) need not “know” what the first one located; by using a relative XPath expression starting with the location designated by origin( ), it automatically gets (in this case) the next sibling of whatever was located by the first link. (If the target resources of the two XPointers were in the same document where the XLinks themselves were located, you could replace the call to origin( ) with a call to here( ) to achieve the same effect.)

Note that the origin( ) function depends for its operation not just on an XPointer-aware processor, but also on some level of XLink awareness. At the time of this writing, the XML landscape is not yet exactly littered with XLink-aware applications.