Add the PureXML.Pattern namespace: a compiler for the streamable XPath subset (names, *, prefix:*, /, //, leading absolute /, trailing @attr) into a Matcher, with predicates and . / .. rejected. The backward-matching algorithm tests an element's ancestor-or-self path. Pattern.matches(_:in:) streams a document through the pull parser and returns matching node paths in document order from the open-element stack alone, no tree built. Closes #44 Closes #45 Closes #22
13 KiB
13 KiB
Changelog
All notable changes to PureXML are documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
[Unreleased]
Added
- Streaming pattern matching (#22, the libxml2
pattern.hmodel). The newPureXML.Patternnamespace compiles the streamable XPath subset (element names,*,prefix:*,/,//, a leading absolute/, and a trailing attribute step) into aMatcher, 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, soposition(),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 namedidorxml:id. - The XPath expression engine and four-type model (toward #21 full XPath 1.0).
PureXML.XPath.Querynow 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 overPureXML.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 gainsvalue(over:variables:),number,string, andbooleanaccessors, and a binding map for$variables. The core functionslast,position,count,not,true,false,boolean,number, andstringship with it. - All thirteen XPath axes (toward #21 full XPath 1.0).
PureXML.XPath.Querynow navigateschild,descendant,parent,ancestor,following-sibling,preceding-sibling,following,preceding,attribute,namespace,self,descendant-or-self, andancestor-or-self, with the./../@///abbreviations and theprocessing-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 excludesxmlnsdeclarations and the namespace axis surfaces in-scope namespace nodes. - Pull-cursor reader (the libxml2
xmlTextReadermodel).PureXML.Parsing.TextReader(viaPureXML.reader(_:)) walks a document one node at a time withread(), exposingnodeKind,name,value,depth,attributes/attributeCount/attribute(_:), andisEmptyElementat 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>.documentTypesurfaces the DTD read so far as the validation hook. - Mutable, parent-aware document tree (the libxml2
tree.hmodel).PureXML.Model.TreeNodeis 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 andTreeNode.nodeconverts back to the value tree for serialization. - External and parameter entities (the libxml2
entities.hmodel), 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 injectedPureXML.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.OptionsgainsincludeXMLDeclaration,xmlVersion,encodingName, andstandalone; 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 libxml2chvalid.hparity): the XML 1.0 (Fifth Edition)Char,NameStartChar, andNameCharproductions as public predicates over Unicode scalars, plusisValidName(_:). The scanner's name recognition now uses these exact ranges (replacing a looseisLettercheck) 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
encodingname, 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 libxml2xmlTextWritermodel): emit a document with start/end and write calls without building a tree. Escaping matches the tree serializer (extracted into a sharedEscapinghelper), so compact output is byte-identical to serializing the equivalent tree. - SAX2 push-callback parsing (the libxml2 SAX2 model).
PureXML.Parsing.SAXHandleris 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
IDmust be unique across the document;IDREFandIDREFSvalues must each resolve to a declaredID(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, andDTDSchemanow checks#REQUIREDattributes are present,#FIXEDattributes 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, viaParser.parseWithDocumentType), andPureXML.Validation.DTDSchemavalidates 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.Querycompiles 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 aSelectionnode-set withelementandstringValueaccessors. 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 byLimits.maxEntityExpansion(billion-laughs amplification raisesParseError.amplificationLimitExceeded), recursive entities raiseParseError.recursiveEntity, undeclared entities raiseParseError.undefinedEntity, and external entities are never loaded (XXE stays closed). The default still rejects<!DOCTYPE>outright. - Streaming byte decode.
PureXML.parse(pullingBytes:)andevents(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-scopexmlnsdeclarations at the start-element boundary (the libxml2 SAX2 model). A default namespace applies to unprefixed element names but not attributes, thexmlprefix is built in,xmlnsdeclarations are preserved as attributes for round-trip, and an unbound prefix raisesParseError.undefinedNamespacePrefix. Namespace-free documents are unchanged (URIs stay nil). - Byte input with encoding detection.
PureXML.parse(bytes:)andPureXML.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) raisesParseError.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 throughparse/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, andQualifiedName, 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.EventReaderis a pull-based event core that consumes input through a character-source closure and emits oneEventat 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.Parserbuilds aModel.Nodetree 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:), andPureXML.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).