This chapter is from the book
This chapter is from the book
This chapter is from the book
6.3 Functions
XPointer is built on top of XPath and extends XPath in several ways. At the most fundamental level, it extends XPath's data model, and this aspect has been covered in section 6.1.1. However, in order to fully exploit this extended data model, XPointer also extends the list of functions provided by XPath. XPath's functions have been described in section 5.4, with an overview provided in Table 5.4. XPointer significantly extends this list of functions. The additional functions provided by XPointer are summarized in Table 6.1.
Before covering the functions in detail, we should note that when XPath was developed it was assumed that the XPath functions would be extended by other specifications. (Indeed, as we have mentioned previously, XPath is more intended as a foundation for other specifications than as a stand-alone standard.) Consequently, the extension of XPath's set of functions is perfectly legal and well defined within the XPath model.
Table 6.1 Overview of XPointer Functions
|
Function name |
Result type |
Arguments |
Page |
|
end-point |
location-set |
location-set |
157 |
|
here |
location-set |
n/a |
158 |
|
origin |
location-set |
n/a |
158 |
|
range |
location-set |
location-set |
158 |
|
range-inside |
location-set |
location-set |
158 |
|
range-to |
location-set |
location-set |
159 |
|
start-point |
location-set |
location-set |
160 |
|
string-range |
location-set |
location-set, |
160 |
|
|
|
string, number?, number? |
|
One particularly useful observation about the XPointer functions is that they all accept arguments and produce results using the extended XPointer data model. Furthermore, from the function names it can be concluded that the majority of functions are used for defining ranges. This is not surprising given that ranges are XPointer's most important extension of the XPath data model and are not supported at all by XPath's functions. In the following list, we cover all XPointer functions (supplementing the core XPath functions) in detail:
end-point – Returns the end point of a location. Signature: location-set end-point(location-set) The end-point function accepts a location set as its argument. For each of the locations in this location set, the function adds the end point of the location to the resulting location set, according to the following rules (with x being a location in the argument location set):
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.
Thus, the end-point function can be used to locate the end point of any location. The complementary function of the end-point function is the start-point function.
here – Returns the context of the XPointer. Signature: location-set here() The here function makes it possible to create XPointers relative to the context in which they appear. Since this makes sense only for XPointers within XML resources, an XPointer part containing the here function always fails if the XPointer does not appear inside an XML resource.24 If the containing resource is XML, the here function returns a location set with one member: 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.
origin – Returns the context of the traversal initiation. Signature: location-set origin() This function makes sense only in a context where XPointers are used within linking constructs (such as those provided by XLink) and where the processing model is such that the XPointer evaluation is initiated by the traversal of links. If this is the case, the origin function returns a location set with one member, which locates the element from which a user or program initiated traversal of the link. If the origin function is used in a URI reference where a URI is also provided and identifies a containing resource di8erent from the resource from which traversal was initiated, the result is a resource error. It is also a resource error to use the origin function in a context where traversal is not occurring.
range – Returns covering ranges of locations. Signature: location-set range(location-set) The range function returns the covering ranges of all locations in the argument location set. Thus, the result location set of the range function always contains a set of range locations, and this set contains, at most, as many range locations as there are locations in the argument location set.25
range-inside – Returns ranges covering the contents of locations. Signature: location-set range-inside(location-set) The range-inside function is similar to the range function in that it also returns ranges covering the locations in the argument location set. However, the range-inside function does not return the covering ranges for the locations in the argument location set but instead returns ranges covering the contents of these locations. The following rules are used to construct the result location set, based on the type of each location in the argument location set:
For range locations, the location (i.e., the range) is added to the result location set.
For point locations, the location (i.e., the point) is added to the result location set. Consequently, the result location set of the range-inside function can contain range and point locations.
For node locations, the location (i.e., the node) is used as the container node of the start and end points of the range location to be added to the resulting location set. 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 the argument node location; otherwise it is the number of children of the argument node location.
This definition of the range-inside function makes sure that only the contents of locations are added to the result location set. For example, if the argument location is an element, then the range-inside function returns the contents of this element as the result (in contrast, the range function would return the element itself).
range-to – Returns range from context location to argument location. Signature: location-set range-to(location-set) This function has a special position among the other functions in that it requires a change of the XPath syntax as described in section 5.2.26 In XPointer, rule 4 of XPath's syntax of location paths is changed from
This modification of the syntax makes it possible to use the range-to function directly as a step of a location path (instead of the situation with other functions, which may be used only within predicates or other expressions). The range-to function operates on the context provided by the previous step and produces the context for the following step.
For each location in the context, the range-to function returns a range. The start of this 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. Thus, if the context is a location set with more than one location, then for each of these locations, the range-to function's argument is evaluated with respect to the location. The result of evaluating the range-to function then is the union of all ranges that are the results of these evaluations.
start-point – Returns the start point of a location. Signature: location-set start-point(location-set) The start-point function accepts a location set as its argument. For each of the locations in this location set, the function adds the start point of the location to the resulting location set, according to the following rules (with x being a location in the argument location set):
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.
Thus, the start-point function can be used to locate the start point of any location. The complementary function of the start-point function is the end-point function.
string-range – Matches strings in a location set. Signature: location-set string-range(location-set, string, number?, number?)
This is one of the most important (and complex) functions provided by XPointer. In many cases, it is necessary not only to use the structure provided by XML (such as elements, attributes, or processing instructions) for identifying resource fragments but also to be able to identify fragments that are text-based. Basically, the string-range function enables the identification of strings (or sets of strings) as ranges (or sets of ranges).
For each location in the argument location set, the location's string value (see section 5.1 for the definition of the string value) is searched for the given string.27 Each non-overlapping match of this string is then added (as a range location) to the resultant location set. If no matching string exists, then the XPointer part (within which the string-range function appears) fails.
The optional third and fourth arguments can be used to control the range, which is added to the resulting location set. The third argument specifies from which point, relative to the start of the matched string, the result should be taken. The default value for the third argument is 1, which means the result should be from before the first character matching the search string. The fourth argument specifies the length of the range to be added. The default is the range that extends to the end of the matched string.
These functions can be used to compose XPointers. It should also be noted that most XPath functions can also be used within XPointers. In particular, it can be observed (most easily from looking at Table 6.1) that XPointer's functions are mainly concerned with supporting the concept of locations, which are a construct introduced by XPointer mainly for the purpose of including ranges in the data model.