diff --git a/site/.hugo_build.lock b/site/.hugo_build.lock new file mode 100644 index 00000000..e69de29b diff --git a/site/content/xslt/_index.md b/site/content/xslt/_index.md new file mode 100644 index 00000000..fae7485c --- /dev/null +++ b/site/content/xslt/_index.md @@ -0,0 +1,4 @@ +--- +title: "XSLT Reference" +description: "Reference documentation for XSLT elements and XPath functions." +--- diff --git a/site/content/xslt/functions/_index.md b/site/content/xslt/functions/_index.md new file mode 100644 index 00000000..8bd0ff87 --- /dev/null +++ b/site/content/xslt/functions/_index.md @@ -0,0 +1,4 @@ +--- +title: "XSLT & XPath Function Reference" +description: "Complete reference for XSLT elements and XPath functions with syntax, parameters, and runnable examples. Covers XSLT 1.0, 2.0, and 3.0." +--- diff --git a/site/content/xslt/functions/xpath-concat.md b/site/content/xslt/functions/xpath-concat.md new file mode 100644 index 00000000..c47ea29e --- /dev/null +++ b/site/content/xslt/functions/xpath-concat.md @@ -0,0 +1,100 @@ +--- +title: "concat()" +description: "Concatenates two or more strings into a single string, accepting any number of arguments." +date: 2026-04-18T00:00:00Z +version: "1.0" +versionLabel: "XSLT 1.0" +category: "string function" +syntax: "concat(str1, str2, ...)" +tags: ["xslt", "reference", "xslt1", "xpath"] +--- + +## Description + +`concat()` joins two or more string arguments into a single string, in the order they are provided. Each argument is converted to a string using the XPath string-value rules before concatenation. + +It requires **at least two arguments** but accepts any number. Arguments that are not strings (numbers, booleans, nodes) are automatically cast to their string representation. + +`concat()` is the standard way to build dynamic attribute values, filenames, URIs, or any computed string in XSLT 1.0. In XSLT 2.0+, `string-join()` is often more readable when the separator is uniform. + +## Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `str1` | xs:anyAtomicType | Yes | First string (or value convertible to string). | +| `str2` | xs:anyAtomicType | Yes | Second string. | +| `...` | xs:anyAtomicType | No | Additional strings; at least two arguments are required. | + +## Return value + +`xs:string` — all arguments concatenated in order, with no separator. + +## Examples + +### Build a full name + +**Input XML:** +```xml + + + Jane + Smith + +``` + +**Stylesheet:** +```xml + + + + + + + + +``` + +**Output:** +``` +Jane Smith +``` + +### Dynamic attribute value + +**Stylesheet:** +```xml + + + + + + + + + + +``` + +**Output:** +```xml +Jane Smith +``` + +### Concatenate node values and literals + +```xml + + +``` + +## Notes + +- `concat()` does not add any separator between arguments. To join with a separator, either include the separator as a literal argument or use `string-join()` (XSLT 2.0+). +- Unlike `string-join()`, `concat()` does not accept a sequence; each argument must be a single value. +- Attribute value templates `{expression}` are a shorthand alternative for simple cases and can call `concat()` inside them. +- Numbers are converted to their canonical string form: `concat(1.0, 'x')` produces `"1x"` not `"1.0x"` (the exact output depends on the XPath string conversion rules). + +## See also + +- [string-join()](../xpath-string-join) +- [contains()](../xpath-contains) diff --git a/site/content/xslt/functions/xpath-contains.md b/site/content/xslt/functions/xpath-contains.md new file mode 100644 index 00000000..921e3f85 --- /dev/null +++ b/site/content/xslt/functions/xpath-contains.md @@ -0,0 +1,118 @@ +--- +title: "contains()" +description: "Returns true if the first string contains the second string as a substring, otherwise returns false." +date: 2026-04-18T00:00:00Z +version: "1.0" +versionLabel: "XSLT 1.0" +category: "string function" +syntax: "contains(string, substring)" +tags: ["xslt", "reference", "xslt1", "xpath"] +--- + +## Description + +`contains()` tests whether a string includes a given substring and returns a boolean result. Both arguments are converted to strings before the comparison. + +The comparison is **case-sensitive** and uses code-point ordering. If you need case-insensitive matching, use `matches()` with the `i` flag (XSLT 2.0+) or normalize both strings with `lower-case()` before comparing. + +If the second argument is an empty string, `contains()` always returns `true` because every string contains the empty string. + +`contains()` is frequently used inside `xsl:if` and `xsl:when` predicates to filter elements based on string content, or in predicates within XPath expressions. + +## Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `string` | xs:string | Yes | The string to search within. | +| `substring` | xs:string | Yes | The substring to look for. | + +## Return value + +`xs:boolean` — `true` if `string` contains `substring`, `false` otherwise. + +## Examples + +### Filter elements by content + +**Input XML:** +```xml + + +
XSLT Tutorial for Beginners
+
Advanced XML Schema
+
XSLT 2.0 Features
+ +``` + +**Stylesheet:** +```xml + + + + + + + + + + + + +``` + +**Output:** +```xml + + XSLT Tutorial for Beginners + XSLT 2.0 Features + +``` + +### Conditional processing + +**Stylesheet:** +```xml + + + + + + + + + + + + + + +``` + +**Output:** +```xml + + XSLT Tutorial for Beginners + XSLT 2.0 Features + +``` + +### Combined with other string functions + +```xml + + + true + +``` + +## Notes + +- `contains()` is case-sensitive. For case-insensitive checks in XSLT 2.0+, use `matches(., 'pattern', 'i')` or `contains(lower-case(title), 'xslt')`. +- To check if a string **starts with** a value, use `starts-with()`. To check a suffix, use `ends-with()` (XSLT 2.0+) or `substring()`. +- `contains()` returns `true` when the substring argument is empty, which can cause unexpected results in dynamic expressions. +- For complex pattern matching (wildcards, character classes), use `matches()` instead. + +## See also + +- [matches()](../xpath-matches) +- [substring()](../xpath-substring) diff --git a/site/content/xslt/functions/xpath-count.md b/site/content/xslt/functions/xpath-count.md new file mode 100644 index 00000000..755c077a --- /dev/null +++ b/site/content/xslt/functions/xpath-count.md @@ -0,0 +1,113 @@ +--- +title: "count()" +description: "Returns the number of nodes in a node-set or items in a sequence as an integer." +date: 2026-04-18T00:00:00Z +version: "1.0" +versionLabel: "XSLT 1.0" +category: "node function" +syntax: "count(node-set)" +tags: ["xslt", "reference", "xslt1", "xpath"] +--- + +## Description + +`count()` evaluates an XPath expression, collects the resulting node-set (or sequence in XPath 2.0+), and returns the number of items as an integer. It is the standard way to determine how many elements match a given path without iterating over them. + +Common use cases include: + +- Conditionally processing content only if at least one element exists. +- Displaying totals ("5 items found"). +- Checking whether a repeated element has a specific number of occurrences. +- Using the count as a denominator or comparator in arithmetic expressions. + +## Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `node-set` | node-set / sequence | Yes | The node-set or sequence whose size is returned. | + +## Return value + +`xs:integer` — the number of nodes or items in the argument. + +## Examples + +### Display item count + +**Input XML:** +```xml + + + XSLT Cookbook + XML in a Nutshell + Learning XML + +``` + +**Stylesheet:** +```xml + + + + + + + books in the library. + + +``` + +**Output:** +``` +3 books in the library. +``` + +### Conditional output based on count + +**Stylesheet:** +```xml + + + + + + + + + No books found. + + + book(s) found. + + + + + +``` + +**Output:** +```xml + + 3 book(s) found. + +``` + +### Count elements matching a condition + +```xml + + +``` + +## Notes + +- `count()` counts nodes in the argument expression, not the context node's children by default. Always specify the path explicitly. +- To count all descendants of a type, use `count(.//element-name)`. +- `count()` always returns a non-negative integer; it returns `0` for an empty node-set, never an error. +- In XSLT 2.0+, you can use `count()` on any sequence, including sequences of atomic values. +- `last()` inside `xsl:for-each` gives the same number as `count(select-expression)` but only within the loop; `count()` can be used anywhere. + +## See also + +- [sum()](../xpath-sum) +- [last()](../xpath-last) diff --git a/site/content/xslt/functions/xpath-current.md b/site/content/xslt/functions/xpath-current.md new file mode 100644 index 00000000..13147a41 --- /dev/null +++ b/site/content/xslt/functions/xpath-current.md @@ -0,0 +1,99 @@ +--- +title: "current()" +description: "Returns the context node of the innermost xsl:template or xsl:for-each, unaffected by nested predicates." +date: 2026-04-18T00:00:00Z +version: "1.0" +versionLabel: "XSLT 1.0" +category: "node function" +syntax: "current()" +tags: ["xslt", "reference", "xslt1", "xpath"] +--- + +## Description + +`current()` returns the **current node** — the node being processed by the nearest enclosing `xsl:template` or `xsl:for-each` instruction. This is different from the **context node** (`.`), which shifts to each node evaluated inside predicates and path steps. + +The key distinction is: + +- `.` (dot) refers to the node currently in focus in an XPath sub-expression, which can change as XPath navigates through predicates. +- `current()` always refers to the XSLT processing context (the node the instruction is currently transforming), regardless of how deeply nested the XPath expression is. + +`current()` is most useful inside predicates when you need to refer back to the outer node being processed, for example to perform a cross-reference lookup based on a value from the current node. + +`current()` is an XSLT function, not a pure XPath function — it is only valid inside XSLT stylesheets, not standalone XPath expressions. + +## Return value + +A node-set containing exactly one node: the current XSLT processing context node. + +## Examples + +### Cross-reference using current() in a predicate + +**Input XML:** +```xml + + + + Electronics + Books + + + Laptop + XSLT Guide + + +``` + +**Stylesheet:** +```xml + + + + + + + + + + — + + + + + + + +``` + +**Output:** +```xml + + Laptop — Electronics + XSLT Guide — Books + +``` + +### Why current() differs from dot + +```xml + + + + + + + +``` + +## Notes + +- `current()` is only meaningful inside an `xsl:template` or `xsl:for-each`. Calling it at the top level of a match pattern is an error. +- It cannot be used inside `xsl:key`'s `use` attribute — that is evaluated outside of any XSLT instruction context. +- In XSLT 2.0+, the need for `current()` is often reduced by using variables (`xsl:variable`) to capture the node before entering a predicate. +- `current()` and `.` are identical outside any predicate or path step. + +## See also + +- [xsl:for-each](../xsl-for-each) diff --git a/site/content/xslt/functions/xpath-format-date.md b/site/content/xslt/functions/xpath-format-date.md new file mode 100644 index 00000000..1e6b1698 --- /dev/null +++ b/site/content/xslt/functions/xpath-format-date.md @@ -0,0 +1,135 @@ +--- +title: "format-date()" +description: "Formats an xs:date value into a human-readable string using a picture pattern, with optional locale and calendar support." +date: 2026-04-18T00:00:00Z +version: "2.0" +versionLabel: "XSLT 2.0" +category: "date function" +syntax: "format-date(date, picture, language?, calendar?, place?)" +tags: ["xslt", "reference", "xslt2", "xpath"] +--- + +## Description + +`format-date()` converts an `xs:date` value into a formatted string according to a **picture pattern**. It is the standard way in XSLT 2.0+ to produce locale-aware, human-readable date output from typed date values. + +The picture string uses component specifiers enclosed in square brackets: + +| Specifier | Meaning | +|-----------|---------| +| `[Y]` | Year (4 digits by default) | +| `[M]` | Month as a number | +| `[MNn]` | Month name (e.g., "April") | +| `[D]` | Day of the month | +| `[d]` | Day of the year | +| `[F]` | Day of the week name (e.g., "Monday") | +| `[FNn]` | Day of week, title case | +| `[W]` | Week of the year | + +Width modifiers control zero-padding: `[D01]` formats day as two digits (`01`, `15`). The `[MNn]` modifier requests the name in title case; `[MN]` gives uppercase. + +Related functions cover time and combined date-time values: +- `format-time(time, picture, ...)` for `xs:time` values. +- `format-dateTime(dateTime, picture, ...)` for `xs:dateTime` values. + +To get today's date for formatting, use `current-date()`. + +## Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `date` | xs:date? | Yes | The date value to format. If an empty sequence, an empty string is returned. | +| `picture` | xs:string | Yes | The picture pattern controlling the output format. | +| `language` | xs:string? | No | BCP 47 language tag controlling names (e.g., `"en"`, `"fr"`, `"de"`). | +| `calendar` | xs:string? | No | Calendar system identifier (e.g., `"AD"`, `"ISO"`). Implementation-defined. | +| `place` | xs:string? | No | Place or timezone identifier. Implementation-defined. | + +## Return value + +`xs:string` — the formatted date string, or an empty string if `date` is an empty sequence. + +## Examples + +### Format a date attribute + +**Input XML:** +```xml + + + XSLT Conference + Holiday + +``` + +**Stylesheet:** +```xml + + + + + + + + + + + + + + + +``` + +**Output:** +```xml + + + Saturday, 18 April 2026 + XSLT Conference + + + Friday, 25 December 2026 + Holiday + + +``` + +### Today's date formatted + +**Stylesheet:** +```xml + + + + + + + + +``` + +**Output (example):** +``` +18/04/2026 +``` + +### French locale month name + +```xml + + +``` + +## Notes + +- The input must be an `xs:date` (not a string). Cast string date values with `xs:date(@date)` before calling `format-date()`. +- Picture patterns are **not** the same as Java `SimpleDateFormat` or `strftime`. Refer to the XPath/XSLT 2.0 specification for the full picture syntax. +- Language support depends on the XSLT processor. Saxon supports common European languages; less common locales may fall back to English. +- For `xs:dateTime` values, use `format-dateTime()` which additionally supports time component specifiers like `[H]` (hour), `[m]` (minute), `[s]` (second). +- `current-date()` returns the processor's current date as `xs:date`; pair it with `format-date()` to embed a build timestamp in the output. + +## See also + +- [current()](../xpath-current) diff --git a/site/content/xslt/functions/xpath-key.md b/site/content/xslt/functions/xpath-key.md new file mode 100644 index 00000000..45adf2fc --- /dev/null +++ b/site/content/xslt/functions/xpath-key.md @@ -0,0 +1,116 @@ +--- +title: "key()" +description: "Looks up nodes using a named xsl:key index, returning all nodes whose key value matches the given value." +date: 2026-04-18T00:00:00Z +version: "1.0" +versionLabel: "XSLT 1.0" +category: "node function" +syntax: "key(name, value)" +tags: ["xslt", "reference", "xslt1", "xpath"] +--- + +## Description + +`key()` retrieves nodes from the source document that have been indexed by an `xsl:key` declaration. It is essentially a pre-built hash-map lookup: you declare the index once with `xsl:key`, and then query it efficiently with `key()`. + +The function is used for two main purposes: + +1. **Cross-reference lookups** — retrieving a node by an ID-like value without iterating the entire document (much faster than `//element[@id='x']` in large documents). +2. **Muenchian grouping** (XSLT 1.0) — identifying the first node of each group by combining `key()` with `generate-id()`. + +## Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `name` | string literal | Yes | The name of the `xsl:key` index to query (must match the `name` attribute of an `xsl:key` declaration). | +| `value` | string / node-set | Yes | The key value to look up. If a node-set, the result is the union of nodes matching each node's string value. | + +### Prerequisite: `xsl:key` declaration + +```xml + +``` + +| Attribute | Description | +|-----------|-------------| +| `match` | Pattern identifying which nodes to index. | +| `use` | Expression that provides the key value for each matched node. | + +## Return value + +A node-set containing all nodes matched by `match` in `xsl:key` whose `use` expression equals `value`. + +## Examples + +### Cross-reference lookup + +**Input XML:** +```xml + + + + Engineering + Marketing + + + Alice + Bob + Carol + + +``` + +**Stylesheet:** +```xml + + + + + + + + + + + + — + + + + + + +``` + +**Output:** +```xml + + Alice — Engineering + Bob — Marketing + Carol — Engineering + +``` + +### Muenchian grouping (XSLT 1.0) + +```xml + + + + + + items + + +``` + +## Notes + +- `key()` only works within the **current document** by default. Use `key()` combined with `document()` to look up across external documents. +- The XSLT processor builds the key index once per document, making `key()` significantly faster than predicate-based searches for repeated lookups. +- In XSLT 2.0+, `xsl:for-each-group` replaces Muenchian grouping with a cleaner syntax. +- If `name` does not match any `xsl:key` declaration, the result is an error. + +## See also + +- [xsl:for-each-group](../xsl-for-each-group) diff --git a/site/content/xslt/functions/xpath-last.md b/site/content/xslt/functions/xpath-last.md new file mode 100644 index 00000000..e053a8df --- /dev/null +++ b/site/content/xslt/functions/xpath-last.md @@ -0,0 +1,90 @@ +--- +title: "last()" +description: "Returns the size of the context node-set, i.e. the index of the last item in the current iteration context." +date: 2026-04-18T00:00:00Z +version: "1.0" +versionLabel: "XSLT 1.0" +category: "node function" +syntax: "last()" +tags: ["xslt", "reference", "xslt1", "xpath"] +--- + +## Description + +`last()` returns an integer equal to the **context size** — the total number of nodes in the node-set (or items in the sequence) currently being processed. It takes no arguments. + +The most common use cases are: + +- Detecting the last item in a loop to apply different formatting (e.g., omitting a trailing separator). +- Building predicates like `item[last()]` to select only the final element in a set. +- Combining with `position()` to produce row counts or progress labels. + +The value of `last()` changes with the context. Inside `xsl:for-each`, it reflects the number of items selected by the `select` attribute. Inside a template triggered by `xsl:apply-templates`, it reflects the number of nodes sent to that template call. + +## Return value + +`xs:integer` — the total number of items in the current context sequence. + +## Examples + +### Omit trailing comma + +**Input XML:** +```xml + + + Red + Green + Blue + +``` + +**Stylesheet:** +```xml + + + + + + + + , + + + +``` + +**Output:** +``` +Red, Green, Blue +``` + +### Select only the last element + +**Stylesheet:** +```xml + + + + + + + + +``` + +**Output:** +``` +Blue +``` + +## Notes + +- `last()` and `position()` are context-dependent. Their values inside a predicate differ from their values in the body of `xsl:for-each` — predicates establish their own context. +- In XSLT 2.0+ with typed sequences, `last()` still works the same way but the context is an `xs:integer`-typed sequence size. +- A common mistake is calling `last()` outside any iterating context; at the top level of a template, it returns 1 (the single context node). + +## See also + +- [position()](../xpath-position) +- [count()](../xpath-count) diff --git a/site/content/xslt/functions/xpath-matches.md b/site/content/xslt/functions/xpath-matches.md new file mode 100644 index 00000000..b15c948e --- /dev/null +++ b/site/content/xslt/functions/xpath-matches.md @@ -0,0 +1,127 @@ +--- +title: "matches()" +description: "Tests whether a string matches a regular expression, returning true or false." +date: 2026-04-18T00:00:00Z +version: "2.0" +versionLabel: "XSLT 2.0" +category: "string function" +syntax: "matches(string, pattern, flags?)" +tags: ["xslt", "reference", "xslt2", "xpath"] +--- + +## Description + +`matches()` tests whether the input `string` matches the regular expression `pattern` and returns `true` or `false`. By default the entire string does not need to match — the pattern is matched anywhere within the string (like a "contains" regex test). To anchor the match to the full string, use `^` and `$` anchors in the pattern. + +The optional `flags` argument controls matching behaviour: + +| Flag | Meaning | +|------|---------| +| `i` | Case-insensitive matching. | +| `m` | Multiline mode: `^` and `$` match at line boundaries. | +| `s` | Dot-all mode: `.` matches any character including newline. | +| `x` | Extended mode: whitespace and `#` comments are ignored in the pattern. | + +`matches()` uses XML Schema / XPath regex syntax, which is similar to but not identical to Perl/PCRE regex. Notably, lookaheads and backreferences are not supported. + +## Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `string` | xs:string | Yes | The string to test. | +| `pattern` | xs:string | Yes | The regular expression pattern. | +| `flags` | xs:string | No | One or more flag characters controlling match behaviour. | + +## Return value + +`xs:boolean` — `true` if the pattern matches anywhere in the string (unless anchored), `false` otherwise. + +## Examples + +### Validate a format + +**Input XML:** +```xml + + + Valid entry + Invalid format + Another valid + +``` + +**Stylesheet:** +```xml + + + + + + + + + + + + + + +``` + +**Output:** +```xml + + Valid entry + Invalid format + Another valid + +``` + +*Note: inside attribute value templates, `{` and `}` must be doubled: `{{` and `}}`.* + +### Case-insensitive search + +**Stylesheet:** +```xml + + + + + + + + + + + + +``` + +**Output:** +```xml + + Valid entry + Invalid format + Another valid + +``` + +### Filter with a pattern predicate + +```xml + + +``` + +## Notes + +- `matches()` is case-sensitive by default. Use the `i` flag for case-insensitive matching. +- The regex is anchored only with `^` / `$` — without them, a partial match anywhere in the string returns `true`. +- XPath regex does not support all PCRE features. Lookahead (`?=`), lookbehind (`?<=`), and named groups are not available. +- In XSLT 1.0, there is no built-in regex support. The only alternative is complex template recursion or extension functions. + +## See also + +- [replace()](../xpath-replace) +- [tokenize()](../xpath-tokenize) +- [contains()](../xpath-contains) diff --git a/site/content/xslt/functions/xpath-position.md b/site/content/xslt/functions/xpath-position.md new file mode 100644 index 00000000..2f739474 --- /dev/null +++ b/site/content/xslt/functions/xpath-position.md @@ -0,0 +1,117 @@ +--- +title: "position()" +description: "Returns the position of the context node within the current node-set, starting at 1." +date: 2026-04-18T00:00:00Z +version: "1.0" +versionLabel: "XSLT 1.0" +category: "node function" +syntax: "position()" +tags: ["xslt", "reference", "xslt1", "xpath"] +--- + +## Description + +`position()` returns an integer representing the **1-based position** of the current context node within the node-set being iterated. It takes no arguments. + +It is most commonly used inside `xsl:for-each` or predicates to: + +- Generate row numbers or sequence numbers in the output. +- Apply alternating styles (odd/even rows). +- Conditionally process only specific positions (first, last, every nth item). +- Omit separators before or after specific items. + +The context for `position()` is determined by the nearest enclosing iteration (`xsl:for-each`, `xsl:apply-templates`, or a predicate). Inside a predicate, `position()` refers to the position within the node-set being filtered, not the outer iteration. + +## Return value + +`xs:integer` — the 1-based position of the context node within the current context sequence. + +## Examples + +### Row numbers in a table + +**Input XML:** +```xml + + + Alice + Bob + Carol + +``` + +**Stylesheet:** +```xml + + + + + + + + + + + +
+ + +``` + +**Output:** +```xml + + Alice + Bob + Carol +
+``` + +### Odd/even row class + +**Stylesheet:** +```xml + + + + + + + + + + + +
+ + +``` + +**Output:** +```xml + + Alice + Bob + Carol +
+``` + +*Note: the `if()` expression requires XSLT 2.0. In XSLT 1.0, use `xsl:choose` instead.* + +### Select every second element using a predicate + +```xml + +``` + +## Notes + +- `position()` inside a predicate `[position() = 1]` can be shortened to `[1]`. +- The shorthand `item[last()]` selects the last item; `item[1]` selects the first. +- Document order is used by default; if `xsl:sort` is present, positions reflect the sorted order. +- Do not confuse `position()` with the numeric value of an `@id` attribute or similar content-based numbering — `position()` is purely about iteration order. + +## See also + +- [last()](../xpath-last) +- [xsl:for-each](../xsl-for-each) diff --git a/site/content/xslt/functions/xpath-replace.md b/site/content/xslt/functions/xpath-replace.md new file mode 100644 index 00000000..d63a4654 --- /dev/null +++ b/site/content/xslt/functions/xpath-replace.md @@ -0,0 +1,128 @@ +--- +title: "replace()" +description: "Replaces all substrings of a string that match a regular expression with a replacement string." +date: 2026-04-18T00:00:00Z +version: "2.0" +versionLabel: "XSLT 2.0" +category: "string function" +syntax: "replace(string, pattern, replacement, flags?)" +tags: ["xslt", "reference", "xslt2", "xpath"] +--- + +## Description + +`replace()` searches the input string for all occurrences of the regular expression `pattern` and substitutes each match with the `replacement` string. Unlike `translate()` (which works character-by-character), `replace()` operates on substrings and patterns, making it suitable for complex string transformations. + +The `replacement` string may include **back-references** to captured groups using `$1`, `$2`, etc., where `$0` refers to the entire matched substring. Dollar signs that are not back-references must be escaped as `\$`. + +The function uses XPath regex syntax (a subset of XML Schema regex), which is similar to Java/Perl regex but does not support lookaheads or backreferences in the pattern itself. + +## Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `string` | xs:string | Yes | The input string to perform replacements on. | +| `pattern` | xs:string | Yes | Regular expression pattern matching the substrings to replace. | +| `replacement` | xs:string | Yes | Replacement string; may use `$0`, `$1`, etc. for captured groups. | +| `flags` | xs:string | No | Regex flags: `i` (case-insensitive), `m` (multiline), `s` (dot-all), `x` (extended). | + +## Return value + +`xs:string` — the input string with all matches of `pattern` replaced by `replacement`. + +## Examples + +### Remove unwanted characters + +**Input XML:** +```xml + + + $1,299.00 + $849.50 + +``` + +**Stylesheet:** +```xml + + + + + + + + + + + + + +``` + +**Output:** +```xml + + 1299.00 + 849.50 + +``` + +### Reformat a date using back-references + +**Input XML:** +```xml + + + Conference + Workshop + +``` + +**Stylesheet:** +```xml + + + + + + + + + + + + + + + +``` + +**Output:** +```xml + + Conference + Workshop + +``` + +*Note: curly braces inside attribute value templates must be doubled: `{{` and `}}`.* + +### Collapse multiple spaces + +```xml + +``` + +## Notes + +- `replace()` replaces **all** occurrences, not just the first. There is no `replaceFirst()` equivalent in XPath. +- To escape a literal `$` in the replacement string, write `\$`. +- The pattern cannot match an empty string; if the pattern can match zero characters Saxon raises a dynamic error. +- For simple character substitution, `translate()` (XSLT 1.0) is simpler and more efficient. Use `replace()` when you need pattern matching or back-references. +- Inside attribute value templates, curly braces within the regex (e.g., `\d{4}`) must be doubled: `\d{{4}}`. + +## See also + +- [matches()](../xpath-matches) +- [tokenize()](../xpath-tokenize) diff --git a/site/content/xslt/functions/xpath-string-join.md b/site/content/xslt/functions/xpath-string-join.md new file mode 100644 index 00000000..97afa795 --- /dev/null +++ b/site/content/xslt/functions/xpath-string-join.md @@ -0,0 +1,99 @@ +--- +title: "string-join()" +description: "Joins a sequence of strings into a single string with a specified separator between each item." +date: 2026-04-18T00:00:00Z +version: "2.0" +versionLabel: "XSLT 2.0" +category: "string function" +syntax: "string-join(sequence, separator?)" +tags: ["xslt", "reference", "xslt2", "xpath"] +--- + +## Description + +`string-join()` takes a sequence of strings and concatenates them into a single string, placing the separator between each consecutive pair of items. If the sequence contains only one item, no separator is added. If the sequence is empty, an empty string is returned. + +The `separator` argument is optional in XPath 3.1; when omitted it defaults to an empty string (items are concatenated with no separator). In XPath 2.0 the separator argument is required. + +`string-join()` is the idiomatic XSLT 2.0+ replacement for the XSLT 1.0 pattern of iterating with `xsl:for-each` and manually appending separators using `position() != last()`. It works on any sequence of atomic values (each is converted to a string) and on element text content via paths like `element/string()`. + +## Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `sequence` | xs:string* | Yes | The sequence of strings to join. Non-string items are converted to strings. | +| `separator` | xs:string | No (XPath 3.1+) / Yes (XPath 2.0) | The string inserted between each pair of adjacent items. | + +## Return value + +`xs:string` — all items in the sequence joined by the separator. + +## Examples + +### Join element values with a comma + +**Input XML:** +```xml + + + xslt + xml + xpath + transformation + +``` + +**Stylesheet:** +```xml + + + + + + + + +``` + +**Output:** +``` +xslt, xml, xpath, transformation +``` + +### Build a pipe-delimited list in an attribute + +**Stylesheet:** +```xml + + + + + + + + +``` + +**Output:** +```xml + +``` + +### Join string values from a sequence expression + +```xml + + +``` + +## Notes + +- `string-join()` requires XSLT 2.0 or later. In XSLT 1.0, replicate the behaviour with `xsl:for-each` and a `position() != last()` conditional separator. +- The function does not add a leading or trailing separator — only between items. +- Non-string items in the sequence (numbers, booleans) are cast to `xs:string` before joining. +- To join node string values, use the path expression directly: `string-join(item, ', ')` extracts each `item` element's text content automatically. + +## See also + +- [tokenize()](../xpath-tokenize) +- [concat()](../xpath-concat) diff --git a/site/content/xslt/functions/xpath-substring.md b/site/content/xslt/functions/xpath-substring.md new file mode 100644 index 00000000..40f6c66c --- /dev/null +++ b/site/content/xslt/functions/xpath-substring.md @@ -0,0 +1,117 @@ +--- +title: "substring()" +description: "Extracts a portion of a string by start position and optional length, returning the resulting substring." +date: 2026-04-18T00:00:00Z +version: "1.0" +versionLabel: "XSLT 1.0" +category: "string function" +syntax: "substring(string, start, length?)" +tags: ["xslt", "reference", "xslt1", "xpath"] +--- + +## Description + +`substring()` returns the portion of a string beginning at position `start` and extending for `length` characters. If `length` is omitted, the function returns all characters from `start` to the end of the string. + +String positions in XPath are **1-based** (the first character is position 1). The `start` and `length` arguments are numbers; they are rounded to the nearest integer using the XPath rounding rules. If `start` is less than 1, the returned string effectively begins at position 1 (the excess is deducted from `length`). + +`substring()` is the fundamental string-slicing function in XPath 1.0. For more complex extraction needs, consider `substring-before()` and `substring-after()`, which split on a delimiter without needing to know its position. + +## Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `string` | xs:string | Yes | The source string to extract from. | +| `start` | xs:double | Yes | 1-based position of the first character to include. | +| `length` | xs:double | No | Number of characters to include. Defaults to the rest of the string. | + +## Return value + +`xs:string` — the extracted substring. + +## Examples + +### Extract a fixed-length prefix + +**Input XML:** +```xml + + + PROD-001-RED + PROD-002-BLU + PROD-003-GRN + +``` + +**Stylesheet:** +```xml + + + + + + + + + + + + + +``` + +**Output:** +```xml + + 001 + 002 + 003 + +``` + +### Extract from a position to end of string + +**Stylesheet:** +```xml + + + + + + + + + + + + + +``` + +**Output:** +```xml + + RED + BLU + GRN + +``` + +### Capitalise first character (XSLT 2.0 pattern) + +```xml + + +``` + +## Notes + +- XPath string positions start at **1**, not 0. `substring('hello', 1, 3)` returns `"hel"`. +- If `start + length` exceeds the string length, the result is simply truncated at the end of the string — no error is raised. +- For delimiter-based splitting, `substring-before()` and `substring-after()` are more convenient than computing numeric positions. +- In XSLT 2.0+, `replace()` with regex groups is often a cleaner way to extract structured parts of strings. + +## See also + +- [contains()](../xpath-contains) +- [replace()](../xpath-replace) diff --git a/site/content/xslt/functions/xpath-sum.md b/site/content/xslt/functions/xpath-sum.md new file mode 100644 index 00000000..13bc0340 --- /dev/null +++ b/site/content/xslt/functions/xpath-sum.md @@ -0,0 +1,115 @@ +--- +title: "sum()" +description: "Returns the sum of the numeric values in a node-set or sequence, or a specified zero value for empty sequences." +date: 2026-04-18T00:00:00Z +version: "1.0" +versionLabel: "XSLT 1.0" +category: "numeric function" +syntax: "sum(node-set)" +tags: ["xslt", "reference", "xslt1", "xpath"] +--- + +## Description + +`sum()` converts each node in a node-set to a number (using the XPath `number()` rules) and returns their total as a double. If any node cannot be converted to a number, its value is treated as `NaN`, and the entire result is `NaN`. + +In XSLT 2.0+, `sum()` accepts any sequence of atomic values that can be added together. A second argument may be provided as a **zero value** to return when the sequence is empty (in XPath 1.0, `sum()` on an empty node-set returns `0`). + +`sum()` is the standard way to compute totals over repeated elements, such as order amounts, quantities, or scores, without writing an explicit loop. + +## Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `node-set` | node-set / sequence | Yes | The nodes or items to sum. Each is converted to a number. | +| `zero` | atomic value | No | Value to return if the sequence is empty (XPath 2.0+). Defaults to `0`. | + +## Return value + +`xs:double` (XPath 1.0) or the type matching the input sequence (XPath 2.0+) — the numeric sum of all items. + +## Examples + +### Sum all child element values + +**Input XML:** +```xml + + + + + + +``` + +**Stylesheet:** +```xml + + + + + + Total: + + + +``` + +**Output:** +``` +Total: 49.49 +``` + +### Conditional sum (sum filtered values) + +**Input XML:** +```xml + + + + + + + +``` + +**Stylesheet:** +```xml + + + + + + + + + + + +``` + +**Output:** +```xml + + 275 + 330 + +``` + +### Empty sequence with fallback (XSLT 2.0) + +```xml + + +``` + +## Notes + +- Nodes that cannot be converted to a number (e.g., text like `"N/A"`) produce `NaN`, which propagates through the sum. Validate data or use `number()` with a fallback before summing. +- `sum()` on an empty node-set returns `0` in XPath 1.0. In XPath 2.0+, the second argument controls this behaviour. +- For an average, there is no built-in `avg()` in XPath 1.0. Compute it as `sum(nodes) div count(nodes)`. XPath 2.0+ provides `avg()`. +- `sum()` works on attribute nodes as well as element text nodes; the path `sum(items/item/@qty)` is valid. + +## See also + +- [count()](../xpath-count) diff --git a/site/content/xslt/functions/xpath-tokenize.md b/site/content/xslt/functions/xpath-tokenize.md new file mode 100644 index 00000000..a4bec9b8 --- /dev/null +++ b/site/content/xslt/functions/xpath-tokenize.md @@ -0,0 +1,113 @@ +--- +title: "tokenize()" +description: "Splits a string into a sequence of substrings using a regular expression as the delimiter pattern." +date: 2026-04-18T00:00:00Z +version: "2.0" +versionLabel: "XSLT 2.0" +category: "string function" +syntax: "tokenize(string, pattern, flags?)" +tags: ["xslt", "reference", "xslt2", "xpath"] +--- + +## Description + +`tokenize()` splits a string into a sequence of substrings wherever the `pattern` (a regular expression) matches. The matched delimiters are not included in the result. The function returns a sequence of `xs:string` items. + +If the input string begins or ends with the delimiter pattern, the result includes an empty string at the start or end of the sequence respectively. If the input is an empty string and the pattern matches the empty string, the result is an empty sequence. + +`tokenize()` is the inverse of `string-join()`: where `string-join()` assembles strings from a sequence, `tokenize()` disassembles a string into a sequence. This makes them natural complements for round-tripping delimited data. + +## Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `string` | xs:string | Yes | The input string to split. | +| `pattern` | xs:string | Yes | A regular expression matching the delimiter. | +| `flags` | xs:string | No | Regex flags: `i` (case-insensitive), `m` (multiline), `s` (dot-all), `x` (extended). | + +## Return value + +`xs:string*` — a sequence of substrings split at each match of `pattern`. + +## Examples + +### Split a comma-separated list + +**Input XML:** +```xml + + + apple,banana,cherry,date + +``` + +**Stylesheet:** +```xml + + + + + + + + + + + + +``` + +**Output:** +```xml + + apple + banana + cherry + date + +``` + +### Split on whitespace + +**Stylesheet:** +```xml + + + + + + + + + + + + + +``` + +### Count tokens + +```xml + + +``` + +### Access a specific token by position + +```xml + + +``` + +## Notes + +- The `pattern` argument is a regular expression, not a plain string. Characters like `.`, `*`, `+`, `?`, `(`, `)` must be escaped with `\` if used literally (e.g., to split on a literal `.`, use `'\.'`). +- `tokenize()` returns zero or more strings; iterate the result with `xsl:for-each` or index it with `[n]`. +- If `pattern` can match an empty string (e.g., `'.*'`), Saxon raises an error — the delimiter must have non-zero length. +- For simple fixed-character splitting (comma, pipe), `tokenize()` is the idiomatic choice in XSLT 2.0+. In XSLT 1.0, use recursive named templates. + +## See also + +- [matches()](../xpath-matches) +- [string-join()](../xpath-string-join) diff --git a/site/content/xslt/functions/xsl-for-each-group.md b/site/content/xslt/functions/xsl-for-each-group.md new file mode 100644 index 00000000..6b85838a --- /dev/null +++ b/site/content/xslt/functions/xsl-for-each-group.md @@ -0,0 +1,150 @@ +--- +title: "xsl:for-each-group" +description: "Groups a sequence of items by a key expression or adjacent values, then iterates over each distinct group." +date: 2026-04-18T00:00:00Z +version: "2.0" +versionLabel: "XSLT 2.0" +category: "element" +syntax: '' +tags: ["xslt", "reference", "xslt2"] +--- + +## Description + +`xsl:for-each-group` divides a sequence into groups and then processes each group once. It replaces the complex Muenchian grouping technique required in XSLT 1.0 with a clean, declarative approach. + +There are four mutually exclusive grouping attributes: + +- **`group-by`** — groups items that share the same value of the key expression (like SQL `GROUP BY`). +- **`group-adjacent`** — groups consecutive items with the same key value. +- **`group-starting-with`** — starts a new group whenever an item matches a pattern. +- **`group-ending-with`** — ends the current group whenever an item matches a pattern. + +Inside the loop body, `current-group()` returns the sequence of items in the current group, and `current-grouping-key()` returns the key value that defines the group (available with `group-by` and `group-adjacent`). + +## Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `select` | XPath expression | Yes | The sequence to be grouped. | +| `group-by` | XPath expression | No* | Key expression evaluated for each item; items with equal keys form a group. | +| `group-adjacent` | XPath expression | No* | Like `group-by` but only consecutive equal-key items are grouped. | +| `group-starting-with` | Pattern | No* | A new group begins each time an item matches the pattern. | +| `group-ending-with` | Pattern | No* | A group ends each time an item matches the pattern. | +| `collation` | URI | No | Collation used for key comparison. | + +*Exactly one grouping attribute must be present. + +## Examples + +### Group items by category + +**Input XML:** +```xml + + + AppleFruit + CarrotVegetable + BananaFruit + BroccoliVegetable + CherryFruit + +``` + +**Stylesheet:** +```xml + + + + + + + + + + + + + + + + + +``` + +**Output:** +```xml + + + Apple + Banana + Cherry + + + Carrot + Broccoli + + +``` + +### Group adjacent elements (section headings) + +**Input XML:** +```xml + + +

Introduction

+

First paragraph.

+

Second paragraph.

+

Conclusion

+

Final paragraph.

+ +``` + +**Stylesheet:** +```xml + + + + + + + +
+ <xsl:value-of select="self::h1"/> + + + +
+ + + + +``` + +**Output:** +```xml + +
+ Introduction + First paragraph. + Second paragraph. +
+
+ Conclusion + Final paragraph. +
+ +``` + +## Notes + +- `current-group()` is only accessible inside the body of `xsl:for-each-group`. +- `xsl:sort` applies to the order of **groups**, not to the items within each group. Sort items inside `xsl:for-each select="current-group()"` separately. +- Multiple grouping keys can be achieved by nesting `xsl:for-each-group` elements. +- For XSLT 1.0, the equivalent technique is the Muenchian method using `xsl:key` and `generate-id()`. See the [XSLT grouping guide](/posts/xslt-grouping-for-each-group). + +## See also + +- [xsl:for-each](../xsl-for-each) +- [key()](../xpath-key) diff --git a/site/content/xslt/functions/xsl-for-each.md b/site/content/xslt/functions/xsl-for-each.md new file mode 100644 index 00000000..e584bbd5 --- /dev/null +++ b/site/content/xslt/functions/xsl-for-each.md @@ -0,0 +1,120 @@ +--- +title: "xsl:for-each" +description: "Iterates over a node-set or sequence, applying the contained template body to each item in document order." +date: 2026-04-18T00:00:00Z +version: "1.0" +versionLabel: "XSLT 1.0" +category: "element" +syntax: "" +tags: ["xslt", "reference", "xslt1"] +--- + +## Description + +`xsl:for-each` selects a set of nodes (or, in XSLT 2.0+, a sequence of items) and processes each one in turn. Within the loop body, the **context node** changes to the current item, so XPath expressions are evaluated relative to it. + +It is the standard way to iterate over child elements or any repeated node structure when you do not want to use recursive template matching. The loop body can contain any sequence of XSLT instructions: output elements, `xsl:value-of`, nested `xsl:for-each` calls, conditionals, and so on. + +An optional `xsl:sort` child element placed immediately inside `xsl:for-each` (before any other content) changes the processing order without altering the source document. + +## Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `select` | XPath expression | Yes | Node-set or sequence to iterate over. | + +### Child element: `xsl:sort` + +Place one or more `xsl:sort` elements as the first children to sort the selected set before processing. + +| Attribute | Description | +|-----------|-------------| +| `select` | XPath expression used as the sort key. | +| `order` | `"ascending"` (default) or `"descending"`. | +| `data-type` | `"text"` (default) or `"number"`. | + +## Examples + +### Iterate over child elements + +**Input XML:** +```xml + + + Widget9.99 + Gadget24.99 + Doohickey4.49 + +``` + +**Stylesheet:** +```xml + + + + + +
    + +
  • + + — $ + +
    • +     +
+ + +``` + +**Output:** +```xml +
    +
  • Widget — $9.99
    • +
  • Gadget — $24.99
    • +
  • Doohickey — $4.49
    • +
+``` + +### Sorted iteration + +**Stylesheet (sort by price descending):** +```xml + + + + + +
    + + +
  • + +
    • +     +
+ + +``` + +**Output:** +```xml +
    +
  • Gadget — $24.99
    • +
  • Widget — $9.99
    • +
  • Doohickey — $4.49
    • +
+``` + +## Notes + +- `position()` and `last()` inside the loop refer to the position within the selected set, not the original document position. +- `current()` inside the loop returns the same node as `.` (the context node). It becomes useful when `current()` is called inside a predicate. +- For grouping scenarios (e.g., group items by category) prefer `xsl:for-each-group` (XSLT 2.0+) over the Muenchian method with `xsl:for-each`. +- Template rules (`xsl:apply-templates`) are generally more flexible and reusable than `xsl:for-each`; use `xsl:for-each` when the transformation logic is short and self-contained. + +## See also + +- [xsl:for-each-group](../xsl-for-each-group) +- [position()](../xpath-position) +- [last()](../xpath-last) diff --git a/site/content/xslt/functions/xsl-function.md b/site/content/xslt/functions/xsl-function.md new file mode 100644 index 00000000..d3ca8027 --- /dev/null +++ b/site/content/xslt/functions/xsl-function.md @@ -0,0 +1,121 @@ +--- +title: "xsl:function" +description: "Defines a named, callable stylesheet function available in XPath expressions throughout the stylesheet." +date: 2026-04-18T00:00:00Z +version: "2.0" +versionLabel: "XSLT 2.0" +category: "element" +syntax: '' +tags: ["xslt", "reference", "xslt2", "xpath"] +--- + +## Description + +`xsl:function` lets you define reusable functions directly inside a stylesheet. Once declared, the function can be called from any XPath expression in the same stylesheet — in `select` attributes, predicates, pattern expressions, or attribute value templates. + +Functions must have a **namespace-qualified name** (a prefix other than `xsl:`). The `as` attribute declares the return type using an XPath sequence type such as `xs:string`, `xs:integer`, `element()`, or `xs:string*`. Parameters are declared with `xsl:param` child elements, each optionally carrying an `as` type constraint. + +Unlike named templates (`xsl:call-template`), stylesheet functions return a value and can be used inline inside XPath expressions. They cannot produce result-tree nodes as a side effect — the function body must evaluate to a sequence that becomes the return value. + +## Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `name` | QName | Yes | The qualified name of the function (must include a non-`xsl:` namespace prefix). | +| `as` | SequenceType | No | Declared return type. Saxon enforces type checking when specified. | +| `visibility` | `"public"` \| `"private"` \| `"final"` \| `"abstract"` | No | Controls visibility in package/module scenarios (XSLT 3.0). Defaults to `"private"`. | +| `override` | `"yes"` \| `"no"` | No | XSLT 2.0 only: whether this function overrides an imported function with the same name and arity. | + +### Child elements + +| Element | Description | +|---------|-------------| +| `xsl:param` | Declares a parameter. Add one per argument in signature order. | +| *(body instructions)* | Any XSLT instructions whose final evaluated result is the function's return value. | + +## Return value + +The return value is whatever the last instruction in the function body evaluates to, or whatever is returned by `xsl:sequence`. The type is validated against the `as` attribute if present. + +## Examples + +### String utility function + +**Stylesheet:** +```xml + + + + + + + + + + + + + + + + + + +``` + +**Input XML:** +```xml + + + alice + bob + carol + +``` + +**Output:** +```xml + + Alice + Bob + Carol + +``` + +### Function using string-join + +**Stylesheet (join a sequence with a custom delimiter):** +```xml + + + + + + + + + + + + + +``` + +## Notes + +- Function names must use a non-empty namespace prefix. `xsl:function name="myFunc"` is invalid. +- Recursive calls are supported and commonly used for tree-walking functions. +- XSLT 3.0 introduces higher-order functions — `xsl:function` can be referenced as a value with `function-lookup()` or passed as an argument. +- Type annotations (`as` on `xsl:param` and `xsl:function`) improve both performance and early error detection in Saxon. + +## See also + +- [string-join()](../xpath-string-join) diff --git a/site/content/xslt/functions/xsl-iterate.md b/site/content/xslt/functions/xsl-iterate.md new file mode 100644 index 00000000..8601b37b --- /dev/null +++ b/site/content/xslt/functions/xsl-iterate.md @@ -0,0 +1,122 @@ +--- +title: "xsl:iterate" +description: "Processes a sequence item-by-item with carry-forward parameters, enabling efficient streaming and stateful iteration in XSLT 3.0." +date: 2026-04-18T00:00:00Z +version: "3.0" +versionLabel: "XSLT 3.0" +category: "element" +syntax: "" +tags: ["xslt", "reference", "xslt3"] +--- + +## Description + +`xsl:iterate` is an XSLT 3.0 instruction that processes a sequence one item at a time, similar to `xsl:for-each`, but with two important additions: + +1. **Carry-forward parameters** — declared with `xsl:param` inside the instruction, updated at the end of each iteration via `xsl:next-iteration`, and available in the final result via `xsl:on-completion`. +2. **Early termination** — `xsl:break` stops iteration before the end of the sequence, optionally emitting output at that point. + +These features make `xsl:iterate` the right tool for running aggregations (cumulative totals, maximums, etc.), building state across items, or stopping as soon as a condition is met. It also works in **streaming mode** (`xsl:stream`) because it processes the sequence without needing to hold it all in memory simultaneously. + +## Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `select` | XPath expression | Yes | The sequence to iterate over. | + +### Child elements + +| Element | Description | +|---------|-------------| +| `xsl:param` | Declares a carry-forward parameter with an initial value. | +| `xsl:next-iteration` | Provides updated parameter values for the next iteration. Must be the last instruction in the body (or inside `xsl:break`). | +| `xsl:on-completion` | Body executed after the last item (or after `xsl:break`). Has access to the final carry-forward parameter values. | +| `xsl:break` | Terminates the iteration immediately; can contain `xsl:on-completion` inline. | + +## Return value + +The instruction produces the nodes/items written by its body instructions and by `xsl:on-completion`. + +## Examples + +### Running total + +**Input XML:** +```xml + + + + + + + +``` + +**Stylesheet:** +```xml + + + + + + + + + + + + + + + + + + +``` + +**Output:** +```xml + + 398.75 + +``` + +### Stop at first match + +**Stylesheet (find the first order over 100):** +```xml + + + + + + + + + + + + + + + + +``` + +**Output:** +```xml + +``` + +## Notes + +- `xsl:iterate` requires XSLT 3.0. Use `xsl:for-each` for XSLT 1.0/2.0 iteration without carry-forward state. +- The `xsl:next-iteration` instruction must appear as the last step of the loop body; any instructions after it are not executed. +- `xsl:on-completion` sees the parameter values from the **last completed** iteration (or initial values if the sequence was empty). +- When used with `xsl:stream`, the select sequence can be a document node read in streaming fashion, processing arbitrarily large files in bounded memory. + +## See also + +- [xsl:for-each](../xsl-for-each) diff --git a/site/content/xslt/functions/xsl-value-of.md b/site/content/xslt/functions/xsl-value-of.md new file mode 100644 index 00000000..b9dac6a3 --- /dev/null +++ b/site/content/xslt/functions/xsl-value-of.md @@ -0,0 +1,103 @@ +--- +title: "xsl:value-of" +description: "Outputs the string value of an XPath expression as a text node in the result tree." +date: 2026-04-18T00:00:00Z +version: "1.0" +versionLabel: "XSLT 1.0" +category: "element" +syntax: '' +tags: ["xslt", "reference", "xslt1"] +--- + +## Description + +`xsl:value-of` evaluates an XPath expression and writes its string value as a text node into the result tree. It is one of the most frequently used XSLT instructions and the primary way to copy data from the source XML into the output. + +When the `select` expression returns a node-set, only the string value of the **first** node is used in XSLT 1.0. In XSLT 2.0 and later the result is a sequence, and all items are concatenated with a single space separator by default (or with the separator specified by the `separator` attribute). + +The optional `disable-output-escaping` attribute, when set to `yes`, writes the text without escaping characters like `<` and `&`. This is rarely needed and can produce invalid XML; avoid it unless you have a specific requirement such as injecting pre-built HTML markup. + +## Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `select` | XPath expression | Yes | Expression whose string value is written to the output. | +| `disable-output-escaping` | `"yes"` \| `"no"` | No | Defaults to `"no"`. When `"yes"`, special characters are not escaped. Use with care. | +| `separator` | string (XSLT 2.0+) | No | String placed between items when the sequence contains more than one item. Defaults to a single space. | + +## Return value + +Produces a text node in the result tree. The instruction itself has no XPath return value. + +## Examples + +### Output a single element value + +**Input XML:** +```xml + + + Learning XSLT + Jane Smith + +``` + +**Stylesheet:** +```xml + + + + + + + by + + + +``` + +**Output:** +``` +Learning XSLT by Jane Smith +``` + +### Concatenate all items (XSLT 2.0) + +**Input XML:** +```xml + + + xslt + xml + xpath + +``` + +**Stylesheet:** +```xml + + + + + + + + +``` + +**Output:** +``` +xslt, xml, xpath +``` + +## Notes + +- In XSLT 1.0, if `select` returns a node-set with multiple nodes, only the first node's string value is output. Use `xsl:for-each` to iterate all nodes. +- The `separator` attribute was introduced in XSLT 2.0 and is not available in 1.0 stylesheets. +- To produce an attribute value, use `xsl:attribute` with a value template `{expression}` instead of `xsl:value-of`. +- `xsl:copy-of` preserves nodes including their type; use it when you need to copy nodes rather than their string representation. + +## See also + +- [xsl:for-each](../xsl-for-each) +- [concat()](../xpath-concat) diff --git a/site/hugo.toml b/site/hugo.toml index 0da174bd..50c23a16 100644 --- a/site/hugo.toml +++ b/site/hugo.toml @@ -35,6 +35,11 @@ publisher = "xsltplaygroundcom" url = "/about/" weight = 3 + [[menu.main]] + name = "Reference" + url = "/xslt/functions/" + weight = 4 + [[menu.main]] name = "Charts" url = "https://alexandrev.github.io/xslt-lab/index.yaml" diff --git a/site/layouts/xslt/functions/list.html b/site/layouts/xslt/functions/list.html new file mode 100644 index 00000000..c9ceb0b0 --- /dev/null +++ b/site/layouts/xslt/functions/list.html @@ -0,0 +1,39 @@ +{{ define "main" }} +
+

XSLT & XPath Function Reference

+

Complete reference for XSLT elements and XPath functions, organized by version. Each entry includes syntax, parameters, and runnable examples.

+
+ +{{ $elements := where .Pages "Params.category" "element" }} +{{ $functions := where .Pages "Params.category" "ne" "element" }} + +{{ if $elements }} +
+

XSLT Elements

+
    + {{ range $elements }} +
  • + {{ .Title }} + {{ with .Params.versionLabel }}{{ . }}{{ end }} + {{ .Description | truncate 80 }} +
    • + {{ end }} +
+
+{{ end }} + +{{ if $functions }} +
+

XPath Functions

+
    + {{ range $functions }} +
  • + {{ .Title }} + {{ with .Params.versionLabel }}{{ . }}{{ end }} + {{ .Description | truncate 80 }} +
    • + {{ end }} +
+
+{{ end }} +{{ end }} diff --git a/site/layouts/xslt/functions/single.html b/site/layouts/xslt/functions/single.html new file mode 100644 index 00000000..9ccf0037 --- /dev/null +++ b/site/layouts/xslt/functions/single.html @@ -0,0 +1,26 @@ +{{ define "main" }} +
+

XSLT Reference

+

{{ .Title }}

+
+ {{ with .Params.versionLabel }}{{ . }}{{ end }} + {{ with .Params.category }}{{ . }}{{ end }} +
+ {{ with .Description }}

{{ . }}

{{ end }} + {{ with .Params.syntax }} +
+ Syntax + 
{{ . }}
+
+ {{ end }} + {{ partial "adsense/in-article.html" . }} +
+ {{ .Content }} +
+
+ Try it in XSLT Playground → +
+

← Back to XSLT Reference

+ {{ partial "related-posts.html" . }} +
+{{ end }} diff --git a/site/static/css/main.css b/site/static/css/main.css index 96c19a26..4576a34f 100644 --- a/site/static/css/main.css +++ b/site/static/css/main.css @@ -297,8 +297,141 @@ code { color: var(--accent); } +/* ── Reference pages ───────────────────────────────────────────── */ + +.ref-meta { + display: flex; + gap: 8px; + margin: 10px 0 16px; + flex-wrap: wrap; +} + +.ref-badge { + display: inline-block; + padding: 2px 10px; + border-radius: 20px; + font-size: 12px; + font-weight: 700; + letter-spacing: 0.04em; + background: rgba(50, 213, 255, 0.12); + color: var(--accent); + border: 1px solid rgba(50, 213, 255, 0.25); +} + +.ref-badge--cat { + background: rgba(255, 126, 103, 0.12); + color: var(--accent-2); + border-color: rgba(255, 126, 103, 0.25); +} + +.ref-badge--sm { + font-size: 10px; + padding: 1px 7px; +} + +.ref-syntax { + margin: 20px 0; + background: rgba(255, 255, 255, 0.03); + border: 1px solid var(--border); + border-radius: 10px; + overflow: hidden; +} + +.ref-syntax-label { + display: block; + padding: 6px 14px; + font-size: 11px; + letter-spacing: 0.1em; + text-transform: uppercase; + color: var(--muted); + border-bottom: 1px solid var(--border); +} + +.ref-syntax pre { + margin: 0; + padding: 14px; + overflow-x: auto; +} + +.ref-syntax pre code { + background: none; + padding: 0; + font-size: 13px; + color: var(--accent); +} + +.ref-try { + margin: 32px 0 24px; +} + +.ref-index-list { + list-style: none; + padding: 0; + margin: 0 0 32px; + display: flex; + flex-direction: column; + gap: 2px; +} + +.ref-index-list li { + display: flex; + align-items: baseline; + gap: 10px; + padding: 8px 12px; + border-radius: 8px; + flex-wrap: wrap; +} + +.ref-index-list li:hover { + background: rgba(255, 255, 255, 0.03); +} + +.ref-index-list a { + font-weight: 600; + font-family: monospace; + font-size: 14px; + min-width: 200px; +} + +.ref-section { + margin: 32px 0; +} + +.ref-section h2 { + border-bottom: 1px solid var(--border); + padding-bottom: 8px; + margin-bottom: 16px; +} + +.post.ref-page .content table { + width: 100%; + border-collapse: collapse; + margin: 20px 0; + font-size: 14px; +} + +.post.ref-page .content th, +.post.ref-page .content td { + padding: 8px 12px; + border: 1px solid var(--border); + text-align: left; + vertical-align: top; +} + +.post.ref-page .content th { + background: rgba(255, 255, 255, 0.04); + color: var(--muted); + font-weight: 600; + font-size: 12px; + text-transform: uppercase; + letter-spacing: 0.05em; +} + +/* ── Media queries ─────────────────────────────────────────────── */ + @media (max-width: 720px) { .header-grid { grid-template-columns: 1fr; } .nav { flex-wrap: wrap; } .post-list li { flex-direction: column; align-items: flex-start; } + .ref-index-list a { min-width: unset; } }