nokolexbor 0.6.4 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3615acd25f6233c5701c91d25ef6c94a73adf2de8433e2e1b6b3aa215f0581ab
-  data.tar.gz: ad3e9f8134a7f26924b2283a2ac10a8dfae2f5684dd650be5903faf069f595ef
+  metadata.gz: fb6fea4008f68e39df01fbc3920634bd747f6c6e58605876b4600b6037745d4a
+  data.tar.gz: 38f67c6e320e95d35a82db68f34b08e7103fa8d56e52fe6e59ebdeb266701c16
 SHA512:
-  metadata.gz: 2d84f341a6b3e1c4dcc8501ab9772e4376bc8c9acf2441753253c331ca381ff161c95cbb93f32568aada6ac03e3bedb01343bbc507d5201c468884f286008228
-  data.tar.gz: f8a85acb4fdd063714316490289bae356a731931aa8c4202a80f677b70d2f02258f69991e0d996cfaadf80dbcad8c505c61b4a6a91456514bbc972e0d7861148
+  metadata.gz: a44ba9da124b17e58ae2abc8c6e99cfab22edbdcdff5b07e9636838f28098a4716aa6f50cf7282c1f15fcbb0630b7bd5ef814b54cb7886dd75b16a864e496405
+  data.tar.gz: 40fcdc69521d2f985be5fa62addf3f4fd03ac577eeb66878f496dbc684fc3925ceddb9fa2f74a870188431c672b16394ccc6c58303caae6c6718af8e978bc967

data/lib/nokolexbor/builder.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Nokolexbor
+  # A DSL for programmatically building HTML documents.
+  #
+  # == No-arg block (instance_eval style) – tag names are called bare:
+  #
+  #   Nokolexbor do
+  #     body do
+  #       h1 'Hello world'
+  #       p 'This little p'
+  #       ul do
+  #         li 'Go to market'
+  #         li 'Go to bed'
+  #       end
+  #     end
+  #   end
+  #
+  # == Block-parameter style – tag names are called on the builder argument:
+  #
+  #   Nokolexbor::Builder.new do |b|
+  #     b.body do
+  #       b.h1 'Hello world'
+  #     end
+  #   end
+  #
+  # == Building into an existing node:
+  #
+  #   Nokolexbor::Builder.with(existing_node) do
+  #     span 'injected'
+  #   end
+  #
+  class Builder
+    # The Document used to create new nodes
+    attr_accessor :doc
+
+    # The node that currently receives new children
+    attr_accessor :parent
+
+    # Arity of the outermost block (drives instance_eval vs yield dispatch)
+    attr_accessor :arity
+
+    # A context object for use when the block has no arguments
+    attr_accessor :context
+
+    # Build into an existing +root+ node.
+    def self.with(root, &block)
+      new(root, &block)
+    end
+
+    # @param root [Node, nil]
+    #   When given, new nodes are appended under +root+ and +root.document+
+    #   is used as the owning document.  When omitted a fresh {Document} and
+    #   a {DocumentFragment} container are created.
+    def initialize(root = nil, &block)
+      if root
+        @doc    = root.document
+        @parent = root
+      else
+        @doc    = Document.new
+        @parent = DocumentFragment.new(@doc)
+      end
+
+      @context = nil
+      @arity   = nil
+
+      return unless block
+
+      @arity = block.arity
+      if @arity <= 0
+        # Capture outer self so that outer methods / ivars remain accessible
+        # via method_missing delegation while the builder acts as self.
+        @context = eval("self", block.binding)
+        instance_eval(&block)
+      else
+        yield self
+      end
+    end
+
+    # Insert a Text node containing +string+.
+    def text(string)
+      insert(@doc.create_text_node(string))
+    end
+
+    # Insert a CDATA node containing +string+.
+    def cdata(string)
+      insert(@doc.create_cdata(string))
+    end
+
+    # Insert a Comment node containing +string+.
+    def comment(string)
+      insert(@doc.create_comment(string))
+    end
+
+    # Append raw HTML (parsed into nodes) under the current parent.
+    def <<(string)
+      @doc.fragment(string).children.each { |x| insert(x) }
+    end
+
+    # Serialize the built content to an HTML string.
+    def to_html
+      @parent.to_html
+    end
+    alias_method :to_s, :to_html
+
+    # Ruby's Kernel#p, Kernel#pp, etc. are defined on Object and therefore on
+    # Builder itself.  They must be overridden so they fall through to
+    # method_missing and create the corresponding HTML element instead of
+    # printing values to stdout.
+    def p(*args, &block) # :nodoc:
+      method_missing(:p, *args, &block)
+    end
+
+    def method_missing(method, *args, &block) # :nodoc:
+      # Only delegate to the outer context for methods the user defined there.
+      # Standard Object / Kernel methods (like :p, :pp, :puts …) must not be
+      # forwarded to @context because all objects respond to them, which would
+      # bypass element creation entirely.
+      if @context && !OBJECT_INSTANCE_METHODS.include?(method) && @context.respond_to?(method)
+        @context.send(method, *args, &block)
+      else
+        node = @doc.create_element(method.to_s.sub(/[_!]$/, ""), *args)
+        insert(node, &block)
+      end
+    end
+
+    def respond_to_missing?(method, include_private = false) # :nodoc:
+      (@context && !OBJECT_INSTANCE_METHODS.include?(method) && @context.respond_to?(method)) || super
+    end
+
+    # Methods defined on plain Object that should never be forwarded to @context
+    # as HTML element creation fallbacks.
+    OBJECT_INSTANCE_METHODS = Object.instance_methods.to_set.freeze
+
+    private
+
+    # Add +node+ as a child of @parent; if a block is given, push @parent
+    # to +node+ for the duration of that block, then restore it.
+    # Returns a {NodeBuilder} for the inserted node so attributes / classes
+    # can be chained: <tt>div.container.hero!</tt>
+    def insert(node, &block)
+      node = @parent.add_child(node)
+      if block
+        old_parent = @parent
+        @parent    = node
+        @arity   ||= block.arity
+        begin
+          if @arity <= 0
+            instance_eval(&block)
+          else
+            yield(self)
+          end
+        ensure
+          @parent = old_parent
+        end
+      end
+      NodeBuilder.new(node, self)
+    end
+
+    # Wraps a built node and exposes a fluent API for setting classes and ids:
+    #
+    #   div.container        # => <div class="container">
+    #   div.box.highlight    # => <div class="box highlight">
+    #   div.thing!           # => <div id="thing">
+    #   div.container.hero!  # => <div class="container" id="hero">
+    #
+    class NodeBuilder # :nodoc:
+      def initialize(node, doc_builder)
+        @node        = node
+        @doc_builder = doc_builder
+      end
+
+      def []=(k, v)
+        @node[k] = v
+      end
+
+      def [](k)
+        @node[k]
+      end
+
+      def method_missing(method, *args, &block)
+        opts = args.last.is_a?(Hash) ? args.pop : {}
+
+        case method.to_s
+        when /^(.*)!$/
+          @node["id"]  = Regexp.last_match(1)
+          @node.content = args.first if args.first
+        when /^(.*)=$/
+          @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 |k, v|
+          @node[k.to_s] = ((@node[k.to_s] || "").split(/\s/) + [v.to_s]).join(" ")
+        end
+
+        if block
+          old_parent           = @doc_builder.parent
+          @doc_builder.parent  = @node
+          arity = @doc_builder.arity || block.arity
+          value = if arity <= 0
+            @doc_builder.instance_eval(&block)
+          else
+            yield(@doc_builder)
+          end
+          @doc_builder.parent = old_parent
+          return value
+        end
+
+        self
+      end
+
+      def respond_to_missing?(_method, _include_private = false) # :nodoc:
+        true
+      end
+    end
+  end
+end

data/lib/nokolexbor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Nokolexbor
-  VERSION = '0.6.4'
+  VERSION = '0.7.0'
 end

data/lib/nokolexbor.rb

@@ -28,11 +28,23 @@ require 'nokolexbor/node_set'
 require 'nokolexbor/document_fragment'
 require 'nokolexbor/xpath'
 require 'nokolexbor/xpath_context'
+require 'nokolexbor/builder'
 
 module Nokolexbor
   class << self
-    def HTML(*args)
+    def parse(*args)
       Document.parse(*args)
     end
+
+    alias_method :HTML, :parse
+  end
+end
+
+# Parse an HTML document, or build one with the DSL when a block is given.
+def Nokolexbor(string_or_io = nil, &block)
+  if block
+    Nokolexbor::Builder.new(&block).parent
+  else
+    Nokolexbor.parse(string_or_io)
   end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: nokolexbor
 version: !ruby/object:Gem::Version
-  version: 0.6.4
+  version: 0.7.0
 platform: ruby
 authors:
 - Yicheng Zhou
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-23 00:00:00.000000000 Z
+date: 2026-03-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake-compiler
@@ -120,6 +119,7 @@ files:
 - ext/nokolexbor/xml_tree.c
 - ext/nokolexbor/xml_xpath.c
 - lib/nokolexbor.rb
+- lib/nokolexbor/builder.rb
 - lib/nokolexbor/document.rb
 - lib/nokolexbor/document_fragment.rb
 - lib/nokolexbor/node.rb
@@ -523,7 +523,6 @@ licenses:
 - MIT
 metadata:
   msys2_mingw_dependencies: cmake
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -538,8 +537,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
-signing_key:
+rubygems_version: 4.0.6
 specification_version: 4
 summary: High-performance HTML5 parser, with support for both CSS selectors and XPath.
 test_files: []