makiri 0.2.0 → 0.4.0

data/lib/makiri/xml/builder.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+module Makiri
+  module XML
+    # A Nokogiri-compatible DSL for building an XML document (or subtree) from
+    # scratch. It is a thin, pure-Ruby layer over the public construction surface
+    # (+XML::Document.new+, +Document#create_element+ / +#create_text_node+ /
+    # +#create_cdata+ / +#create_comment+, and +Node#add_child+); no C code is
+    # involved.
+    #
+    # @example Block-with-argument form (recommended)
+    #   builder = Makiri::XML::Builder.new do |xml|
+    #     xml.feed("xmlns" => "urn:a") do
+    #       xml.entry do
+    #         xml.title("Hello")
+    #       end
+    #     end
+    #   end
+    #   builder.to_xml
+    #
+    # @example instance_eval form (no block argument)
+    #   builder = Makiri::XML::Builder.new do
+    #     root { child("text") }
+    #   end
+    #
+    # An element is created by calling a method named after the tag. Trailing
+    # arguments follow the Nokogiri convention: a Hash sets attributes (including
+    # +xmlns+ / +xmlns:prefix+ namespace declarations), any other argument becomes
+    # the element's text content, and a block builds nested children.
+    #
+    # Tag names that collide with a Ruby/Kernel method (or with one of this
+    # builder's own helpers below - +text+, +cdata+, +comment+, +doc+, +parent+,
+    # +to_xml+, +to_s+) must be written with a trailing underscore, which is
+    # stripped: +xml.id_("9")+ produces +<id>9</id>+. This matches Nokogiri.
+    #
+    # A namespace prefix is selected for the next element with +[]+:
+    # +xml["dc"].title+ produces +<dc:title>+ (the prefix must be in scope, i.e.
+    # declared via an +"xmlns:dc"+ attribute on an ancestor or on the element
+    # itself, exactly as Makiri resolves prefixes at insertion time).
+    class Builder
+      # The document being built (a {Makiri::XML::Document}).
+      attr_reader :doc
+
+      # The node new children are currently appended to. While a nested block is
+      # running this is that block's element; otherwise it is {#doc}.
+      attr_reader :parent
+
+      # @param options [Hash] accepted for Nokogiri compatibility and ignored - a
+      #   Makiri document has no configurable options (it is always UTF-8).
+      # @param root [Makiri::XML::Node, nil] when given, build into this node:
+      #   top-level calls append to it and its document is used. (This is what
+      #   {.with} passes; mirrors +Nokogiri::XML::Builder.new(options, root)+.)
+      # @yield [self] when the block takes an argument; otherwise the block is
+      #   +instance_eval+'d against the builder.
+      def initialize(options = {}, root = nil, &block)
+        if root
+          @doc = root.document
+          @parent = root
+        else
+          @parent = @doc = Makiri::XML::Document.new
+        end
+        @ns_prefix = nil
+        @arity = nil
+        return unless block
+
+        run(&block)
+        @parent = @doc # like Nokogiri: after a build block, settle back at the document
+      end
+
+      # Build into an existing node: top-level calls append to +node+, using
+      # +node+'s document. Mirrors +Nokogiri::XML::Builder.with+.
+      #
+      # @param node [Makiri::XML::Node]
+      # @return [Builder]
+      def self.with(node, &block)
+        new({}, node, &block)
+      end
+
+      # Append a text node to the current parent.
+      # @return [NodeBuilder]
+      def text(string)
+        insert(@doc.create_text_node(string.to_s))
+      end
+
+      # Append a CDATA section to the current parent.
+      # @return [NodeBuilder]
+      def cdata(string)
+        insert(@doc.create_cdata(string.to_s))
+      end
+
+      # Append a comment node to the current parent.
+      # @return [NodeBuilder]
+      def comment(string)
+        insert(@doc.create_comment(string.to_s))
+      end
+
+      # Parse +string+ as an XML fragment (against the document's in-scope
+      # namespaces) and append its children to the current parent. The Builder
+      # analogue of +Nokogiri::XML::Builder#<<+.
+      # @return [self]
+      def <<(string)
+        @doc.fragment(string).children.to_a.each { |child| insert(child) }
+        self
+      end
+
+      # Select the namespace prefix for the next element (consumed by the next
+      # tag method). Returns self so it reads as +xml["dc"].title+.
+      # @return [self]
+      def [](ns_prefix)
+        @ns_prefix = ns_prefix.to_s
+        self
+      end
+
+      # Serialize the built document. Forwards to {Document#to_xml} (so +pretty:+
+      # works).
+      def to_xml(...)
+        @doc.to_xml(...)
+      end
+      alias_method :to_s, :to_xml
+
+      # Any other method name is a tag: create the element and insert it.
+      def method_missing(name, *args, &block)
+        tag = name.to_s.sub(/[_!]\z/, "")
+        prefix = @ns_prefix
+        if prefix
+          tag = "#{prefix}:#{tag}"
+          @ns_prefix = nil
+        end
+        node = create_element(tag, args)
+        check_prefix_defined!(node, prefix) if prefix
+        insert(node, &block)
+      end
+
+      # Tag methods are open-ended, so report respond_to? truthfully for them
+      # (anything that is not already a real method is a candidate tag).
+      def respond_to_missing?(_name, _include_private = false)
+        true
+      end
+
+      private
+
+      # Translate the Nokogiri-style trailing arguments (a Hash is attributes,
+      # anything else is text content) into a {Document#create_element} call.
+      def create_element(tag, args)
+        text = nil
+        attributes = nil
+        args.each do |arg|
+          if arg.is_a?(Hash)
+            attributes = attributes ? attributes.merge(arg) : arg
+          else
+            text = arg
+          end
+        end
+        cargs = []
+        cargs << text.to_s unless text.nil?
+        cargs << attributes unless attributes.nil?
+        @doc.create_element(tag, *cargs)
+      end
+
+      # Raise like Nokogiri when a prefix selected via +[]+ resolves nowhere: not
+      # in scope at the insertion point (+@parent+ and its ancestors) and not
+      # self-declared on +node+ itself (e.g. +xml["foo"].root("xmlns:foo" => ...)+).
+      def check_prefix_defined!(node, prefix)
+        return if @parent.respond_to?(:namespaces) && @parent.namespaces.key?("xmlns:#{prefix}")
+        return if node.namespace_definitions.any? { |ns| ns.prefix == prefix }
+
+        raise ArgumentError, "Namespace #{prefix} has not been defined"
+      end
+
+      # Append +node+ to the current parent, then, if a block is given, descend
+      # into the inserted node for the duration of that block. Returns a
+      # {NodeBuilder} over the inserted node (which may be an imported copy, e.g.
+      # from a fragment), so the Nokogiri attribute-shortcut chain works.
+      def insert(node, &block)
+        node = @parent.add_child(node)
+        descend(node, &block) if block
+        NodeBuilder.new(node, self)
+      end
+
+      # Run +block+ with +node+ as the current parent, restoring the previous
+      # parent afterward (even if the block raises) and returning the block's
+      # value. The single place the parent is pushed/popped - shared by #insert and
+      # NodeBuilder's nested-block chain, so neither manipulates the parent state
+      # directly.
+      def descend(node, &block)
+        previous = @parent
+        @parent = node
+        begin
+          run(&block)
+        ensure
+          @parent = previous
+        end
+      end
+
+      # Run a DSL block, choosing instance_eval vs yield once (from the first
+      # block seen), the same way Nokogiri does, so the form is consistent
+      # throughout a build.
+      def run(&block)
+        @arity = block.arity if @arity.nil?
+        if @arity <= 0
+          instance_eval(&block)
+        else
+          block.call(self)
+        end
+      end
+
+      # The value returned by each element call, wrapping the just-inserted node
+      # so attributes can be added with the Nokogiri terse-chain syntax:
+      #
+      #   xml.object.classy.thing!   # => <object class="classy" id="thing"/>
+      #
+      # A plain method name appends to the +class+ attribute, +name!+ sets +id+
+      # (and content if given), +name=+ sets that attribute, a trailing Hash adds
+      # each key as an attribute, and a block descends into the node. +[]+ / +[]=+
+      # read and write attributes directly. Semantics mirror
+      # +Nokogiri::XML::Builder::NodeBuilder+.
+      class NodeBuilder
+        def initialize(node, doc_builder)
+          @node = node
+          @doc_builder = doc_builder
+        end
+
+        # Read an attribute of the wrapped node.
+        def [](key)
+          @node[key]
+        end
+
+        # Write an attribute of the wrapped node.
+        def []=(key, value)
+          @node[key] = value
+        end
+
+        def method_missing(method, *args, &block)
+          opts = args.last.is_a?(Hash) ? args.pop : {}
+          case method.to_s
+          when /\A(.*)!\z/
+            @node["id"] = Regexp.last_match(1)
+            @node.content = args.first if args.first
+          when /\A(.*)=\z/
+            @node[Regexp.last_match(1)] = args.first
+          else
+            @node["class"] = ((@node["class"] || "").split(/\s/) + [method.to_s]).join(" ")
+            @node.content = args.first if args.first
+          end
+
+          opts.each do |key, value|
+            @node[key.to_s] = ((@node[key.to_s] || "").split(/\s/) + [value]).join(" ")
+          end
+
+          # Descend into this node for a nested block via the builder's own parent
+          # stack (with its ensure-based restore), rather than re-rooting it by hand.
+          return @doc_builder.send(:descend, @node, &block) if block
+
+          self
+        end
+
+        def respond_to_missing?(_name, _include_private = false)
+          true
+        end
+      end
+    end
+  end
+end

data/lib/makiri/xml/document.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Makiri
+  module XML
+    # XML-specific document conveniences. The XML node leaves and the document
+    # itself are defined in C (ext/makiri/glue/ruby_xml*.c); construction sugar
+    # that is pure composition over the public surface lives here, not on the
+    # abstract Makiri::Document (which carries no construction).
+    class Document
+      # Set (or replace) the document's root element: with an existing root it
+      # replaces that root, otherwise it appends one (subject to the single-root
+      # rule). Pure composition over {Node#replace} / {Node#add_child};
+      # Nokogiri-compatible. XML only - an HTML5 document has a fixed
+      # html/head/body structure, so a free-form root is not meaningful there.
+      #
+      # @param node [Makiri::XML::Element]
+      # @return [Makiri::XML::Element] the node
+      def root=(node)
+        r = root
+        r ? r.replace(node) : add_child(node)
+      end
+    end
+  end
+end

data/lib/makiri/xml/node_methods.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Makiri
+  module XML
+    # Ruby additions over the C-defined XML node readers, mirroring
+    # Makiri::HTML::NodeMethods so the XML node surface matches the HTML one for
+    # the methods consumers (e.g. Dommy) rely on. Each is guarded with
+    # `method_defined?` so a future native implementation on this module takes
+    # precedence rather than being shadowed.
+    module NodeMethods
+      # Element ancestors, nearest first, excluding self (element nodes only) —
+      # matching Makiri::HTML's #ancestors.
+      unless method_defined?(:ancestors)
+        def ancestors
+          out = []
+          node = parent
+          while node
+            out << node if node.node_type == 1
+            node = node.respond_to?(:parent) ? node.parent : nil
+          end
+          out
+        end
+      end
+
+      # Whether an attribute with the given qualified name is present
+      # (case-sensitive, per XML).
+      unless method_defined?(:key?)
+        def key?(name)
+          wanted = name.to_s
+          attribute_nodes.any? { |attr| attr.name == wanted }
+        end
+      end
+
+      alias_method :has_attribute?, :key? unless method_defined?(:has_attribute?)
+
+      # CSS selector queries over XML, lowered to the native XPath engine (so
+      # matching is case-sensitive and namespace-aware, unlike a Lexbor HTML
+      # matcher). Nokogiri-compatible namespaces: the document's in-scope
+      # declarations are collected automatically (a bare type selector binds to
+      # the default namespace), and an optional +ns+ hash of {prefix => uri}
+      # supplements/overrides them.
+      #
+      #   doc.css("entry")               # default-namespace bound (Atom/RSS just work)
+      #   doc.css("a|entry", "a" => uri) # explicit prefix
+      #
+      # @return [Makiri::NodeSet]
+      def css(selector, ns = nil)
+        _css(selector.to_s, _css_namespaces(ns))
+      end
+
+      # First descendant matching +selector+, or nil. @return [Makiri::Node, nil]
+      def at_css(selector, ns = nil)
+        _at_css(selector.to_s, _css_namespaces(ns))
+      end
+
+      # Whether this node matches +selector+ (full selector, combinators included).
+      # @return [Boolean]
+      def matches?(selector, ns = nil)
+        _css_matches(selector.to_s, _css_namespaces(ns))
+      end
+
+      private
+
+      # Build the {prefix => uri} hash the C primitives register. Matching
+      # Nokogiri: with NO explicit namespaces the document's own declarations are
+      # collected (the default namespace under the synthetic prefix "xmlns", so a
+      # bare type selector binds to it - the RSS/Atom common case); but once the
+      # caller passes a namespaces hash, ONLY those prefixes are used and a bare
+      # selector resolves to no namespace (Nokogiri disables the default binding
+      # the moment an explicit map is given). Reading only the root's
+      # declarations is O(root attributes), not the whole-document walk.
+      def _css_namespaces(user)
+        return user.transform_keys(&:to_s).transform_values(&:to_s) if user && !user.empty?
+
+        reg = {}
+        root = document&.root
+        root&.namespace_definitions&.each do |ns|
+          reg[ns.prefix.nil? ? "xmlns" : ns.prefix] = ns.href
+        end
+        reg
+      end
+    end
+  end
+end

data/lib/makiri/xml.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Makiri
+  # XML-specific node leaves and document conveniences (§12), mirroring
+  # Makiri::HTML. The XML nodes and the document are defined in C
+  # (ext/makiri/glue/ruby_xml*.c); the per-class Ruby additions live in this
+  # namespace's files (xml/document.rb).
+  module XML
+  end
+end

data/lib/makiri/xpath_context.rb

@@ -16,7 +16,7 @@ module Makiri
   class XPathContext
     # +#evaluate+ is defined in C. It evaluates under the GVL (XPath never
     # releases it), so concurrent +evaluate+ / +register_*+ / +node=+ on the
-    # same context — and any tree mutation of the document being queried — are
+    # same context - and any tree mutation of the document being queried - are
     # serialised by the GVL and cannot corrupt memory.
 
     # Nokogiri-compatible name for {#register_namespace}.

data/lib/makiri.rb

@@ -15,11 +15,18 @@ end
 
 require_relative "makiri/node"
 require_relative "makiri/document"
+require_relative "makiri/html"
+require_relative "makiri/html/node_methods"
+require_relative "makiri/html/document"
+require_relative "makiri/xml"
+require_relative "makiri/xml/node_methods"
+require_relative "makiri/xml/document"
+require_relative "makiri/xml/builder"
 require_relative "makiri/element"
-require_relative "makiri/attribute"
+require_relative "makiri/attr"
 require_relative "makiri/text"
 require_relative "makiri/comment"
-require_relative "makiri/cdata"
+require_relative "makiri/cdata_section"
 require_relative "makiri/processing_instruction"
 require_relative "makiri/document_type"
 require_relative "makiri/document_fragment"
@@ -27,6 +34,7 @@ require_relative "makiri/node_set"
 require_relative "makiri/xpath_context"
 require_relative "makiri/xpath"
 require_relative "makiri/css"
+require_relative "makiri/compat_aliases"
 
 module Makiri
   # Base exception class for Makiri-specific errors.
@@ -35,13 +43,24 @@ module Makiri
   # Convenience constructor mirroring Nokogiri.
   #
   # @param source [String] HTML source (UTF-8).
-  # @return [Makiri::Document]
+  # @return [Makiri::HTML::Document]
   def self.HTML(source) # rubocop:disable Naming/MethodName
-    Document.parse(source)
+    HTML::Document.parse(source)
   end
 
   # Alias for {.HTML}.
   def self.parse(source)
-    Document.parse(source)
+    HTML::Document.parse(source)
+  end
+
+  # Convenience XML constructor mirroring Nokogiri::XML(source). A method named
+  # XML on the Makiri module, coexisting with the Makiri::XML constant (the
+  # module), as Nokogiri::XML does. Delegates to {Makiri::XML::Document.parse},
+  # exactly as {.HTML} delegates to {Makiri::HTML::Document.parse}.
+  #
+  # @param source [String, #read] XML source (its String encoding is honoured).
+  # @return [Makiri::XML::Document]
+  def self.XML(source, **opts) # rubocop:disable Naming/MethodName
+    XML::Document.parse(source, **opts)
   end
 end

data/script/build_native_gem.rb

@@ -24,7 +24,7 @@ root = File.expand_path("..", __dir__)
 spec = Gem::Specification.load(File.join(root, "makiri.gemspec"))
 
 libs = Dir[File.join(root, "lib", "makiri", "*", "makiri.{so,bundle}")].sort
-abort "no precompiled libraries found under lib/makiri/*/ — stage them first" if libs.empty?
+abort "no precompiled libraries found under lib/makiri/*/ - stage them first" if libs.empty?
 
 # Native gem: ship binaries, not the C sources or the vendored Lexbor tree, and
 # declare no extension so install never tries to compile.
@@ -34,7 +34,7 @@ spec.files = spec.files.reject { |f| f.start_with?("ext/", "vendor/") }
 spec.files += libs.map { |p| p.sub("#{root}/", "") }
 spec.files.uniq!
 
-# Bound the Ruby versions this binary gem serves — one subdir per ABI minor.
+# Bound the Ruby versions this binary gem serves - one subdir per ABI minor.
 abis = libs.map { |p| File.basename(File.dirname(p)) }.sort_by { |v| v.split(".").map(&:to_i) }
 lo_major, lo_minor = abis.first.split(".").map(&:to_i)
 hi_major, hi_minor = abis.last.split(".").map(&:to_i)