The xinclude package implements the XML Inclusions (XInclude) 1.0 specification, enabling XML document assembly from multiple resource inclusions. It operates by recursively resolving <xi:include> elements and integrating external or internal XML fragments into a single document.
Complementary to this, the xpointer package provides fragment identification capabilities used by XInclude to select specific subsections of included documents rather than incorporating entire resources. Both rely on the xpath1 package for expression evaluation and the core helium DOM for XML node manipulations and base URI handling.
Sources:
The main entry function in the xinclude package is:
This function recursively processes XInclude elements within the given document, expanding includes by:
Recursive Expansion and Substitution
Process traverses the document tree, replacing each <xi:include> element with the nodes loaded from the referenced resource. If these included nodes themselves contain <xi:include>, they are processed recursively.
Circularity Detection To prevent infinite loops in document inclusion, the package maintains an inclusion context stack that tracks active base URIs. Before loading a resource, it checks if the URI is already on the stack. If so, processing halts with a circularity error.
Base URI Fixup
When included nodes originate from a document different from the including one, the package fixes the xml:base attributes of those nodes (or adds them if missing) to retain their original base URI. This preserves the correct resolution context for relative URIs within included content.
Fallback Element Support
If resource loading fails (e.g., due to network errors or missing files), the processor looks for a <xi:fallback> child. If present, the fallback content is used in place of the include. Otherwise, an error occurs.
Sources:
The xpointer package provides fragment addressing to select portions of XML documents, enabling XInclude to include precise parts rather than whole files.
Document.GetElementByID(id) lookup.element(myID), or element(/1/2/3) selects a nested child element.xpointer(xpath1(expression)) to select node sets.The package exposes:
which parses the pointer string, dispatches the selection logic based on the scheme, and returns matching nodes.
xpointer leverages the xpath1 engine for complex fragment selectors:
This dependency is critical for supporting XPath-based fragment addressing in XInclude.
Sources:
| Symbol | Description |
|---|---|
Process(doc *helium.Document) (int, error) | Recursively processes <xi:include> elements in the document, substituting referenced content. Returns count of substitutions performed. |
context | Internal struct tracking inclusion stack, base URIs, and processing flags to detect circularity and manage base URI fixup. |
loadResource() | Fetches and parses external XML resources referenced by href. Integrates with helium.Parser to obtain a Document. Handles fallback logic and error detection. |
fixupBaseURI(doc *Document, node helium.Node, baseURI string) | Adjusts xml:base attributes on included nodes to maintain proper URI context relative to inclusion point. |
| Symbol | Description |
|---|---|
Evaluate(doc *helium.Document, ptr string) ([]helium.Node, error) | Evaluates an XPointer fragment identifier against the given document and returns matching nodes. Supports shorthand, element(), and xpath1() schemes. |
extractScheme(ptr string) string | Internal helper function that parses the scheme from an XPointer string, e.g., returns "xpath1", "element", or "" for shorthand. |
The Process function creates and uses an internal context structure to manage the stack of currently included base URIs. When a new resource is to be loaded:
This ensures robustness against self-referential or mutually recursive document inclusions.
Included fragments often originate from a different base URI than the including document. To preserve the expected relative URL semantics within included content, fixupBaseURI:
xml:base attributes).xml:base accordingly.This functionality is controlled via the parser option FixBaseURIs(bool) .claude/docs/packages.md12
The inclusion fragment selection requires evaluating XPath expressions embedded in the XPointer fragment. The xpointer package wraps xpath1 to implement this efficiently:
xpath1.Compile() .claude/docs/packages.md50xpath1.Evaluate() .claude/docs/packages.md51By building on the well-tested xpath1 engine, the xpointer and xinclude packages avoid duplicating XPath parsing and evaluation logic.
Sources:
Sources:
The xinclude and xpointer packages implement robust, recursive XML inclusion and fragment addressing compatible with the W3C specifications. By relying on the core helium DOM and the xpath1 package, they provide a modular, reusable infrastructure for advanced XML composition with:
This layer is essential for building complex XML processing pipelines that compose documents from distributed or modular sources.
Refresh this wiki
This wiki was recently refreshed. Please wait 1 day to refresh again.