XPath provides for locating any subset of the nodes in an
XML document, where nodes generally correspond to information set items such
as elements, attributes, comments, and processing instructions. XPath functionality,
such as filtering an axis output by predicate, is generally defined in terms
of operations on nodes and node-sets.
XPointer has a requirement to identify document portions that are not nodes
in this sense. One example of such a non-node region is an arbitrary user
selection indicated by a drag between two points in a document. The two points
might have different sets of ancestors in the hierarchy, or the region might
form only a small part of a node. For example, a range could be a single letter
or could extend from the middle of one paragraph to the middle of the next,
thus containing only part of the relevant paragraphs and text nodes. Even
though such locations are not nodes, XPointer needs to be able to apply XPath
operations to them as well as to nodes.
To accomplish this, XPointer defines location as a generalization
of XPath's node. Every location is either a point,
a range, or an XPath node. Thus, XPointer
also defines location-set as a generalization of XPath's node-set.
All locations generated by XPath constructs are nodes; XPointer constructs
can also generate points and ranges.
Note:
The order of characters displayed on a computer screen might not reflect
their order in the underlying XML document, for example, when a portion of
a right-to-left language such as Arabic is embedded in a left-to-right language
such as French. For XPointers that identify ranges of strings, the document
order is used, not the display order. Thus, an XPointer for a single range
might be displayed non-contiguously, and conversely a user selection of an
apparent single range might correspond to multiple non-contiguous XPointer
ranges in the underlying document.
To address non-node locations, XPointer defines two new location types, point
and range, that can appear in location-sets and can be operated
on by XPath node tests and predicates. Locations of the point
and range type represent positions and ranges as in DOM Level
2 [DOM2]. This section defines the point and range
types and their characteristics required for XPath interoperability.
Note:
Unlike DOM Level 2, which is based on UTF-16 units, XPath and XPointer
are based on UCS characters. So while the concepts of points and ranges are
based on the DOM 2 notions of positions and ranges, there are differences
in detail. For example, a sequence which in DOM counts as two characters might
count in XPointer as one character.
Points and ranges can be used as XPointer context locations. This allows
the XPointer [] operator to be used to select from sets of ranges.
Also, a point as a context location, when followed by a range-to
function, selects a range.
[Definition: A
location of type point is defined by a node,
called the container node, and a non-negative integer, called
the index.] It can represent the location preceding
any individual character, or preceding or following any node in an XML document.
Note:
This specification does not constrain the implementation of points; applications
need not actually represent points using data structures consisting of a node
and an index.
[Definition: When the container node of
a point is of a node type that can have child nodes (that is, when the container
node is an element node or a root node), then the index is an index into the
child nodes; such a point is called a node-point.] The
index of a node-point must be greater than
or equal to zero and less than or equal to the number of child nodes of the
container. An index of zero indicates the point before any child nodes, and
a non-zero index n indicates the point immediately after the nth
child node.
Note:
The zero-based counting of node-points differs from the one-based counting
of string-range and other XPointer and XPath functions.
[Definition: When the container
node of a point is of a node type that cannot have child nodes (such as text
nodes, comments, and processing instructions), then the index is an index
into the characters of the string-value of the node; such a point is called
a character-point.] The index of a character-point must be greater than or equal to zero and less than
or equal to the length of the string-value of the node. An index of zero indicates
a point immediately before the first character of the string-value, and a
non-zero index n indicates an point immediately after the nth
character of the string-value.
Point locations do not have an expanded-name.
The string-value of
a point location is empty.
The axes of a point location are defined as follows:
-
A point location has no children.
-
A character-point has no preceding or following siblings.
-
A node-point's siblings are the children of the container node that
are before or after the node-point.
A location of type range is defined by
two points, a start point and an end point. A range represents all of the
XML structure and content between the start point and end point. This is distinct
from any list of nodes and/or characters, in part because some nodes might
be only partly included. The start and end points of a range must
be in the same document. The start point must
not appear after the end point in document order.
[Definition: A range whose start
and end points are equal is a collapsed range.]
If the container node of one point of a range is a node of a type other
than element, text, or root, the container node of the other point of the
range must be the same node. For example,
it is allowed to specify a range from the start of a processing instruction
to the end of an element (encompassing both those nodes, but still a singleton),
but not to specify a range from text inside a processing instruction to text
outside it.
Range locations do not have an expanded-name.
The string-value of
a range location is defined as follows. If the points are both character-points
and the container nodes of the points are the same, then the string-value
consists of the characters between the two points. Otherwise, the string-value
consists of the characters that are in text nodes and that are between the
two points.
The axes of a range location are the axes of its start point.
Note:
The start-point and end-point
functions can be used to navigate with respect to the respective boundaries
of a range location.
[Definition: A covering
range is a range that wholly encompasses a location.] For
every location, a covering range is defined as follows:
-
For a range location, the covering range is identical to the range.
-
For an attribute or namespace location,
the container node of the start point and end point of the covering range
is the attribute or namespace location; the index of the start point of the
covering range is 0; and the index of the end point of the covering range
is the length of the string-value of the attribute or namespace location.
-
For the root location, the container node of the start
point and end point of the covering range is the root node; the index of the
start point of the covering range is 0; and the index of the end point of
the covering range is the number of children of the root location.
-
For a point location, the start and end points of the
covering range are the point itself.
-
For any other kind of location, the container node of the start point
and end point of the covering range is the parent of the location; the index
of the start point of the covering range is the number of preceding sibling
nodes of the location; and the index of the end point is one greater than
the index of the starting point.
This definition ensures that for a range location, as for every other type
of location, the ancestor, preceding, following, descendant, and self axes
do not intersect and that they together contain all locations in the document
(other than attribute, namespace, and range locations).
XPointer extends the XPath production for NodeType
by adding items for the point and range location
types. That production becomes as follows:
NodeType
| NodeType | ::= | 'comment' |
| | | | 'text' |
| | | | 'processing-instruction' |
| | | | 'node' |
| | | | 'point' |
| | | | 'range' |
This definition allows NodeTests
to select locations of type point and range from
a location-set that might include locations of all three types.
XPointer extends XPath's concept of document order to cover
point and range locations.
For any point, there is an immediately preceding node defined as follows
(except that there is no point defined preceding or following the root):
-
For a node-point with a non-zero
index, the immediately preceding node is the node immediately preceding the
point (that is, the node that is the nth child of the container
node, where n is the index).
-
For a node-point with a zero index, the container
node is also the immediately preceding node unless it has any attribute
or namespace nodes. If the container node does have attribute or namespace
nodes, then the immediately preceding node is the last of those nodes.
-
For a character-point
the immediately preceding node is the container node of the character-point.
For any point, the immediately following node is the node that is immediately
after the immediately preceding node (as just defined).
A node is before a point if the node is before or equal in document order
to the immediately preceding node of the point; otherwise, the node is after
the point.
The relative order of a node and a range is determined by the relative
order of the node and the starting point of the range.
Document order for a point is defined as follows:
-
If the immediately preceding nodes of the two points are the same,
then either the points are the same or they are both character-points with
the same container node; in the latter case, the order of the indices determines
the document order.
-
Otherwise, the document order of the immediately preceding nodes
of the points determines the document order of the points.
One range node is before another range node if and only if
-
the starting point of the one range is before the starting point
of the other range, or
-
the starting point of the one range is the same as the starting point
of the other range, and the ending point of the one range is before the ending
point of the other range.
XPointer adds the following functions to those in XPath; these functions must be provided by XPointer applications.
location-set range-to(expression
)
For each location in the context, range-to returns
a range. The start point of the range is the start of the context location,
and the end point of the range is the end of the location found by evaluating
the expression argument with respect to
that context location.
For example, the following XPointer locates the range from the element
with ID "chap1" to the element with ID "chap2".
xpointer(id("chap1")/range-to(id("chap2")))
|
As another example, imagine a document that uses empty elements ( such
as <REVST/> for revision start and <REVEND/>
for revision end) to mark the boundaries of edits. The following XPointer
would select, for each revision, a range starting at the beginning of the REVST
element and ending at the end of the next REVEND element:
xpointer(descendant::REVST/range-to(following::REVEND[1]))
|
Note:
XPath does not permit functions immediately following the slash as shown
here; XPointer does.
location-set string-range(location-set
, string, number?, number?
)
[Definition: For each location in
the location-set argument, string-range returns a set
of string ranges, a set of substrings in a string. Specifically,
the string-value of the
location is searched for substrings that match the string argument,
and the resulting location-set will contain a range location for each non-overlapping
match.] An empty string is considered to match before each character
of the string-value and after the final character. Whitespace in a string
is matched literally, with no normalization except that provided by XML for
line ends. The third argument gives the position of the first character to
be in the resulting range, relative to the start of the match. The default
value is 1, which makes the range start immediately before the first character
of the matched string. The fourth argument gives the number of characters
in the range; the default is that the range extends to the end of the matched
string.
Element boundaries, as well as entire embedded nodes such as processing
instructions and comments, are ignored as defined in [XPath].
If the string in the second argument is not found in the string-value of
the location, or if a value in the third or fourth argument indicates a string
that is beyond the beginning or end of the document, the expression fails.
The points of the range-locations in the returned location-set will all
be character points.
For example, the following expression returns a range that selects the
17th occurrence of the string "Thomas Pynchon" occurring in a title
element:
string-range(//title,"Thomas Pynchon")[17]
|
As another example, the following expression returns a collapsed range
whose points immediately precede the letter "P" (8 from the start
of the string) in the third occurrence of the string "Thomas Pynchon"
in a P element:
string-range(//P,"Thomas Pynchon",8,0)[17]
|
Alternatively this could be specified as follows:
string-range(string-range(//P,"Thomas Pynchon")[17],"P",1,0)
|
String-values are "views" into only the string content of
a document; they do not retain the structural context of any non-text nodes
interspersed with the text. Because the string-range
function operates on a string-value, markup that intervenes in the middle
of a string does not prevent a match. (Note that for this reason, a string-range
match is on the range describing the relevant substring of the string-value,
not necessarily on a contiguous string in a single text node in the document.)
For example, if the 17th occurrence of "Thomas Pynchon" had some
inline markup in it as follows, it would not change the string returned by
the XPointer application:
The following expression selects the fifth exclamation mark in any text
node in the document and the character immediately following it:
string-range(/,"!",1,2)[5]
|
Although these examples locate ranges in elements, string-range
is useful for locating ranges that are wholly enclosed in other node types
as well, such as attributes, processing instructions, and comments.
location-set range(location-set
)
The range function returns ranges covering the locations
in the argument location-set. For each location x in the argument
location-set, a range location representing the covering range of x
is added to the result location-set.
location-set range-inside(location-set
)
The range-inside function returns ranges covering
the contents of the locations in the argument location-set. For each location x
in the argument location-set, a range location is added to the result location-set.
If x is a range location, then x is added to the result
location-set. If x is not a range location, then x is
used as the container location of the start and end points of the range location
to be added; the index of the start point of the range is zero; if the end
point is a character point then its index is the length of the string-value
of x, and otherwise is the number of location children of x.
point start-point(point)
For each location x in the argument location-set, start-point
adds a location of type point to the result location-set. That point represents
the start point of location x and is determined by the following
rules:
-
If x is of type point, the start point is x.
-
If x is of type range, the start point is the start
point of x.
-
If x is of type root, element, text, comment, or processing
instruction, the container node of the start point is x and the
index is 0.
-
If x is of type attribute or namespace, the function must signal a syntax
error.
point end-point(point)
For each location x in the argument location-set, end-point
adds a location of type point to the result location-set. That point represents
the end point of location x and is determined by the following
rules:
-
If x is of type point, the resulting point is x.
-
If x is of type range, the resulting point is the end point of x.
-
If x is of type root or element, the container node of the resulting
point is x and the index is the number of location children of x.
-
If x is of type text, comment, or processing instruction, the container
node of the resulting point is x and the index is the length of the string-value
of x.
-
If x is of type attribute or namespace, the function must
signal a syntax error.
location-set here()
The here function returns a location-set with a single
member. That location locates the node that directly contains the XPointer
being evaluated. This expression results in a syntax
error if the resource in which the containing XPointer appears is
not XML.
Note:
The type of the node is likely to be text, attribute,
or processing-instruction. The returned location for an XPointer
appearing in element content does not have a node type of element
because the XPointer is in a text node that is itself inside an element.
location-set origin()
The origin function enables addressing relative to
out-of-line links such as defined in XLink. This
allows XPointers to be used in applications to express relative locations
when links do not reside directly at one of their endpoints. The function
returns a location-set with a single member, which locates the element from
which a user or program initiated traversal of the link. The origin()
function thus provides a meaningful location-set only if the XPointer is being
processed by application software in response to a traversal instruction from
an XML document. (See [XLink] for information about traversal.)
It is a resource error to use origin
in the fragment identifier portion of a URI reference where a URI is also
provided and identifies a containing resource different from the resource
from which traversal was initiated, or in a situation where traversal is not
occurring.
boolean unique()
The predicate function unique returns true if and
only if context size is equal to 1.
This is particularly useful in applications where a singleton location
is to be located for automated processing and an XPointer that does not locate
exactly one location would be in error.
The unique function is shorthand for the following
XPath expression:
Making this its own function might simplify optimization of XPointer evaluation,
such as by using methods understood from the treatment of singleton results
in database systems.
Note that different XPointers can create different location-sets that cover
similar document scopes in the same XML information, but where the sets divide
up the scopes differently: retrieving a set of smaller locations, as opposed
to the range the covers the same total scope. For example, consider a list
element with ID "list37", which contains three item
element children, but no other children. The following XPointer returns a
location-set that has three members, the item children in that list:
xpointer(id('list37')/item)
|
The returned location-set will not be a singleton: it has as many members
as there are item children. In contrast, the following XPointer returns
a singleton location-set:
xpointer(id('list37')/item[1]/range-to(following-sibling(item)[2])
|
This singleton happens to start at the same point that the first member
of the location-set just shown does, and end at the same point that the last
member of it does; but it is not the same location-set: It is a singleton
location-set whose one member is a range, not a three-member location-set
whose members are item element nodes.