XPath Quick Reference

Transcription

1

2 XPath Quick Reference Node Types Nodes can be of the following types: NodeType root element attribute text cornrnent processing narnespace Name Element name Attribute name Processing instruction target Namespace prefix String Value Concatenation of ali text nodes in the document Concatenation of ali text nodes descended from the element Attribute value Text Text held within the comment Text in the processing instruction after the space after the targetname Namespace URI bject Types Values in XSLT can be one of the following five types: bject Type boolean number Description true or false A floating-point number: a double-precision 64-bit format IEEE 754 value Table continued on following page

3 Appendix A bject Type string node set result tree fragment Description A sequence of XML characters An unordered collection of nodes The root node of a generated node tree The various object types can be converted to each other by the following rules. bject Boolean Number String boolean 1 if the boolean is true, if the boolean is false, true' if the boolean is true, 'false' if the boolean is false number false ifthe number is or NaN, otherwise true A string version of the number with no leading or trailing zeros; 'NaN' if the number is NaN,, Infinity' if the number is infinity, and '-Infinity' ifthe number is negative infinity string false ifthe string is an empty string, otherwise true The number held by the string, as long as it is a valid XPath number (which doesn't include exponents or grouping separators) ; otherwise NaN node set true if the node set holds nodes; false ifthe node set is empty The result of converting the string value of the first node in the node set to a number The string value of the first node in the node set result tree fragment true The result of converting the string value of the re suit tree fragment to a number The string value of the re suit tree fragment Booleans, numbers, and strings cannot be converted to node sets or result tree fragments. 694

4 Paths XPath Quick Reference Paths are made up of a number of steps, separated by / s. Each 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 posi tion () of a node is calculated - forward axes look at document order, reverse axes look at reverse document order. Axis self ehild parent attribute deseendant deseendantor-self aneestor aneestor-or-self following-sibling preeeding-sibling following preeeding namespaee Direction Forward Forward Reverse Forward Forward Forward Reverse Reverse Forward Reverse Forward Reverse Forward Description Selects the context node itself Selects the children of the context node Selects the parent of the context node Selects the attributes of the context node Selects the descendants of the context node at any level Selects the descendants of the context node, and the context node itself Selects the ancestors of the context node Selects the ancestors of the context node, and the context node itself Selects the siblings of the context node that follow the context node in document order Selects the siblings of the context node that precede the context node in document order Selects the nodes (asi de from attribute and namespace nodes) that follow the context node in document order and that are not descendants of the context node Selects the nodes (asi de from attribute and namespace nodes) that precede the context node in document order and that are not ancestors of the context node Selects the namespace nodes on the context node 695

5 Appendix A Node Tests Node tests match different kinds of nodes as follows: Node Test node() * name text( ) comment () processing-instruction() Description Matches nodes of all types Matches elements with any name (or attributes if you're using the attribute axis) Matches elements with the given name (or attribute if you're using the attribute axis) Matches text nodes Matches comment nodes Matches processing instruction nodes Matches processing instruction nodes with the given target Abbreviated Syntax You can use several abbreviations in XPath expressions, as described in the following table. Abbreviation Full Equivalent self: :node() parent: :node () processinginstruction('target') /descendant-orself: :node () / attribute: : Description The context node The parent of the context node SuppIies quick access to descendants of the context node Shortens expressions that access attributes perators The operators in XPath can be spiit into four groups: o Logical operators Comparisons Numerical operators N ode set operators 696

6 XPath Quick Reference The precedence of the operators (from lowest to highest) is as follows: 1. or 2. and 3. =,!= 4. <=,<,>=,> 5. +, - 6. *,div,mod 7. unary - 8. Logical perators perator or and Description true if either operand is true when converted to booleans; the right operand is not evaluated if the Ieft operand is true true if both operands are true when converted to booleans; the right operand is not evaluated ifthe Ieft operand is false Comparisons perator Description Equal to!= Not equal to < Less than <= Less than or equal to > Greater than >= Greater than or equal to Comparisons between node sets and values are true if the comparison is true for the string value of any node in the node set.. 697

7 Appendix A The numeric comparisons «, <=, >, and >=) can only be used to do numeric comparisons - you can't use them to test whether one string is alphabetically less than another string. Numerical perators perator + * div mod unary - Description Addition Subtraction Multiplication Floating-point division Remainder from integer division Negation Node Set perator perator Description Creates a union of two node sets Functions XPath and XSLT together define the following functions: boolean() boolean boolean (object) See also: string (), number () Converts the argument to a boolean value (either true or false). Usually this is done automatically, for example in test attributes. ceiling() number ceiling (number) See also: floor (), round () Rounds the argument up to the nearest integer. For negative numbers, this means rounding nearer to 0, so ceiling (-1. 5) is

8 XPath Quick Reference concat() string concat (string, string+) Concatenates the strings passed as arguments into a single string. contains() boolean contains (string, string) See also: starts-with () Returns true if the string passed as the first argument contains the string passed as the second argument or if the second argument is an empty string, and false otherwise. count() number count (node-set) See also: last ( ), posi tion (), <xsl: number> Counts the number of nodes in the node set passed as the argument. current() node-set current ( ) See also: the path. Returns the current node - the node that's current1y being processed within the <xsl: for-each> or <xsl: template> as opposed to the context node, which is the node currently being looked at within an XPath. document() node-set document (object, node-set?) If the first argument is a string, returns the node found at the URL specified by that string (usualiy the root node of a document). The URL is resolved relative to the location of the file containing the first node in the node set passed as the second argument (which is usualiy used to resolve the URL relative to the source document). If the second argument is- missing, the URL is resolved relative to the stylesheet itself. If the first argument is a node set, then the result is a node set containing ali the nodes that are retrieved by calling the document () function with the string values of the nodes in the node set. element-available( ) boolean element-available (string) See also: function-available ( ), <xsl: fallback> 699

9 Appendix A 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. false() boolean false ( ) See also: true ( ), boolean ( ) Returns false. floor number floor (number) See also: ceiling (), round () Rounds the number down to the nearest integer. If the number is negative, then it gets rounded away from zero, so floor (-1.5) returns -2. format-number( ) string format-number (number, string, string?) See also: number (), <xsl: decimal-format>, <xsl: number> Returns the number passed as the first argument formatted according to the format pattern passed as the second argument. The format pattern usually contains # to mean an optional digit, to indicate a required digit,. to indicate the decimal point, and, to indicate a grouping separator. For example, format-number (1234.5, '#, ##0.00' ) returns 1, If the third argument is specified, it gives the name of a decimal format, declared with the <xsl: decimal-format> element, which can de fine other characters to be used instead of #,, " and function-avai lable() boolean function-available (string) See also: element-available ( ) Returns true if the processor supports the function named by the argument string. The string usually includes a prefix to test for the availability of extension functions. generate-id( ) string generate-id (node-set?) Returns an ID for the first node in the node set passed as the argument which is both unique and a valid XML ID. If no argument is given, it returns a unique ID for the context node. The unique IDs are not stable - they are different from processor to processor, and even for the same processor operating over the same stylesheet with the same source XML document. 700

10 XPath Quick Reference id node-set id (object) See also: key ( ) Retums the nodes with the XML IDs specified by the argument. If the argument is a string, then it's split up at the whitespace, and the function retums ah the nodes in the current document that have any of the IDs. If the argument is a node set, the same is done but with the string values of each of the nodes in the node set. You have to have declared an attribute as an ID function within a DTD for the id ( ) attribute to work, and the context node must be in the same document as the nodes that you want to retrieve. key(} node-set key(string, object) See also: id (), <xsl: key> Retums the nodes that are indexed by the value specified by the second argument in the key named by the first argument. If the second argument is a node set, then ah the nodes with any of the values are retumed. You have to have declared the key with an <xs 1 : key> declaration, and the context node must be in the same document as the nodes that you want to retrieve. lang boolean lang (string) Retums true if the language of the context node (as specified with the xml : lang attribute) matches the language specified by the argument. This test is aware of sub languages and is case-insensitive, so for example lang ( 'en ') would retum true even ifthe context node's language was specified as EN-US. last number last () See also: posi tion (), count ( ) Retums the index of the last node in the list that's currently being looked at (or the number of nodes that are currently being looked at, depending on how you like to view it). local-name( } string local-name (node-set?) See also: name (), namespace-uri () Retums the local name of the first node in the node set - the part of the name after any prefix that there might be. If no argument is passed, then retums the local name of the context node. 701

11 Appendix A name() string name (node-set?) See also: local-name (), namespace-uri () Returns the fub name of the first node in the node set, including the prefix for its namespace as declared in the source document. If no argument is passed, then returns the fub name of the context node. namespace-uri( ) string namespace-uri (node-set?) See also: name ( ), local-name ( ) Returns the namespace URI for the first node in the node set, or an empty string if the node is in no namespace. If no argument is passed, then returns the namespace URI of the context node. normalize-space( ) string normalize-space (string?) See also: string (), <xsl: strip-space> Returns the argument string with leading and trailing whitespace stripped, and any sequences of whitespace converted to single spaces. If no argument string is specified, then it returns the normalized string value of the context node. not() boolean not (boolean) See also: true ( ), false (), boolean () Returns false if the argument is true, and true if the argument is false. number() number number (object?) See also: string (), boolean (), format-number (), <xsl :number> Converts the argument to a number; if no argument is given, returns the numerical value of the context node. You don't usually need to use this function because values are converted to numbers automatically if they need to be numbers. position() number posi tion ( ) See also: last (), count (), <xsl :number> 702

12 XPath Quick Reference Returns the position of the context node amongst the list of nodes that are currentiy being looked at. Unlike the numbers generated through <xsl: number>, the posi tion () function depends on the order in which nodes are processed regardless of their original order in the source document. round number round (number) See also: floor (), cei ling () Rounds the argument number to the nearest integer. If the number is exacdy between two integers, then it rounds up (the same as cei ling ( )). starts-with( ) boolean starts-with (string, string) See also: contains ( ) Returns true if the first argument string starts with the second argument string, or if the second argument string is empty, and returns false otherwise. stringe) string string(object?) See also: boolean ( ), number ( ) Converts the argument to a string; if no argument is given, returns the string value of the context node. You don't normally need to use this function because values are converted to strings automatically if they need to be strings. string-iength( ) number string-length (string?) See also: substring () Returns the length of the string passed as the argument. If no argument is passed, then returns the length of the string value of the context node. substring( ) string substring (string, number, number?) See also: substring-before (), substring-after () Returns a sub string of the first argument string starting from the number passed as the second argument and a number of characters long equal to the third argument number. If the third argument isn't specified, then it returns the rest of the string, to the last character. The first character in the string is numbered

13 Appendix A substring-after( ) string substring-after (string, string) See also: substring-before (), substring () Retums the substring of the first argument string that occurs after the second argument string. If the second string is not contained in the first string, or if the second string is empty, then it retums an empty string. substring-before( ) string substring-before (string, string) See also: substring-after (), substring () Retums the substring of the first argument string that occurs before the second argument string. If the second string is not contained in the first string, or if the second string is empty, then it retums an empty string. sum() number sum(nade-set) Retums the sum of the values of the nodes in the node set. If any of the nodes' values isn't numeric, then this function retums NaN. Ifthe node set is empty, it retums. system-property( ) abject system-property (string) See also: element-available ( ), function-available ( ) Supplies information about the processor that's being used to run the stylesheet. The argument string specifies the kind of information that's retumed. There are three standard arguments: o xsl: vers ion - the version of XSLT supported by the processor (usually 1. in current XSLT processors) xsl :vendor - the name ofthe vendor ofthe XSLT processor xsl : vendor-url - a URL for the vendor of the XSLT processor Processors can support their own system properties. For example, MSXML supports the system property msxs 1 : ver sion which returns the version of MSXML that' s being used. translate( ) 704 string translate (string, string, string) Returns the first argument string with all occurrences of the characters in the second argument string replaced by their corresponding characters in the third string. If a character in the second string doesn't have a corresponding character in the third string, then the character is deleted from the first string.

14 XPath Quick Reference true() boolean true ( ) See also: false ( ), boolean ( ) Retums true. unparsed-entity-uri( ) string unparsed-enti ty-uri (string) Retums the URI of the unparsed entity whose name is passed as the argument. Unparsed entities are declared within DTDs as a way of pointing to non-xml files, but they aren't very common nowadays. 705

15

16 XSLT Quick Reference XSLT Elements This section describes each of the XSLT 1.0 elements in alphabetical order. The syntax for each element is shown, followed by a description. Within the syntax descriptions, attributes that are attribute value templates are indicated by curly braces ( { } ) within the attribute value. Required attributes and default values are shown in bold. xsl:apply-imports <xsl:apply-imports /> See also: <xsl: import>, <xsl: apply-templates> The <xsl: apply-imports> instruction tells the XSLT processor to take the current node and try to find a template in an imported stylesheet that (a) is in the same mode as the current template and (b) matches the current node. If the processor locates a template, it uses that template to process the current node; otherwise it uses the default templates. The <xsl: apply-imports> instruction must be within an <xsl: template> element, and is not allowed as a descendant of an <xsl: for-each> - the current node at the point at which the <xsl: apply-imports> instruction is used must be the same as the current node of the template it's in.

17 Appendix B xsl :apply-templates <xsl:apply-templates select="node-set-expression" mode="qualified-name"> (xsl:sort I xsl:with-param)* </xsl:apply-templates> See also: <xsl: sort>, <xsl :with-param>, <xsl: template>, <xsl: call-template>, <xsl:for-each>,<xsl:apply-imports> The <xsl: apply-templates> instruction tells the processor to gather together a set of nodes and to process each of the nodes by finding a template that matches it and using that template. The nodes that the processor applies templates to are selected by the path held in the select attribute. If the select attribute is missing, then the processor applies templates to the child nodes of the current node. The nodes are processed in the order determined by the <xsl : sort> elements that are contained by the <xsl: apply-templates> instruction. See the description of <xsl: sort> for details. If there are no <xsl: sort> elements within the <xsl: apply-templates> instruction, the processor goes through the nodes in document order (the order in which they appeared in their document). The only templates that can match the nodes to which the processor applies templates are those whose mode attribute has the same value as the value of the mode attribute on the <xsl : applytemplates>. If the <xsl: apply-templates> instruction doesn't have a mode attribute, then the only templates that are applied are those without a mode attribute. The templates that are used are passed the parameters specified by the <xsl: wi th-param> elements within the <xsl: apply-templates> instruction. See the description of <xsl :wi th-param> for details. xsl:attribute <xsl:attribute name=" {qualified-name} " namespace=" {namespace-uri} "> template </xsl:attribute> See also: <xsl: attribute-set>, <xsl: element> The <xsl: attribute> instruction creates an attribute. When adding attributes to an element, any <xsl: attribute> instructions must come before any instructions that add content to the element. The <xsl: attribute> instruction can also be included within an <xsl: attribute-set> element; see the description of <xsl: attribute-set> for details. 708

18 XSLT Quick Reference The name of the attribute that's created is determined by its name and namespace attributes. The name attribute gives the qualified name for the attribute and the namespace attribute gives the namespace for the attribute. If the name held in the name attribute doesn't include a prefix and the namespace attribute has a value, then the generated attribute will be given a prefix generated by the XSL T processor. If the namespace attribute is missing, then the qualified name specified by the name attribute is used to identify the namespace for the attribute - the namespace associated with the qualified name's prefix. If the qualified name doesn't have a prefix, then the attribute is in no namespace. Both the name and namespace attributes are attribute value templates, so their values can be calculated on the fiy. The value of the created attribute is the re suit of processing the content of the <xs 1 : a t tr ibu te> instruction. The instructions within the <xsl: attribute> must not generate any nodes aside from text nodes. xsl :attri bute-set <xsl:attribute-set name="qualified-name" use-attribute-sets= " list-of-qualified-names" > xsl:attribute* </xsl:attribute-set> See also: <xsl: at tribute>, <xsl : element>, <xsl : copy>, xsl: use-attribute-sets The <xsl: attribute-set> declaration defines a set of attributes that can then au be added to an element at once through the use-attribute-sets attribute on <xsl: element> or <xsl: copy>, 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 <xsl: stylesheet>. The name attribute holds the qualified name of the attribute set, by which it can be referred to later ono The <xsl: attribute-set> element contains a number of <xsl: attribute> elements. The usea t tribute-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 :call-template <xsl:call-template name="qualified-name"> xsl:with-param* </xsl:call-template> See also: <xsl: template>, <xsl: apply-templates> 709

19 Appendix 8 The <xsl: call-template> instruction calls a template by name. The name of the called template is held in the name attribute. The <xs 1 : wi th -par am> elements held within the <xs 1 : calltemplate> are used to define parameters that are passed to the template. See the description of <xs 1 : wi th -param> for more details. xsl:choose <xsl:choose> (xsl:when+, xsl:otherwise?) </xsl:choose> See also: <xsl :when>, <xsl: otherwise>, <xsl: if> The <xsl: choose> instruction is a conditional construct that causes different instructions to be processed in different circumstances. The XSLT processor processes the instructions held in the first <xsl :when> element whose test attribute evaluates as true. Ifnone ofthe <xsl :when> elements' test attributes evaluate as true, the content of the <xsl: otherwise> element, if there is one, is processed. xsl:comment <xsl:comment> template </xsl:comment> See also: <xsl :processing-instruction> The <xsl: comment> instruction generates a comment node. The instructions within the <xsl: comment> element determine the value of the comment. These instructions must not generate any nodes apart from text nodes, and the text nodes that they generate must not contain two hyphens next to each other ('--'), as this sequence isn't allowed in comments. xsl:copy <xsl:copy use-attribute-sets="list-of-qualified-names"> template </xsl:copy> 710 See also: <xsl: copy-of>, <xsl: attribute-set> The <xs 1: copy> instruction creates a shallow copy of the current node. For most nodes, this is equivalent to a deep copy, but for element and root nodes it's slightly different.

20 XSLT Quick Reference If the current node is an element or root node, the children of the copy are the results of processing the contents of the <xs 1 : copy> instruction. If the current node is an element, then any namespace nodes from the original element are copied over. The attributes from the attribute sets named in useattribute-sets are added to the copied element (along with any attributes that might be added through <xsl: attribute> instructions within the <xsl: copy». xsl :copy-of <xsl:copy-of select.="expression" /> See also: <xsl: copy>, <xsl :value-of> The <xsl: copy-of> instruction creates a deep copy ofwhatever is selected by the expression held in its select attribute. If the expres sion evaluates to a string, number, or boolean, then it creates a text node whose value is that value. If the expres sion evaluates to a node set or a re suit tree fragment, then it creates a deep copy of the nodes in the node set or the result tree fragment. This deep copy includes child nodes, attributes, and namespace nodes. xsl :decimal-format <xsl:decimal-format name="qualified-name" digit="character" zero-digit="character" decimal-separator="character" grouping-separator="character" minus-sign=licharacter ll pattern-separator="character" percent="character" per-mille="character" infinity="string" NaN="string" /> See also: format-number () <xs 1 : dec imal-forma t> elements de fine methods of interpreting the format pattern strings that are used as the second argument of the format-number () function. They live at the top level of the stylesheet, as children of <xsl : stylesheet>. There can be many decimal formats, but they must ali have different names, specified by the name attribute. If the name attribute is missing, the decimal format is used as the default decimal format. When you use the format-number () function, the XSLT processor identifies a decimal format to use to interpret the pattern that you specify as the second argument. Ifthe format-number () function is passed three arguments, the third argument is taken as the name of a decimal format, and that decimal format is used. If the format-number () function is passed two arguments, then the default decimal format is used; if you haven't specified a default decimal format, then the XSLT processor uses one with ali attributes set to their default values. 711

21 Appendix B When the XSLT processor formats the number, it looks first to see if it is infinity or not a number. If it is infinity, then the XSLT processor returns the string held in the inf ini ty attribute. If it is not a number, then the XSLT processor returns the string held in the NaN attribute. If the number is a number, and not infinity, the XSLT processor has to format it according to the pattern string passed as the second argument of format-number () and the decimal format that is identified. The processor splits the pattern into a positive pattern and a negative pattern at the character held by the pattern-separator attribute, which defaults to the semicolon character (;). The minus sign is indicated by the character held by the minus-sign attribute, which defaults to the hyphen character (-), within the negative pattern. If there's no negative pattern, then it defaults to the same as the positive pattern, prefixed by the character held in the minus-sign attribute ofthe decima! format. If the pattern contains the character held by the percent attribute (which defaults to the percent character, %), then the number being formatted is multiplied by 100 prior to formatting, and that character is included as specified by the pattern. If the pattern contains the character held by the permille attribute (which defaults to the per-mille character, 80 or &#x2 030;), then the number being formatted is multiplied by prior to formatting, and that character is included as specified by the pattern. The remaining pattern string is interpreted to indicate how many digits should occur before and after the decimal point and if the digits should be grouped, and if so what by. Within the pattern, essential digits are indicated by the character held in the zero-digit attribute (which defaults to the zero character, ), and optional digits are indicated by the character held in the digit attribute (which defaults to the hash character, #). The decimal point is the character held in the decimal-point attribute of the decimal format (which defaults to the period character,.). Groups of digits are separated by the character held in the grouping-separator attribute (which defaults to the comma character,,). xsl :element 712 <xsl:element name="{qualified-name}" namespace=" {namespace-uri} " use-attribute-sets=" list-of-quali fied-names" > template </xsl:element> See also: <xsl: attribute-set> The <xsl: element> instruction creates an element. The name of the element that's created is determined by its name and namespace attributes. The name attribute gives the qualified name for the element and the namespace attribute gives the namespace for the element. If the namespace attribute is missing, then the qualified name specified by the name attribute is used to identify the namespace for the element - the namespace associated with the qualified name's prefix, or the default namespace if it doesn't have a prefix. Both the name and namespace attributes are attribute value templates, so their values can be calculated on the fiy - in fact, this is the only reason you should use <xsl: element> rather than a literal re suit element. Ifthe use-attribute-sets attribute is present, then the attributes held in the attribute sets named within this attribute are added to the created element. ther attributes and the content of the element are generated as the result of processing the content of the <xs l : el emen t> instruction.

22 XSL T Quick Reference xsl:fallback <xsl:fallback> template </xsl:fallback> The <xsl : fallback> element provides alternative processing in the event that an implementation does not support a particular element. When an XSL T processor comes across an instruction that it doesn't understand (such as an XSLT 2.0 instruction or an extension element), it looks for an <xs 1 : f allback> element amongst its children. If it finds one, it processes the content of that <xs 1 : f allback> element; if it doesn't, it stops processing and the transformation fails. xsl :for-each <xsl:for-each select="node-set-expression"> (xsl:sort, template) </xsl:for-each> See also: <xsl : sort>, <xsl: apply-templates> The <xsl: for-each> instruction tells the XSLT processor to gather together a set of nodes and process them one by one. The nodes are selected by the expres sion held in the select attribute. If there are any <xsl: sort> elements, these change the order in which the nodes are processed; ifthere aren't any, then they are processed in document order. Each of the nodes is then processed according to the instructions held in the <xsl : for-each> after any <xsl : sort> elements. xsl:if <xsl:if test="boolean-expression"> template </xsl:if> See also: <xsl: choose>, <xsl :when> The <xs 1 : i f> instruction performs some conditional processing. The content of the <xs 1 : i f> is only processed if the expression held in its tes t attribute evaluates to boolean true. xsl:import 713

23 Appendix B <xsl:import href="uri" /> See also: <xsl: include>, <xsl: apply-imports> The <xsl: import> element imports a stylesheet into this one. This gives you access to au the declarations and templates within that stylesheet, and auows you to override them with your own if you need to. The href attribute gives the location of the imported stylesheet. Any <xsl : import> elements must be the very first elements within the stylesheet, the first children of the <xsl: stylesheet> document element. xsl:include <xsl:include href="uri" /> See also: <xsl : import> The <xsl: include> element includes a stylesheet in this one. This gives you access to au the declarations within that stylesheet, exact1y as if they had been specified in your stylesheet. The href attribute gives the location of the included stylesheet. The <xsl : incl ude> element is a top-ievel element, and must appear as a direct child of the <xsl: stylesheet> document element. xsl:key <xsl:key name="qualified-name" match="pattern" use="expression" /> See also: key ( ) The <xs 1 : key> element declares a key, which indexes au 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 ma tch attribute. The value by which each node is indexed is specified through the use attribute. The expression held in the use attribute is evaluated for each matched node. If it results in a string, number, or boolean, then that value is used to index the node. If the expression evaluates as a node set, then there are multiple entries for the matched node, one for each of the selected nodes, using the string value of each of those nodes. This enables you to access a node through multiple values using the key () function. The <xsl: key> elements are top-ievel elements, direct children of the <xsl: stylesheet> 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. 714

24 XSL T Quick Reference xsl:message <xsl:message terminate="yes I no"> template </xsl:message> The <xsl: message> instruction sends a message to the XSLT processor, which will usually forward the message on to the person running the transformation. If the terminate attribute is present with the value yes, then the transformation ends with the error message, otherwise it continues. The content of the <xs 1 : mes sage> instruction provides the message itself. xsl :namespace-alias <xsl:narnespace-alias stylesheet-prefix="narnespace-prefix I #default" result-prefix="narnespace-prefix I #default" /> The <xsl: namespace-alias> element tells the XSLT processor that a namespace as used in the stylesheet should be substituted by another namespace in the result tree. This is usually used when creating stylesheets that create stylesheets: a namespace alias enables you to create the XSLT elements for the result as literal result elements, without the XSLT processor confusing them with instructions that it should follow. The stylesheet-prefix attribute holds the prefix associated with the alias namespace within the stylesheet. The resul t-prefix attribute holds the prefix associated with the namespace that should be used instead, in the result (which is usually xsl when generating XSLT). The keyword #defaul t can be used to indicate the default (unprefixed) namespace in either attribute. xsl:number <xsl:nurnber level="single I multiple I any" count="pattern" from="pattern" value="numeric-expression" format=" {format-pattern}" lang=" {language-code} " letter-value="{alphabetic I traditional}" grouping-separator=" {character} " grouping-size="{integer}" /> See also: format-number (), posi tion () 715

25 Appendix B The <xs 1 : number> instruction inserts a number into the result tree. The <xsl : number> instruction actually has two roles: generating a number and formatting that number. By default, <xsl : number> generates a number based on the position of the current node amongst its similarly named siblings within the source XML document. You can control what number is generated more precisely using the level, count, and from attributes. The level attribute determines what kinds of numbers are generated. The value single numbers nodes amongst their siblings. The value any numbers nodes throughout the source tree. The value mul tiple creates multilevel numbering based on the hierarchical structure of the source tree. nly nodes that match the pattern held in the count attribute will be counted when creating a number. The from attribute holds a pattern matching the node from which numbering should start afresh. If you already know the number that you want, you can use the val ue attribute to specify the number directly, rather than using the number-generating aspect of <xsl: number>. The number is formatted according to the format pattern held in the format attribute. This works in a different way from the format pattern used by the format-number () function, because it's used to number integers rather than decimal numbers. The format pattern can hold any punctuation characters and placeholders that indicate where the number should be included and in what format. There are five standard placeholders: 1 for decimal numbers, a for lowercase alphabetical numbers, A for uppercase alphabetical numbers, i for lowercase Roman numbers, and I for uppercase Roman numbers. Processors can support other numbering schemas as well. The lang and letter-value attributes help the processor decide which alphabet and numbering scheme to use. If the number is large, then the digits may be grouped into groups of the size specified by the groupingsize attribute and separated by the character specified by the grouping-separator attribute. xsl :otherwise <xsl:otherwise> template </xsl:otherwise> See also: <xsl : choose>, <xsl: when> The <xsl: otherwise> element appears only within an <xsl: choose> element, containing the instructions that are processed if none of the expressions held in the tes t attributes of the <xsl :when> elements evaluate as true. 716

26 XSL T Quick Reference xsl:output <xsl: output method= "xml I text I html I qualified-name" media-type="content-type" version="version-number" encoding="encoding" indent="yes I no" doct ype-public= " string" doctype-system=" URI" omit-xml-declaration="yes I no" standalone="yes I no" cdata-section-elements="list-of-name-tests" /> The <xsl: output> element descrihes how the result of the transformation should he serialized into a file. The method attrihute has the most effect on the serialization, determining whether the stylesheet creates XML, text, HTML, or some other format defined hy a processor implementer. The mediatype and version attrihutes give tighter definition ahout the format heing generated. The encoding attribute determines the character encoding used during serialization, and defaults to UTF-8 or UTF-16. The indent attrihute determines whether whitespace-only text nodes are added to the result tree in order to make it easier to read; this is yes hy default for HTML and no hy default for XML. The doctype-public and doctype-system attrihutes hold the puhlic and system identifiers for the result, which are included in a DCTYPE declaration at the top of the generated file. When generating XML, a processor wih add an XML declaration at the start of the output, unless the omi t-xml-declaration attrihute is present with the value yes. Even if this attrihute is present, the XML declaration wih stih 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 pseudoattribute with the specified value). The cdata-section-elements attribute lists the names of elements in the result whose text content should he wrapped within CDATA sections. The <xsl: output> element should appear at the top level of the stylesheet, as a child of the <xsl: stylesheet> document element. There can be multiple <xsl: output> elements in a stylesheet, in which case they are comhined on an attrihute-hy-attrihute hasis; it is an error for more than one <xsl: output> element to specify the same attrihute with different values. xsl:param <xsl:param name="qualified-name" select="expression"> template </xsl:param> 717

27 Appendix B See also: <xsl: wi th-param>, <xsl: variable>, <xsl : template> The <xsl: param> element declares a parameter for a template (if it's within a template) 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 select attribute or the content of the <xsl: param> element holds the default value for the parameter, which will be used if no value is explicitly pas sed in to the stylesheet or template for that parameter. It is an error to specify both a select attribute and some content; use the select attribute if you can, otherwise you'll create a result tree fragment. xsl :preserve-space <xsl:preserve-space elements="list-of-name-tests" /> See also: <xsl: strip-space> The <xsl: preserve-space> element specifies the elements whose child whitespace-only text nodes should be preserved within the source node tree. The elements attribute holds a whitespace-separated list of name tests (which can include specific names, or * to mean any element, for example). Whitespace-only text nodes are preserved by default, so this element is only required if <xsl: stripspace> has been used to strip whitespace-only text nodes from the node tree. xsl:processing-instruction <xsl:processing-instruction name="unqualified-name"> template </xsl:processing-instruction> See also: <xsl: comment> The <xsl :processing-instruction> instruction creates a processing instruction whose target is the name held in the name attribute and whose value is the result of processing the template that it contains. The content ofthe <xsl: processing-instruction> element must not result in the generation of any nodes aside from text nodes, and the text nodes that it generates must not contain the string,? > '. xsl:sort 718 <xsl:sort select="string-expression" data-type="{text I nurnber I qualified-name} " order="{ascending I descending}" lang=" {language-code} " case-order="{upper-first I lower-first}" />

28 XSLT Quick Reference See also: <xsl: apply-templates>, <xsl: for-each> The <xsl: sort> element specifies a method of sorting a set of nodes. For each of the nodes selected in the surrounding <xsl: apply-templates> or <xsl: for-each> instruction, the <xsl: sort> element creates a sort key by evaluating the expres sion held in the select attribute with the node as the current node and converting it to a string. The nodes are then sorted according to this sort key and the other attributes on the <xsl: sort> element. The data-type attribute determines whether the nodes are sorted by their sort key in alphabetical order (text), in numeric order (number), or in some other order supported by the implementation. The order attribute determines whether the nodes are sorted in ascending order or descending order. The lang and case-order attributes are used ifit's an alphabetical sort; the default language is determined from the system environment, while the case ordering (whether uppercase letters are sorted before lowercase letters or vice versa) is based on the language being used. If there are multiple <xsl: sort> elements, then they define sub-sort keys on which nodes are sorted only if they have the same value for their sort key according to the previous sort. xsl :stri p-space <xsl:strip-space elements="list-of-name-tests" /> See also: <xsl :preserve-space>, normalize-space () The <xsl: strip-space> element specifies the elements whose child whitespace-only text nodes are removed from the node tree when it is created. The elements attribute holds a whitespace-separated list of name tests (which can include specific names, or * to mean any element, for example). The <xsl :preserve-space> element can override this specification. xsl :stylesheet <xsl:stylesheet version="l." id=" identifier" extension-element-prefixes= " list-of-namespace-prefixes" exclude-result-prefixes="list-of-namespace-prefixes" > (xsl:import*, top-level-elements) </xsl:stylesheet> See also: <xsl: transform> The <xsl: stylesheet> element is the document element for a stylesheet, and holds an the top-ievel elements such as global variable and parameter declarations, templates, decimal format and attribute set definitions, key declarations, output declarations, and so ono Any <xsl: import> elements that the stylesheet contains must come before anything else within the <xsl : stylesheet> element. 719

29 Appendix B The <xsl: stylesheet> element must have a version attribute indicating the version of XSLT being used, which for now should always be 1.. Ifyou're embedding a stylesheet within an XML document, the id attribute can be used as an identifier so that you can point to the stylesheet. The extension-element-prefixes attribute lists the prefixes ofnamespaces that are used for extension elements. The exclude-result-prefixes attribute lists the prefixes ofnamespaces that shouldn't be included in the result document, which are usually those namespaces that are used in the source XML document. xsl:template <xsl:template match="pattern" mode="qualified-name" priority="number" name="qualified-name" > (xsl:param*, template) </xsl:template> See also: <xsl: apply-templates>, <xsl: call-template> The <xsl: template> 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. When templates are applied to a node set using <xsl: apply-templates>, they might be applied in a particular mode; the mode attribute on <xsl: template> indicates the mode in which templates need to be applied for this template to be used. If templates are applied in the relevant mode, then the match attribute is used to determine whether the template can be used with the particular node. The ma tch 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 <xs 1 : wi thparam> element. To receive a parameter, however, the template must contain an <xsl : param> 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. xsl:text <xsl:text disable-output-escaping="yes ID"> text </xsl:text> 720

30 XSL T Quick Reference The <xsl: text> element is used to add some text to the re suit tree. Unlike elsewhere within an XSLT stylesheet, whitespace-only text nodes within <xsl: text> elements are included, so <xsl: text> 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 inden t attribute on <xsl : ou tpu t». The <xsl: text> element is also useful for limiting the amount of space that's included around text when it's added to the re suit. Ifthe disable-output-escaping attribute is specified with the value yes then the content ofthe <xsl : text> element is output without special characters such as < and & being escaped with &1 t; or &. xsl :transform <xsl:transform version="l." id=" identifier" extension-element-prefixes="list-of-namespace-prefixes" exclude-result-prefixes="list-of-namespace-prefixes"> (xsl:import*, top-level-elements) </xsl:transform> See also: <xsl: transform> The <xsl: transform> element is an alias for <xsl: stylesheet>; see the definition of <xsl: stylesheet> for details. xsl:value-of <xsl:value-of select.="string-expression" disable-output-escaping="yes I no" /> See also: <xsl: copy-of> The <xsl: value-of> instruction adds the string value of the selected expres sion to the re suit tree. The select attribute holds the expression that's evaluated. If the re suit is a node set, then <xs 1 : val ue-of> adds the string value of the first node in that node set; none of the structure of the node is preserved (you need <xsl : copy-of> for that). Ifthe disable-output-escaping attribute is specified with the value yes then the value is output without special characters such as < and & being escaped with &1 t; or &. 721

31 Appendix B xsl:variable <xsl:variable name="qualified-name" select="expression"> template </xsl:variable> See also: <xsl : param> The <xsl: variable> element declares a variable. If the <xsl : variable> element appears at the top level of the stylesheet, as a child of the <xs 1 : s tyl esheet> document element, then it is a global variable with a scope covering the entire stylesheet. therwise, it is a local variable with a scape 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 <xsl: variable> element. It is an error to have both a select attribute and some content. If you can, use the select attribute to set the variable; otherwise the variable holds a result tree fragment. xsl:when <xsl:when test.="boolean-expression"> template </xsl:when> See also: <xsl: choose>, <xsl: otherwise>, <xsl: if> The <xsl: when> element appears within an <xsl: choose> instruction and specifies a set of processing that could occur and the condition when it occurs. The XSL T processor processes the content of the first <xsl :when> within the <xsl: choose> whose test attribute contains an expression that evaluates as true. xsl:with-param 722 <xsl:with-param name="qualified-name" select="expression"> template </xsl:with-param> See also: <xsl :param>, <xsl: apply-templates>, <xsl: call-template>

32 XSL T Quick Reference The <xsl :with-param> element specifies the value that should be passed to a template parameter.1t can be used when applying templates with <xsl: apply-templates> or calling templates with <xsl: call-template>. 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 <xsl: wi th-param> element. It is an error to have both a select attribute and some content. If you can, use the select attribute to set the parameter; otherwise the parameter will be passed a result tree fragment as its value. XSLT Attributes There are four attributes from the XSL T namespace that can be added to any literal result element. xsl :extension-element-prefixes <element xsl:extension-element-prefixes="list-of-namespace-prefixes"> template </element> See also: <xsl : stylesheet> The xs 1 : extension -elemen t -pref ixes attribute lists the prefixes of namespaces that are being used for extension elements. This works exact1y like the extension-element-prefixes attribute on <xsl: stylesheet>, but only within the scope of the literal result element. xsl:exclude-result-prefixes <element xsl:exclude-result-prefixes="list-of-namespace-prefixes"> template </element> See also: <xsl : stylesheet> The xsl : exclude-resul t-prefixes attribute lists the prefixes of namespaces that should not be included within the result tree. This works exact1y like the exclude-result-prefixes attribute on <xsl: stylesheet>, but only within the scope ofthe literal result element. 723

33 Appendix B xsl:use-attribute-sets <element xsl:use-attribute-sets="list-of-qualified-names"> template </element> See also: <xsl: attribute-set>, <xsl: element>, <xsl: copy> The xsl : use-attribute-sets attribute lists the names of attribute sets that contain attributes that should be added to the literal result element, in exactly the same way as the use-attribute-sets attribute works with <xsl : element> and <xsl : copy>. xsl :version <element xsl:version="l."> template </element> See also: <xsl : stylesheet> The xsl : vers ion attribute specifies the version of XSLT that is being used within its content (which is currently always 1. ). This attribute is required on the document element of simplified stylesheets, which have a literal result element as their document element. 724

34 XSl T Quick Reference 725

35

36 10015 XSLT Processors Saxon rceforge. net! o Java (and "instant" version) supports XSLT 1.0/ has limited support for XSLT 2.0 lots of extension elements and functions supports user-defined extension functions in XSLT andjava supports TrAX GAXP 1.1 conformant) Xalan-J Java current version several extension elements and functions supports user-defined extension functions through Bean Scripting Framework supports TrAX GAXP 1.1 conformant)