A generalization of the XPath concepts of nodes, node types, and
node-sets to the XPointer concepts of locations,
location types, and location-sets, which subsume nodes, points, and ranges.
Two new location types, point and range,
corresponding to DOM positions and ranges, that can appear in location-set
results; also tests (akin to node tests) for these location types.
Rules for establishing the XPath evaluation context.
The functions string-range and range-to,
which return the range location type for selections that are not single XML
nodes.
The functions here and origin,
to provide for addressing relative to the location of an XPointer expression
itself, and to the point of origin for hypertext traversal when XPointers
are used in that (very common) application domain.
The functions start-point and end-point,
to address the beginning and ending locations which bound another location
such as a node or range.
Like [XSLT], XPointer allows the root node to have
multiple child elements, to allow XPointers to address into arbitrary external
parsed entities as well as well-formed documents.
5.1 XPointer Additions to XPath Terms and Concepts
XPath provides for locating any subset of the nodes in an
XML document. 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.
5.2 Evaluation Context Initialization
An XPointer is evaluated to yield an object of type location-set. This
evaluation is carried out within a context identical to the XPath evaluation
context, except for the generalization of nodes to locations. XPointer applications must initialize the evaluation context as described
in this section before evaluating an XPtrExpr.
An XPointer evaluation context contains the following information:
A location (the context location), initialized to the
root node of an XML document. When the XPointer is a fragment identifier of
a URI reference, the document is the one identified by the URI portion. If
an application uses XPointers in another context than as a URI reference's
fragment identifier, this specification does not constrain how the applicable
document is chosen.
A non-zero context position, initialized to 1.
A non-zero context size, initialized to 1. (At the start, the only
location in the current location list is the context location.)
A set of variable bindings. No means for initializing these is defined
for XPointer applications. Thus, the set of variable bindings used when evaluating
an XPointer is empty, and use of a variable reference in an XPointer results
in a syntax error.
A library of functions. Only functions defined in XPath or XPointer
can be used in XPointers. An XPointer that uses other functions results in
a syntax error.
A set of namespace declarations, described in 5.2.1 Namespace Initialization.
5.2.1 Namespace Initialization
For any XPointer part that uses the xpointer scheme, the evaluation
context of that part must be initialized
to a set of namespace declarations consisting of a declaration of the xml
prefix, bound to the URI http://www.w3.org/XML/1998/namespace,
plus any namespace declarations specified by xmlns XPointer parts
appearing to its left. Each xmlns part defines a namespace declaration
as a prefix (NCName) and namespace URI
(XPtrNsURI). In the event that two or more xmlns
parts specify the same prefix, the rightmost one is used. Any xmlns
parts attempting to override the xml prefix must
be ignored.
As an example, assume the following target XML resource:
<doc>
<x:a xmlns:x="http://example.com/foo">
<x:a xmlns:x="http://example.org/bar">This element and
its parent are in different namespaces.</x:a>
</x:a>
</doc> |
The evaluation of the following XPointer appearing in a non-XML document
(or in an XML document with no declaration of the namespace prefix x)
will result in a sub-resource error; it cannot be known which a element
is desired because no namespace declarations are in scope:
The following avoids this evaluation error and ensures that the outer a
element is addressed:
xmlns(x=http://example.com/foo) xpointer(//x:a) |
The following (printed on two lines for convenience) allows for accurate
addressing of the inner a element; note that the prefix used inside
the XPointer need not correspond to the prefix (if any) actually used in the
target resource:
xmlns(x=http://example.com/foo) xmlns(y=http://example.org/bar)
xpointer(//x:a/y:a) |
5.3 The point and range Location Types
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.
5.3.1 Definition of Point Location
[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 the data set
constructed from an XML document. The self axis of a point is the
point itself. The parent axis of a point is a location set containing
a single location, the container node. Two points are identical if they have
the same container node and index.
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.
Also note that, while some nodes containing points have explicit boundaries
(such as element start-tags and end-tags), the boundaries of text nodes are
implicit. Applications that present a graphical user interface for the selection
or rendering of points and ranges need to take into consideration the fact
that some seemingly identical points, such as the points just inside and just
outside the closing boundary of a text node inside an element, are in fact
distinguished.
[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 the point immediately after the nth
character of the string-value.
A point location does not have an expanded-name.
The string-value of
a point location is empty.
The axes of a point location are defined as follows:
The child, descendant, preceding-sibling, following-sibling, attribute,
and namespace axes are empty.
The self axis contains the point itself.
The parent axis contains the node-point's container node.
The ancestor axis contains the node-point's container node
and its ancestors.
A node-point's siblings are the children of the container node that
are before or after the node-point.
5.3.2 Definition of Range Location
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 (see 5.3.5 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.
A range location does 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 identical to the axes of its start point.
For example, the parent axis of a range returns the parent of the
start point of the range.
Note:
The start-point and end-point
functions can be used to navigate with respect to the respective boundaries
of a range location.
5.3.3 Covering Ranges for All Location Types
[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 start point.
5.3.4 Tests for point 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
| [11] | 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.
5.3.5 Document Order
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 start 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 location is before another range location if and only if
the start point of the one range is before the start point of the
other range, or
the start point of the one range is the same as the start point of
the other range, and the end point of the one range is before the end point
of the other range.
5.4 XPointer Functions
XPointer adds the following functions to those in XPath; these functions must be provided by XPointer applications.
5.4.1 range-to Function
location-set range-to(location-set
)
For each location in the context, range-to returns
a range. The start of the range is the start-point of the context location,
and the end of the range is the end-point of the location found by evaluating
the expression argument with respect to
that context location.
The change made to the XPath syntax to support the range-to
construct corresponds to a single addition to the Step
production of the [XPath] specification. The original
production is as follows:
[4] Step ::= AxisSpecifier NodeTest Predicate*
| AbbreviatedStep |
The XPointer version is as follows:
[4xptr] Step ::= AxisSpecifier NodeTest Predicate*
| AbbreviatedStep
| 'range-to' '(' Expr ')' Predicate* |
This change is a single exception for the range-to
function. It is not a generic change and is not extensible to other functions.
The modified production expresses that a range computation must be made for
each of the nodes in the current node list.
As an example of using the range-to function, the
following XPointer locates the range from the start-point for the element
with ID "chap1" to the end-point for 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])) |
5.4.2 string-range() Function
location-set string-range(location-set
, string, number?, number?
)
For each location in the location-set argument, string-range
returns a set of [Definition: string
ranges, 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
and attribute values. 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 specified by the definition of string-value in [XPath].
If the string argument is not found in the string-value of the
location, or if the third or fourth argument indicates a position that is
beyond the beginning or end of the document, the XPointer part in which the
function appears 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)[3] |
Alternatively this could be specified as follows:
string-range(string-range(//P,"Thomas Pynchon")[3],"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 a range describing the relevant substring of the string-value, not
necessarily 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.
5.4.3 Additional Range-Related Functions
The following functions are related to ranges.
5.4.3.1 range Function
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.
5.4.3.2 range-inside Function
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 or a point, then x is added
to the result location-set. If x is not a range location, then x
is used as the container node 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 children of x.
5.4.3.3 start-point Function
location-set start-point(location-set
)
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 XPointer
part in which the function appears fails.
5.4.3.4 end-point Function
location-set end-point(location-set
)
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 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 XPointer
part in which the function appears fails.
5.4.4 here Function
location-set here()
The here function returns a location-set with a single
member. There are two possibilties for the location returned:
If the XPointer being evaluated appears in a text node inside an
element node, the location returned is the element node.
Otherwise, the location returned is the node that directly contains
the XPointer being evaluated.
In the following example, the here function appears
inside an XPointer that is in an attribute node. The XPointer as a whole,
then, returns the slide element just preceding the slide
element that most directly contains the attribute node in question.
<button
xlink:type="simple"
xlink:href="#xpointer(here()/ancestor::slide[1]/preceding::slide[1])">
Previous
</button> |
Note:
The type of the node in which the here function appears
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.
If the resource in which the XPointer appears is not XML, the XPointer
part in which the here function appears fails.
5.4.5 origin Function
location-set origin()
The origin function enables addressing relative to
third-party and inbound 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.