taurus 0.1.0

data/Rakefile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+task default: :spec

data/TODO.impl/01-architecture.md

@@ -0,0 +1,217 @@
+# TODO 1 — Architecture: C-backed Nokogiri-compatible Ruby binding
+
+## Goal
+
+Rewrite `taurus-ruby` to be a **thin FFI wrapper** around libtaurus v0.4.2,
+exposing a **Nokogiri-compatible API**. The C DOM is the single source of
+truth — no Ruby-side tree copy.
+
+## Current state (problem)
+
+The existing `taurus-ruby` has:
+- A **pure-Ruby** XML tree model (Document < Element, Node, NodeSet)
+- A FFI bridge that does a **one-shot copy** from C to Ruby on parse
+- A **pure-Ruby XPath engine** (lexer, parser, compiler, VM in Ruby)
+
+This defeats libtaurus's performance: the C library's optimized bytecode
+VM + element index are never used. XPath goes through the slow Ruby engine.
+
+## Target architecture
+
+```
+User Ruby code
+    ↓
+Taurus::XML::Document / Node / NodeSet  (thin Ruby wrappers)
+    ↓ FFI
+libtaurus v0.4.2  (C99: DOM, XPath bytecode VM, element index)
+```
+
+Key principles:
+- **Every Ruby method is a single FFI call** to the C library.
+- **No Ruby-side tree copy.** The C DOM is the truth; Ruby objects are
+  handles (wrapping opaque pointers).
+- **XPath goes through C.** `doc.xpath('//book')` calls
+  `taurus_xpath_eval` directly. No Ruby XPath engine.
+- **SAX goes through C.** `Taurus::XML::SAX::Parser` wraps
+  `taurus_sax_parse` with Ruby callback dispatch.
+
+## Module structure (Nokogiri-compatible)
+
+```ruby
+module Taurus
+  module XML
+    # Top-level parse entry points
+    def self.parse(string_or_io)  →  Document
+    def self.parse_options         →  ParseOptions
+
+    class Document < Node
+      def root                    →  Element (or nil)
+      def create_element(name)    →  Element
+      def create_text_node(text)  →  Text
+      def to_xml(options)         →  String
+      def xpath(expr)             →  NodeSet | Float | String | Boolean
+      def at_xpath(expr)          →  Node (or nil)
+      def search(expr)            →  NodeSet
+      def canonicalize(...)       →  String
+      def free                    →  void  (explicit)
+    end
+
+    class Node
+      include Searchable
+
+      def name                    →  String
+      def content / text          →  String
+      def [](attr_name)           →  String (or nil)
+      def []=(attr_name, value)
+      def attributes              →  Hash {String => Attr}
+      def children                →  NodeSet
+      def child                   →  Node (or nil)
+      def first_element_child     →  Element (or nil)
+      def last_element_child      →  Element (or nil)
+      def next_sibling            →  Node (or nil)
+      def previous_sibling        →  Node (or nil)
+      def parent                  →  Node (or nil)
+      def document                →  Document
+      def type                    →  Integer (element/text/comment/cdata/pi)
+      def element?                →  Boolean
+      def text?                   →  Boolean
+      def comment?                →  Boolean
+      def cdata?                  →  Boolean
+      def processing_instruction? →  Boolean
+      def add_child(node)         →  Node
+      def add_next_sibling(node)  →  Node
+      def add_previous_sibling(node) → Node
+      def remove                  →  Node
+      def replace(node)           →  Node
+      def to_xml(options)         →  String
+      def inner_html              →  String
+      def traverse(&block)
+    end
+
+    class Element < Node
+      def add_class(name)
+      def remove_class(name)
+      def classes                 →  Array<String>
+    end
+
+    class Text < Node; end
+    class Comment < Node; end
+    class CDATA < Node; end
+    class ProcessingInstruction < Node; end
+    class Attr
+      def name                    →  String
+      def value                   →  String
+      def value=(val)
+      def parent                  →  Element
+      def remove
+    end
+
+    class NodeSet
+      include Enumerable
+      include Searchable
+
+      def length / size           →  Integer
+      def first(n)                →  Node | NodeSet
+      def last                    →  Node
+      def [](index)               →  Node
+      def each(&block)
+      def empty?                  →  Boolean
+      def xpath(expr)             →  NodeSet
+      def search(expr)            →  NodeSet
+      def to_xml                  →  String
+      def inner_text              →  String
+    end
+
+    module Searchable
+      def xpath(*paths)           →  NodeSet | Float | String | Boolean
+      def at_xpath(*paths)        →  Node (or nil)
+      def css(*selectors)         →  NodeSet (converts CSS to XPath)
+      def at_css(*selectors)      →  Node (or nil)
+      def search(*args)           →  NodeSet (auto-detect CSS/XPath)
+      def at(*args)               →  Node (or nil)
+    end
+
+    class ParseOptions
+      DEFAULT_XML = ...
+      RECOVER = ...
+      NOERROR = ...
+      NOWARNING = ...
+      NOCDATA = ...
+      STRICT = ...
+    end
+
+    module SAX
+      class Parser
+        def initialize(handler = DocHandler.new)
+        def parse(io_or_string)
+      end
+
+      class Document
+        def start_element(name, attrs = [])
+        def end_element(name)
+        def characters(string)
+        def start_document
+        def end_document
+        def comment(string)
+        def cdata(string)
+        def processing_instruction(name, content)
+        def error(message, line, column)
+      end
+    end
+  end
+end
+```
+
+## Memory model
+
+- **Document** owns the C document pool. `Taurus::XML::Document.new`
+  calls `taurus_parse_string` → returns a `TaurusDocument` pointer.
+  `Document#free` calls `taurus_document_free`. Auto-free via
+  `ObjectSpace.define_finalizer` as a safety net (but callers should
+  call `#free` explicitly for predictable lifecycle).
+- **Node / Element / Text etc.** are **non-owning handles** wrapping
+  a C pointer. The pointer is valid as long as the parent Document
+  is alive. Freeing a Node just drops the Ruby wrapper; the C node
+  lives until `Document#free`.
+- **NodeSet** wraps a `TaurusXPathResult` pointer from
+  `taurus_xpath_eval`. Freeing a NodeSet calls
+  `taurus_xpath_result_free`.
+- **Attr** wraps a C attribute pointer (owned by the parent element's
+  pool). Non-owning.
+
+## CSS support
+
+Nokogiri supports CSS selectors via `css()` and `at_css()`. Taurus
+doesn't have a CSS engine in C, so CSS-to-XPath conversion must be
+done in Ruby. Options:
+1. Use the `css_parser` gem (depends on `racc`).
+2. Write a minimal CSS-to-XPath converter in pure Ruby.
+
+For v0.4.2 compatibility, option 2 (minimal converter) is recommended.
+Nokogiri's CSS selector support is comprehensive but the common subset
+is small: `tag`, `.class`, `#id`, `> child`, `descendant`,
+`[attr]`, `[attr=value]`, `:first-child`, `:last-child`, `:not(...)`.
+
+## Dependencies
+
+```ruby
+# taurus.gemspec
+spec.add_dependency 'ffi', '~> 1.16'
+```
+
+No other runtime dependencies. No C extension compilation needed —
+just FFI to the pre-built libtaurus shared library.
+
+## Reference material
+
+- Nokogiri source: `~/src/external/nokogiri/`
+  - `lib/nokogiri/xml/node.rb` — 77 public methods
+  - `lib/nokogiri/xml/node_set.rb` — 31 public methods
+  - `lib/nokogiri/xml/document.rb` — 22 public methods
+  - `lib/nokogiri/xml/searchable.rb` — xpath/css/search module
+- libtaurus public headers: `src/include/taurus/`
+  - `types.h` — opaque handle typedefs
+  - `dom/document.h`, `dom/element.h`, `dom/serialize.h`
+  - `xpath/xpath.h` — XPath eval API
+  - `sax/sax.h` — SAX parser API
+- libtaurus v0.4.2: tag `v0.4.2` on `github.com:lutaml/taurus`

data/TODO.impl/02-ffi-declarations.md

@@ -0,0 +1,236 @@
+# TODO 2 — FFI declarations: complete libtaurus v0.4.2 public API
+
+## Goal
+
+Create `lib/taurus/xml/ffi.rb` that attaches to EVERY public function
+in libtaurus v0.4.2 via the `ffi` gem. This is the single source of
+truth for the C ↔ Ruby boundary.
+
+## Library loading
+
+```ruby
+module Taurus
+  module XML
+    module FFI
+      extend ::FFI
+
+      ffi_lib [
+        ENV['TAURUS_LIB_PATH'],
+        'taurus',
+        '/usr/local/lib/libtaurus.dylib',
+        '/usr/local/lib/libtaurus.so',
+        File.expand_path('../../../build/src/libtaurus.dylib', __dir__),
+        File.expand_path('../../../build/src/libtaurus.so', __dir__),
+      ].compact
+    end
+  end
+end
+```
+
+## Opaque type declarations
+
+```ruby
+typedef :pointer, :document
+typedef :pointer, :element
+typedef :pointer, :node_ref
+typedef :pointer, :xpath_result
+typedef :pointer, :sax_parser
+typedef :pointer, :attribute
+```
+
+## Complete function list (attach all of these)
+
+Source: `src/include/taurus/types.h`, `src/include/taurus.h`, and
+`src/include/taurus/*.h`.
+
+### Version
+```ruby
+attach_function :taurus_version, [], :string
+```
+
+### Document lifecycle
+```ruby
+attach_function :taurus_parse_string, [:string, :size_t, :pointer], :document
+attach_function :taurus_document_free, [:document], :void
+attach_function :taurus_document_root, [:document], :element
+attach_function :taurus_document_serialize, [:document, :pointer], :pointer
+attach_function :taurus_document_set_strict, [:document, :int], :void
+attach_function :taurus_xinclude_process, [:document, :string], :int
+```
+
+### Node access
+```ruby
+attach_function :taurus_node_get_type, [:node_ref], :int
+attach_function :taurus_node_first_child, [:node_ref], :node_ref
+attach_function :taurus_node_next_sibling, [:node_ref], :node_ref
+attach_function :taurus_node_previous_sibling, [:node_ref], :node_ref
+attach_function :taurus_node_child_count, [:node_ref], :size_t
+attach_function :taurus_node_as_element, [:node_ref], :element
+attach_function :taurus_element_as_node, [:element], :node_ref
+attach_function :taurus_element_first_child_any, [:element], :element
+```
+
+### Element queries
+```ruby
+attach_function :taurus_element_name, [:element], :string
+attach_function :taurus_element_text, [:element], :string
+attach_function :taurus_element_attribute, [:element, :string, :string], :string
+attach_function :taurus_element_attribute_count, [:element], :size_t
+attach_function :taurus_element_first_attribute, [:element], :pointer
+attach_function :taurus_element_parent, [:element], :element
+attach_function :taurus_element_next_sibling_any, [:element], :element
+attach_function :taurus_element_get_namespace_uri, [:element], :string
+attach_function :taurus_element_get_prefix, [:element], :string
+attach_function :taurus_element_get_name, [:element], :string
+```
+
+### Element mutation
+```ruby
+attach_function :taurus_element_set_name, [:element, :string], :void
+attach_function :taurus_element_set_attribute, [:element, :string, :string], :void
+attach_function :taurus_element_remove_attribute, [:element, :string], :void
+attach_function :taurus_element_append_child, [:element, :element], :int
+attach_function :taurus_element_create_child, [:element, :string], :element
+attach_function :taurus_element_set_text, [:element, :string], :void
+attach_function :taurus_element_remove_child, [:element, :element], :void
+```
+
+### Element creation
+```ruby
+attach_function :taurus_element_create, [:string], :element
+attach_function :taurus_text_node_create, [:string], :element
+attach_function :taurus_comment_node_create, [:string], :element
+attach_function :taurus_cdata_node_create, [:string], :element
+attach_function :taurus_pi_node_create, [:string, :string], :element
+```
+
+### Text / Comment / CDATA / PI access
+```ruby
+attach_function :taurus_text_node_get_content, [:node_ref], :string
+attach_function :taurus_comment_node_get_content, [:node_ref], :string
+attach_function :taurus_cdata_node_get_content, [:node_ref], :string
+attach_function :taurus_pi_node_get_target, [:node_ref], :string
+attach_function :taurus_pi_node_get_data, [:node_ref], :string
+```
+
+### XPath
+```ruby
+attach_function :taurus_xpath_eval,
+  [:document, :element, :string], :xpath_result
+attach_function :taurus_xpath_eval_with_vars,
+  [:document, :string, :pointer], :xpath_result
+attach_function :taurus_xpath_result_type, [:xpath_result], :int
+attach_function :taurus_xpath_result_count, [:xpath_result], :size_t
+attach_function :taurus_xpath_result_get, [:xpath_result, :size_t], :element
+attach_function :taurus_xpath_result_boolean, [:xpath_result], :int
+attach_function :taurus_xpath_result_number, [:xpath_result], :double
+attach_function :taurus_xpath_result_string, [:xpath_result], :pointer
+attach_function :taurus_xpath_result_free, [:xpath_result], :void
+```
+
+### XPath variables
+```ruby
+attach_function :taurus_xpath_variable_set_new, [], :pointer
+attach_function :taurus_xpath_variable_set_free, [:pointer], :void
+attach_function :taurus_xpath_variable_set_boolean, [:pointer, :string, :int], :int
+attach_function :taurus_xpath_variable_set_number, [:pointer, :string, :double], :int
+attach_function :taurus_xpath_variable_set_string, [:pointer, :string, :string], :int
+```
+
+### SAX
+```ruby
+# TaurusSAXHandler is a struct of function pointers. Use FFI::Struct.
+class SAXHandler < ::FFI::Struct
+  layout \
+    :start_document,    :pointer,
+    :end_document,      :pointer,
+    :start_element,     :pointer,
+    :end_element,       :pointer,
+    :characters,        :pointer,
+    :comment,           :pointer,
+    :cdata,             :pointer,
+    :processing_instruction, :pointer,
+    :start_prefix_mapping,   :pointer,
+    :end_prefix_mapping,     :pointer,
+    :error,             :pointer
+end
+
+attach_function :taurus_sax_parse,
+  [:string, :size_t, SAXHandler.by_pointer, :pointer], :int
+attach_function :taurus_sax_parser_create,
+  [SAXHandler.by_pointer, :pointer], :sax_parser
+attach_function :taurus_sax_parser_feed,
+  [:sax_parser, :string, :size_t, :int], :int
+attach_function :taurus_sax_parser_free, [:sax_parser], :void
+attach_function :taurus_sax_parser_set_streaming,
+  [:sax_parser, :int], :int
+```
+
+### Serialization
+```ruby
+# TaurusSerializeOptions struct
+class SerializeOptions < ::FFI::Struct
+  layout \
+    :indent,          :int,
+    :xml_declaration, :int,
+    :no_empty_tags,   :int,
+    :preserve_whitespace, :int
+end
+
+attach_function :taurus_serialize_document,
+  [:document, :pointer], :pointer
+attach_function :taurus_c14n_canonicalize,
+  [:document, :int, :int], :pointer
+```
+
+### Memory
+```ruby
+attach_function :taurus_free_string, [:pointer], :void
+```
+
+## Status codes
+
+```ruby
+TAURUS_OK              = 0
+TAURUS_ERROR_MEMORY    = -1
+TAURUS_ERROR_PARSE     = -2
+TAURUS_ERROR_XPATH     = -3
+TAURUS_ERROR_NULL_ARG  = -4
+TAURUS_ERROR_INVALID_ARG = -5
+TAURUS_ERROR_NOT_FOUND = -6
+TAURUS_ERROR_IO        = -7
+```
+
+## Node type constants
+
+```ruby
+NODE_ELEMENT  = 0
+NODE_ATTRIBUTE = 1
+NODE_TEXT     = 2
+NODE_COMMENT  = 3
+NODE_CDATA    = 4
+NODE_PI       = 5
+NODE_DOCTYPE  = 6
+```
+
+## XPath result type constants
+
+```ruby
+XPATH_NODESET = 0
+XPATH_BOOLEAN = 1
+XPATH_NUMBER  = 2
+XPATH_STRING  = 3
+```
+
+## Notes
+
+- Use `Blocking: true` for SAX callbacks (FFI::Function).
+- Use `AutoPointer` for document and xpath_result to get automatic
+  cleanup. But ALSO provide explicit `#free` methods since GC timing
+  is non-deterministic.
+- The `taurus_element_*` functions that return `:string` return
+  document-owned strings (valid until `taurus_document_free`).
+  Ruby copies them automatically on FFI return — safe.
+- Functions that return `:pointer` for strings (like
+  `taurus_xpath_result_string`, `taurus_serialize_document`) return
+  heap-owned strings that the caller must free via `taurus_free_string`.