Download XSLT and XML Attributes and Elements: A Comprehensive Guide and more Schemes and Mind Maps Latin literature in PDF only on Docsity!
697
A P P E N D I X A
XPath Quick Reference
T his appendix gives you a quick guide to XPath, including its syntax and a guide to all the
functions that are available to you.
Sequences
Every XPath expression returns a sequence, which can be empty or hold any number of items. Items can be nodes or atomic values.
Nodes
Nodes can be of the kinds shown in Table A-1.
Table A-1. Node Kinds
Node Kind Name String Value
Document - Concatenation of all text nodes in the document
Element Element name Depends on element type
Attribute Attribute name Depends on attribute type
Text - Text
Comment - Text held within the comment
Processing instruction Processing instruction target Text in the processing instruction after the space after the target name
Namespace Namespace prefix Namespace URI
Node Types
Element and attribute nodes can be annotated with a type based on validation against a schema. The types, string values, and typed values of element and attribute nodes are summarized in Table A-2.
Table A-2. Node Types
Node Kind Validity Type String Value Typed Value
Element Unvalidated xdt:untyped Concatenation String value as of all text node xdt:untypedAtomic descendants value
Element Invalid or xdt:anyType Concatenation String value as partially validated of all text node xdt:untypedAtomic descendants value
Element Valid Simple Text with Sequence of items of whitespace appropriate type normalized based on type
Element Valid Mixed Concatenation String value as of all text node xdt:untypedAtomic descendants value
Element Valid Element-only Concatenation of all Undefined text node descendants
Attribute Unvalidated xdt:untypedAtomic Value with String value as whitespace xdt:untypedAtomic replaced value
Attribute Invalid or xdt:untypedAtomic Value with String value as partially validated whitespace xdt:untypedAtomic replaced value
Attribute Valid Simple Value with Sequence of items of whitespace appropriate type normalized based on type
Atomic Values Atomic values in Basic XSLT can be of any of the atomic types shown in Table A-3. The relevant namespace URIs are
- http://www.w3.org/2001/XMLSchema (xs prefix by convention)
- http://www.w3.org/2005/04/xpath-datatypes (xdt prefix by convention)
■ Caution The namespace for XPath datatypes changes with each version of the spec.
Basic XSLT processors may support other, implementation-defined types as well as those given in Table A-3.
xdt:anyAtomicType
xs:dateTime xs:date xs:time xs:gYear xs:gYearMonth xs:gMonth xs:gMonthDay xs:gDay
xs:boolean
xs:decimal xs:float xs:double xdt:untypedAtomic xs:string xdt:yearMonthDuration xdt:dayTimeDuration xs:integer xs:normalizedString
xs:long xs:nonPositiveInteger xs:nonNegativeInteger xs:token xs:int
xs:short xs:byte
xs:negativeInteger xs:positiveInteger xs:unsignedLong xs:language xs:Name xs:NMTOKEN xs:NCName
xs:ID xs:IDREF xs:ENTITY
xs:unsignedInt xs:unsignedShort xs:unsignedByte
primitive type XSD type XPath type
Key:
xs:hexBinary xs:base64Binary xs:anyURI xs:QName xs:NOTATION xs:duration
Figure A-1. The hierarchy of built-in types
In Schema-Aware XSLT processors, all the atomic types from XML Schema and XPath are built in. These are shown in Figure A-1. You may also import types from a schema using <xsl:import-schema>.
Atomic values can be cast to other types using constructor functions—the name of the constructor function is the same as the name of the type—or the cast expression. Casting is allowed between the following primitive types:
- xs:string and xdt:untypedAtomic values can be cast to any other type (though the cast won’t always succeed), with the exceptions of xs:QName and xs:NOTATION.
- Values of numeric types (xs:decimal, xs:float, and xs:double) can be cast to other numeric types, though casts from xs:double and xs:float to xs:decimal won’t always succeed.
- Values of numeric types can be cast to xs:boolean and vice versa.
- xs:dateTime values can be cast to any of the date/time types.
- xs:date values can be cast to xs:dateTime, xs:gYear, xs:gYearMonth, xs:gMonth, xs:gMonthDay, and xs:gDay types.
- Values of the binary types (xs:hexBinary and xs:base64Binary) can be cast to each other.
Whether a cast will succeed or not can be tested using the castable expression.
■ Note Literal stringscan be cast to xs:QName and to subtypes of xs:NOTATION.
Effective Boolean Value
Within tests, a value (equivalent to a single-item sequence) will be converted to its effective Boolean value, as shown in Table A-4.
Table A-4. Effective Boolean Values
Value Effective Boolean Value
Node true
String true if the string contains any characters, false otherwise
Number false if number is 0 or NaN, true otherwise
Boolean true^ if^ true,^ false^ if^ false
Other atomic value Raises an error
The effective Boolean value of a sequence is false if it is empty and true if the first item in the sequence is a node. Otherwise, if the sequence contains more than one item, you get an error.
Sequence Types
Sequence types are patterns that match sequences. Sequence types are summarized in Table A-5.
Table A-5. Sequence Types
Sequence Type Description
void() Matches the empty sequence
itemType Matches a sequence containing a single item
itemType? Matches a sequence that contains 0 or 1 items
itemType + Matches a sequence that contains 1 or more items
itemType * Matches a sequence that contains any number of items
Sequence types may use an item type to specify the type of the items in the sequence. Item types are summarized in Table A-6.
Table A-6. Item Types
Item Type Description
item() Matches any item
atomicType Matches items of the named atomic type (see Table A-3)
nodeKindTest Matches items that are nodes that match the node kind test (see Table A-7)
Paths
Paths are made up of a number of steps, separated by /s. Each step can be a general step or an axis step. A general step is any expression; the expression must result in a sequence of nodes for all steps except the last in a path. Each axis step is made up of an optional axis (defaults to child), a node test, and any number of predicates (held in square brackets).
Axes
Axes dictate the relationship between the context node and the selected nodes. The direction of an axis determines how the position() of a node is calculated within a predicate—forward axes look at document order, reverse axes look at reverse document order. The axes are listed in Table A-8.
Table A-8. XPath Axes
Axis Direction Description
self Forward Selects the context node itself
child Forward Selects the children of the context node
parent Reverse Selects the parent of the context node
attribute Forward Selects the attributes of the context node
descendant Forward Selects the descendants of the context node at any level
descendant-or-self Forward Selects the descendants of the context node, and the context node itself
ancestor Reverse Selects the ancestors of the context node
ancestor-or-self Reverse Selects the ancestors of the context node, and the context node itself
following-sibling Forward Selects the siblings of the context node that follow the context node in document order
preceding-sibling Reverse Selects the siblings of the context node that precede the context node in document order
following Forward Selects the nodes (aside from attribute and namespace nodes) that follow the context node in document order and that are not descendants of the context node
preceding Reverse Selects the nodes (aside from attribute and namespace nodes) that precede the context node in document order and that are not ancestors of the context node
namespace Forward Selects the namespace nodes on the context node
■ Note The namespace axis is deprecated; not all XSLT processors will support it.
Node Tests
Node tests match different kinds of nodes as shown in Table A-9.
Table A-9. Node Tests
Node Test Description
- Matches all attributes when used with the attribute axis, all namespace nodes when used with the namespace axis, and all elements when used with other axes
name Matches attributes with the specified name when used with the attribute axis, namespaces with the specified name when used with the namespace axis, and elements with the specified name when used with other axes
nodeKindTest Matches nodes that match the node kind test (see Table A-7)
Abbreviated Syntax
You can use several abbreviations in XPath expressions, as described in Table A-10.
Table A-10. XPath Abbreviations
Abbreviation Full Equivalent Description
.. parent::node() Indicates the parent of the context node
// /descendant-or-self::node()/ Supplies quick access to descendants of the context node
/ (at the beginning of a path) (root() cast as document-node())/ Goes up to the root of the node tree, and gives an error if it is not a document node
@ attribute:: Shortens expressions that access attributes
Expressions and Operators
The expressions in XPath can be split into eight groups:
- Sequence operators (see Table A-11)
- Arithmetic operators (see Table A-12)
- Comparisons (see Tables A-13 and A-14)
- Logical operators (see Table A-15)
- for expression
- Conditional expression
- Quantified expressions
- Expressions on SequenceTypes (see Table A-16)
The precedence of the operators (from lowest to highest) is as follows:
Arithmetic Operators
The operators shown in Table A-12 can be used to perform arithmetic either on numbers or on date/times and durations.
Table A-12. Arithmetic Operators
Operator Description
div Division
idiv Integer division
mod Remainder from integer division
unary - Negation
unary + No-op
Comparisons
Table A-13 shows the comparisons you can perform between sequences and between values. General comparisons between sequences and values are true if the comparison is true for any item in the sequence. Value comparisons can only be used to compare single items.
Table A-13. Value and General Comparisons
Value Comparison General Comparison Description
eq = Equal to
ne != Not equal to
lt < Less than
le <= Less than or equal to
gt > Greater than
ge >= Greater than or equal to
The comparisons shown in Table A-14 are used to compare two nodes.
Table A-14. Node Comparisons
Operator Description
is true if the two operands are identical
<< true if the left operand appears before the right operand in document order
true if the right operand appears before the left operand in document order
Logical Operators
The logical operators, shown in Table A-15, compare two Boolean values.
Table A-15. Logical Operators
Operator Description
or true if either operand is true when converted to Booleans
and true if both operands are true when converted to Booleans
for Expression
Syntax:
for $ var1 in sequence1 , $ var2 in sequence2 , ... return expression
Returns a sequence containing the results of evaluating expression for every combination of items in sequence1, sequence2, and so on. The variables $var1, $var2, and so on can be used within the expression to refer to the relevant item in each sequence.
Conditional Expression
Syntax:
if ( test ) then true-expression else false-expression
Returns the result of evaluating true-expression if the effective Boolean value of the result of evaluating test is true, and the result of evaluating false-expression otherwise.
Quantified Expressions
The following quantified expressions test the items in a sequence to see whether they meet a particular condition.
some Expression
Syntax:
some $ var1 in sequence1 , $ var2 in sequence2 , ... satisfies test
Returns true if the effective Boolean value of the result of evaluating test for some com- bination of items in sequence1, sequence2, and so on is true. The variables $var1, $var2, and so on can be used within the test to refer to the relevant item in each sequence.
abs()
Returns the absolute value of the argument: the value itself if it’s positive, and the value multi- plied by –1 if it’s negative. If the argument is an empty sequence, returns an empty sequence.
numeric? abs(numeric?)
See also round(), floor(), ceiling(). From XPath 2.0.
adjust-date-to-timezone()
Returns the xs:date passed as the first argument adjusted to the timezone specified by the second argument. If the second argument is missing, it defaults to the implicit timezone. If the second argument is an empty sequence, the timezone of the xs:date is removed. If the first argument is an empty sequence, returns an empty sequence.
xs:date? adjust-date-to-timezone(xs:date?) xs:date? adjust-date-to-timezone(xs:date?, xdt:dayTimeDuration?)
See also adjust-dateTime-to-timezone(), adjust-time-to-timezone(), timezone-from-date(). From XPath 2.0.
adjust-dateTime-to-timezone()
Returns the xs:dateTime passed as the first argument adjusted to the timezone specified by the second argument. If the second argument is missing, it defaults to the implicit timezone. If the second argument is an empty sequence, the timezone of the xs:dateTime is removed. If the first argument is an empty sequence, returns an empty sequence.
xs:dateTime? adjust-dateTime-to-timezone(xs:dateTime?) xs:dateTime? adjust-dateTime-to-timezone(xs:dateTime?, xdt:dayTimeDuration?)
See also adjust-date-to-timezone(), adjust-time-to-timezone(), timezone-from-dateTime(). From XPath 2.0.
adjust-time-to-timezone()
Returns the xs:time passed as the first argument adjusted to the timezone specified by the second argument. If the second argument is missing, it defaults to the implicit timezone. If the second argument is an empty sequence, the timezone of the xs:time is removed. If the first argument is an empty sequence, returns an empty sequence.
xs:time? adjust-time-to-timezone(xs:time?) xs:time? adjust-time-to-timezone(xs:time?, xdt:dayTimeDuration?)
See also adjust-dateTime-to-timezone(), adjust-date-to-timezone(), timezone-from-time(). From XPath 2.0.
avg()
Returns the average value of the items in the argument sequence, which must all be numeric, all be xdt:dayTimeDurations, or all be xdt:yearMonthDurations. Returns the empty sequence if the argument is an empty sequence.
xdt:anyAtomicType? avg(xdt:anyAtomicType*)
See also sum(), count(), min(), max(). From XPath 2.0.
base-uri()
Returns the base URI of the node passed as the argument. If there’s no argument, returns the base URI of the stylesheet in which it’s used. If the argument is an empty sequence, returns an empty sequence.
xs:anyURI? base-uri() xs:anyURI? base-uri(node()?)
See also resolve-uri(), document(). From XPath 2.0.
boolean()
Returns the effective Boolean value of the argument. Usually this is done automatically, for example, in test attributes.
xs:boolean boolean(item()*)
See also string(), number(), not(), xs:boolean() constructor function. From XPath 1.0.
ceiling()
Rounds the argument up to the nearest integer (though this isn’t returned as an xs:integer unless the argument is an xs:integer). For negative numbers, this means rounding nearer to 0, so ceiling(-1.5) is -1. If the argument is an empty sequence, returns an empty sequence.
numeric? ceiling(numeric?)
See also floor(), round(). From XPath 1.0.
codepoint-equal()
Returns true if the first string is equal to the second string according to the Unicode codepoint collation. Returns an empty sequence if either argument is an empty sequence.
xs:boolean? codepoint-equal(xs:string?, xs:string?)
See also compare(), eq operator. From XPath 2.0.
xs:boolean contains(xs:string?, xs:string?) xs:boolean contains(xs:string?, xs:string?, xs:string)
See also matches(), starts-with(), ends-with(). From XPath 1.0.
count()
Returns the number of items in the sequence passed as the argument.
xs:integer count(item()*)
See also last(), position(), <xsl:number>. From: XPath 1.0.
current()
Returns the current item—the item that’s currently being processed within the <xsl:for-each> or <xsl:template>, or matched by a pattern, as opposed to the context item , which is the item currently being looked at within an XPath.
item() current()
See also the. expression. From XSLT 1.0.
current-date()
Returns the xs:date for the transformation. This doesn’t change during the transformation.
xs:date current-date()
See also current-dateTime(), current-time(). From XPath 2.0.
current-dateTime()
Returns the xs:dateTime for the transformation. This doesn’t change during the transformation.
xs:dateTime current-dateTime()
See also current-date(), current-time(). From XPath 2.0.
current-group()
Returns the items in the current group when grouping within <xsl:for-each-group>. When used outside <xsl:for-each-group>, returns an empty sequence.
item()* current-group()
See also current-grouping-key(), <xsl:for-each-group> instruction. From XSLT 2.0.
current-grouping-key()
Returns the value that’s being used to group items within <xsl:for-each-group> using group-by or group-adjacent attributes. Returns an empty sequence if used outside <xsl:for-each-group> or if the grouping is being done with group-starting-with or group-ending-with attributes.
xdt:anyAtomicType? current-grouping-key()
See also current-group(), <xsl:for-each-group> instruction. From XSLT 2.0.
current-time()
Returns the xs:time for the transformation. This doesn’t change during the transformation.
xs:time current-time()
See also current-dateTime(), current-date(). From XPath 2.0.
data()
Returns a sequence of atomic values from a sequence of items. Each node in the argument sequence is replaced by its typed value; each atomic value in the argument sequence remains as it is.
xdt:anyAtomicType* data(item()*)
See also string(). From XPath 2.0.
dateTime()
Returns an xs:dateTime value constructed by the date given as the first argument and the time given as the second argument. Raises an error if the date and time have different timezones; otherwise adopts the timezone of the arguments (no timezone if neither have timezones, the timezone of the argument with the timezone if only one has a timezone).
xs:dateTime dateTime(xs:date, xs:time)
See also xs:dateTime() constructor function. From XPath 2.0.
day-from-date()
Returns the day component from an xs:date. If the argument is an empty sequence, returns an empty sequence.
xs:integer? day-from-date(xs:date?)
See also year-from-date(), month-from-date(), timezone-from-date(). From XPath 2.0.
doc()
Returns a document node for the resource specified by the argument URI. If the argument is an empty sequence, returns an empty sequence.
document-node()? doc(xs:string?)
See also doc-available(), document(), unparsed-text(), collection(). From XPath 2.0.
doc-available()
Returns true if a call to doc() with the same URI argument will result in a document node; otherwise returns false.
xs:boolean doc-available(xs:string?)
See also doc(), document(). From XPath 2.0.
document()
Returns the nodes identified by the URIs specified via the first argument, resolved using the base URI of the node specified as the second argument. If the second argument is missing, URIs that are specified as atomic values are resolved relative to the base URI for the stylesheet, while URIs that are specified in nodes are resolved relative to the node in which they’re specified.
node()* document(item()) node() document(item()*, node())
See also doc(), doc-available(), unparsed-text(), collection(). From XSLT 1.0.
document-uri()
Returns the URI for the resource used to create a document node. Usually, this will be the same as the base URI for the document node, but it might be different if the document node was returned as part of a collection. For all other node kinds, or if the document doesn’t have a document URI, returns an empty sequence.
xs:string? document-uri(node()?)
See also base-uri(), collection(), doc(), document(). From XPath 2.0.
element-available()
Returns true if the processor supports the extension element or new XSLT instruction named by the string passed as the argument. The string should be a qualified name, with a prefix.
xs:boolean element-available(xs:string)
See also function-available(), <xsl:fallback> element. From XSLT 1.0.
empty()
Returns true if the argument is an empty sequence, and false otherwise.
xs:boolean empty(item()*)
See also not(), exists(). From XPath 2.0.
ends-with()
Returns true if the first argument string ends with the second argument string, according to the collation specified in the third argument string, or if the second argument string is an empty string or empty sequence, and returns false otherwise. If the third argument isn’t specified, it defaults to the Unicode codepoint collation.
xs:boolean ends-with(xs:string?, xs:string?) xs:boolean ends-with(xs:string?, xs:string?, xs:string)
See also starts-with(), contains(), matches(). From XPath 2.0.
error()
Raises an error that halts the transformation. The first argument, if supplied, identifies the error; if it’s not supplied (there’s no argument or the first argument is an empty sequence), it defaults to the qualified name {http://www.w3.org/2004/07/xqt-errors}FOER0000. The first argument may be mapped to a URL in the form namespaceURI # localName by a processor. The second argument is a description of the error, and the third argument supplies additional items that provide information about the error.
■ Caution The URI http://www.w3.org/2004/07/xqt-errors will change in future versions of the spec.
error() error(xs:QName) error(xs:QName?, xs:string) error(xs:QName?, xs:string, item()*)
■ Note This function doesn’t return anything: calling it halts the transformation.
See also trace(), <xsl:message>. From XPath 2.0.
