taurus 0.1.0

data/lib/taurus/xml/node_set.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+class Taurus::XML::NodeSet
+  include Enumerable
+  include Taurus::XML::Searchable
+
+  attr_reader :document
+
+  # Two construction modes:
+  # - eager: pass an Array of Nodes (e.g. Element#children builds one)
+  # - lazy:  pass an FFI::Pointer to a TaurusXPathResult that this NodeSet
+  #          will keep alive and free on GC. Each [i] / each call goes
+  #          through taurus_xpath_result_get instead of pre-materializing.
+  def initialize(document, source = nil)
+    @document = document
+    case source
+    when ::FFI::Pointer
+      if source.null?
+        @result_ptr = nil
+        @array = []
+      else
+        # Wrap in AutoPointer for automatic GC-time cleanup. NodeSet has no
+        # explicit #free method (Nokogiri doesn't either), so the AutoPointer
+        # double-free risk that Document#free hit doesn't apply here.
+        @result_ptr = ::FFI::AutoPointer.new(source, Taurus::XML::FFI.method(:taurus_xpath_result_free))
+        @array = nil
+      end
+    when nil
+      @result_ptr = nil
+      @array = []
+    else
+      @result_ptr = nil
+      @array = source.to_a
+    end
+  end
+
+  def self.from_result(document, result_ptr)
+    new(document, result_ptr)
+  end
+
+  def length
+    @result_ptr ? Taurus::XML::FFI.taurus_xpath_result_count(@result_ptr) : @array.length
+  end
+  alias_method :size, :length
+
+  def empty?
+    length == 0
+  end
+
+  def [](idx)
+    if @result_ptr
+      return nil if idx < 0 || idx >= length
+      ptr = Taurus::XML::FFI.taurus_xpath_result_get(@result_ptr, idx)
+      return nil if ptr.null?
+      Taurus::XML::Node.wrap(ptr, @document)
+    else
+      @array[idx]
+    end
+  end
+
+  def each
+    return enum_for(:each) unless block_given?
+    if @result_ptr
+      # Batch-fetch all node pointers in one FFI call (taurus_xpath_result_get_nodes,
+      # libtaurus v0.11.4) and wrap each. Saves N-1 FFI calls vs the per-index
+      # taurus_xpath_result_get loop. Wrappers are still cached per-Document via
+      # Node.wrap, so a re-iteration of the same NodeSet hits the cache.
+      n = length
+      if n > 0
+        buf = ::FFI::MemoryPointer.new(:pointer, n)
+        begin
+          copied = Taurus::XML::FFI.taurus_xpath_result_get_nodes(@result_ptr, buf, n)
+          copied.times do |i|
+            ptr = buf.get_pointer(i * ::FFI.type_size(:pointer))
+            next if ptr.null?
+            yield Taurus::XML::Node.wrap(ptr, @document)
+          end
+        ensure
+          buf.free
+        end
+      end
+    else
+      @array.each { |n| yield n }
+    end
+    self
+  end
+
+  def to_a
+    return @array if @array
+    return [] if @result_ptr.nil?
+    out = []
+    each { |n| out << n }
+    @array = out  # memoize so subsequent to_a / each avoids re-fetch
+    out
+  end
+  alias_method :to_ary, :to_a
+
+  def first(n = nil)
+    return self[0] if n.nil?
+    n.times.map { |i| self[i] }.take_while { |x| !x.nil? }
+  end
+
+  def last
+    if @result_ptr
+      self[length - 1]
+    else
+      @array.last
+    end
+  end
+
+  def inner_text
+    map(&:content).join
+  end
+  alias_method :text, :inner_text
+
+  def xpath(*paths)
+    handler, _ns, _vars = parse_search_args(paths)
+    raise ArgumentError, "custom XPath handlers not supported" if handler
+    expr = paths.join(" | ")
+    accumulated = Taurus::XML::NodeSet.new(@document)
+    each do |node|
+      next unless node.is_a?(Taurus::XML::Element)
+      result_ptr = Taurus::XML::FFI.taurus_xpath_eval(
+        @document.c_ptr, node.c_ptr, expr)
+      next if result_ptr.null?
+      sub = Taurus::XML::NodeSet.send(:from_result, @document, result_ptr)
+      accumulated = merge_node_sets(accumulated, sub)
+    end
+    accumulated
+  end
+
+  def inspect
+    to_a.inspect
+  end
+
+  private
+
+  def merge_node_sets(a, b)
+    Taurus::XML::NodeSet.new(@document, a.to_a + b.to_a)
+  end
+end

data/lib/taurus/xml/parse_options.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class Taurus::XML::ParseOptions
+  DEFAULT_XML = 0
+  RECOVER = 1 << 0
+  NOERROR = 1 << 5
+  NOWARNING = 1 << 6
+  NOCDATA = 1 << 8
+  STRICT = 1 << 18
+
+  attr_reader :options
+
+  def initialize(options = DEFAULT_XML)
+    @options = options.to_i
+  end
+
+  def strict?;    !@options.zero?; end
+  def recover?;   @options & RECOVER != 0; end
+end

data/lib/taurus/xml/processing_instruction.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class Taurus::XML::ProcessingInstruction < Taurus::XML::Node
+  def name
+    Taurus::XML::FFI.taurus_pi_node_get_target(@c_ptr)
+  end
+  alias_method :target, :name
+
+  def content
+    Taurus::XML::FFI.taurus_pi_node_get_data(@c_ptr).to_s
+  end
+
+  def target=(new_target)
+    status = Taurus::XML::FFI.taurus_pi_node_set_target(@c_ptr, new_target.to_s)
+    raise Taurus::XML::Error,
+      Taurus::XML::FFI.taurus_status_string(status) unless status == Taurus::XML::FFI::TAURUS_OK
+    new_target
+  end
+
+  def data=(new_data)
+    status = Taurus::XML::FFI.taurus_pi_node_set_data(@c_ptr, new_data.to_s)
+    raise Taurus::XML::Error,
+      Taurus::XML::FFI.taurus_status_string(status) unless status == Taurus::XML::FFI::TAURUS_OK
+    new_data
+  end
+end

data/lib/taurus/xml/sax/document.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+class Taurus::XML::SAX::Document
+  # Called when an XML declaration is parsed.
+  def xmldecl(version, encoding, standalone)
+  end
+
+  def start_document
+  end
+
+  def end_document
+  end
+
+  # Called at the beginning of an element.
+  # +attrs+ is an Array of [name, value] pairs in source order.
+  def start_element(name, attrs = [])
+  end
+
+  def end_element(name)
+  end
+
+  def characters(string)
+  end
+
+  def comment(string)
+  end
+
+  def cdata_block(string)
+  end
+
+  def processing_instruction(name, content)
+  end
+
+  def start_prefix_mapping(prefix, uri)
+  end
+
+  def end_prefix_mapping(prefix)
+  end
+
+  def warning(string)
+  end
+
+  def error(message, line = 0, column = 0)
+  end
+end

data/lib/taurus/xml/sax/parser.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+class Taurus::XML::SAX::Parser
+  CHUNK_SIZE = 4096
+  private_constant :CHUNK_SIZE
+
+  attr_accessor :document, :encoding
+
+  def initialize(handler = Taurus::XML::SAX::Document.new, encoding = nil)
+    @document = handler
+    @encoding = encoding
+  end
+
+  # Parse a string, IO, or file path. Dispatches to parse_memory /
+  # parse_io / parse_file based on the argument type.
+  def parse(input)
+    case input
+    when String                then parse_memory(input)
+    when ->(x) { x.respond_to?(:read) } then parse_io(input)
+    else
+      raise ArgumentError, "SAX parser expects a String or IO, got #{input.class}"
+    end
+  end
+
+  def parse_memory(string)
+    string = string.dup.force_encoding("UTF-8")
+    handler_struct = build_handler_struct
+    rc = Taurus::XML::FFI.taurus_sax_parse(
+      string, string.bytesize, handler_struct.pointer, nil)
+    if rc != 0
+      raise Taurus::XML::ParseError,
+        "taurus_sax_parse failed (rc=#{rc})"
+    end
+    self
+  end
+
+  def parse_io(io)
+    handler_struct = build_handler_struct
+    parser_ptr = Taurus::XML::FFI.taurus_sax_parser_create(
+      handler_struct.pointer, nil)
+    if parser_ptr.null?
+      raise Taurus::XML::Error, "taurus_sax_parser_create failed"
+    end
+    begin
+      while (chunk = io.read(CHUNK_SIZE))
+        rc = Taurus::XML::FFI.taurus_sax_parser_feed(
+          parser_ptr, chunk, chunk.bytesize, 0)
+        if rc != 0
+          raise Taurus::XML::ParseError, "taurus_sax_parser_feed failed (rc=#{rc})"
+        end
+      end
+      # Final flush
+      rc = Taurus::XML::FFI.taurus_sax_parser_feed(parser_ptr, "", 0, 1)
+      if rc != 0
+        raise Taurus::XML::ParseError, "taurus_sax_parser_feed (final) failed (rc=#{rc})"
+      end
+    ensure
+      Taurus::XML::FFI.taurus_sax_parser_free(parser_ptr)
+    end
+    self
+  end
+
+  def parse_file(path)
+    File.open(path, "r") { |f| parse_io(f) }
+  end
+
+  private
+
+  # Build a TaurusSAXHandler struct populated with FFI::Function callbacks
+  # that dispatch to the Ruby handler. The struct (and its callbacks) are
+  # anchored against GC via the local variable for the duration of the
+  # synchronous parse call.
+  def build_handler_struct
+    s = Taurus::XML::FFI::SAXHandler.new
+    handler = @document  # capture in closures
+
+    s[:start_document] = callback(:void, [:pointer]) do |_|
+      handler.start_document
+    end
+
+    s[:end_document] = callback(:void, [:pointer]) do |_|
+      handler.end_document
+    end
+
+    s[:start_element] = callback(:void, [:pointer, :string, :pointer]) do |_, name, attrs_ptr|
+      attrs = walk_attr_array(attrs_ptr)
+      handler.start_element(name, attrs)
+    end
+
+    s[:end_element] = callback(:void, [:pointer, :string]) do |_, name|
+      handler.end_element(name)
+    end
+
+    s[:characters] = callback(:void, [:pointer, :pointer, :size_t]) do |_, text_ptr, len|
+      handler.characters(text_ptr.read_bytes(len).force_encoding("UTF-8"))
+    end
+
+    s[:comment] = callback(:void, [:pointer, :string]) do |_, comment|
+      handler.comment(comment)
+    end
+
+    s[:cdata] = callback(:void, [:pointer, :string]) do |_, cdata|
+      handler.cdata_block(cdata)
+    end
+
+    s[:processing_instruction] = callback(:void, [:pointer, :string, :string]) do |_, target, data|
+      handler.processing_instruction(target, data)
+    end
+
+    s[:start_prefix_mapping] = callback(:void, [:pointer, :string, :string]) do |_, prefix, uri|
+      handler.start_prefix_mapping(prefix, uri)
+    end
+
+    s[:end_prefix_mapping] = callback(:void, [:pointer, :string]) do |_, prefix|
+      handler.end_prefix_mapping(prefix)
+    end
+
+    s[:error] = callback(:void, [:pointer, :string, :int, :int]) do |_, msg, line, col|
+      handler.error(msg, line, col)
+    end
+
+    s
+  end
+
+  def callback(return_type, params, blocking: true, &block)
+    ::FFI::Function.new(return_type, params, blocking: blocking, &block)
+  end
+
+  # The C `const char** attrs` is a NULL-terminated flat array of name/value
+  # pairs: [name1, value1, name2, value2, ..., NULL]. Walk into pairs.
+  def walk_attr_array(attrs_ptr)
+    return [] if attrs_ptr.null?
+    ptr_size = ::FFI.type_size(:pointer)
+    result = []
+    offset = 0
+    loop do
+      name_ptr = attrs_ptr.get_pointer(offset)
+      break if name_ptr.null?
+      value_ptr = attrs_ptr.get_pointer(offset + ptr_size)
+      break if value_ptr.null?
+      result << [name_ptr.read_string, value_ptr.read_string]
+      offset += 2 * ptr_size
+    end
+    result
+  end
+end

data/lib/taurus/xml/sax.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module Taurus
+  module XML
+    module SAX
+      autoload :Document, "taurus/xml/sax/document"
+      autoload :Parser, "taurus/xml/sax/parser"
+    end
+  end
+end

data/lib/taurus/xml/searchable.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Taurus::XML::Searchable
+  def xpath(*paths)
+    handler, _ns, _vars = parse_search_args(paths)
+    raise ArgumentError, "custom XPath handlers not supported" if handler
+    expr = paths.join(" | ")
+
+    doc_ptr = is_a?(Taurus::XML::Document) ? c_ptr : document.c_ptr
+    context_ptr = is_a?(Taurus::XML::Document) ? nil : c_ptr
+
+    result_ptr = Taurus::XML::FFI.taurus_xpath_eval(doc_ptr, context_ptr, expr)
+    if result_ptr.null?
+      raise Taurus::XML::XPathError,
+        Taurus::XML::FFI.taurus_status_string(Taurus::XML::FFI::TAURUS_ERROR_XPATH)
+    end
+
+    wrap_xpath_result(result_ptr)
+  end
+
+  def at_xpath(*paths)
+    result = xpath(*paths)
+    result.is_a?(Taurus::XML::NodeSet) ? result.first : result
+  end
+
+  def search(*args)
+    paths = args.first.is_a?(Array) ? args.first : [args.first]
+    paths.map(&:to_s).all? { |p| looks_like_xpath?(p) } ? xpath(*paths) : css(*paths)
+  end
+  alias_method :/, :search
+
+  def at(*args)
+    result = search(*args)
+    result.is_a?(Taurus::XML::NodeSet) ? result.first : result
+  end
+  alias_method :%, :at
+
+  def css(*args)
+    handler, ns, _ = parse_search_args(args)
+    raise ArgumentError, "namespace bindings not supported in css" if ns && !ns.empty?
+    raise ArgumentError, "custom CSS handlers not supported" if handler
+    expr = args.map { |r| Taurus::XML::CssToXPath.convert(r) }.join(" | ")
+    xpath(expr)
+  end
+
+  def at_css(*args)
+    result = css(*args)
+    result.is_a?(Taurus::XML::NodeSet) ? result.first : result
+  end
+
+  protected
+
+  def parse_search_args(args)
+    handler = args.find { |a| !a.is_a?(String) && !a.is_a?(Hash) && !a.is_a?(Symbol) }
+    args = args - [handler] if handler
+    hashes = []
+    while args.last.is_a?(Hash) || args.last.nil?
+      hashes << args.pop
+      break if args.empty?
+    end
+    ns, vars = hashes.reverse
+    [handler, ns, vars]
+  end
+
+  def looks_like_xpath?(str)
+    %r{\A(\./|/|\.\.|\.)}.match?(str)
+  end
+
+  def wrap_xpath_result(result_ptr)
+    type = Taurus::XML::FFI.taurus_xpath_result_type(result_ptr)
+    case type
+    when Taurus::XML::FFI::XPATH_NODESET
+      Taurus::XML::NodeSet.send(:from_result, document, result_ptr)
+    when Taurus::XML::FFI::XPATH_BOOLEAN
+      v = Taurus::XML::FFI.taurus_xpath_result_boolean(result_ptr) != 0
+      Taurus::XML::FFI.taurus_xpath_result_free(result_ptr)
+      v
+    when Taurus::XML::FFI::XPATH_NUMBER
+      v = Taurus::XML::FFI.taurus_xpath_result_number(result_ptr)
+      Taurus::XML::FFI.taurus_xpath_result_free(result_ptr)
+      v
+    when Taurus::XML::FFI::XPATH_STRING
+      str_ptr = Taurus::XML::FFI.taurus_xpath_result_string(result_ptr)
+      v = str_ptr.null? ? "" : str_ptr.read_string
+      Taurus::XML::FFI.taurus_free_string(str_ptr) unless str_ptr.null?
+      Taurus::XML::FFI.taurus_xpath_result_free(result_ptr)
+      v
+    else
+      Taurus::XML::FFI.taurus_xpath_result_free(result_ptr)
+      raise Taurus::XML::XPathError, "unknown xpath result type #{type}"
+    end
+  end
+end

data/lib/taurus/xml/text.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class Taurus::XML::Text < Taurus::XML::Node
+  def name; "text"; end
+
+  def content
+    Taurus::XML::FFI.taurus_text_node_get_content(@c_ptr)
+  end
+
+  def content=(new_content)
+    status = Taurus::XML::FFI.taurus_text_node_set_content(@c_ptr, new_content.to_s)
+    raise Taurus::XML::Error,
+      Taurus::XML::FFI.taurus_status_string(status) unless status == Taurus::XML::FFI::TAURUS_OK
+    new_content
+  end
+end

data/lib/taurus/xml.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Taurus
+  module XML
+    autoload :FFI, "taurus/xml/ffi"
+    autoload :Node, "taurus/xml/node"
+    autoload :Element, "taurus/xml/element"
+    autoload :Text, "taurus/xml/text"
+    autoload :Comment, "taurus/xml/comment"
+    autoload :CDATA, "taurus/xml/cdata"
+    autoload :ProcessingInstruction, "taurus/xml/processing_instruction"
+    autoload :Attr, "taurus/xml/attr"
+    autoload :Namespace, "taurus/xml/namespace"
+    autoload :Document, "taurus/xml/document"
+    autoload :DocumentFragment, "taurus/xml/document_fragment"
+    autoload :DocType, "taurus/xml/doc_type"
+    autoload :NodeSet, "taurus/xml/node_set"
+    autoload :Searchable, "taurus/xml/searchable"
+    autoload :ParseOptions, "taurus/xml/parse_options"
+    autoload :CssToXPath, "taurus/xml/css_to_xpath"
+    autoload :SAX, "taurus/xml/sax"
+    require "taurus/xml/c14n"  # module-level helper, eager load
+
+    class Error < StandardError; end
+    class ParseError < Error; end
+    class XPathError < Error; end
+    class UseAfterFreeError < Error; end
+  end
+end

data/lib/taurus.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "taurus/version"
+
+module Taurus
+  autoload :XML, "taurus/xml"
+end

data/taurus.gemspec

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "lib/taurus/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "taurus"
+  spec.version = Taurus::VERSION
+  spec.authors = ["Ribose Inc."]
+  spec.email = ["open.source@ribose.com"]
+
+  spec.summary = "Nokogiri-compatible Ruby binding for libtaurus (XML 1.0, XPath 1.0, SAX)"
+  spec.description = <<~DESC
+    Taurus is a Nokogiri-compatible Ruby binding for libtaurus, a pure-C99 XML
+    1.0 parser with full XPath 1.0 and SAX support. The C DOM is the single
+    source of truth; Ruby objects are thin FFI wrappers (one Ruby method =
+    one FFI call).
+  DESC
+  spec.homepage = "https://github.com/lutaml/taurus-ruby"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata = {
+    "homepage_uri" => spec.homepage,
+    "source_code_uri" => "https://github.com/lutaml/taurus-ruby",
+    "changelog_uri" => "https://github.com/lutaml/taurus-ruby/blob/main/CHANGELOG.md",
+  }
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+  spec.bindir = "bin"
+  spec.executables = []
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "ffi", "~> 1.15"
+
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+end