PureXML/CHANGELOG.md
Mihaela Mihaljevic 7ce6b4da73 feat(xslt): template parameters and modes
Honor xsl:param defaults, xsl:with-param on apply-templates and
call-template, and mode on templates and apply-templates. A passed parameter
overrides the declared default; a mode routes nodes only to templates of that
mode, and the built-in rules recurse in the same mode. Add the parity-
completion epic to the roadmap.

Closes #62
2026-06-08 07:48:05 +02:00

321 lines
22 KiB
Markdown

# Changelog
All notable changes to PureXML are documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
### Added
- XSLT template parameters and modes (toward full parity, #61). `xsl:param`
declarations (with defaults), `xsl:with-param` on `apply-templates` and
`call-template`, and `mode` on templates and `apply-templates` are now honored:
a passed parameter overrides the declared default, and a mode routes nodes only
to templates declared in that mode (the built-in rules recurse in the same
mode).
- Push / feed streaming API (#1), the last epic. A resumable scanner reports a
token only once its terminator is fully buffered and otherwise signals
need-more (the Expat `XML_TOK_PARTIAL` model), so `PureXML.Parsing.PushParser`
parses input fed in arbitrary chunks with `feed(_:)`/`finish()`, driving a
`SAXHandler`, while retaining only the current incomplete token plus the
open-element stack. `PureXML.events(feeding:)` exposes an `AsyncThrowingStream`
of events over any async sequence of text chunks. Splitting a document at any
byte boundary, down to one character per feed, yields identical events.
- HTML parser and serializer (#20, the libxml2 `HTMLparser.h`/`HTMLtree.h`
model). `PureXML.HTML.parse` reads tag-soup HTML leniently (case-insensitive
tags; quoted, unquoted, and boolean attributes; comments; doctype; character
references) and builds a node tree handling void elements (no end tag),
optional end tags (implicit close of `li`, `p`, table rows and cells, and the
like), raw-text elements (`script`, `style`), and unmatched end tags.
`PureXML.HTML.serialize` writes it back with void elements unclosed and
raw-text content unescaped.
- XSLT 1.0 transformation engine, completing #3. `PureXML.XSLT.transform`
applies a stylesheet to a source document by the XSLT processing model: it
matches each node to the highest-priority template (or the built-in rules) and
instantiates the template's sequence constructor. Implements `apply-templates`
(with template dispatch and `sort`), `value-of`, `for-each`, `if`, `choose`,
`element`, `attribute`, `copy`, `copy-of`, `call-template`, `variable`, literal
result elements, and attribute value templates, all over the existing XPath
engine. The identity transform round-trips a document including its attributes.
- XSLT 1.0 stylesheet model and parser (toward #3). `PureXML.XSLT` gains a
stylesheet model (template rules with match patterns and computed default
priorities, the instruction sequence constructor, attribute value templates)
and a parser that compiles an `xsl:stylesheet` document into it. Recognizes the
XSLT vocabulary by namespace or `xsl` prefix; other elements are literal result
elements. Supports `template`, `apply-templates`, `value-of`, `for-each`, `if`,
`choose`, `element`, `attribute`, `copy`, `copy-of`, `call-template`,
`variable`, `text`, and `sort`.
- Schema conformance fixtures, completing XSD and RELAX NG validation (#2). A
cross-cutting suite validates realistic schemas (a patterned, bounded,
ID-keyed XSD purchase order and a RELAX NG contact card using interleave,
attribute value choices, and optional/repeatable elements) against conforming
and non-conforming instances, plus datatype boundary fixtures.
- RELAX NG validation by derivatives (toward #2). `PureXML.Schema.RelaxNG`
parses a RELAX NG schema in the XML syntax into a pattern grammar (`element`,
`attribute`, `text`, `empty`, `notAllowed`, `group`, `choice`, `interleave`,
`optional`, `zeroOrMore`, `oneOrMore`, `mixed`, `list`, `ref`/`define`, `data`,
`value`, and the name classes), and `validate(_:)` checks an instance document
by James Clark's derivative algorithm: the pattern is derived through each
start-tag, attribute, text, and end-tag event, and the document is valid when
the residual pattern is nullable. Handles interleave, recursive grammars, and
reuses the XSD datatype library for `data`/`value`.
- XSD schema-document parser, completing the XSD validation pipeline (toward #2).
`PureXML.Schema.Document(xsd)` compiles a schema document into its global
element declarations and named-type table, and `validate(_:)` checks an
instance document end to end. The parser matches the schema vocabulary by local
name and supports global and local element declarations, named and inline
simple and complex types, `sequence`/`choice`/`all` model groups with
occurrence, attribute uses, simple content (restriction/extension), the full
facet set, and recursive types (via named type references resolved during
validation).
- XSD complex types and particles (toward #2 schema validation).
`PureXML.Schema.ComplexValidator` validates an element against a
`ComplexType`: its attribute uses (required and typed, with unknown-attribute
rejection), and its content model. Content is `empty`, `simpleContent` (text
validated against a simple type), `elementOnly`, or `mixed`. Particles compile
to a Thompson NFA over element names honoring `minOccurs`/`maxOccurs`, with
`sequence`/`choice` compositors; `all` groups are validated order-independently
by counting. Child elements are validated recursively against their declared
types (the XSD Element-Declarations-Consistent rule makes the name-to-type map
well defined).
- XSD simple-type datatype library (toward #2 schema validation). The new
`PureXML.Schema` namespace validates a lexical value against the XSD Part 2
built-in datatypes (`string`, `boolean`, `decimal`, the bounded integer family,
`float`/`double`, `duration`, the eight date/time types, `hexBinary`,
`base64Binary`, `anyURI`, `QName`, and the `Name`/`NCName`/`NMTOKEN`/`language`
family) and the constraining facets (`length`/`minLength`/`maxLength`,
`pattern` via the regex engine, `enumeration`, `whiteSpace`,
`min`/`maxInclusive`/`Exclusive`, `totalDigits`, `fractionDigits`). Decimals are
compared exactly with no floating-point loss, date/time fields are
range-validated (leap years, `24:00:00`, timezone bounds), and the integer
types enforce their intrinsic bounds.
- Regular-expression engine (#30, the XML Schema regex flavor, gating XSD). The
new `PureXML.Regex` namespace compiles a pattern (literals, `.`, character
classes with ranges and negation, the escapes `\d \D \w \W \s \S \i \I \c \C`,
single-character escapes, grouping, alternation, and the quantifiers `?`, `*`,
`+`, `{n}`, `{n,}`, `{n,m}`) to a Thompson NFA and matches the whole string, as
`xs:pattern` facets require. Matching is linear in the input with no
backtracking blow-up. `\p{...}` Unicode category escapes are not yet supported.
- Canonical XML (#26, the libxml2 `c14n.h` model). The new `PureXML.Canonical`
namespace renders the C14N form of a node: namespace declarations sorted by
prefix (default first) and attributes by namespace URI then local name, empty
elements expanded to start/end pairs, CDATA folded into escaped text, and the
C14N text/attribute escaping rules. Inclusive mode renders every in-scope
namespace; exclusive mode renders only the namespaces an element and its
attributes visibly use (with an `InclusiveNamespaces` prefix list). Comments
are omitted unless requested. For whole-tree canonicalization C14N 1.0 and 1.1
coincide, so the single inclusive mode covers both.
- XInclude, URI resolution, and `xml:base` (#24, the libxml2 `xinclude.h`/`uri.h`
model). The new `PureXML.XInclude` namespace adds RFC 3986 reference
resolution (`URIReference.resolve(_:against:)`, with dot-segment removal) and
`process(_:base:loadingURI:)`, which replaces `xi:include` elements with their
targets. `href`s resolve against the supplied base and the in-scope `xml:base`,
`parse="xml"` includes the document element (or an `xpointer()` fragment via
`PureXML.XPointer`), `parse="text"` includes raw text, and a failed load uses
`xi:fallback` or errors. Includes nest. PureXML does no I/O itself: fetching is
only through the injected `loadingURI` closure, so the default fetches nothing.
- XML Catalog resolution (#27, the libxml2 `catalog.h` model). The new
`PureXML.Catalog` namespace parses an OASIS XML catalog (matching `public`,
`system`, `uri`, `rewriteSystem`, `rewriteURI`, and `group`/`catalog` by local
name) into a `Resolver` that maps public/system identifiers and URI names to
replacement URIs, with longest-prefix rewriting and system-over-public
precedence. `Resolver.entityResolver(loadingURI:)` builds a
`Parsing.EntityResolver` that resolves an external identifier through the
catalog and then loads the URI via an injected closure, so a catalog plus a
loader wires external entities and DTDs in while the default (no loader) keeps
XXE closed.
- Schematron validation (#25, the libxml2 `schematron.h` model).
`PureXML.Validation.Schematron(schema:)` compiles a Schematron schema
(namespace-agnostic over the ISO and legacy namespaces) and `validate(_:)`
checks a document: each `<rule>`'s `context` XPath selects the nodes it fires
on, and each `<assert>`/`<report>` `test` is evaluated relative to that node, a
failed assert becoming an error issue and a matched report a warning. Within a
pattern a node fires the first matching rule. Built on the XPath context-node
evaluation, with a new `XPath.Query.nodes(over:)` that returns matched tree
nodes for repeated querying of one tree.
- XPointer (#23, the libxml2 `xpointer.h` schemes). The new `PureXML.XPointer`
namespace resolves the shorthand bare-name form (`name` = `id('name')`), the
`element()` scheme (child-element positions from an id or the document root,
e.g. `element(intro/2)`, `element(/1/2)`), and the `xpointer()` scheme (a full
XPath expression). A pointer may chain scheme parts; they are tried in order
and the first non-empty selection wins (the fallback rule). Built on
`PureXML.XPath`.
- Streaming pattern matching (#22, the libxml2 `pattern.h` model). The new
`PureXML.Pattern` namespace compiles the streamable XPath subset (element
names, `*`, `prefix:*`, `/`, `//`, a leading absolute `/`, and a trailing
attribute step) into a `Matcher`, rejecting predicates and `.`/`..` as outside
the subset. `PureXML.Pattern.matches(_:in:)` streams a document through the
pull parser and returns the paths of matching nodes (`/a/b/c`, `/a/@id`) in
document order, deciding each match from the open-element stack alone, so no
tree is built. `Matcher.matchesElement(path:)` reuses a compiled pattern.
- The XPath evaluation context, completing full XPath 1.0 (#21).
`Query.value(at:position:size:variables:)` evaluates an expression against an
explicit context node already in a tree, with its proximity position, size,
and variable bindings, so `position()`, `last()`, and the upward axes resolve
from that node. This is the per-node entry point downstream engines (XSLT,
Schematron) drive.
- The full XPath 1.0 function library (toward #21 full XPath 1.0). Beyond the
core functions, the string family (`concat`, `starts-with`, `contains`,
`substring-before`, `substring-after`, `substring`, `string-length`,
`normalize-space`, `translate`), the number family (`sum`, `floor`, `ceiling`,
`round`), and the node family (`local-name`, `name`, `namespace-uri`, `id`,
`lang`). All pure Swift with no Foundation. Without a DTD, `id()` matches by an
attribute named `id` or `xml:id`.
- The XPath expression engine and four-type model (toward #21 full XPath 1.0).
`PureXML.XPath.Query` now compiles and evaluates full expressions, not just
location paths: the operator grammar (`or`, `and`, `=`, `!=`, `<`, `<=`, `>`,
`>=`, `+`, `-`, `*`, `div`, `mod`, unary `-`, `|`) with correct precedence,
number and string literals, function calls, variable references, and filter
expressions, all over `PureXML.XPath.Value` (node-set, boolean, number,
string) with the spec's coercion rules and canonical number formatting.
Predicates are now arbitrary expressions (a numeric predicate is a position
test). Query gains `value(over:variables:)`, `number`, `string`, and `boolean`
accessors, and a binding map for `$variables`. The core functions `last`,
`position`, `count`, `not`, `true`, `false`, `boolean`, `number`, and `string`
ship with it.
- All thirteen XPath axes (toward #21 full XPath 1.0). `PureXML.XPath.Query` now
navigates `child`, `descendant`, `parent`, `ancestor`, `following-sibling`,
`preceding-sibling`, `following`, `preceding`, `attribute`, `namespace`,
`self`, `descendant-or-self`, and `ancestor-or-self`, with the `.`/`..`/`@`/`//`
abbreviations and the `processing-instruction()` node test. Evaluation runs
over the parent-aware tree, so upward and sibling navigation are first-class;
results come back de-duplicated and in document order regardless of axis
direction. The attribute axis excludes `xmlns` declarations and the namespace
axis surfaces in-scope namespace nodes.
- Pull-cursor reader (the libxml2 `xmlTextReader` model).
`PureXML.Parsing.TextReader` (via `PureXML.reader(_:)`) walks a document one
node at a time with `read()`, exposing `nodeKind`, `name`, `value`, `depth`,
`attributes`/`attributeCount`/`attribute(_:)`, and `isEmptyElement` at each
step. It layers on the streaming core, so it never holds the whole document.
A childless element is reported once as an empty element (no separate end
node), normalizing `<a/>` and `<a></a>`. `documentType` surfaces the DTD read
so far as the validation hook.
- Mutable, parent-aware document tree (the libxml2 `tree.h` model).
`PureXML.Model.TreeNode` is a reference type that knows its parent and
siblings, so a document can be navigated upward and sideways (`parent`,
`nextSibling`, `previousSibling`, `ancestors`, `root`, `elementChildren`,
`stringValue`) and edited in place (`append`, `insert(before:)`,
`insert(after:)`, `removeFromParent`, `replace(with:)`, `copy`). Children are
held strongly and the parent weakly; attaching a node detaches it from any
previous parent, and a node can never become its own ancestor. `parseTree(_:)`
builds one from XML and `TreeNode.node` converts back to the value tree for
serialization.
- External and parameter entities (the libxml2 `entities.h` model), secure by
default. Internal parameter entities (`<!ENTITY % name "value">`) are stored
and expanded within the DTD, including bare `%name;` references that inject
markup declarations, bounded by depth and the expansion budget. External
general entities and the external DTD subset are recorded but never fetched by
PureXML itself: they are loaded only through an injected
`PureXML.Parsing.EntityResolver` (a struct of closures). The default resolver
refuses every external reference, so XXE stays closed; an external entity then
fails as undefined and the external subset is left unread. Internal
declarations win over the external subset.
- Serialization option parity for the XML declaration (the libxml2 save-option
model). `PureXML.Emitting.Options` gains `includeXMLDeclaration`, `xmlVersion`,
`encodingName`, and `standalone`; when requested, both the tree serializer and
the incremental writer prepend an `<?xml ...?>` declaration from a single shared
computation. `Writer.writeStartDocument()` emits it. Defaults stay off so
fragment output is unchanged.
- Spec-exact XML character classification (`PureXML.Parsing.XMLCharacter`, the
libxml2 `chvalid.h` parity): the XML 1.0 (Fifth Edition) `Char`,
`NameStartChar`, and `NameChar` productions as public predicates over Unicode
scalars, plus `isValidName(_:)`. The scanner's name recognition now uses these
exact ranges (replacing a loose `isLetter` check) from a single source of truth,
and handles both precomposed and combining-mark names.
- Full encoding support. Byte input now decodes UTF-32 (both byte orders, BOM or
sniffed) and the single-byte encodings ISO-8859-1 and Windows-1252 selected by
the XML declaration's `encoding` name, in addition to UTF-8 and UTF-16. The
streaming byte path also decodes UTF-32. Standard library only, no Foundation.
- Incremental XML writer (`PureXML.Emitting.Writer`, the libxml2 `xmlTextWriter`
model): emit a document with start/end and write calls without building a tree.
Escaping matches the tree serializer (extracted into a shared `Escaping` helper),
so compact output is byte-identical to serializing the equivalent tree.
- SAX2 push-callback parsing (the libxml2 SAX2 model). `PureXML.Parsing.SAXHandler`
is a struct of optional callbacks (start/end document, start/end element,
characters, CDATA, comment, processing instruction); `PureXML.parse(_:sax:)`
drives them from the streaming core. Element names are namespace-resolved, so
the URI is available on each callback.
- DTD ID/IDREF validation. Attributes typed `ID` must be unique across the
document; `IDREF` and `IDREFS` values must each resolve to a declared `ID`
(forward references included, via a second pass). Completes the structural DTD
validation layer alongside content models and attribute rules.
- DTD attribute validation (`<!ATTLIST>`). The parser surfaces attribute
declarations alongside element models, and `DTDSchema` now checks `#REQUIRED`
attributes are present, `#FIXED` attributes match when present, and enumerated
attributes take a declared value. Tokenized types (ID/IDREF/NMTOKEN) are parsed
but their value rules (uniqueness, references) are not yet enforced.
- DTD content-model validation. The parser now surfaces the `<!DOCTYPE>` internal
subset's `<!ELEMENT>` declarations (`PureXML.Parsing.DocumentType`, via
`Parser.parseWithDocumentType`), and `PureXML.Validation.DTDSchema` validates a
tree against them: `EMPTY`, `ANY`, `(#PCDATA)`, mixed content, and element
content models (sequence/choice with `?`/`*`/`+`, matched as a regular language
over child element names). `PureXML.validateAgainstInternalDTD(_:)` parses and
validates in one call. `<!ATTLIST>` validation is not yet covered.
- XPath query support (a practical subset). `PureXML.XPath.Query` compiles a
location path and evaluates it over a node; `PureXML.xpath(_:over:)` is the
one-shot convenience. Supports the forward axes (child, descendant `//`, self
`.`, attribute `@`), the node tests (name, `*`, `text()`, `node()`,
`comment()`), and the predicates `[n]`, `[@a]`, `[@a='v']`, `[child]`,
`[child='v']`. Returns a `Selection` node-set with `element` and `stringValue`
accessors. Upward/sibling axes and the full expression language are out of
scope (the model has no parent pointers).
- Optional DTD with internal general entities, off by default. With
`Limits(allowDoctype: true)` the parser reads a `<!DOCTYPE>` internal subset,
honors internal `<!ENTITY name "value">` declarations, and expands them in text
and attribute values. Defenses are mandatory: expansion is bounded by
`Limits.maxEntityExpansion` (billion-laughs amplification raises
`ParseError.amplificationLimitExceeded`), recursive entities raise
`ParseError.recursiveEntity`, undeclared entities raise
`ParseError.undefinedEntity`, and external entities are never loaded (XXE stays
closed). The default still rejects `<!DOCTYPE>` outright.
- Streaming byte decode. `PureXML.parse(pullingBytes:)` and
`events(pullingBytes:)` accept an incremental byte source (`() -> UInt8?`) and
decode UTF-8 or UTF-16 on the fly, so the bytes are never fully buffered.
Encoding is detected from the leading bytes; invalid sequences become the
Unicode replacement character rather than failing the stream.
- Namespace resolution. Qualified names now carry an optional resolved
`namespaceURI`, populated by the parser from in-scope `xmlns` declarations at
the start-element boundary (the libxml2 SAX2 model). A default namespace applies
to unprefixed element names but not attributes, the `xml` prefix is built in,
`xmlns` declarations are preserved as attributes for round-trip, and an unbound
prefix raises `ParseError.undefinedNamespacePrefix`. Namespace-free documents
are unchanged (URIs stay nil).
- Byte input with encoding detection. `PureXML.parse(bytes:)` and
`PureXML.events(bytes:)` accept raw `[UInt8]` and detect the encoding (UTF-8 or
UTF-16, with or without a byte-order mark) following the XML sniff order, then
decode with the Swift standard library (no Foundation). `PureXML.Parsing.
InputEncoding.detect(_:)` exposes the detector. Malformed input (such as an
odd-length UTF-16 stream) raises `ParseError.malformedEncoding`.
- Configurable, bounded-by-default parser limits (`PureXML.Parsing.Limits`):
maximum nesting depth (default 256), name length, and content length, enforced
during scanning. Protects against pathological input and keeps the recursive
node model safe to build and tear down. Threaded through `parse`/`events`.
- Initial package scaffold: root Swift package, namespacing under `PureXML`, and
the portability and verification gates carried over from PureYAML.
- XML node model (`PureXML.Model`): `Node`, `Element`, `Attribute`, and
`QualifiedName`, preserving document order and node kinds.
- XML emitter (`PureXML.Emitting.Serializer`) with pretty-printed and compact
output and correct text and attribute escaping.
- Structural validation (`PureXML.Validation.Validator`) for duplicate attribute
names.
- Streaming, iterative XML parser. `PureXML.Parsing.EventReader` is a pull-based
event core that consumes input through a character-source closure and emits one
`Event` at a time, holding only bounded state (an open-element stack and a small
lookahead buffer). It never requires the whole document in memory and can drive
chunked input. `PureXML.Parsing.Parser` builds a `Model.Node` tree iteratively
over the event core (no recursion). Handles elements, attributes, text, the five
predefined entities and numeric character references, comments, CDATA, and
processing instructions. Safe by default: `<!DOCTYPE>` is rejected (no DTD/XXE).
- Top-level API: `PureXML.parse(_:)`, `PureXML.parse(pulling:)`, and
`PureXML.events(_:)` / `PureXML.events(pulling:)` for streaming.
### Changed
- The emitter is now iterative (explicit work stack, not recursion), mirroring
libxml2's approach, so deep trees do not overflow the call stack.
- The emitter escapes tab/newline/CR (and `>`) in attribute values so attributes
round-trip through spec-compliant parsers; mixed content is no longer
reformatted (formatting is suppressed for elements with text/CDATA children).