XPointer xpointer() Scheme

XPointer xpointer() Scheme 490 阅读 0 评论 0 点赞

XPointer xpointer() Scheme

W3C Working Draft 19 December 2002

This version:

http://www.w3.org/TR/2002/WD-xptr-xpointer-20021219/

Latest version:

http://www.w3.org/TR/xptr-xpointer/

Previous version:

http://www.w3.org/TR/2002/WD-xptr-xpointer-20020710/

Editors:

Steven DeRose, Brown University Scholarly Technology Group, Bible Technologies Group <sderose@acm.org>

Eve Maler, Sun Microsystems <eve.maler@sun.com>

Ron Daniel Jr., Taxonomy Strategies <rdaniel@taxonomystrategies.com>

This document is also available in these non-normative formats: XML, (its DTD), and (an XSL stylesheet for it).

Abstract

Status of this Document

This is a W3C Working Draft for review by W3C members and other interested parties. It is a draft document and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use W3C Working Drafts as reference material or to cite them as other than "work in progress". Comments on this document should be sent to the public mailing list www-xml-linking-comments@w3.org (archive).

This document has been produced by the W3C XML Linking Working Group as part of the XML Activity. The goals of this work are set out in the XPointer Requirements document.

There are patent disclosures and license commitments associated with this working draft, which may be found on the XPointer IPR Statement page in conformance with W3C policy.

This specification is one of four into which the prior XPointer specification has been divided. This version addresses comments received on the XPointer Candidate Recommendation which were relevant to the xpointer() scheme it defines. Except for responding to the relevant Last Call comments, and incorporating non-substantive editorial improvements, this documents is substantially identical to that part of the Last Call XPointer specification which is not covered by [XPtrFrame], [XPtr-xmlns], and [XPtr-element],

A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR/

Table of Contents

1 Introduction

1.1 Origin and Goals

1.2 Notation and Document Conventions

2 Terms and Concepts

3 Conformance

4 Language and Processing

4.1 Syntax

4.2 Additions to XPath Terms and Concepts

4.3 Evaluation Context Initialization

4.4 The point and range Location Types

4.4.1 Definition of Point Location

4.4.2 Definition of Range Location

4.4.3 Covering Ranges for All Location Types

4.4.4 Tests for point and range Locations

4.4.5 Document order

4.5 Functions Added by the xpointer() Scheme

4.5.1 range-to Function

4.5.2 string-range Function

4.5.3 Additional Range-Related Functions

4.5.3.1 covering-range Function

4.5.3.2 range-inside Function

4.5.3.3 start-point Function

4.5.3.4 end-point Function

4.5.4 here Function

4.5.5 origin Function

4.6 Root Node Children

Appendices

A References

A.1 Normative References

A.2 Non-Normative References

B On points and ranges (Non-Normative)

B.1 Notation

B.2 Ranges equivalent to points, characters, and nodes

C Working Group Members (Non-Normative)

1 Introduction

The XPointer xpointer() scheme is intended to be used with the XPointer Framework [XPtrFrame] to provide a high level of functionality for addressing portions of XML documents. It is based on XPath [XPath], and adds the ability to address strings, points, and ranges in accordance with definitions provided in DOM 2: Range.[DOM2] This scheme supports addressing into the internal structures of XML documents and external parsed entities. It allows for examination of a document's hierarchical structure and choice of portions based on various properties, such as element types, attribute values, character content, and relative position. In particular, it provides for specific reference to elements, character strings, and other XML information, whether or not they bear an explicit ID attribute.

The xpointer() scheme is built on top of the XML Path Language [XPath], which is a joint expression language also underlying the XSL Transformations (XSLT) language. The xpointer() scheme's extensions to XPath add the ability to identify locations that are not single, whole elements (such as those corresponding to typical selections and selection points in some user interfaces), and to combine string matching with the other location methods provided.

The xpointer() scheme does not cover addressing into the internal structures of DTDs or the XML declaration.

1.1 Origin and Goals

In addition to XPath, a number of prior systems and standards have helped guide the development of this specification; these are listed in the non-normative references section.A.2 Non-Normative References See the XPointer Requirements Document [XPREQ]for a thorough explanation of requirements for the design of the xpointer() scheme.

1.2 Notation and Document Conventions

[Definition: The key words must, must not, required, shall, shall not, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC 2119].]

The terms pointer, pointer part, scheme, XPointer processor, application, error, failure, and namespace binding context are used in this specification as defined in the XPointer Framework specification. Note that errors defined by this specification are distinct from XPointer Framework errors.

The formal grammar for the xpointer() scheme is given using simple Extended Backus-Naur Form (EBNF) notation, as described in the XML Recommendation [XML].

The prototypes for xpointer() scheme functions are given using the same notation used in the [XPath] Recommendation.

This specification explicitly extends some aspects of the syntax and semantics of XPath (mainly in relation to support for locations other than whole nodes). Except in such cases, [XPath] constructs and definitions remain in effect in the xpointer() scheme.

2 Terms and Concepts

Some special terms are defined here in order to clarify their relationship to similar terms used in the technologies on which the xpointer() scheme is based. Additional terms specific to the xpointer() scheme are defined in the flow of the text. Refer to [XPath], [DOM2], [Infoset], and [RFC 2396] for definitions of other technical terms used in this specification.

point

A location in an XML Information Set with no content or children. For example, the location between two adjacent nodes, or after a particular character within a text node. This notion is defined fully later (see point), and comes from the DOM Level 2 [DOM2]specification's notion of positions; this specification refers to such positions by the term "point" to avoid confusion with XPath positions.

range

An identification of all the XML Information Set content between a pair of points. This notion is defined fully later (see range), and comes from the DOM Level 2 [DOM2] specification.

[Definition: location]

A generalization of XPath's node that includes points and ranges in addition to XPath nodes (which include the 7 node types defined by the XML Information Set.[Infoset]

[Definition: location-set]

An unordered list of locations, such as produced by an xpointer() scheme expression. This corresponds to the node-set that is produced by XPath expressions, except for the generalization to include points and ranges. Just as for an XPath node-set, a location-set is unordered, but can be treated as having a specific order depending on the axis that is operating on it. In this specification, the ordering depends on the notion of document order defined in4.4.5 Document order, which applies to point and range locations as well as nodes, rather than on XPath's treatment of document order for nodes.

3 Conformance

Conforming XPointer processors claiming to support the xpointer() scheme must conform to the behavior defined in this specification and may conform to additional XPointer scheme specifications.

This specification is intended for use with the XPointer Framework [XPtrFrame] specification, and thus conforming XPointer processors must conform to the requirements of the XPointer Framework.

This specification normatively refers to the XPath [XPath] Recommendation, and conforming XPointer processors must therefore conform to the requirements of XPath except as this specification modifies them.

This specification also normatively uses the XPointer xmlns() scheme specification [XPtr-xmlns]; XPointer processors claiming to conform to this specification must also conform to the xmlns() specification.

Scheme data for the xpointer() scheme conforms to this specification if it does not cause an error as described in this specification.

Should need arise to refer to the namespace for objects defined by this specification, the normative namespace URI for the xpointer() scheme is http://www.w3.org/2001/05/XPointer.

4 Language and Processing

XPath expressions work with a data set that is derived from the elements and other markup constructs of an XML document. The xpointer() scheme model augments this data set. Both xpointer() expressions and XPath expressions operate by selecting portions of such data sets, often by their structural relationship to other parts (for example, the parent of a node with a certain ID value). The xpointer(), like XPath, uses iterative selections, each operating on what is found by the prior one.

Selection of portions of the information hierarchy is done through three main constructs: axes, predicates, and functions (constructs defined in XPath [XPath] ). An axis defines a sequence of candidates that might be located; predicates then test for various criteria relative to such portions; and functions generate new candidates or perform various other tasks. For example, an expression can identify certain elements from among the siblings of some previously located element, based on whether those sibling elements have an attribute with a certain value or are of a certain type such as "footnote". Another expression could identify the point location immediately preceding a certain element (which in turn was identified by ID or other tests).

4.1 Syntax

This section describes the syntax and semantics of the xpointer() scheme and the behavior of XPointer processors with respect to this scheme.

The scheme name is "xpointer". If scheme data in a pointer part with the xpointer() scheme does not conform to the syntax defined in this section, it is an error and the pointer part fails.

xpointer() Scheme Syntax

[1] xpointerschemedata ::= Expr

Expr is as defined in the XPath Recommendation [XPath], with the extensions defined in this specification.

4.2 Additions to XPath Terms and Concepts

The xpointer() scheme extends XPath by adding the following:

A generalization of the XPath[XPath] concepts of nodes, node types, and node-sets to the xpointer() scheme concepts of locations (which subsume nodes, points, and ranges), location types (namely the Infoset node types plus point and range), and location-sets, which are sets of locations in the same way that XPath node sets are sets of nodes.

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.

Allowance (as in [XSLT]) for the root node to have multiple child elements, to allow expressions to address into arbitrary external parsed entities as well as well-formed documents.

The functions covering-range and range-inside, to address the covering ranges of locations in location sets.

The functions string-range and range-to, to identify ranges by identifying the location of a given literal string in the text of some node(s), or by extending from the start of one location to the end of another.

The function here, applicable when the xpointer() scheme expression being evaluated is found within an XML document. here identifies the element directly bearing or containing the xpointer() scheme expression.

The function origin, applicable when an xpointer() scheme expression is interpreted in the course of a hypertext link traversal (for example, as defined in the XLink recommendation [XLink]). origin identifies the location from which of the current hypertext traversal was initiated (sometimes called the "origin anchor".

The functions start-point and end-point, to identify the beginning and ending point locations that bound another location such as a node or range.

XPath provides for locating any subset of the nodes in an XML document or external parsed entities. XPath functionality, such as filtering an axis output by predicate, is generally defined in terms of operations on nodes and node-sets. As noted earlier, the xpointer() scheme also identifies locations that are points and ranges. For example, a range 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.

Note:

The order of a location's characters as displayed on a computer screen might not reflect their order in the underlying XML document. For example, this may occur when a portion of a right-to-left language such as Arabic is embedded in a left-to-right language such as French. For expressions that identify ranges of strings, the document order is used, not the display order. Thus, an expression 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 ranges in the underlying document.

4.3 Evaluation Context Initialization

An xpointer() scheme expression in a pointer part (as defined in the XPointer Framework [XPtrFrame]) is evaluated to yield an object of type location-set. This evaluation is carried out within a context similar to the XPath evaluation context except for the generalization of nodes to locations. XPointer processors must initialize this evaluation context to include the following information before evaluating an expression:

A location (the context location), initialized to the root node of an XML document or external parsed entity.

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() scheme processors. Thus, the set of variable bindings used when evaluating an expression is empty, and use of a variable reference in an expression results in failure of the pointer part.

A library of functions. Only functions defined in XPath or this specification can be used in expressions. An xpointer() scheme expression that uses other functions results in failure of the pointer part.

A namespace binding context consisting of the initial context defined in the XPointer Framework specification and additional contributions made by any pointer parts having the xmlns() scheme to the left of the current pointer part.

When applicable, properties for the locations that the origin and here functions identify.

4.4 The point and range Location Types

For non-node locations, point and range locations can appear in the location sets identified by expression of the xpointer() scheme. This section defines these types and their characteristics required for XPath interoperability. Locations that are also nodes, have the same characteristics as XPath nodes.

Note:

Unlike DOM Level 2, which is based on UTF-16 units, XPath and the xpointer() scheme are based on UCS characters. So while the concepts of points and ranges are based on the notions of positions and ranges, there are differences in detail. For example, a sequence which in DOM counts as two characters might count in the xpointer() scheme as one character.

Points and ranges can be used as context locations in the xpointer() scheme. This allows the [] operator to be used to select locations from location sets in general.

The range-to function may be applied with a context location of any location type, and identifies a range whose start-point is start-point of the context location, and whose end-point is the end-point of the location identified by the function's argument.

The local-name, namespace-uri, and name functions operate on the first location in document order, not the first location which is also a node.

4.4.1 Definition of Point Location

[Definition: A location of type point is defined in terms of two data items:] The first is the [Definition: container node, which is that node that directly contains the point.] For example, a point between two adjacent characters within a text node will be the text node. The second is the [Definition: index], which is a non-negative integer that represents the offset of the point among the child nodes or the character content of the container node (each node type can have only one or the other). An index of zero indicates the point before any child nodes or contained characters, and a non-zero index n indicates the point immediately after the nth child node or character.

Note:

The zero-based counting of node-points is compatible with that of DOM 2[DOM2], and therefore differs from the one-based counting used for XPath string functions such as string-range that are available in the xpointer() scheme.

As defined, points are sufficient to identify the location preceding or following any individual character, or preceding or following any node in the data set constructed from an XML document or external parsed entity.

Given this definition, two points are necessarily identical if they have the same container node and index.

Note:

This specification does not constrain the implementation of points; XPointer processors need not actually represent points using data structures consisting of a node and an index.

Also note that while some nodes 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 points that might not be distinguished in the user interface, such as the points just inside and just outside the closing boundary of a text node inside an element, are in fact distinct.

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, preceding, following, attribute, and namespace axes are empty.

The descendant-or-self axis contains the point itself.

The self axis contains the point itself.

The parent axis contains the point's container node.

The ancestor axis contains the point's container node and its ancestors.

The ancestor-or-self axis contains the point itself, the point's container node, and its ancestors.

4.4.2 Definition of Range Location

A location of type [Definition: range is defined by two points], a [Definition: start point] and an [Definition: 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 point and end point of a range must be in the same document or external parsed entity. The start point must not appear after the end point in document order (see 4.4.5 Document order).

[Definition: A range whose start point and end point 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 immediately before a processing instruction to the end of an element, 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 consists of the characters that are in text nodes and that are between the start point and end point of the range.

The axes of a range location are identical to the axes of its start point. For example, the parent axis of a range contains the parent of the start point of the range.

4.4.3 Covering Ranges for All Location Types

[Definition: A covering range is a range that wholly and exactly encompasses a location. The covering range can be identified by applying the covering-range function to any location. The equivalent covering range for each type of location is defined as follows:]

For a range location, the covering range is identical to the range (note that as in DOM [DOM2], although ranges are well-defined within all node types, ranges may not extend from inside the boundaries of namespace, attribute, comment, or processing instruction nodes to outside, or from outside to inside).

For a point location, the start and end points of the covering range are the point itself.

For a node location that is an element, text, comment, or processing instruction node, the container node of the start point and of the end point of the covering range are both the parent of the identified node; 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.

For a node location that is the root node, the container node of the start point and end point of the covering range are both 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 node location that is an attribute or namespace node, the container node of the start point and end point of the covering range is the attribute or namespace node itself; 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 node.

4.4.4 Tests for point and range Locations

The xpointer() scheme extends the XPath production for NodeType... by adding items for the point and range location types. The production (number 38 in XPath) becomes as follows:

NodeType

[2] 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 many types.

4.4.5 Document order

XPointer must be able to represent locations that are entire element nodes, like XPath; but also locations that are not. For example, an edit insertion point does not correspond to any whole node, but rather to a zero-size location, such as the point immediately preceding a character of text within a text node or between two adjacent element nodes. Similarly, typical drag-selections in various applications correspond to ranges, not nodes.

As in DOM 2: Range[DOM2], a point is determined by the node that contains it, and the offset of the point within that node. A range is determined by its starting and ending points.

The appendix "On points and ranges" provides a simple notation that is similar in syntax to the XPointer element() scheme, but that is not limited to identifying whole elements. That notation clarifies the definition of document ordering given here and has useful additional properties, but ordering can be implemented using that or any other representation.

The diagram below shows the numbering of nodes and points in a graphic representation of an XML Information Set.

Sample XML tree, with nodes and inter-node points numbered.

Figure 1: Numbering of nodes and points

For example,

point(1.0) is just inside the beginning of the p element.

point(1.2) is between the end of the em element and the following text node (which contains "world.").

point(.0) immediately precedes the root node.

point(1/2/1.1) immediately following the "b" in the middle text node.

Intuitively, points are ordered largely as one would expect from a pre-order traversal of the document, or the XML stream order.

More formally, any two document locations that are comparable, regardless of which type(s) they are, can be compared by comparing their covering ranges. A comparison of ranges is defined purely by a sequence of comparisons of their starting and ending points. Because all comparisons thus reduce to comparisons of points, point comparison is defined first below. The sequence of point comparisons required to compare two ranges is defined second, and is sufficient for comparing any locations that can be compared.

Because text nodes are not explicitly represented in XML documents, the point immediately before (or after) a text node occurs at the same place in an XML source document as the point immediately before (or after) that text node's first (or last) character. This specification defines those locations as distinct; they do not compare as equal. For example, point(1.2) is not equal to point(1/3.0).

Because the attribute and namespace nodes of a given element node are unordered, it is illegal to compare them in certain ways, and the result of such an attempted comparison is undefined. Specifically:

Points within different attribute and/or namespace nodes of the same container node may not be compared.

A point within an attribute or namespace node may not be compared to the location of its container node.

A point within an attribute or namespace node, however, may be compared to any node other than its parent node or to any point within any node other than its parent node. In such comparisons, the point is ordered as its parent node would be.

Two points within the same attribute or namespace node may be compared, and are compared by their offsets just as are points within any other node.

Points within the same container node compare as do the values of their respective offsets.

Points within different nodes cannot be correctly ordered merely by comparing the order of their container nodes. For example, the later point could be late in a large node N, while the earlier point could be within an earlier child M of N. In that case node N is before M (because it started earlier), and so merely comparing M and N would produce the incorrect result.

To compare any comparable points P1 and P2:

point(.0) compares as before any other point; point(.1) compares as after any other point.

Define Node1 as the child sequence of the node directly containing point P1, and Node2 as the child sequence of the node directly containing point P2.

Define Offset1 as the offset of point P1 within the node identified by Node1, and Offset2 as the offset of point P2 within the node identified by Node2.

Beginning at the uppermost end of Node1 and Node2 (typically both 1 for the XML document element), compare corresponding components of the two paths and discard all such pairs that are equal.

If a further component(s) is available from neither Node1 nor Node2, the points are directly within the same containing node, and are ordered simply by their respective offsets.

If a further component(s) is available from both Node1 and Node2, then the node whose next component value is greater represents the point that is later in document order.

If a further component(s) is available for only Node1, then P1 is within some descendant of the node in which P2 directly occurs. Thus it is necessary to determine the position of Offset2 relative to the ancestor of P1 that is at the same level (that is a child of Node2). To do this, compare Offset2 to the first of the further components for Node1. If Offset2 is greater than or equal, then P2 follows P1 in document order; otherwise it precedes P1.

If a further component(s) is available for only Node2, compare Offset1 to the first of the further components for Node2. If Offset1 is greater than or equal, then P1 follows P2 in document order; otherwise it precedes P2.

Note:

As of this writing, the ordering algorithm in DOM 2: Range[DOM2] appears to produce incorrect results for some cases. Until a correction to this problem is issued, implementors should be particularly careful that their implementations for document order comparison produce the results defined here.

Two ranges R1 and R2 are ordered using the following sequence of comparisons of their starting and ending points (these definitions avoid circularity because the definition of point ordering given above does not involve casting the compared points to their equivalent collapsed ranges):

If the start point of R1 is not equal to the start point of R2, then the ranges are ordered as their respective start points are ordered. That is, if R1 starts before R2 it is before R2, and if R1 starts after R2 it is after R2.

If the start point of R1 is equal to the start point of R2, then the ranges are ordered as their respective end points are ordered. That is, if R1 and R2 start at the same point, then: if R1 ends before R2 it is before R2; if R1 and R2 end at the same point R1 is equal to R2; and if R1 ends after R2 it is after R2.

Thus, R1 and R2 are equal if and only if their respective start points and end points are equal.

Comparisons between any two types of locations (point vs. node, etc.) must produce the same results as obtained through converting all comparands to their equivalent ranges and comparing those ranges.

This algorithm yields the correct results; however, implementations need not use this specific algorithm to compare point locations. They may use any algorithm that produces the same results.

4.5 Functions Added by the xpointer() Scheme

The xpointer() scheme adds the following functions to those in XPath.

4.5.1 range-to Function

location-set range-to(location-set)

For each location in the context, range-to returns a range. The start point of the range is the start point of the context location (as determined by the start-point function), and the end point of the range is the end point (as determined by the end-point function) 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 version in the xpointer() scheme 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 locations in the current location list.

As an example of using the range-to function, the following pointer part locates the range from the start point of the element with ID "chap1" to the end point of 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 pointer part 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]))

4.5.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 ranges determined by searching the string-value of the location for substrings that match the string argument. An empty string is defined to match before each character of the string-valueand after the final character. White space in a string is matched literally, with no normalization except that provided by XML for line ends and attribute values. Each non-overlapping match can contribute a range to the resulting location set.

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 sub-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. Thus, both the start point and end point of each range returned by the string-range function will be within text nodes.

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].

For any particular location, if the string argument is not found in the string-value of the location, or if the third and fourth argument indicates a range that is wholly beyond the beginning or end of the document or entity, then no range is added to the result for that match.

The start and end 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 of those "Thomas Pynchon" strings appearing 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 of those "Thomas Pynchon" strings appearing 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 or entity; 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 identified by the XPointer processor:

Thomas <em>Pyn</em>chon

The following expression selects the fifth of those exclamation marks appearing in any text node in the document and the character immediately following that exclamation mark:

string-range(/,"!",1,2)[5]

Although these examples locate ranges via text in the string-values of 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.

4.5.3 Additional Range-Related Functions

The following functions are related to ranges.

4.5.3.1 covering-range Function

location-set range(location-set)

The covering-range function returns the covering ranges for 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.

4.5.3.2 range-inside Function

location-set range-inside(location-set)

The range-inside function returns the distinct covering ranges of the locations in the argument location-set. For each location x in the argument location-set, a 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. Otherwise x is used as the container node of the start and end points of the range location to be added, which is defined in this way: 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 thestring-value of x; otherwise its index is the number of children of x.

4.5.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 resulting 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 resulting point is x.

If x is of type range, the resulting point is the start point of x.

If x is of type root, element, text, comment, or processing instruction, the container node of the resulting point is x and the index is 0.

If x is of type attribute or namespace, the pointer part in which the function appears fails.

4.5.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 pointer part in which the function appears fails.

4.5.4 here Function

location-set here()

The here function is meaningful only when the expression being interpreted occurs in an XML document or external parsed entity; otherwise the pointer part in which the here function appears fails. When in an XML context, the here function returns a location-set with a single member. There are two possibilities for the location returned:

If the expression 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 expression being evaluated.

In the following example, the here function appears inside an expression that is in an attribute node. The expression 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])">

</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 expression appearing in element content does not have a node type of element because the expression is in a text node that is itself inside an element.

4.5.5 origin Function

location-set origin()

The origin() function is meaningful only when the expression is being processed in response to traversal of a link expressed in an XML document. The origin function enables addressing relative to third-party and inbound links such as defined in the XLink Recommendation. This allows expressions 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. (See [XLink] for information about traversal.)

It is an error to use origin in the fragment identifier portion of a URI reference where a URI is also provided and identifies a resource different from the resource from which traversal was initiated, or in a situation where traversal is not occurring.

4.6 Root Node Children

The XML Recommendation requires well-formed documents to contain a single element at the top level. Thus, the XPath data model of a well-formed document will have a root node with a single child node of type element. In order to address locations in arbitrary external parsed entities, along with well-formed documents, the xpointer() scheme extends the XPath data model to allow the root node to have any sequence of nodes as children that would be possible of an element node. This extension is identical to the one made by XSLT. Thus, the root node may contain child nodes of type text, and any number of child nodes of type element.

A References

A.1 Normative References

DOM2

Document Object Model (DOM) Level 2 Specification: Version 1.0. World Wide Web Consortium, 2000.

Dom2Range

Document Object Model (DOM) Level 2 Traversal and Range Specification. Version 1.0. W3C Recommendation, 13 November, 2000.

RFC 2119

RFC 2119: Key words for use in RFCs to Indicate Requirement Levels. Internet Engineering Task Force, 1997.

RFC 2396

RFC 2396: Uniform Resource Identifiers. Internet Engineering Task Force, 1995.

XML

Tim Bray, Jean Paoli, C.M. Sperberg-McQueen, and Eve Maler, editors. Extensible Markup Language (XML) 1.0 (Second Edition). World Wide Web Consortium, 2000.

XPtrFrame

Paul Grosso, Eve Maler, Jonathan Marsh, and Norman Walsh, editors. XPointer Framework W3C Proposed Recommendation. World Wide Web Consortium, 2002.

XPtr-element

Paul Grosso, Eve Maler, Jonathan Marsh, and Norman Walsh, editors. XPointer element() Scheme W3C Proposed Recommendation. World Wide Web Consortium, 2002.

XPtr-xmlns

Steven DeRose, Ron Daniel Jr., Eve Maler and Jonathan Marsh, editors. XPointer xmlns() Scheme W3C Proposed Recommendation. World Wide Web Consortium, 2002.

Unicode

The Unicode Consortium. The Unicode Standard.

XPath

James Clark and Steve DeRose, editors. XML Path Language (XPath). World Wide Web Consortium, 1999.

A.2 Non-Normative References

CHUM

Steven J. DeRose and David G. Durand. 1995. "The TEI Hypertext Guidelines." In Computing and the Humanities 29(3). Reprinted in Text Encoding Initiative: Background and Context, ed. Nancy Ide and Jean Veronis, ISBN 0-7923-3704-2.

Dexter

Halasz, Frank. 1994. "The Dexter Hypertext Reference Model." In Communications of the Association for Computing Machinery 37 (2), February 1994: 30-39.

FRESS

Steven J. DeRose and Andries van Dam. 1999. "Document structure in the FRESS Hypertext System." Markup Languages 1 (1) Winter. Cambridge: MIT Press: 7-32. (See http://www.stg.brown.edu/~sjd/fress.html.)

HTML

Dave Raggett, Arnaud Le Hors, and Ian Jacobs. HTML 4.01 Specification. World Wide Web Consortium, 1999.

Infoset

John Cowan and Richard Tobin, editors. XML Information Set. World Wide Web Consortium, 2001.

ISO/IEC 10744

ISO/IEC 10744-1992 (E). Information technology --Hypermedia/Time-based Structuring Language (HyTime). Geneva: International Organization for Standardization, 1992. Extended Facilities Annex. [Geneva]: International Organization for Standardization, 1996.

OHS

van Ossenbruggen, Jacco, Anton Eliëns and Lloyd Rutledge. "The Role of XML in Open Hypermedia Systems." Position paper for the 4th Workshop on Open Hypermedia Systems, ACM Hypertext '98. (See http://aue.auc.dk/~kock/OHS-HT98/Papers/ossenbruggen.html.)

RLocs

Thomas A Phelps and Robert Wilensky. Robust Intra-document Locations. University of California, Berkeley.

TEI

C. M. Sperberg-McQueen and Lou Burnard, editors. Guidelines for Electronic Text Encoding and Interchange. Association for Computers and the Humanities (ACH), Association for Computational Linguistics (ACL), and Association for Literary and Linguistic Computing (ALLC). Chicago, Oxford: Text Encoding Initiative, 1994.

XLink

Steve DeRose, Eve Maler, David Orchard, and Ben Trafford, editors. XML Linking Language (XLink). World Wide Web Consortium, 2001.

XPREQ

Steve DeRose, editor. XML XPointer Language Requirements Version 1.0. World Wide Web Consortium, 1999.

XSLT

James Clark, editor. XSL Transformations (XSLT) Version 1.0. World Wide Web Consortium, 1999.

B On points and ranges (Non-Normative)

B.1 Notation

The notation defined here builds on the XPointer element() scheme. However, where element() can only identify a whole element node in an XML Infoset, the notation defined here can also identify any point or range. This notation is intended to be easy to understand and to provide a clear way to explicate the sometimes-complex ordering relationships of document locations. It also has advantageous properties such as that many useful properties of document locations can be determined merely by examining their representation in this notation, and without having to resort to the actual document or Infoset.

The initial portion of the notation is identical to element(): a list of child numbers separated by the slash character ("/"). Such a list is called a [Definition: child sequence]. The following XML source corresponds to the diagram below it and shows the element()scheme's child sequence number above each node:

<p>hello, <emph>big </emph>world.</p>

ROOT

----------------------------------

| | |

1/1 1/2 1/3

| | |

txt emph txt

------------- ------- -----------

h e l l o , _ | w o r l d .

1/2/1

txt

-------

b i g _

Figure 2: Structure diagram with child sequences for all nodes.

"ROOT" here indicates the root node, "txt" indicates text nodes, "_" indicates the space character, and "p" and "emph" indicate element nodes.

For example:

element(1) identifies the p element (the document element; note that the root node has no number).

element(1/2/1) identifies the (only) text node within the emph element, which contains the text "big ".

Points, ranges, and non-element nodes cannot be identified by the numbering mechanism. However, the DOM 2: Range[DOM2] specification (http://www.w3.org/TR/DOM-Level-2-Traversal-Range/ranges.html) defines points in terms of a containing node and an offset within it. This numbering covers all the points adjacent to nodes of all ordered node types, and all the points adjacent to characters within the text-containing node types (not only text nodes, but also comments, processing instructions, namespace and attribute nodes).

For the exact same structure shown above, those points are numbered as shown below.

ROOT

^ p ^

0 | 1

----------------------------------

| | |

^ txt ^ emph ^ txt ^

0 ^ 1 | 2 ^ 3

/ | /

------------- txt -----------

h e l l o , _ ^ w o r l d .

^ ^ ^ ^ ^ ^ ^ ^ / ^ ^ ^ ^ ^ ^ ^

0 1 2 3 4 5 6 7 / 0 1 2 3 4 5 6

-------

b i g _

^ ^ ^ ^ ^

0 1 2 3 4

Figure 3: Structure diagram with points numbered.

For example:

the point just before the first text node is offset 0 within the p element

the point after the "r" of "world" is offset 3 within the last text node.

the point between the emph element and the following text node is offset 2 within the p element

Note:

Implementors must take care regarding a difference in how XPath [XPath] and DOM 2: Range [DOM2] count characters. XPath and (and hence this specification) count UCS characters; DOM instead counts UTF-16 code points.

A point is always within some node, but a point cannot have children as a node can. Thus, a point can always be identified by the child sequence of the node it is in, plus the offset of the point within that node.

This specification therefore defines the [Definition: point sequence] notation to be like the element() scheme syntax except that:

the slash-separated numbers are determined not by counting only element nodes, but by counting nodes of all types

an integer is appended when representing a point, to represent the point's offset within the node specified by the preceding child sequence

the final integer is separated from the preceding ones by "." instead of "/", to distinguish its different meaning

the child sequence may be empty, meaning that the point is directly within the root node

the notation is not named "element", but "point"

For example:

the point sequence to identify the point immediately following the period within the last text node above is point(1/3.6). "1/3" identifies the last text node, while ".6" indicates the offset with that node.

the point immediately preceding the p element has point sequence point(.0).

The last component must be delimited by "." instead of "/" in order to distinguish specifying a point from specifying a node at the same level. For example, point(1/2) is a child sequence that identifies the emph element above, but point(1.2) identifies the point immediately following it. Thus the XPointer startpoint() and endpoint() functions can be easily implemented in terms of this representation.

The point preceding the root node itself is identified as ".0"; the point after the root node itself is identified as ".1". The sequence "/" refers to the root node itself and may optionally be written before the first numeric component.

For an expression range(S, E) in which S and E are both points: If S precedes E in document order the expression represents the range beginning at S and ending at E; if S is equal to E in document order, the expression represents the collapsed range (equivalent to the point) at S (and equally at E); if S follows E in documents order, the expression is in error and results are undefined.

An expression point(P) in which P is not a point, is treated as point(start-point(P)). An expression range(S) is treated as range(S,S). An expression range(S, E) in which either S or E is not a point, is equivalent to range(start-point(S),end-point(E)).

The name of the point notation is "point", and its formal grammar is:

[1] PointSchemeData ::= (NCName PointSequence?) | PointSequence

[2] PointSequence ::= (ChildSequence Offset?) | (Root Offset?) | Offset

[3] ChildSequence ::= ('/' [1-9] [0-9]*)+

[4] Root ::= '/'

[5] Offset ::= ('.' [0-9]+)

The name of the range notation is "range", and its formal grammar is:

[6] RangeSchemeData ::= PointSchemeData s* ("," s* PointSchemeData)?

The diagram in the section "Document Ordering" above, shows the point sequences to all points in its example, omitting the "point(" and ")" to save space.

Note:

As noted earlier, the point immediately before (or after) a text node occurs at the same place in an XML source document as the point immediately before (or after) that text node's first (or last) character. This specification defines those locations as distinct; they do not compare as equal. For example, the point at offset 2 within the p element above is not equal to the point at offset 0 within the text node containing "world." It is beyond the scope of this specification to define editing operations such as insertion, but we note that the permissible operations at such points may differ. For example, an interface might reject inserting a node within a text node even at offset 0, or inserting characters at the corresponding offset within the containing element.

Since a range is defined in terms of a starting point and an ending point, a range is uniquely identified by two point sequences. For example, the range extending from before the 2nd "l" of "hello", to immediately after the emph element, is from point(1/1.3) to point(1.2) and is here written range(1/1.3, 1.2).

B.2 Ranges equivalent to points, characters, and nodes

The covering range of any location, as defined above, is equivalent to the location and compares identically. For example,

the point just described following "l" is equivalent to range(1/1.3, 1/1.3).

the "i" itself is equivalent to range(1/2/1.1, 1/2/1.2).

the emph element above is equivalent to range(1.1, 1.2).

the entire content of the root node (but not the root node itself) is equivalent to range(.0,.1) or range(/.0, /.1)..

the entire root node is equivalent to range(/,/).

Note:

The node representation just shown is analogous to the "outerHTML" property in some scripting languages, as it contains the entire node as a whole, not merely its children or contents. The "inner" aspect of a node is also representable. For example, the complete content of the p element above, but not the p element itself, is range(1.0, 1.3). The 3 represents offset 3 within the p element, the position following its 3rd child (which is the text node containing 'world.').

Note:

Several useful operations can be done using solely the point sequence representation of ranges. For example, order comparisons, tests of containment and equivalence, tests of whether a range could form a well-formed XML entity, and measures of nesting depth can all be trivially constructed based on this representation. However, this specification does not mandate implementation of this or any other internal representation, so long as the results specified here are obtained.

C Working Group Members (Non-Normative)

The first working drafts of this specification were developed in the XML Working Group, whose members are listed in [XML]. The work was completed in the XML Linking Working Group, with the following members active at the completion of this specification:

Peter Chen, LSU, Bootstrap Alliance

Ron Daniel, Taxonomy Strategies (XPointer co-editor and acting chair)

Steven DeRose, invited expert (XPointer co-editor)

David Durand, University of Southhampton, Dynamic Diagrams

Masatomo Goto, Fujitsu Laboratories

Paul Grosso, Arbortext

Dmitry Lenkov, Oracle

Chris Maden, Lexica

Eve Maler, Sun Microsystems (past co-chair and co-editor)

Jonathan Marsh, Microsoft

David Orchard, Jamcracker

Henry Thompson, W3C and University of Edinburgh (co-chair and W3C staff contact)

Daniel Veillard, invited expert (co-chair)

The editors wish to acknowledge substantial contributions from Tim Bray, who previously served as co-editor and co-chair; from James Clark on integration with XPath; from Gavin Nicol and Martin Dürst on passages related to internationalization; and from Jeni Tennison on the formal definition of document ordering. Finally, we would like to thank the XML Linking Interest Group and Working Group for their support and input.

点赞(0) 打赏