leptris 1.9.199.0-arm-linux

data/CLAUDE.md

@@ -0,0 +1,115 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+`leptris-ruby` is the official Ruby binding for `libleptris`
+(https://github.com/leptris/leptris), a pure-C99 XML 1.0 parser with a
+W3C-conformant XPath 1.0 engine (438/438 on the W3C suite), full SAX,
+pull parsing, and C14N. The binding is **FFI-based** (no C extension,
+no compilation at install) and ships **precompiled platform gems**
+with the shared library vendored inside: x86_64/aarch64-linux (glibc
+and musl), x86_64/arm64-darwin, x64-mingw32/ucrt, aarch64-mingw-ucrt,
+plus the pure-Ruby fallback gem.
+
+Version lockstep: the gem version is
+`{libleptris full semver}.{binding patch}` — gem `1.9.76.0` pairs
+with libleptris `1.9.76`; binding-only changes bump the fourth
+segment (`1.9.76.1`), an upstream adoption moves to `{C}.0`. A C
+release means one PR carrying version.rb + the Rakefile
+`LIBLEPTRIS_VERSION` pin + the CHANGELOG entry, then the release
+workflow (`next_version={C}.0`).
+
+## Commands
+
+```bash
+bundle exec rake compile   # build libleptris (pinned tarball) into lib/
+bundle exec rspec          # full suite (uses the vendored library)
+bundle exec rspec spec/xml/xpath_spec.rb:42   # one example
+bundle exec rake gem:native:arm64-darwin      # platform gem
+```
+
+`LEPTRIS_LIB_PATH=/path/to/libleptris.dylib bundle exec rspec` runs
+against an arbitrary build (e.g. a libleptris checkout under test).
+
+## Architecture
+
+The C DOM is the single source of truth; Ruby objects are thin FFI
+handles. One Ruby method = one FFI call wherever possible.
+
+```
+lib/leptris.rb                — Leptris::VERSION + eager FFI bootstrap
+lib/leptris/xml.rb            — autoload registry, error classes,
+                                Leptris::XML.parse / parse_html
+lib/leptris/xml/ffi.rb        — every public C declaration + seam
+                                helpers (check_status, read_owned_string,
+                                serialize_into_string, scratch buffers)
+lib/leptris/xml/document.rb   — the only C-memory owner (finalizer);
+                                factories; Document.copy_of: the single
+                                deep-copy seam behind Node#dup/Element#dup
+lib/leptris/xml/node.rb       — Node.wrap: the ONLY wrapper constructor
+                                (identity cache + type dispatch,
+                                ResultText for sequence items)
+lib/leptris/xml/element.rb    — attributes via the v1.1.0 iteration
+                                face; namespace= (nil-detach/rebind)
+lib/leptris/xml/result_text.rb — sequence/map/array result items
+                                (values captured at materialization)
+lib/leptris/xml/result_attr.rb  — attribute-node result items
+                                (name/value captured at materialization)
+lib/leptris/xml/iteration_scope.rb — owning context for iterparse
+                                elements (liveness, identity, memos)
+lib/leptris/xml/node_set.rb   — lazy XPath/XQuery results; batch fetch
+                                via get_nodes_ex; ResultText capture
+lib/leptris/xml/searchable.rb — xpath/css/at_*; result materialization
+lib/leptris/xml/evaluation_context.rb — receiver -> (document,
+                                context-node ptr) for the expression faces
+lib/leptris/xml/xpath.rb      — compiled expressions (parse once,
+                                eval many)
+lib/leptris/xml/xquery.rb     — compiled XQuery 1.0 core face
+lib/leptris/xml/xslt.rb       — compiled XSLT 1.0-3.0 face
+lib/leptris/xml/sax/          — callback SAX (streaming + DOM dispatch)
+lib/leptris/xml/pull.rb       — StAX-style pull parsing
+lib/leptris/xml/iterparse.rb  — bounded-memory element iteration
+lib/leptris/xml/serialization.rb — serialize/c14n (Document + Element
+                                one-liners over this module)
+lib/leptris/xml/c_string_array.rb — NULL-terminated char** adapter
+lib/leptris/xml/css_to_xpath.rb   — minimal CSS translation
+```
+
+### Ownership and seams
+
+- `Document` owns C memory (explicit `#free` or GC finalizer; wrapper
+  cache is a strong Hash cleared on free). Every other class is a
+  borrowed handle valid while its Document lives.
+- All wrapper construction goes through `Node.wrap` — wrapper
+  identity (`doc.root.equal?(doc.root)`) is guaranteed by the
+  per-document cache.
+- Status checks go through `FFI.check_status`; C `char*` returns go
+  through `FFI.read_owned_string`; array wire format (both
+  directions) goes through `CStringArray`. Never hand-roll these.
+- The release workflow's publish loop is idempotent (already-published
+  gems are skipped).
+
+## Conventions
+
+- Autoload only — no `require_relative` or intra-library `require`
+  inside `lib/` (sanctioned exceptions, with reasons in-file:
+  `leptris/version` at the gem root and the eager FFI bootstrap).
+- No `instance_variable_set`/`_get` across objects; no `send` to
+  private methods; no `respond_to?` type checks (dispatch on types
+  with `is_a?`/`case`); specs use real documents, never doubles.
+- New C surface: attach in `ffi.rb`, sugar where it earns its keep,
+  specs against a locally built library, CHANGELOG, lockstep release.
+- All changes via PRs; no AI attribution; `git add` explicit paths.
+
+## Reference
+
+- Domain vocabulary: CONTEXT.md. Settled decisions: docs/adr/ —
+  check both before proposing refactors; they exist so reviews
+  stop re-deriving settled questions.
+- libleptris public headers (`src/include/leptris/*.h`) are the
+  contract; when symbols change, bump lockstep and run
+  `rake audit:symbols` (attached == exported on the vendored
+  library; fails listing both directions of drift).
+- Upstream issues worth tracking live at leptris/leptris.

data/CONTEXT.md

@@ -0,0 +1,39 @@
+# Domain glossary
+
+The vocabulary for talking about leptris-ruby. Architecture reviews
+use these names; see docs/adr/ for settled decisions.
+
+**The DOM** — the C tree built by libleptris. Single source of
+truth: every Ruby object is a view over it, and one Ruby method is
+one FFI call wherever possible.
+
+**The seam** — `Leptris::XML::FFI`: every attach, every struct
+layout, every buffer protocol, and the encoding policy (UTF-8 on
+both faces: returns and callback params). ABI knowledge appears
+nowhere else (document.rb's finalizer is ownership machinery;
+CStringArray is the char** adapter).
+
+**Ownership / the borrowed handle** — Document owns C memory
+(explicit `#free` or GC finalizer); every other object (Node,
+Element, Text, Comment, CDATA, PI, Attr, DocumentFragment, DocType)
+is a handle borrowed for its document's lifetime. Mutations raise
+ReadOnlyError on readonly documents; use of a handle after `#free`
+raises UseAfterFreeError.
+
+**Wrapper identity** — `Node.wrap` is the only wrapper constructor;
+the per-document strong cache makes the same C node always yield the
+same Ruby object (`doc.root.equal?(doc.root)`).
+
+**The readonly contract** — `readonly: true` makes reads memoizable
+because they cannot go stale; every read method follows the same
+three-line pattern (return memo → compute → store memo). Mutations
+are refused; detached factories still work.
+
+**Lockstep** — the gem's major.minor tracks libleptris; a C release
+is one PR (version.rb + Rakefile pin + CHANGELOG) then the release
+workflow; ffi.rb mirrors the public header so the attached-vs-
+exported audit (`nm -gU`) catches drift.
+
+**The recover mode** — `recover: true` parses return an empty
+document with the failure recorded on the thread-global last error
+(+ position), instead of raising ParseError.

data/LICENSE.md

@@ -0,0 +1,33 @@
+Licenses & Copyright
+====================
+
+This license file adheres to the formatting guidelines of
+[readable-licenses](https://github.com/nevir/readable-licenses).
+
+
+Ribose's BSD 2-Clause License
+-----------------------------
+
+Copyright (c) 2025, [Ribose Inc](https://www.ribose.com).
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1.  Redistributions of source code must retain the above copyright notice,
+    this list of conditions and the following disclaimer.
+
+2.  Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation
+    and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.