Xpath Quick Reference

Home , CDATA, Node (computer science), Processing Instruction, XInclude, XML Base, XML namespace

3243chAppA.qxd 6/20/05 10:34 AM Page 697

APPENDIX A ■ ■ ■ XPath Quick Reference

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

697 3243chAppA.qxd 6/20/05 10:34 AM Page 698

698 APPENDIX A ■ XPATH QUICK REFERENCE

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. 3243chAppA.qxd 6/20/05 10:34 AM Page 699

APPENDIX A ■ XPATH QUICK REFERENCE 699

Table A-3. Atomic Types in Basic XSLT Atomic Type Representation Description xs:string The string itself A sequence of XML characters xs:boolean 'true', 'false', '1', true or false or '0' xs:decimal Any number of digits, with A decimal number, with size optional fractional part limits being implementation- defined xs:integer Any number of digits An integer, with size limits being implementation-defined xs:double As xs:decimal, but with optional A floating-point number: exponent, 'NaN', 'INF', or '-INF' a double-precision 64-bit format IEEE 754 value xs:float As xs:double A floating-point number: a single-precision 32-bit format IEEE 754 value xs:date YYYY-MM-DD A date: year, month, day, and optional timezone xs:time hh:mm:ss A time: hours, minutes, seconds, and optional timezone xs:dateTime YYYY-MM-DDThh:mm:ss A date and time: year, month, day, hours, minutes, seconds, and optional timezone xs:gYear YYYY A year with optional timezone xs:gYearMonth YYYY-MM A year and month with optional timezone xs:gMonth --MM A month with optional timezone xs:gMonthDay --MM-DD A month and day with optional timezone xs:gDay ---DD A day with optional timezone xs:duration PyYmMdDThHmMsS A duration of years, months, days, hours, minutes, and seconds xdt:dayTimeDuration PdDThHmMsS A duration of days, hours, minutes, and seconds xdt:yearMonthDuration PyYmM A duration of years and months xs:QName prefix:local-name or just A qualified name: local-name; namespace must a namespace URI and a local be declared name xs:anyURI URI syntax A URI xs:hexBinary Hex-encoded octets Binary data xs:base64Binary Base64-encoded octets Binary data xdt:untypedAtomic Any string An atomic value whose type is not known, and can be cast implicitly to another type 3243chAppA.qxd 6/20/05 10:34 AM Page 700

700 APPENDIX A ■ XPATH QUICK REFERENCE

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 .

xdt:anyAtomicType

xs:dateTime xs:date xs:time xs:gYear xs:gYearMonth xs:gMonth xs:gMonthDay xs:gDay

xs:boolean xs:hexBinary xs:base64Binary xs:anyURI xs:QName xs:NOTATION xs:duration

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:negativeInteger xs:positiveInteger xs:unsignedLong xs:language xs:Name xs:NMTOKEN xs:short xs:unsignedInt xs:NCName xs:byte xs:unsignedShort xs:ID xs:IDREF xs:ENTITY xs:unsignedByte

Key: primitive type XSD type XPath type

Figure A-1. The hierarchy of built-in types

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. 3243chAppA.qxd 6/20/05 10:34 AM Page 701

APPENDIX A ■ XPATH QUICK REFERENCE 701

■Note Literal strings can 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) 3243chAppA.qxd 6/20/05 10:34 AM Page 702

702 APPENDIX A ■ XPATH QUICK REFERENCE

Node kind tests are used to test nodes. Node kind tests are summarized in Table A-7.

Table A-7. Node Kind Tests Node Kind Node Test Description Nodes node() Matches or selects all kinds of nodes Document nodes document-node() Matches or selects all document nodes document-node(element(name)) Matches or selects document nodes with a single document element with a particular name document-node(element(*, type)) Matches or selects document nodes with a single document element with a particular type document-node(element(name, type)) Matches or selects document nodes with a single document element with a particular name and type document-node(schema-element(name)) Matches or selects document nodes with a single document element that matches a global element declaration within a schema Text text() Elements element() Matches or selects all elements element(name) Matches or selects elements with a particular name element(*, type) Matches or selects elements with a particular type element(name, type) Matches or selects elements with a particular name and type schema-element(name) Matches or selects elements based on a global element declaration within a schema Attributes attribute() Matches or selects all attributes attribute(name) Matches or selects attributes with a particular name attribute(*, type) Matches or selects attributes with a particular type attribute(name, type) Matches or selects attributes with a particular name and type schema-attribute(name) Matches or selects attributes based on a global attribute declaration within a schema Comments comment() Processing processing-instruction() Matches or selects all processing Instructions instructions processing-instruction(target) Matches or selects processing instructions with a particular target 3243chAppA.qxd 6/20/05 10:34 AM Page 703

APPENDIX A ■ XPATH QUICK REFERENCE 703

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. 3243chAppA.qxd 6/20/05 10:34 AM Page 704

704 APPENDIX A ■ XPATH QUICK REFERENCE

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: 3243chAppA.qxd 6/20/05 10:34 AM Page 705

APPENDIX A ■ XPATH QUICK REFERENCE 705

1. , (sequence concatenation)

2. for, some, every, if

3. or

4. and

5. eq, ne, lt, le, gt, ge, =, !=, <,

6. to

7. +, -

8. *, div, idiv, mod

9. union, |

10. intersect, except

11. instance of

12. treat

13. castable

14. cast

15. unary -, unary +-, unary +

Sequence Operators The operators shown in Table A-11 can be used to create sequences.

Table A-11. Sequence Operators Operator Description , Concatenates two sequences together to Creates a sequence containing all the integers from the left operand to the right operand | Creates a node sequence containing all the nodes that are in either operand, in document order union Creates a node sequence containing all the nodes that are in either operand, in document order intersect Creates a node sequence containing all the nodes that are in both operands, in document order except Creates a node sequence containing all the nodes that are in the left operand but not in the right operand, in document order

■Note The operands for to must be integers. The operands for |, union, intersect, and except must be sequences of nodes. 3243chAppA.qxd 6/20/05 10:34 AM Page 706

706 APPENDIX A ■ XPATH QUICK REFERENCE

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 + Addition - Subtraction * Multiplication 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 3243chAppA.qxd 6/20/05 10:34 AM Page 707

APPENDIX A ■ XPATH QUICK REFERENCE 707

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 combination 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. 3243chAppA.qxd 6/20/05 10:34 AM Page 708

708 APPENDIX A ■ XPATH QUICK REFERENCE

every Expression Syntax:

every $var1 in sequence1, $var2 in sequence2, ... satisfies test

Returns true if the effective Boolean value of the result of evaluating test for every combination 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.

Expressions on Sequence Types The expressions shown in Table A-16 deal with testing and casting values so that they meet a particular sequence type.

Table A-16. Expressions on Sequence Types Expression Description expression instance of SequenceType Returns true if the result of evaluating expression matches SequenceType expression cast as atomicType Returns the result of casting the result of evaluating expression to a single item of the named atomic type, or an error if it cannot be cast expression cast as atomicType? Returns the result of casting the result of evaluating expression to an optional item of the named atomic type, or an error if it cannot be cast expression castable as atomicType Returns true if the result of expression cast as atomicType is not an error expression castable as atomicType? Returns true if the result of expression cast as atomicType? is not an error expression treat as SequenceType Returns the result of evaluating expression if it matches SequenceType, or an error if it does not match SequenceType

Functions This section describes the functions defined in XPath and XSLT 2.0. As well as these functions, there are built-in constructor functions for every atomic type known to the XSLT processor. Individual XSLT processors may also support extension functions. Individual stylesheets may define their own stylesheet functions. The signatures of the functions in this section use the sequence-type syntax to describe the return type and the argument types. The term numeric is used when the argument or return type can be any of the numeric types xs:integer, xs:decimal, xs:float, or xs:double; in these cases, untyped arguments are usually cast to xs:double. 3243chAppA.qxd 6/20/05 10:34 AM Page 709

APPENDIX A ■ XPATH QUICK REFERENCE 709

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. 3243chAppA.qxd 6/20/05 10:34 AM Page 710

710 APPENDIX A ■ XPATH QUICK REFERENCE

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. 3243chAppA.qxd 6/20/05 10:34 AM Page 711

APPENDIX A ■ XPATH QUICK REFERENCE 711

codepoints-to-string() Returns the result of converting each integer in the argument sequence to the appropriate Unicode character and concatenating the results into a string. Raises an error if any of the integers is the codepoint of a character that’s not legal in XML, and returns an empty string if the argument sequence is empty.

xs:string codepoints-to-string(xs:integer*)

See also string-to-codepoints(). From XPath 2.0.

collection() Returns a sequence of nodes based on the argument URI or the default collection if no argument is specified. How a particular sequence of nodes is associated with a particular URI is implementation-defined. Returns an empty sequence if the argument is an empty sequence.

node()* collection() node()* collection(xs:string?)

See also doc(), document(). From XPath 2.0.

compare() Compares the first and second arguments using the collation specified as the third argument. Returns 0 if they’re the same, -1 if the first argument is less than the second argument, and 1 if the first argument is greater than the second argument. If no third argument is specified, uses the default collation. If either of the first or second arguments is an empty sequence, returns an empty sequence.

xs:integer? compare(xs:string?, xs:string?) xs:integer? compare(xs:string?, xs:string?, xs:string)

See also codepoint-equal(), comparison operators (eq, ne, lt, le, gt, ge). From XPath 2.0.

concat() Concatenates the strings passed as arguments into a single string.

xs:string concat(xs:string?, xs:string?, ...)

See also , . From XSLT 1.0.

The declaration defines a set of attributes that can then all be added to an element at once through the use-attribute-sets attribute on or , or the xsl:use-attribute-sets attribute on literal result elements. It is located at the top level of the stylesheet, as a child of . 3243chAppB.qxd 6/20/05 10:35 AM Page 750

750 APPENDIX B ■ XSLT QUICK REFERENCE

The name attribute holds the qualified name of the attribute set, by which it can be referred to later on. The element contains a number of elements. The use-attribute-sets attribute contains a space-delimited list of the qualified names of other attribute sets. The attributes from the used attribute sets are added to this one.

(xsl:attribute*)

See also , , , xsl:use-attribute-sets. From XSLT 1.0.

The instruction calls a template by name. The name of the called template is held in the name attribute. The elements held within the are used to define parameters that are passed to the template. See the description of for more details.

(xsl:with-param*)

See also . From XSLT 1.0.

The instruction creates a shallow copy of the current node. For most nodes, this is equivalent to a deep copy, but for element and document nodes it’s slightly different. If the current node is an element or document node, the children of the copy are the results of processing the contents of the instruction. If the current node is an element, then any namespace nodes from the original element are copied over, unless the copy-namespaces attribute is present with the value no. If inherit-namespaces is present with the value no, the children of the new element will not have copies of the namespace nodes of the copied element. The attributes from the attribute sets named in use-attribute-sets are added to the copied element (along with any attributes that might be added through instructions within the ). If the current node is an element, attribute, or document node, the type and validation attributes control the validation of the element, attribute, or document. See the descriptions in , , and for details. 3243chAppB.qxd 6/20/05 10:35 AM Page 752

752 APPENDIX B ■ XSLT QUICK REFERENCE

sequence-constructor

See also , . From XSLT 1.0.

The instruction creates a deep copy of whatever is selected by the expression held in its select attribute. A deep copy of a node includes child nodes, attributes, and namespace nodes (unless the copy-namespaces attribute is present with the value no). If the node to be copied is an element, attribute, or document node, the type and validation attributes control the validation of the copy. See the descriptions in , , and for details.

See also , . From XSLT 1.0.

The element makes type definitions and element and attribute declarations available for use within the stylesheet. It lives at the top level of the stylesheet, as a child of the document element. A W3C XML Schema schema can be embedded within the element, in which case the namespace attribute, if present, must have the same value as the target namespace of that schema. Alternatively, the XSLT processor may try to locate a schema using the namespace attribute alone (a missing namespace attribute indicates a schema with no target namespace) or in conjunction with the schema-location attribute.

(xs:schema?)

From XSLT 2.0.

The element includes a stylesheet in this one. This gives you access to all the declarations within that stylesheet, exactly as if they had been specified in your stylesheet. The href attribute gives the location of the included stylesheet. The element is a top-level element, and must appear as a direct child of the document element.

See also . From XSLT 1.0.

The element declares a key that indexes all the nodes in a document by a particular value. Each key is identified by its name attribute. The nodes that are indexed by a key are those that match the pattern held in its match attribute. The value by which each node is indexed is specified through the use attribute or the content of the element (you can’t have both), which is evaluated for each matched node. If it results in a single value, then that value is used to index the node. If the expression evaluates as a sequence, then there are multiple entries for the matched node, one for each of the values. This enables you to access a node through multiple values using the key() function. When a node is retrieved using a string value, via the key() function, the collation specified by the collation attribute is used to compare that value with the value used to index the node. The elements are top-level elements, direct children of the document element. There can be multiple keys with the same name within a stylesheet; they are combined for the purpose of retrieving nodes using the key() function. 3243chAppB.qxd 6/20/05 10:35 AM Page 758

758 APPENDIX B ■ XSLT QUICK REFERENCE

sequence-constructor

See also , . From XSLT 1.0.

The element describes how a result tree should be serialized into a file. The name attribute gives the name of the output definition, which can be used to refer to it via the format attribute on . If the element does not have a name, it’s the default output definition. The method attribute has the most effect on the serialization, determining whether the stylesheet creates XML, text, HTML, XHTML, or some other format defined by a processor implementer. The media-type and version attributes give tighter definition about the format being generated. The encoding attribute determines the character encoding used during serialization, and defaults to UTF-8 or UTF-16. The byte-order-mark attribute determines whether a Byte Order Mark is written at the start of the file; it defaults to yes for UTF-16, is implementation-defined for UTF-8, and defaults to no for other encodings. Characters that are held in character maps named by the use-character-maps attribute are replaced by the associated strings. The indent attribute determines whether whitespace-only text nodes are added to the result tree in order to make it easier to read; this is yes by default for HTML and XHTML, and no by default for XML. The normalization-form attribute determines how the result is Unicode normalized and defaults to none. The doctype-public and doctype-system attributes hold the public and system identifiers for the result, which are included in a DOCTYPE declaration at the top of the generated file. When generating XML or XHTML, a processor will add an XML declaration at the start of the output, unless the omit-xml-declaration attribute is present with the value yes. Even if this attribute is present, the XML declaration will still be added if the encoding is something other than UTF-8 or UTF-16, or if the standalone attribute is present (in which case the XML declaration contains a standalone pseudo-attribute with the specified value). To cater for 3243chAppB.qxd 6/20/05 10:35 AM Page 762

762 APPENDIX B ■ XSLT QUICK REFERENCE

XML 1.1, you can permit a processor to include namespace undeclarations using the undeclare-prefixes attribute with the value yes. When generating HTML or XHTML, a processor will add a element in the element of the document unless the include-content-type attribute has the value no. It will also escape attributes that hold URIs, such as the href attribute on the element, unless the escape-uri-attributes attribute has the value no. The cdata-section-elements attribute lists the names of elements in the result whose text content should be wrapped within CDATA sections. The element should appear at the top level of the stylesheet, as a child of the document element. There can be multiple elements in a stylesheet, in which case they are combined on an attribute-by-attribute basis; it is an error for more than one element to specify the same attribute with different values.

See also , . From XSLT 1.0.

The element is used within an element to define a mapping between a character and a string. When a character map is used during serialization, the character held in the character attribute is replaced with the string held in the string attribute.

See also . From XSLT 2.0. 3243chAppB.qxd 6/20/05 10:35 AM Page 763

APPENDIX B ■ XSLT QUICK REFERENCE 763

The element declares a parameter for a template (if it’s within ), a stylesheet function (if it’s within ), or for the stylesheet as a whole (if it’s at the top level of the stylesheet). The name attribute holds the name of the parameter. The as attribute specifies the type of the value expected for the parameter. For template and stylesheet parameters, the required attribute indicates whether a value must be supplied for the parameter (the default is no, that it isn’t required). The select attribute or the content of the element (you can’t have both) holds the default value for the parameter, which will be used if no value is explicitly passed in to the stylesheet or template for that parameter. For template parameters, the tunnel attribute indicates whether the parameter is a tunneling parameter. If it has the value yes, the parameter can be set from an whose own tunnel attribute is yes, even if there are intervening templates that don’t declare or explicitly pass on the parameter.

sequence-constructor

See also . From XSLT 1.0.

The instruction creates a processing instruction whose target is the name held in the name attribute. The value of the created processing instruction is the result of processing the content of the instruction or evaluating its select attribute (it cannot have both). The resulting sequence is atomized, each item cast to a string, and those strings concatenated, with a single space separator between each item if the select attribute is used and no separator if the content of the instruction is used. The resulting value must not contain the string '?>'.

sequence-constructor

See also . From XSLT 1.0.

The instruction creates a result document node. The result document node is associated with the URI specified in the href attribute, if there is one. The content of the resulting document node is determined by evaluating the content of the instruction. After it’s constructed, the result document may be validated, depending on the values of the type or validation attributes, only one of which may be present. See for details. If the result tree is serialized, the output definition that’s used is the one named by the format attribute, or the default output definition if there’s no format attribute. The remaining attributes on override the equivalent attributes on that output definition.

APPENDIX B ■ XSLT QUICK REFERENCE 765

doctype-public="{string}"? doctype-system="{URI}"? omit-xml-declaration="{yes | no}"? standalone="{yes | no}"? undeclare-prefixes="{yes | no}"? escape-uri-attributes="{yes | no}"? include-content-type="{yes | no}"? cdata-section-elements="{list-of-qualified-names}"?> sequence-constructor

See also . From XSLT 1.0.

The element declares a template. Templates can be used in two ways within a stylesheet—they can be applied to nodes or they can be called by name. Each template must specify either a match attribute, so that it can be applied to nodes, or a name attribute, so that it can be called by name with . Both a name and a match pattern can be specified. When templates are applied to a sequence of nodes using , they might be applied in a particular mode; the mode attribute on indicates the mode in which templates need to be applied for this template to be used. If the value is #all, then the template will be used whatever the mode. If templates are applied in a matching mode, then the match attribute is used to determine whether the template can be used with the particular node. The match attribute holds a pattern against which nodes are matched. If a node matches the pattern, then the template can be used to process that node. If there’s more than one template that matches a node in the specified mode, then the priority attribute is used to determine which one should be used—the highest priority wins. If no priority is specified explicitly, the priority of a template is determined from its match pattern. Whether templates are applied or called, they can be passed parameters through the element. To use a parameter, however, the template must contain an element that declares a parameter of that name. These parameters are given before the body of the template, which is used to process the node and create a result. You can declare the type of the result of the template using the as attribute.

(xsl:param*, sequence-constructor)

See also , , , , . From XSLT 1.0. 3243chAppB.qxd 6/20/05 10:35 AM Page 768

768 APPENDIX B ■ XSLT QUICK REFERENCE

The element creates a text node. Unlike elsewhere within an XSLT stylesheet, whitespace-only text nodes within elements are included, so is the only way to add whitespace-only text nodes to the result tree (aside from those automatically added if you tell the processor to indent the output using the indent attribute on ). The element is also useful for limiting the amount of space that’s included around text when it’s added to the result. If the disable-output-escaping attribute is specified with the value yes, then the content of the element is output without special characters such as < and & being escaped with < or &.

text

See also . From XSLT 1.0.

The element is an alias for ; see the definition of for details.

(xsl:import*, top-level-elements)

See also . From XSLT 1.0.

The instruction creates a text node. The value of the created text node is the result of processing the content of the instruction or evaluating its select attribute (you can’t have both). The resulting sequence is atomized, each item cast to a string, and those strings concatenated with the value of the separator attribute used as a separator between each item. If the separator attribute isn’t present, it defaults to a single space if the select attribute is used, and to an empty string if the content of the element is used. If the disable-output-escaping attribute is specified with the value yes, then the value is output without special characters such as < and & being escaped with < or &. 3243chAppB.qxd 6/20/05 10:35 AM Page 769

APPENDIX B ■ XSLT QUICK REFERENCE 769

sequence-constructor

See also , . From XSLT 1.0.

The element declares a variable. If the element appears at the top level of the stylesheet, as a child of the document element, then it is a global variable with a scope covering the entire stylesheet. Otherwise, it is a local variable with a scope of its following siblings and their descendants. The name attribute specifies the name of the variable. After declaration, the variable can be referred to within XPath expressions using this name, prefixed with the $ character. The value of the variable is determined either by the select attribute or by the contents of the element (you can’t have both). The as attribute indicates the expected type of the variable. If the as attribute is missing, and you set the variable using its content, the variable holds the document node of a temporary tree. Otherwise, the variable holds the selected or constructed sequence.

sequence-constructor

See also . From XSLT 1.0.

The element appears within an instruction and specifies a set of processing that could occur and the condition when it occurs. The XSLT processor processes the content of the first within the whose test attribute contains an expression that evaluates to a value whose effective Boolean value is true.

sequence-constructor

See also , , , if expression. From XSLT 1.0.

The element specifies the value that should be passed to a template parameter. It can be used when applying templates with or calling templates 3243chAppB.qxd 6/20/05 10:35 AM Page 770

770 APPENDIX B ■ XSLT QUICK REFERENCE

with . The name attribute holds the name of the parameter for which the value is being passed. The value of the parameter is determined either by the select attribute or by the contents of the element (you can’t have both). The as attribute indicates the expected type of the parameter. If the as attribute is missing, and you set the parameter using its content, the parameter holds the document node of a temporary tree. Otherwise, the parameter holds the selected or constructed sequence. The tunnel attribute determines whether the parameter is a tunneling parameter or not. If it is, then even if a template doesn’t declare or explicitly pass on the parameter, it will be passed through that template in any case. Tunneling parameters can only be used in templates that declare parameters using an element with a tunnel attribute equal to yes.

sequence-constructor