leptris 1.9.201.0-arm-linux → 1.9.201.2-arm-linux

data/vendor-src/libleptris/docs/ROADMAP-SAXON-PARITY.md

@@ -0,0 +1,194 @@
+# Leptris → Saxon-HE Parity Roadmap
+
+**Goal:** full feature parity with the latest Saxon-HE (13.x) — the
+open-source edition of the reference XSLT/XPath/XQuery processor.
+
+**What "parity with Saxon-HE" means (and doesn't):** Saxon-HE ships
+XSLT 3.0 (non-streaming), XPath 3.1 (+ select 4.0 extensions in 13),
+XQuery 3.1/4.0, and a non-schema-aware processor. Schema-aware
+processing and streaming are **PE/EE-only** — parity therefore
+excludes them (our full XSD 1.1 validator lives on TODO.validate;
+streaming on TODO.stream).
+
+**References:**
+- Source: `~/src/external/Saxon-HE/13` (Java sources,
+  `net/sf/saxon/{expr,om,style,query,type,functions,...}`).
+- Test suites: `~/src/external/saxon-xslt30tests` (8,486 stylesheets,
+  catalog-driven) + Saxonica/qt3tests (to clone; XPath/XQuery 3.1).
+- Behavioral reference for the 1.x line: libxslt
+  (`~/src/external/libxslt`).
+
+**Current position (2026-08-25):** libleptris 1.9.0-dev on main:
+XML 1.0 (W3C-conformant parse), XPath 1.0 (438/438 W3C suite),
+XSLT 1.0 (feature-complete per §1–§16; the adopted libxslt suite is
+the active conformance gate — 48/205 cases passing, 157 tracked in
+`test/xslt/open_cases.txt`; **no XSLT release ships until 205/205**).
+
+---
+
+## Version plan
+
+Each version = one theme, shipped only when its suite gate passes.
+Durations assume the current cadence (engine work + suites + release).
+
+### v1.10.0 — XSLT 1.0 conformance (libxslt gate)
+**Theme:** close every open libxslt-suite case. **Gate:** 205/205 +
+45/45 XsltFull + full suite green.
+- Remaining clusters (by size, from `test/xslt/open_cases.txt`):
+  - 20+ cases: `xsl:number` `from`/`level=any` edge semantics,
+    `format-number` pattern corners (bug-25-, bug-63.., bug-90..)
+  - 15+ cases: attribute-set merge/import precedence (bug-93-102
+    family), `xsl:attribute` namespace AVT
+  - 10+ cases: `document()` multi-file chains, `xsl:strip-space` on
+    included sheets, output indent="yes"
+  - 8 cases:  `key()` cross-document, `generate-id()` stability
+  - 3 crash cases (bug-111/130/147): recursion-depth accounting in
+    `xsl:apply-templates` chains
+- Exit criteria: open list empty, ASAN/TSAN/Windows CI green.
+
+### v1.11.0 — Engine hardening + EXSLT completion
+**Theme:** everything around XSLT 1.0 that processors actually ship.
+- EXSLT full: `dyn:*` (dynamic evaluation), `exsl:document`,
+  `saxon:*` compatibility subset, `str:tokenize` corners, crypto:NO.
+- `xsl:output` `indent="yes"` pretty-printer for XML + HTML
+  (libxslt-compatible modes).
+- Large-document performance pass: template-selection memoization,
+  key index sharing across transforms, RTF pool reuse.
+- Gate: libxslt suite stays 205/205; EXSLT suite
+  (`~/src/external/libxslt/tests/exslt`) adopted as specs (all of
+  common/functions/math/sets/strings/date).
+
+### v2.0.0 — XPath 2.0/3.1 type system + sequences
+**Theme:** the data model rewrite everything else builds on.
+(Saxon: `net/sf/saxon/om`, `net/sf/saxon/value`, `net/sf/saxon/type`.)
+- Sequence model: every expression yields `item()*` — replaces the
+  1.0 four-type result; nodesets are sequences of items.
+- Atomic types: `xs:integer/decimal/double/float/string/boolean/
+  anyURI/QName/Name/NCName/date/time/dateTime/duration/
+  dayTimeDuration/yearMonthDuration/base64Binary/hexBinary/
+  untypedAtomic`, with typed value spaces + subtype relations.
+- `castable as` / `cast as` / `instance of` / `treat as`, constructor
+  functions, `xs:*` validation-lite (non-schema-aware = untyped ok).
+- Backwards mode: 1.0 expressions keep exact 1.0 semantics (the
+  versioned-expression switch; 438/438 suite must stay green).
+- Gate: qt3tests XPath-cast/constructor/sequence subset adopted;
+  1.0 suites green.
+
+### v2.1.0 — XPath 2.0 expressions
+**Theme:** the 2.0 expression surface (Saxon: `net/sf/saxon/expr`).
+- `for $x in ... return`, `if/then/else`, `some/every ... satisfies`,
+  quantified expressions, `to` ranges, sequence ops (`union`,
+  `intersect`, `except` on any sequences), `instance of` tests.
+- Comparisons: value vs general (`eq`, `lt`, `>`, `is`), node
+  identity, `deep-equal`, collations.
+- Functions 2.0+: `matches/replace/tokenize` (Unicode-aware regex —
+  replaces POSIX), `avg/min/max/sum/distinct-values`,
+  `substring-before/after` with collation, `format-date/time`,
+  `adjust-timezone`, `resolve-uri`, `encode-for-uri`, `QName()`,
+  `local-name-from-QName`, `node-name`, `zero-or-one/one-or-more`,
+  `exactly-one`, `subsequence`, `insert-before`, `remove`, `index-of`,
+  `reverse`, `unordered`, `deep-equal`, `root`, `idref`.
+- Maps + arrays (3.1 preview since they share the value model):
+  map constructors `{...}`, lookup `?key`, array `[...]`, `?number`.
+- Gate: qt3tests expression subset; 1.0 suites green.
+
+### v2.2.0 — XPath 3.0/3.1 + dynamic function machinery
+- Inline functions `function($x){...}`, arrow `=>`, `!` mapping,
+  named function references `name#arity`, higher-order calls,
+  `function-lookup`, `function-name`, `function-arity`, partial
+  application `?`.
+- String templates, `parse-xml`/`parse-xml-fragment`,
+  `analyze-string`, `format-integer` full, `xml-to-json`/
+  `json-to-xml`, `load-xquery-module` (stub), `collation-key`,
+  `available-environment-variables`, `environment-variable`.
+- 4.0 previews behind a flag (Saxon 13 defaults much of 4.0):
+  `otherwise`, `||` string concat, `fn:charset`… tracked as
+  Saxon-13 parity items, not spec-3.1 ones.
+- Gate: qt3tests full XPath 3.1 subset adopted + green.
+
+### v3.0.0 — XSLT 2.0
+**Theme:** the 2.0 instruction surface (Saxon: `net/sf/saxon/style`).
+- Backwards-compatible + 2.0 strict modes; `xsl:stylesheet
+  version="2.0"` switches sequence semantics.
+- `xsl:function` (user functions, typed signatures),
+  `xsl:sequence` (no-copy node construction), tunnel parameters,
+  `xsl:for-each-group` (4 grouping kinds), `xsl:analyze-string`
+  (+ matching/non-matching), `xsl:result-document` (multiple
+  outputs), `xsl:next-match`, temporary trees, typed
+  `xsl:variable as="..."`, regex groups `$1..$n`, `xsl:perform-
+  with-accumulators` (later), pattern enhancements (predicates on
+  any step), `xsl:value-of select="..." separator`.
+- Schema-free typed access (document-less PSVI-lite).
+- Gate: xslt30tests version="2.0" subset (the suite's 2.0 test
+  sets) adopted + green.
+
+### v3.1.0 — XSLT 3.0 (non-streaming)
+- `xsl:evaluate` (dynamic expression eval), `xsl:iterate` +
+  `xsl:next-iteration`/`xsl:break`, `xsl:try`/`xsl:catch` (error
+  codes + diagnostics), `xsl:accumulator`/`xsl:accumulator-rule`,
+  `xsl:mode` declarations (on-no-match/on-deep-match),
+  shadow attributes `_name="{...}"`, `xsl:where-populated`,
+  `xsl:on-empty`, `xsl:on-non-empty`, text value templates
+  (`{...}` in text nodes with expand-text), `xsl:global-context-
+  item`, packages (`xsl:use-package` — non-streaming), `xsl:assert`.
+- Map/array construction + navigation as first-class results.
+- Gate: xslt30tests non-streaming subset green (target ≥ Saxon's
+  own HE pass rate on the non-streaming sets).
+
+### v3.2.0 — XQuery 3.1/4.0
+(Saxon: `net/sf/saxon/query`.)
+- Prolog: `declare variable/function/namespace/collation/
+  base-uri/construction/ordering/default collation`, module
+  imports + library modules, `declare context item`.
+- FLWOR: `for/let/where/group by/order by/count/return/window`,
+  `allowing empty`, `count` clauses, tumbling/sliding windows.
+- 3.1 built-ins: map/array functions, `transform()` (XSLT-from-
+  XQuery), `fn:load-xquery-module`, higher-order library.
+- Gate: qt3tests XQuery subset + qt3extra adopted + green.
+
+### v3.3.0 — Parity polish (Saxon-HE 13 feature checklist)
+- 4.0 extensions Saxon 13 ships by default (Saxonica spec status):
+  assignment expressions, `fn:items-at`, string concat `||`,
+  `otherwise`, records (limited), `fn:foot`/`fn:hd`/`fn:ticks`,
+  coercion rules, keyword arguments in calls.
+- APIs Saxon-HE parity: compile-to-bytecode is internal (our VM
+  already is); `Configuration`-level toggles mapped to leptris
+  options; CLI `xslt`/`xquery`/`gizmo`-equivalent entry points.
+- Serialization: full `fn:serialize` params (indent, line-separator,
+  suppress-indentation, byte-order-mark, normalization-form,
+  item-separator, json-node-output-method, html-version).
+- Gate: side-by-side Saxon-HE behavior audit on a sampled corpus
+  (same outputs for same inputs on the adopted suites).
+
+---
+
+## Suite gates (the definition of done per version)
+
+| Version | Suite | Where |
+|---|---|---|
+| 1.10 | libxslt general (205) + XsltFull (45) | in-tree |
+| 1.11 | libxslt EXSLT | `~/src/external/libxslt/tests/exslt` |
+| 2.0–2.2 | qt3tests (XPath 2.0→3.1 subsets) | Saxonica/qt3tests (clone) |
+| 3.0 | xslt30tests (2.0 test sets) | `~/src/external/saxon-xslt30tests` |
+| 3.1 | xslt30tests (non-streaming 3.0 sets) | same |
+| 3.2 | qt3tests XQuery + qt3extra | clone |
+| 3.3 | Saxon-HE side-by-side corpus audit | generated |
+
+## Non-goals (explicitly out of parity scope)
+
+- **Streaming** (XSLT 3.0 streaming transformations) — Saxon EE;
+  tracked on TODO.stream.
+- **Schema-aware processing** (XSD validation feeding the type
+  system) — Saxon PE/EE; tracked on TODO.validate. The 2.0+ type
+  system lands schema-free (untyped/psvi-lite), exactly like HE.
+- **XSLT 4.0 / XPath 4.0 full** — Saxon 13 ships previews; parity
+  targets what Saxon-HE 13 enables BY DEFAULT.
+
+## Standing rules
+
+1. **No release until its gate passes** (user directive, 2026-08-25).
+2. Every adopted suite's open list must shrink monotonically; a
+   reopened case is a release blocker.
+3. Port semantics from the Saxon sources; never invent. Where
+   libxslt and Saxon disagree on 1.0, libxslt is the reference (we
+   adopted its suite first).

data/vendor-src/libleptris/docs/guide/building.md

@@ -0,0 +1,199 @@
+# Building Leptris
+
+## Prerequisites
+
+- **CMake** >= 3.20
+- **C99 compiler** (GCC, Clang, or MSVC)
+- C++11 compiler (only for tests and benchmarks)
+- Optional: **utf8proc** (Unicode validation), **iconv** (encoding conversion), **Doxygen** (API docs)
+
+### Platform packages
+
+```bash
+# Debian/Ubuntu
+sudo apt-get install cmake ninja-build libutf8proc-dev
+
+# macOS (Homebrew)
+brew install cmake ninja utf8proc
+
+# Windows (vcpkg)
+vcpkg install utf8proc iconv
+```
+
+## Quick Start
+
+```bash
+cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
+cmake --build build
+ctest --test-dir build --output-on-failure
+```
+
+The default build produces the static library (`libleptris.a`), the `leptris` CLI binary, and the full Google Test suite.
+
+## Build Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `BUILD_TESTING` | `ON` | Build Google Test suite |
+| `LEPTRIS_BUILD_CLI` | `ON` | Build the `leptris` CLI tool |
+| `LEPTRIS_BUILD_STATIC` | `ON` | Build `libleptris.a` |
+| `LEPTRIS_BUILD_SHARED` | `OFF` | Build `libleptris.{so,dylib,dll}` |
+| `LEPTRIS_BUILD_BENCHMARKS` | `OFF` | Performance comparison targets |
+| `LEPTRIS_BUILD_MAN_PAGES` | `OFF` | Generate man pages from AsciiDoc |
+| `LEPTRIS_BUILD_DOCS` | `OFF` | Generate Doxygen HTML docs |
+| `LEPTRIS_ENABLE_UTF8PROC` | `ON` | UTF-8 validation via utf8proc |
+| `LEPTRIS_ENABLE_ICONV` | `ON` | Encoding conversion via iconv |
+| `LEPTRIS_ENABLE_ASAN` | `OFF` | Build with AddressSanitizer |
+| `LEPTRIS_ENABLE_FUZZING` | `OFF` | Build libFuzzer harness |
+| `LEPTRIS_ENABLE_PGO` | `OFF` | Profile-guided optimization phase: `OFF`, `GENERATE`, or `USE`. See [PGO](#pgo-build) below. |
+
+## PGO build
+
+Profile-guided optimization lets the compiler specialise the
+hot paths in the bytecode VM dispatch loop, the parser's tight
+scan loops, and the XPath predicate filter loops. In our tests
+on macOS arm64 + clang, PGO shaves ~8% off `bench_xpath_leptris`
+total time vs the LTO-only baseline. Works on clang, GCC, and
+MSVC — no GCC-isms.
+
+The build is a three-step process:
+
+```bash
+# 1. Build with instrumentation.
+cmake -B build-pgo -S . -DCMAKE_BUILD_TYPE=Release \
+                     -DLEPTRIS_ENABLE_PGO=GENERATE \
+                     -DLEPTRIS_BUILD_BENCHMARKS=ON
+cmake --build build-pgo -j
+
+# 2. Run a representative workload against the instrumented
+#    binary. The test suite + benchmark suite is a good default;
+#    if you ship leptris inside another app, use *its* test suite
+#    instead so the profile matches real traffic.
+ctest --test-dir build-pgo
+build-pgo/benchmarks/bench_xpath_leptris > /dev/null
+build-pgo/benchmarks/bench_xpath_pugixml > /dev/null
+
+# 3a. clang only: merge the .profraw into a single .profdata.
+#    Skip on GCC/MSVC — the profile is already usable.
+xcrun llvm-profdata merge \
+    build-pgo/pgo-data/default.profraw \
+    -o build-pgo/pgo-data/default.profdata
+
+# 3b. Rebuild with the profile applied.
+cmake -B build-pgo -S . -DCMAKE_BUILD_TYPE=Release \
+                     -DLEPTRIS_ENABLE_PGO=USE \
+                     -DLEPTRIS_BUILD_BENCHMARKS=ON
+cmake --build build-pgo -j
+```
+
+PGO defaults to OFF because the three-step workflow is heavier
+than most users need. Distributions and packagers who want the
+last ~10% on XPath dispatch should enable it.
+
+## Static vs Shared
+
+Default is static. To build a shared library instead:
+
+```bash
+cmake -B build -S . -DLEPTRIS_BUILD_STATIC=OFF -DLEPTRIS_BUILD_SHARED=ON \
+                -DCMAKE_BUILD_TYPE=Release
+```
+
+The shared library carries an SOVERSION matching the major version (`libleptris.so.0`).
+
+## ASAN Build
+
+```bash
+cmake -B build-asan -S . -DLEPTRIS_ENABLE_ASAN=ON -DBUILD_TESTING=ON \
+                     -DCMAKE_BUILD_TYPE=Debug
+cmake --build build-asan
+ASAN_OPTIONS=detect_leaks=1:halt_on_error=1 ctest --test-dir build-asan
+```
+
+On macOS, ASAN does not provide leak detection. Use the system `leaks` tool instead:
+
+```bash
+leaks --atExit -- ./build/test/test_dom
+```
+
+## Fuzzer Build (requires LLVM clang)
+
+```bash
+brew install llvm   # macOS
+export CC=/opt/homebrew/opt/llvm/bin/clang
+cmake -B build-fuzz -S . -DLEPTRIS_ENABLE_FUZZING=ON
+cmake --build build-fuzz --target fuzz_parse
+./build-fuzz/test/fuzz_parse test/fixtures/*.xml
+```
+
+## Doxygen API Docs
+
+```bash
+brew install doxygen     # or: sudo apt-get install doxygen
+cmake -B build -S . -DLEPTRIS_BUILD_DOCS=ON
+cmake --build build --target docs
+# Open build/docs/api-generated/html/index.html
+```
+
+## Installation
+
+```bash
+cmake --install build --prefix /usr/local
+```
+
+Installs headers under `include/leptris/`, the static library under `lib/`, and the CLI under `bin/`. pkg-config and CMake config files are installed for downstream consumers.
+
+### Downstream CMake
+
+```cmake
+find_package(leptris CONFIG REQUIRED)
+target_link_libraries(my_app PRIVATE leptris::leptris)
+```
+
+### Downstream pkg-config
+
+```bash
+gcc app.c $(pkg-config --cflags --libs leptris)
+```
+
+## Using vcpkg
+
+Leptris ships a vcpkg overlay port under `ports/leptris/`. Use it directly:
+
+```bash
+cmake -B build -S . \
+    -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake \
+    -DCMAKE_SOURCE_PATH=$PWD
+```
+
+Or copy `ports/leptris/` into your vcpkg overlay ports directory.
+
+## Runtime Configuration
+
+Leptris exposes thread-default configuration that is inherited by every document parsed on that thread:
+
+- `leptris_set_max_depth(int)` — overrides the 256-element nesting cap (DoS protection).
+- `leptris_set_strict_mode(int)` — enables strict XML well-formedness checks (rejects unknown entities, missing semicolons, etc.).
+- `leptris_document_set_strict(doc, int)` — overrides strict mode per-document.
+- `leptris_document_set_allocators(doc, alloc, dealloc)` — routes document-scoped allocations through custom hooks.
+
+See `src/include/leptris.h` for the complete public API.
+
+## Running Tests
+
+Tests are Google Test binaries under `build/test/`. Run a single suite:
+
+```bash
+./build/test/test_dom --gtest_filter=TestName.TestCase
+./build/test/test_xpath --gtest_filter=Axes.*
+```
+
+Or run all tests via ctest:
+
+```bash
+ctest --test-dir build --output-on-failure
+```
+
+## Validation Script
+
+`./scripts/validate.sh` does clean build → tests → CLI smoke → DOM → XPath → benchmarks → memory leak check → element-size check. Use this as a sanity check before tagging a release.

data/vendor-src/libleptris/docs/guide/getting-started.md

@@ -0,0 +1,134 @@
+# Getting Started with Leptris
+
+This guide will help you get started with the Leptris XML parser library.
+
+## Quick Start
+
+### Minimal Example
+
+```c
+#include <leptris.h>
+
+int main() {
+    /* Parse an XML document from a string */
+    const char* xml = "<root>Hello, World!</root>";
+    LeptrisDocument doc = leptris_parse_string(xml, strlen(xml), NULL);
+
+    if (!doc) {
+        fprintf(stderr, "Failed to parse XML\n");
+        return 1;
+    }
+
+    /* Get the root element */
+    LeptrisElement root = leptris_document_root(doc);
+    const char* name = leptris_element_name(root);
+    const char* text = leptris_element_text(root);
+
+    printf("Element: %s\n", name);
+    printf("Text: %s\n", text);
+
+    /* Clean up */
+    leptris_document_free(doc);
+    return 0;
+}
+```
+
+### Compiling Your Program
+
+```bash
+# Using pkg-config
+gcc -o myprogram myprogram.c $(pkg-config --cflags --libs leptris)
+
+# Or manually
+gcc -o myprogram myprogram.c -I/usr/local/include -L/usr/local/lib -lleptris -lm
+```
+
+## What is Leptris?
+
+Leptris is a high-performance XML parser and XPath 1.0 engine implemented in pure C. It provides:
+
+- **Fast XML parsing**: Optimized for performance with zero-copy parsing
+- **DOM API**: Tree-based navigation and manipulation
+- **SAX API**: Event-driven parsing for large files
+- **XPath 1.0**: Full XPath 1.0 query support
+- **Small footprint**: Minimal memory usage with compact element structure
+
+## Key Features
+
+### Memory Management
+
+Leptris uses pool allocation for efficient memory management:
+
+```c
+LeptrisDocument doc = leptris_parse_string(xml, len, NULL);
+/* All DOM nodes are allocated from the document's pool */
+leptris_document_free(doc);  /* Frees all nodes at once */
+```
+
+### Zero-Copy Parsing
+
+When parsing from a string, Leptris can use the original buffer without copying:
+
+```c
+/* In-place parsing - Leptris takes ownership of the buffer */
+char* xml_copy = strdup(xml_string);
+LeptrisDocument doc = leptris_parse_string_inplace(xml_copy, strlen(xml_copy), NULL);
+/* Don't free xml_copy - leptris_document_free() will do it */
+leptris_document_free(doc);
+```
+
+### XPath Queries
+
+Execute XPath queries on your documents:
+
+```c
+LeptrisXPathResult* result = leptris_xpath_eval(doc, "//book[price > 30]", NULL);
+
+if (result && leptris_xpath_result_type(result) == LEPTRIS_XPATH_NODESET) {
+    int count = leptris_xpath_result_nodeset_count(result);
+    for (int i = 0; i < count; i++) {
+        LeptrisElement elem = leptris_xpath_result_nodeset_item(result, i);
+        printf("Found: %s\n", leptris_element_name(elem));
+    }
+}
+
+leptris_xpath_result_free(result);
+```
+
+## Next Steps
+
+- **Building**: See [building.md](building.md) for compilation and installation instructions
+- **Parsing**: See the parsing guide for advanced parsing options
+- **XPath**: See the XPath query guide for XPath examples
+- **API Reference**: See `api/` directory for detailed API documentation
+
+## Error Handling
+
+Leptris uses status codes for error handling:
+
+```c
+const char* xml = "<root>...</root>";
+LeptrisStatus status;
+LeptrisDocument doc = leptris_parse_string(xml, strlen(xml), &status);
+
+if (status != LEPTRIS_OK) {
+    fprintf(stderr, "Parse error: %d\n", status);
+    return 1;
+}
+```
+
+Common status codes:
+- `LEPTRIS_OK` (0) - Success
+- `LEPTRIS_ERROR_MEMORY` (-1) - Memory allocation failed
+- `LEPTRIS_ERROR_PARSE` (-2) - XML syntax error
+- `LEPTRIS_ERROR_NULL_ARG` (-4) - NULL argument passed
+- `LEPTRIS_ERROR_IO` (-7) - I/O error
+
+## Thread Safety
+
+Leptris is thread-safe with the following rules:
+
+- Multiple threads can parse different documents simultaneously
+- Multiple threads can query different documents with XPath simultaneously
+- A document should not be modified while being accessed from multiple threads
+- Each document should be freed by the same thread that created it