moxml 0.1.26 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d829252809a02c146a09b8458ec5d9a297e5a31e91e6b04b6b6eda27a31e30a9
-  data.tar.gz: '09018d566262901ac5fe3fd864cd80e52dfe05f449e5b9e03054624044cab1af'
+  metadata.gz: 1e82117ebd56032bed4f9edffbb2714dec306b7bec52999193ef69fe62835ab9
+  data.tar.gz: 824fb9a07952249c2c97e650d5610d90c53ee23f279980aa5987e2a53922d74a
 SHA512:
-  metadata.gz: 56cc005125bd3953a3e40f2867ef76f4bd2ea4823e3363904ff20330e67d62740ae26c444b10d6706d66d4c7b0f38ba4805e957cfbf6cb4cdf413a6480eefd03
-  data.tar.gz: 58ec645d3a117ecd8ad275705fc03a345da7b52485b8119e8e0c0ebb12611c36dc01a12600b4871db050a23c7ac93d04b77632499307b94b5f7bb6000ccf366b
+  metadata.gz: 845a7de92860b25e68353e14efee1cc0015abfdc5a32f526b0baf1c45870e2966c1db6560eb45267a2fd0beab62936063493ac559fcca4317feffdcd0e54042a
+  data.tar.gz: 8242097334c0d1287bcc5c61658042e095ca1a34e375ff034c1504b9607f272937d62bd3ded2c439f45e7d6ae71ea58d86f5af37992858ab9a5fbadbe31fe738

data/.github/workflows/windows.yml

@@ -0,0 +1,62 @@
+name: windows
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  adapters:
+    name: Adapter specs on Windows (libxml)
+    runs-on: windows-latest
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: "recursive"
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: false
+
+      - name: Install libxml2 and build tools via MSYS2
+        shell: cmd
+        run: |
+          C:\msys64\usr\bin\pacman.exe -S --needed --noconfirm ^
+            mingw-w64-ucrt-x86_64-libxml2 ^
+            mingw-w64-ucrt-x86_64-libiconv ^
+            mingw-w64-ucrt-x86_64-zlib ^
+            mingw-w64-ucrt-x86_64-ragel ^
+            mingw-w64-ucrt-x86_64-make ^
+            mingw-w64-ucrt-x86_64-gcc
+
+      - name: Put MSYS2 UCRT64 toolchain on PATH
+        shell: pwsh
+        run: |
+          "PATH=C:\msys64\ucrt64\bin;C:\msys64\usr\bin;$env:PATH" >> $env:GITHUB_ENV
+
+      - name: Configure libxml-ruby build
+        shell: pwsh
+        run: |
+          bundle config build.libxml-ruby --with-xml2-include=C:/msys64/ucrt64/include/libxml2 --with-xml2-lib=C:/msys64/ucrt64/lib --with-iconv-include=C:/msys64/ucrt64/include --with-iconv-lib=C:/msys64/ucrt64/lib
+
+      - name: Generate ragel / ruby-ll outputs in vendored forks
+        shell: pwsh
+        run: |
+          gem install ruby-ll --no-document
+          rake vendor:prepare
+
+      - name: Install dependencies
+        run: bundle install --jobs 4
+
+      - name: Compile vendored native extensions
+        run: bundle exec rake vendor:compile
+
+      - name: Run adapter specs
+        run: bundle exec rake spec:adapter

data/Gemfile

@@ -9,6 +9,7 @@ gemspec
 gem "benchmark"
 gem "benchmark-ips"
 gem "get_process_mem"
+gem "leptris", "~> 1.1"
 gem "libxml-ruby", "~> 5.0"
 gem "nokogiri", "~> 1.18"
 gem "openssl", "~> 3.0"
@@ -30,7 +31,8 @@ gem "rubocop-performance"
 gem "rubocop-rake"
 gem "rubocop-rspec"
 gem "simplecov", require: false
-gem "stackprof"
+# stackprof relies on POSIX signals (SIGPROF/sigaction) unavailable on Windows
+gem "stackprof" unless Gem.win_platform?
 gem "tempfile"
 
 # Needed by get_process_mem on Windows

data/README.adoc

@@ -47,12 +47,21 @@ LibXML:: https://github.com/xml4r/libxml-ruby[libxml-ruby], Ruby bindings
 for the performant https://github.com/GNOME/libxml2[libxml2] C library.
 Alternative to Nokogiri with similar performance characteristics.
 
+Leptris:: https://github.com/leptris/leptris[Leptris], a pure-C99 XML 1.0
+parser with a W3C-conformant XPath 1.0 engine, consumed through the
+https://github.com/leptris/leptris-ruby[leptris-ruby] FFI binding
+(precompiled platform gems — no compilation at install). Fastest on
+every measured operation; requires leptris >= 1.2 for programmatic
+document construction.
+
 ==== Default adapter selection
 
 When no adapter is explicitly specified, Moxml selects one automatically based on
 the runtime environment:
 
 . If running on Opal (`RUBY_ENGINE == "opal"`), Oga is used (pure Ruby, no C extensions)
+. Otherwise, if the installed leptris gem supports programmatic document
+  construction (`Leptris::XML::Document.create`, leptris >= 1.2), Leptris is used
 . Otherwise, Moxml detects already-loaded XML libraries in this order:
   .. Nokogiri
   .. Ox
@@ -63,7 +72,7 @@ the runtime environment:
 ----
 # Automatic detection — picks the best available adapter
 ctx = Moxml.new
-ctx.config.adapter_name  # => :nokogiri (or :oga on Opal)
+ctx.config.adapter_name  # => :leptris (leptris >= 1.2), :nokogiri otherwise, :oga on Opal
 
 # Explicit override — always takes precedence
 ctx = Moxml.new(:ox)
@@ -80,9 +89,9 @@ The following table summarizes the features supported by each library.
 NOTE: The checkmarks indicate support for the feature, while the footnotes
 provide additional context for specific features.
 
-[cols="1,1,1,1,1,3"]
+[cols="1,1,1,1,1,1,1,3"]
 |===
-|Feature |Nokogiri |Oga |REXML |LibXML |Ox |HeadedOx
+|Feature |Nokogiri |Oga |REXML |LibXML |Ox |HeadedOx |Leptris
 
 |Parsing, serializing
 | ✅
@@ -91,6 +100,7 @@ provide additional context for specific features.
 | ✅
 | ✅
 | ✅
+| ✅
 
 |SAX parsing
 | ✅ Full (10/10 events)
@@ -99,6 +109,7 @@ provide additional context for specific features.
 | ✅ Full (10/10 events)
 | ⚠️ Core (4/10 events) See NOTE 7.
 | ⚠️ Core (4/10 events) See NOTE 7.
+| ✅ Full See NOTE 8.
 
 |Node manipulation
 | ✅
@@ -107,6 +118,7 @@ provide additional context for specific features.
 | ✅
 | ✅ See NOTE 1.
 | ✅ See NOTE 1.
+| ✅
 
 |Basic XPath
 | ✅
@@ -115,6 +127,8 @@ provide additional context for specific features.
 | ✅
 | Uses Ox-specific API `locate`. See NOTE 2.
 | ✅ Full XPath 1.0. See NOTE 3.
+| ✅ Full XPath 1.0 via Moxml's Ruby engine. See NOTE 8.
+
 
 |XPath with namespaces
 | ✅
@@ -123,6 +137,7 @@ provide additional context for specific features.
 | ✅
 | Uses Ox-specific API `locate`. See NOTE 2.
 | ⚠️ Basic. See NOTE 3.
+| ✅ Full See NOTE 8.
 
 |===
 
@@ -139,15 +154,23 @@ NOTE: Ox/HeadedOx SAX: Only core events supported (start_element, end_element,
 characters, errors). No separate CDATA, comment, or processing instruction
 events.
 
+NOTE: Leptris: XPath is evaluated by Moxml's pure-Ruby XPath 1.0 engine
+(same as HeadedOx) rather than libleptris's native engine, because the
+native engine does not resolve expression prefixes against
+document-declared namespaces. XML declarations, programmatic DOCTYPEs,
+and entity references are value objects stored via NativeAttachment —
+libleptris has no first-class nodes for them.
+
 == Adapter comparison
 
 === Feature compatibility matrix
 
-[cols="3,1,1,1,1,1,1", options="header"]
+[cols="3,1,1,1,1,1,1,1", options="header"]
 |===
-| Feature/Operation | Nokogiri | Oga | REXML | LibXML | Ox | HeadedOx
+| Feature/Operation | Nokogiri | Oga | REXML | LibXML | Ox | HeadedOx | Leptris
 
 | *Core Operations*
+
 |
 |
 |
@@ -162,6 +185,7 @@ events.
 | ✅ Full
 | ✅ Full
 | ✅ Full
+| ✅ Full
 
 | Parse XML file/IO
 | ✅ Full
@@ -170,6 +194,7 @@ events.
 | ✅ Full
 | ✅ Full
 | ✅ Full
+| ✅ Full
 
 | Serialize to XML
 | ✅ Full
@@ -178,9 +203,12 @@ events.
 | ✅ Full
 | ✅ Full
 | ✅ Full
+| ✅ Full
 
 | *Element Operations*
+
 |
+ 
 |
 |
 |
@@ -194,6 +222,7 @@ events.
 | ✅ Full
 | ✅ Full
 | ✅ Full
+| ✅ Full
 
 | Get/set attributes
 | ✅ Full
@@ -202,6 +231,7 @@ events.
 | ✅ Full
 | ✅ Full
 | ✅ Full
+| ✅ Full
 
 | Add/remove children
 | ✅ Full
@@ -210,6 +240,7 @@ events.
 | ✅ Full
 | ✅ Full
 | ✅ Full
+| ✅ Full
 
 | Replace nodes
 | ✅ Full
@@ -218,9 +249,12 @@ events.
 | ✅ Full
 | ⚠️ Limited^1^
 | ⚠️ Limited^1^
+| ✅ Full
 
 | *Namespace Operations*
+
 |
+ 
 |
 |
 |
@@ -234,6 +268,7 @@ events.
 | ✅ Full
 | ✅ Full
 | ✅ Full
+| ✅ Full
 
 | Default namespaces
 | ✅ Full
@@ -242,6 +277,7 @@ events.
 | ✅ Full
 | ⚠️ Basic
 | ⚠️ Basic
+| ✅ Full
 
 | Namespace inheritance
 | ✅ Full
@@ -250,6 +286,7 @@ events.
 | ✅ Full
 | ❌ None
 | ❌ None^5^
+| ✅ Full
 
 | Namespaced attributes
 | ✅ Full
@@ -258,9 +295,12 @@ events.
 | ✅ Full
 | ⚠️ Limited
 | ⚠️ Limited^5^
+| ✅ Full
 
 | *XPath Queries*
+
 |
+ 
 |
 |
 |
@@ -274,6 +314,7 @@ events.
 | ✅ Full
 | ✅ Full
 | ✅ Full
+| ✅ Full
 
 | Attribute predicates (`[@id]`)
 | ✅ Full
@@ -282,6 +323,7 @@ events.
 | ✅ Full
 | ⚠️ Existence only^2^
 | ✅ Full
+| ✅ Full
 
 | Attribute values (`[@id='123']`)
 | ✅ Full
@@ -290,6 +332,7 @@ events.
 | ✅ Full
 | ❌ None^3^
 | ✅ Full
+| ✅ Full
 
 | Logical operators (`[@a and @b]`)
 | ✅ Full
@@ -298,6 +341,7 @@ events.
 | ✅ Full
 | ❌ None
 | ✅ Full
+| ✅ Full
 
 | Position predicates (`[1]`, `[last()]`)
 | ✅ Full
@@ -306,6 +350,7 @@ events.
 | ✅ Full
 | ❌ None
 | ✅ Full
+| ✅ Full
 
 | Text predicates (`[text()='x']`)
 | ✅ Full
@@ -314,6 +359,7 @@ events.
 | ✅ Full
 | ❌ None
 | ✅ Full
+| ✅ Full
 
 | Namespace-aware queries
 | ✅ Full
@@ -322,6 +368,7 @@ events.
 | ✅ Full
 | ❌ None
 | ⚠️ Basic^5^
+| ✅ Full
 
 | Parent axis (`..`)
 | ✅ Full
@@ -330,6 +377,7 @@ events.
 | ✅ Full
 | ❌ None
 | ✅ Full
+| ✅ Full
 
 | Sibling axes
 | ✅ Full
@@ -338,6 +386,7 @@ events.
 | ✅ Full
 | ❌ None
 | ❌ None^5^
+| ✅ Full
 
 | XPath functions (`count()`, etc.)
 | ✅ Full
@@ -346,9 +395,12 @@ events.
 | ✅ Full
 | ❌ None
 | ✅ All 27
+| ✅ All 27
 
 | *Special Content*
+
 |
+ 
 |
 |
 |
@@ -362,6 +414,7 @@ events.
 | ✅ Full
 | ✅ Full
 | ✅ Full
+| ✅ Full
 
 | Comments
 | ✅ Full
@@ -370,6 +423,7 @@ events.
 | ✅ Full
 | ✅ Full
 | ✅ Full
+| ✅ Full
 
 | Processing instructions
 | ✅ Full
@@ -378,6 +432,7 @@ events.
 | ✅ Full
 | ✅ Full
 | ✅ Full
+| ✅ Full
 
 | DOCTYPE declarations
 | ✅ Full
@@ -386,9 +441,12 @@ events.
 | ✅ Full
 | ✅ Full
 | ✅ Full
+| ⚠️ Value-object sidecar^8^
 
 | *Performance*
+
 |
+ 
 |
 |
 |
@@ -402,6 +460,7 @@ events.
 | Fast
 | Very Fast
 | Very Fast
+| Fastest
 
 | Serialize speed
 | Fast
@@ -410,6 +469,7 @@ events.
 | Medium
 | Very Fast
 | Very Fast
+| Very Fast
 
 | Memory usage
 | Good
@@ -418,6 +478,7 @@ events.
 | Good
 | Excellent
 | Excellent
+| Excellent
 
 | Thread safety
 | ✅ Yes
@@ -426,13 +487,15 @@ events.
 | ✅ Yes
 | ✅ Yes
 | ✅ Yes
+| ⚠️ One doc per thread^8^
 |===
 +
 ^1^ Ox/HeadedOx: Text node replacement may fail in some cases due to internal node structure +
 ^2^ Ox: `//book[@id]` works (returns all book elements), but doesn't filter by attribute existence +
 ^3^ HeadedOx: Full XPath 1.0 with all 27 functions and 6 axes. Pure Ruby XPath engine on Ox's C parser. 99.20% pass rate. See link:docs/headed-ox.adoc[] +
 ^4^ Ox: Use `.find { |el| el["id"] == "123" }` instead of XPath attribute value predicates +
-^5^ HeadedOx limitations: Namespace introspection and 7 axes not implemented. See link:docs/HEADED_OX_LIMITATIONS.md[]
+^5^ HeadedOx limitations: Namespace introspection and 7 axes not implemented. See link:docs/HEADED_OX_LIMITATIONS.md[] +
+^8^ Leptris: XPath runs through Moxml's pure-Ruby XPath 1.0 engine (the native C engine does not resolve expression prefixes against document namespaces); DOCTYPEs and XML declarations are value objects stored via NativeAttachment; libleptris documents are not thread-safe — one document per thread
 
 === Adapter selection guide
 

data/lib/compat/opal/moxml_boot.rb

@@ -24,6 +24,9 @@ require "moxml/namespace"
 require "moxml/doctype"
 require "moxml/entity_reference"
 require "moxml/entity_registry"
+require "moxml/entity"
+require "moxml/entity/reference"
+require "moxml/xml_emitter"
 require "moxml/adapter"
 require "moxml/adapter/base"
 require "moxml/adapter/customized_rexml"
@@ -36,6 +39,8 @@ require "moxml/sax/block_handler"
 require "moxml/sax/namespace_splitter"
 require "moxml/adapter/rexml"
 require "moxml/adapter/customized_oga"
+require "moxml/adapter/customized_oga/entity_decoder"
+require "moxml/adapter/customized_oga/raw_value_override"
 require "moxml/adapter/customized_oga/xml_declaration"
 require "moxml/adapter/customized_oga/xml_generator"
 require "moxml/adapter/oga"

data/lib/moxml/adapter/base.rb

@@ -5,62 +5,29 @@ module Moxml
     class Base
       # include XmlUtils
 
-      # Entity marker for adapters that resolve entities during parsing.
-      # U+FFFC (Object Replacement Character) + U+FEFF (BOM) is a two-character
-      # sentinel chosen because this exact sequence followed by a valid entity
-      # name pattern is vanishingly unlikely in real XML content.
-      # Non-standard entities like © are converted to this marker before
-      # parsing, then restored during serialization.
-      # Standard XML entities (& < > " ') are NOT converted.
-      ENTITY_MARKER = "\u{FFFC}\u{FEFF}"
-      ENTITY_NAME_PATTERN = "[a-zA-Z_][\\w.:-]*"
-      ENTITY_NAME_RE = /&(#{ENTITY_NAME_PATTERN});/
-      ENTITY_MARKER_RE = /\u{FFFC}\u{FEFF}(#{ENTITY_NAME_PATTERN});/
-      SERIALIZED_ENTITY_MARKER_RE = /(#{ENTITY_NAME_PATTERN});/
-      STANDARD_ENTITIES = %w[amp lt gt quot apos].freeze
+      # Entity round-trip pipeline lives in Moxml::Entity; these
+      # constants and methods stay on the adapter protocol so
+      # adapters and wrappers keep their calling convention.
+      ENTITY_MARKER = Entity::MARKER
+      ENTITY_NAME_PATTERN = Entity::NAME_PATTERN
+      ENTITY_NAME_RE = Entity::NAME_RE
+      ENTITY_MARKER_RE = Entity::MARKER_RE
+      SERIALIZED_ENTITY_MARKER_RE = Entity::SERIALIZED_MARKER_RE
+      STANDARD_ENTITIES = Entity::STANDARD_ENTITIES
 
       class << self
         include XmlUtils
 
-        # Replace non-standard entity references with markers before parsing.
-        # Always returns a UTF-8 encoded string.
         def preprocess_entities(xml)
-          return "" if xml.nil?
-
-          str = if xml.encoding == Encoding::BINARY
-                  # Binary strings are assumed to be UTF-8. If the bytes are
-                  # not valid UTF-8, fall back to encoding as UTF-8 with
-                  # replacement to avoid raising on gsub.
-                  dup = xml.dup.force_encoding("UTF-8")
-                  if dup.valid_encoding?
-                    dup
-                  else
-                    xml.dup.encode("UTF-8",
-                                   "ASCII-8BIT", invalid: :replace, undef: :replace)
-                  end
-                elsif xml.encoding == Encoding::UTF_8
-                  xml
-                else
-                  xml.encode("UTF-8")
-                end
-          # Fast path: no `&` means no entity references to mark — skip
-          # the regex scan and string allocation entirely. The vast
-          # majority of XML payloads contain no entity references.
-          return str unless str.include?("&")
-
-          str.gsub(ENTITY_NAME_RE) do |match|
-            STANDARD_ENTITIES.include?(::Regexp.last_match(1)) ? match : "#{ENTITY_MARKER}#{::Regexp.last_match(1)};"
-          end
+          Entity.preprocess_entities(xml)
         end
 
-        # Restore entity markers back to named entity references.
-        def restore_entities(text)
-          return text unless text.is_a?(String)
+        def decode_entities(text)
+          Entity.decode_entities(text)
+        end
 
-          # Force UTF-8 encoding since markers are UTF-8 characters
-          str = text.encoding == Encoding::UTF_8 ? text : text.dup.force_encoding("UTF-8")
-          result = str.gsub(ENTITY_MARKER_RE, '&\1;')
-          result.gsub(SERIALIZED_ENTITY_MARKER_RE, '&\1;')
+        def restore_entities(text)
+          Entity.restore_entities(text)
         end
 
         def set_root(_doc, _element)
@@ -71,7 +38,7 @@ module Moxml
           )
         end
 
-        def parse(_xml, _options = {})
+        def parse(_xml, _options = {}, _context = nil)
           raise Moxml::NotImplementedError.new(
             "parse not implemented",
             feature: "parse",
@@ -172,12 +139,35 @@ namespace_validation_mode: :strict)
           create_native_entity_reference(name)
         end
 
+        # Mutation return contract: protocol methods that may change
+        # which native a wrapper tracks (set_attribute_name,
+        # set_namespace, set_attribute_value) always return the native
+        # the wrapper must keep tracking — the same object when
+        # mutated in place, a fresh object when the adapter recreates
+        # the node.
         def set_attribute_name(attribute, name)
           attribute.name = name
+          attribute
+        end
+
+        def set_namespace(_node, _namespace)
+          raise Moxml::NotImplementedError.new(
+            "set_namespace not implemented",
+            feature: "set_namespace",
+            adapter: name,
+          )
         end
 
         def set_attribute_value(attribute, value)
           attribute.value = value
+          attribute
+        end
+
+        # Remove a specific native attribute node from its owning
+        # element. Semantics (which attribute a name addresses) live
+        # in Moxml::AttributeResolver; this is the raw primitive.
+        def remove_attribute_native(attr)
+          attr.remove
         end
 
         def entity_reference_name(node)
@@ -212,6 +202,20 @@ namespace_validation_mode: :strict)
         # Called when a Declaration node is removed from a document.
         def remove_declaration(_native_doc); end
 
+        # Source line of a native node (1-based), or nil when the
+        # underlying backend does not track source positions.
+        # Adapters that track lines (Nokogiri, LibXML) override this.
+        def line_number(_node)
+          nil
+        end
+
+        # Local name of a native attribute node. Adapters whose natives
+        # carry qualified names override this to expose the local part;
+        # the wrapper composes the prefix.
+        def attribute_name(attr)
+          attr.name
+        end
+
         # Return the actual native node after an add_child operation.
         # Override for adapters where node identity may change (e.g., LibXML doc.root=).
         def actual_native(child_native, _parent_native)

data/lib/moxml/adapter/customized_leptris/declaration.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Moxml
+  module Adapter
+    module CustomizedLeptris
+      # Wrapper for an XML declaration. libleptris stores declaration
+      # data on the document struct (read-only, serialized via options)
+      # and has no first-class declaration node, so Moxml exposes this
+      # mutable value object instead.
+      class Declaration
+        attr_accessor :version, :encoding, :standalone, :parent_doc
+
+        def initialize(version = "1.0", encoding = "UTF-8", standalone = nil)
+          @version = version
+          @encoding = encoding
+          @standalone = standalone
+        end
+
+        def to_xml
+          XmlEmitter.declaration_xml(version, encoding, standalone)
+        end
+
+        def ==(other)
+          other.is_a?(self.class) &&
+            version == other.version &&
+            encoding == other.encoding &&
+            standalone == other.standalone
+        end
+      end
+    end
+  end
+end

data/lib/moxml/adapter/customized_leptris/doctype.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Moxml
+  module Adapter
+    module CustomizedLeptris
+      # Wrapper for a programmatic DOCTYPE. libleptris only parses
+      # DOCTYPEs from source; it has no API to create one, so Moxml
+      # stores this value object in the document's attachments.
+      class Doctype
+        attr_accessor :name, :external_id, :system_id, :parent_doc
+
+        def initialize(name, external_id = nil, system_id = nil)
+          @name = name
+          @external_id = external_id
+          @system_id = system_id
+        end
+
+        def to_xml
+          XmlEmitter.doctype_xml(name, external_id, system_id)
+        end
+
+        def ==(other)
+          other.is_a?(self.class) &&
+            name == other.name &&
+            external_id == other.external_id &&
+            system_id == other.system_id
+        end
+      end
+    end
+  end
+end

data/lib/moxml/adapter/customized_leptris/entity_reference.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Moxml
+  module Adapter
+    module CustomizedLeptris
+      # libleptris expands the five built-in entities at parse time
+      # and has no custom ones; the adapter carries entity references
+      # as Moxml::Entity::Reference values over marker-bearing text.
+      EntityReference = ::Moxml::Entity::Reference
+    end
+  end
+end