diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6189944..40923d9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Added
+- XSLT `xsl:message` (#81). The message body is instantiated as diagnostic text;
+ `terminate="yes"` aborts the transformation with that text as an
+ `XSLTError.terminated`, and processing stops at that point. A non-terminating
+ message produces no result-tree output.
- XSLT `xsl:strip-space` / `xsl:preserve-space` (#81). Whitespace-only text nodes
are removed from the source tree for elements named by `strip-space` before
transformation, with `preserve-space` and a more specific name test winning over
diff --git a/Sources/XSLT/XSLTModel.swift b/Sources/XSLT/XSLTModel.swift
index d13c479..2f95ccb 100644
--- a/Sources/XSLT/XSLTModel.swift
+++ b/Sources/XSLT/XSLTModel.swift
@@ -59,6 +59,9 @@ public extension PureXML.XSLT {
/// `xsl:processing-instruction` whose target is `name` and whose data is
/// the instantiated body.
case processingInstruction(name: ValueTemplate, body: [Instruction])
+ /// `xsl:message`: instantiates its body as a diagnostic. `terminate` ends
+ /// the transformation with that text; it produces no result-tree output.
+ case message(terminate: Bool, body: [Instruction])
}
/// The `xsl:output` controls that shape serialization: the output method, and
diff --git a/Sources/XSLT/XSLTParser.swift b/Sources/XSLT/XSLTParser.swift
index a800449..45c975e 100644
--- a/Sources/XSLT/XSLTParser.swift
+++ b/Sources/XSLT/XSLTParser.swift
@@ -54,13 +54,16 @@ private enum XSLTNode {
}
public extension PureXML.XSLT {
- /// Errors compiling a stylesheet.
+ /// Errors compiling or running a stylesheet.
enum XSLTError: Swift.Error, Equatable, Sendable, CustomStringConvertible {
case notAStylesheet
+ /// An `xsl:message terminate="yes"` ended the transformation with this text.
+ case terminated(String)
public var description: String {
switch self {
case .notAStylesheet: "the document is not an xsl:stylesheet"
+ case let .terminated(message): "transformation terminated: \(message)"
}
}
}
@@ -226,6 +229,7 @@ extension PureXML.XSLT {
case "text": .literalText(node.stringValue)
case "variable", "param": variable(node)
case "copy": .copy(body: body(node))
+ case "message": .message(terminate: XSLTNode.attribute(node, "terminate") == "yes", body: body(node))
default: nil
}
}
diff --git a/Sources/XSLT/XSLTTransform.swift b/Sources/XSLT/XSLTTransform.swift
new file mode 100644
index 0000000..ece120b
--- /dev/null
+++ b/Sources/XSLT/XSLTTransform.swift
@@ -0,0 +1,48 @@
+public extension PureXML.XSLT {
+ /// Transforms `source` with `stylesheet`, returning the serialized result.
+ /// `documentLoader` resolves the URI argument of the `document()` function to
+ /// source text; it returns `nil` (the default) when external documents are
+ /// not available, which keeps `document()` from reaching the filesystem or
+ /// network by default.
+ static func transform(
+ stylesheet: String,
+ source: String,
+ options: PureXML.Emitting.Options = .compact,
+ documentLoader: @escaping (String) -> String? = { _ in nil },
+ ) throws -> String {
+ let sheet = try XSLTParser.parse(stylesheet, loader: documentLoader)
+ let root = try PureXML.parseTree(source)
+ Whitespace.strip(root, stylesheet: sheet)
+ let transformer = Transformer(stylesheet: sheet, root: root, documentLoader: documentLoader)
+ let result = transformer.run()
+ if let message = transformer.terminationMessage { throw XSLTError.terminated(message) }
+ if sheet.output.method == "text" { return textValue(of: result) }
+ return PureXML.serialize(result, options: options.applying(sheet.output))
+ }
+
+ /// Transforms `source` with `stylesheet`, returning the result tree.
+ static func transformToNode(
+ stylesheet: String,
+ source: String,
+ documentLoader: @escaping (String) -> String? = { _ in nil },
+ ) throws -> PureXML.Model.Node {
+ let sheet = try XSLTParser.parse(stylesheet, loader: documentLoader)
+ let root = try PureXML.parseTree(source)
+ Whitespace.strip(root, stylesheet: sheet)
+ let transformer = Transformer(stylesheet: sheet, root: root, documentLoader: documentLoader)
+ let result = transformer.run()
+ if let message = transformer.terminationMessage { throw XSLTError.terminated(message) }
+ return result
+ }
+
+ /// The concatenated text content of a result tree, for the `text` output
+ /// method: character data only, with markup, comments, and PIs dropped.
+ private static func textValue(of node: PureXML.Model.Node) -> String {
+ switch node {
+ case let .text(value), let .cdata(value): value
+ case let .document(children): children.map(textValue).joined()
+ case let .element(element): element.children.map(textValue).joined()
+ case .comment, .processingInstruction: ""
+ }
+ }
+}
diff --git a/Sources/XSLT/XSLTTransformer.swift b/Sources/XSLT/XSLTTransformer.swift
index 1e1ce21..fff1a98 100644
--- a/Sources/XSLT/XSLTTransformer.swift
+++ b/Sources/XSLT/XSLTTransformer.swift
@@ -13,6 +13,13 @@ private struct XSLTContext {
var variables: [String: PureXML.XPath.Value]
}
+/// Shared, mutable signal that an `xsl:message terminate="yes"` fired, carrying
+/// its text. A reference type so the value-semantics transformer can set it.
+/// File-scope and private.
+private final class Termination {
+ var message: String?
+}
+
extension PureXML.XSLT {
/// Runs a compiled stylesheet against a source tree, producing a result tree
/// by the XSLT 1.0 processing model: apply templates from the root, match each
@@ -23,6 +30,12 @@ extension PureXML.XSLT {
let root: PureXML.Model.TreeNode
let documentLoader: (String) -> String?
private let keyIndex: PureXML.XSLT.KeyIndex
+ private let termination = Termination()
+
+ /// The `xsl:message terminate="yes"` text, if one fired during `run()`.
+ var terminationMessage: String? {
+ termination.message
+ }
init(stylesheet: Stylesheet, root: PureXML.Model.TreeNode, documentLoader: @escaping (String) -> String? = { _ in nil }) {
self.stylesheet = stylesheet
@@ -31,7 +44,7 @@ extension PureXML.XSLT {
keyIndex = PureXML.XSLT.Library.buildKeyIndex(stylesheet: stylesheet, root: root)
}
- fileprivate func run() -> PureXML.Model.Node {
+ func run() -> PureXML.Model.Node {
var variables: [String: PureXML.XPath.Value] = [:]
let baseContext = XSLTContext(node: root, position: 1, size: 1, variables: variables)
for global in stylesheet.globals {
@@ -122,6 +135,7 @@ extension PureXML.XSLT {
var items: [ResultItem] = []
var context = context
for instruction in body {
+ if termination.message != nil { break }
if case let .variable(name, select, varBody) = instruction {
context.variables[name] = variableValue(select, varBody, context)
} else {
@@ -213,6 +227,15 @@ extension PureXML.XSLT.Transformer {
}
}
+ /// Instantiates an `xsl:message` body as its text; `terminate` records the
+ /// signal so the transform aborts with it. Produces no result-tree output.
+ private func message(_ terminate: Bool, _ body: [PureXML.XSLT.Instruction], _ context: XSLTContext) -> [ResultItem] {
+ if terminate, termination.message == nil {
+ termination.message = Self.text(of: instantiate(body, context))
+ }
+ return []
+ }
+
private func structuralEvaluate(_ instruction: PureXML.XSLT.Instruction, _ context: XSLTContext) -> [ResultItem] {
switch instruction {
case let .literalElement(name, attributes, body):
@@ -229,6 +252,8 @@ extension PureXML.XSLT.Transformer {
[.node(.comment(Self.text(of: instantiate(body, context))))]
case let .processingInstruction(name, body):
[.node(.processingInstruction(target: avt(name, context), data: Self.text(of: instantiate(body, context))))]
+ case let .message(terminate, body):
+ message(terminate, body, context)
default:
[]
}
@@ -350,47 +375,3 @@ extension PureXML.XSLT.Transformer {
return (try? query.value(at: node).string) ?? ""
}
}
-
-public extension PureXML.XSLT {
- /// Transforms `source` with `stylesheet`, returning the serialized result.
- /// `documentLoader` resolves the URI argument of the `document()` function to
- /// source text; it returns `nil` (the default) when external documents are
- /// not available, which keeps `document()` from reaching the filesystem or
- /// network by default.
- static func transform(
- stylesheet: String,
- source: String,
- options: PureXML.Emitting.Options = .compact,
- documentLoader: @escaping (String) -> String? = { _ in nil },
- ) throws -> String {
- let sheet = try XSLTParser.parse(stylesheet, loader: documentLoader)
- let root = try PureXML.parseTree(source)
- Whitespace.strip(root, stylesheet: sheet)
- let result = Transformer(stylesheet: sheet, root: root, documentLoader: documentLoader).run()
- if sheet.output.method == "text" { return textValue(of: result) }
- return PureXML.serialize(result, options: options.applying(sheet.output))
- }
-
- /// Transforms `source` with `stylesheet`, returning the result tree.
- static func transformToNode(
- stylesheet: String,
- source: String,
- documentLoader: @escaping (String) -> String? = { _ in nil },
- ) throws -> PureXML.Model.Node {
- let sheet = try XSLTParser.parse(stylesheet, loader: documentLoader)
- let root = try PureXML.parseTree(source)
- Whitespace.strip(root, stylesheet: sheet)
- return Transformer(stylesheet: sheet, root: root, documentLoader: documentLoader).run()
- }
-
- /// The concatenated text content of a result tree, for the `text` output
- /// method: character data only, with markup, comments, and PIs dropped.
- private static func textValue(of node: PureXML.Model.Node) -> String {
- switch node {
- case let .text(value), let .cdata(value): value
- case let .document(children): children.map(textValue).joined()
- case let .element(element): element.children.map(textValue).joined()
- case .comment, .processingInstruction: ""
- }
- }
-}
diff --git a/Tests/XSLTMessageTests.swift b/Tests/XSLTMessageTests.swift
new file mode 100644
index 0000000..bf0274b
--- /dev/null
+++ b/Tests/XSLTMessageTests.swift
@@ -0,0 +1,58 @@
+@testable import PureXML
+import Testing
+
+@Suite("XSLT xsl:message")
+struct XSLTMessageTests {
+ private let xsl = "xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\""
+
+ private func transform(_ stylesheet: String, _ source: String) throws -> String {
+ try PureXML.XSLT.transform(stylesheet: stylesheet, source: source)
+ }
+
+ @Test("A non-terminating message produces no output and does not abort")
+ func test_nonTerminating() throws {
+ let style = """
+
+
+
+ just a note
+
+
+
+ """
+ #expect(try transform(style, "") == "")
+ }
+
+ @Test("terminate=yes aborts the transform, carrying the message text")
+ func test_terminate() throws {
+ let style = """
+
+
+
+ stop now
+
+
+ """
+ var thrown: PureXML.XSLT.XSLTError?
+ do {
+ _ = try transform(style, "")
+ } catch let error as PureXML.XSLT.XSLTError {
+ thrown = error
+ }
+ #expect(thrown == .terminated("stop now"))
+ }
+
+ @Test("A terminating message can interpolate the source via value-of")
+ func test_terminateDynamic() throws {
+ let style = """
+
+
+ bad value:
+
+
+ """
+ #expect(throws: PureXML.XSLT.XSLTError.terminated("bad value: 7")) {
+ _ = try transform(style, "")
+ }
+ }
+}