XPath Engines

Relevant source files

• .claude/docs/packages.md
• .claude/docs/xpath3-architecture.md
• .claude/docs/xpath3-design.md

Helium provides two distinct XPath implementations designed for different use cases and specification levels:

• A legacy-compatible XPath 1.0 engine (xpath1)
• A modern, feature-rich XPath 3.1 engine (xpath3)

Both engines share a common underlying infrastructure for efficient and consistent DOM tree traversal and resource management, built within the internal/xpath package. They are tightly integrated with the Helium DOM (helium.Node) and follow a compile-once, evaluate-many pattern for optimized XPath expression evaluation.

Architectural Overview

Shared Internal Infrastructure: internal/xpath

At the core of both XPath engines lies the internal/xpath package, which implements specification-agnostic functionality crucial for XPath evaluation. Key features include:

• Axis Navigation: Implements the 13 XPath axes (e.g., child, parent, descendant) as the fundamental mechanism for node traversal in XPath expressions, exposed via the function TraverseAxis internal/xpath/axes.go39
• Document Order Handling: Provides DocOrderCache and methods like DeduplicateNodes to sort node sets by XML document order and remove duplicates, which is critical for correct XPath result semantics internal/xpath/docorder.go45-48
• Resource Limits: Implements safety limits such as DefaultMaxRecursionDepth and DefaultMaxNodeSetLength to guard against pathological expressions causing resource exhaustion internal/xpath/limits.go34
• String Value Extraction: Standardizes logic to compute the string-value of any node type in the DOM, used by both XPath engines for string conversions internal/xpath/stringvalue.go56

This shared internal layer ensures consistency in fundamental behaviors across both XPath 1.0 and 3.1 implementations.

Sources: .claude/docs/xpath3-architecture.md27-34 .claude/docs/xpath3-architecture.md36-51

Comparison of XPath Engines

Aspect	XPath 1.0 Engine (xpath1)	XPath 3.1 Engine (xpath3)
Specification	W3C XPath 1.0	W3C XPath 3.1
Data Model	Node-sets, Strings, Numbers, Booleans	Strongly-typed Sequences of Items (Nodes, Atomics, Maps, Arrays, Functions)
Execution Model	Direct AST interpretation and evaluation	VM-based bytecode execution with a compiler fast-path fallback
Type System	Weak and implicit (simple unions)	Rich, XSD-aware, strict types with atomic types and sequences
Extensibility	Custom Go functions via FunctionContext	Higher-Order Functions, inline functions, and custom Go functions
Performance	Direct evaluation for legacy scenarios	Compiled to VM instructions with optimizations for common patterns

Sources: .claude/docs/xpath3-architecture.md6-9 .claude/docs/xpath3-architecture.md63-86 .claude/docs/xpath3-design.md23-26

System Architecture and Code Entities

Below is a representation of the XPath 3.1 expression evaluation pipeline and its relationship with shared internal infrastructure components. XPath 1.0 has a simpler but analogous pipeline using xpath1.

XPath 3.1 Evaluation Pipeline

This pipeline tokenizes the input, performs parsing to form an AST, applies a fast-path compiler for simple expressions xpath3/compile_direct.go75 or lowers to a full VM bytecode program xpath3/compiler.go76 The VM then executes expressions against a context node using evalContext state xpath3/eval_state.go86 accessing shared axis traversal and ordering logic.

Sources: .claude/docs/xpath3-architecture.md20-25 .claude/docs/xpath3-architecture.md134-137

Context and Configuration Model

Helium uses the Context Carrier Pattern for configuring XPath evaluation parameters. The system uses functions that mutate Go's context.Context to set up evaluation environments.

Common configuration mutators supported by both engines include:

• WithNamespaces(ctx, nsMap) xpath1/xpath.go54 xpath3/xpath3.go73 — adds prefix-to-URI mappings for QName resolution.
• WithVariables(ctx, varsMap) xpath1/xpath.go55 xpath3/xpath3.go74 — binds variable names to values.
• WithFunctions(ctx, funcsMap) xpath1/xpath.go58 xpath3/xpath3.go76 — registers custom extension functions.
• WithURIResolver(ctx, resolver) xpath3/xpath3.go78 — (XPath 3.1) configures resolution for external resources like fn:doc.

Configuration Flow Diagram

Sources: .claude/docs/xpath3-architecture.md110-112 .claude/docs/xpath3-architecture.md95-96 .claude/docs/packages.md54-56

When to Use Each Engine

XPath 1.0 Engine (xpath1)

Choose xpath1 if:

• You need legacy XPath 1.0 compliance (e.g., for XInclude or XPointer support) xpath1/xpath.go48-54
• You require behavior closely aligned with libxml2’s XPath 1.0 implementation.
• Your expressions are simple, primarily using the 13 axes with basic string/number functions.
• You want simple integration with custom Go functions via FunctionContext xpath1/xpath.go58

For details, see XPath 1.0 Engine (xpath1).

XPath 3.1 Engine (xpath3)

Choose xpath3 if:

• You need advanced features: FLWOR expressions, Quantified expressions, or Higher-Order Functions (HOFs) xpath3/eval_control.go82
• You require a strong, XSD-aware type system with Maps, Arrays, and Atomic types xpath3/types.go68
• You want better performance through the VM-based evaluation engine xpath3/vm.go88
• You need the extensive standard function library (namespaces fn:, math:, map:, array:) xpath3/function_library.go110
• You want structured error types with W3C error codes, like XPathError xpath3/errors.go131

For details, see XPath 3.1 Engine — Public API (xpath3).

Sources: .claude/docs/xpath3-architecture.md6-9 .claude/docs/xpath3-design.md9-16

Detailed Engine Documentation

• XPath 1.0 Engine (xpath1) — Documents the xpath1 package: Find/Evaluate APIs, lexer/parser/evaluator pipeline, and custom function state.
• XPath 3.1 Engine — Public API (xpath3) — Documents the xpath3 public API: NewCompiler, Compile, Expression.Evaluate, Result, and context configuration.
• XPath 3.1 Engine — Parser and AST — Covers the lexer, recursive descent parser (21 precedence levels), and AST node types (FLWOR, arrow operator, etc.).
• XPath 3.1 Engine — VM Compiler and Evaluator — Explains the compilation pipeline (fast-path vs VM), vmProgram structure, and resource limits.
• XPath 3.1 Engine — Type System and Sequences — Documents the Item hierarchy, Sequence as eager []Item, atomization, and EBV logic.
• XPath 3.1 Engine — Built-in Function Library — Covers the registry, domain-partitioned implementation files, regex support, and URI resolution.

Sources: .claude/docs/xpath3-architecture.md6-9 .claude/docs/xpath3-design.md1-40