umath 0.1.0

data/lib/umath/artifact.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Umath
+  # The compiled grammar and its declared Ruby bindings, loaded, verified
+  # and paired once per pair of paths.
+  class Artifact
+    Loaded = Struct.new(:parse, :bindings)
+
+    # Loads the Parsanol::PARG::Artifact at +path+ and checks it has an
+    # entry for every decimal marker.
+    def self.load_parse(path)
+      raise ArtifactError, "artifact not found: #{path}" unless File.file?(path)
+
+      artifact = Parsanol::PARG::Artifact.load(path)
+      missing = Configuration::DECIMAL_ENTRIES.values - artifact.entries
+      unless missing.empty?
+        raise ArtifactError, "artifact #{path} lacks required entries: #{missing.join(', ')}"
+      end
+
+      artifact
+    rescue JSON::ParserError => e
+      raise ArtifactError, "artifact #{path} is not valid JSON: #{e.message.lines.first&.strip}"
+    rescue Parsanol::PARG::Error, SystemCallError, KeyError, TypeError, NoMethodError => e
+      raise ArtifactError, "artifact #{path} is invalid: #{e.class}: #{e.message}"
+    end
+
+    # Loads the Ruby bindings artifact at +path+: kind, checksum, target and
+    # binding version are verified, then it is paired with +parse+ (same
+    # grammar, version and source hash). Every entry must bind the tree
+    # capture twice: raw (the tree with slices) and as plain data (the model input).
+    def self.load_bindings(path, parse)
+      raise ArtifactError, "bindings artifact not found: #{path}" unless File.file?(path)
+
+      bindings = Parsanol::PARG::Bindings::Artifact.from_json(File.read(path, encoding: "UTF-8"),
+                                                              target: "ruby")
+      bindings.pair_with!(parse)
+      Configuration::DECIMAL_ENTRIES.each_value do |entry|
+        declared = bindings.bindings(entry).map { |b| [b["capture"], b["path"], b["type"]] }
+        required = [[Configuration::TREE_CAPTURE.to_s, Configuration::TREE_CAPTURE.to_s, "raw"],
+                    [Configuration::TREE_CAPTURE.to_s, Configuration::MODEL_BINDING.to_s, "any"]]
+        missing = required - declared
+        next if missing.empty?
+
+        raise ArtifactError, "bindings artifact #{path} does not bind " \
+                             "#{missing.map { |c, p, t| "#{c} -> #{p} (#{t})" }.join(', ')} for entry #{entry}"
+      end
+      bindings
+    rescue JSON::ParserError => e
+      raise ArtifactError, "bindings artifact #{path} is not valid JSON: #{e.message.lines.first&.strip}"
+    rescue Parsanol::PARG::Error, SystemCallError, KeyError, TypeError, NoMethodError => e
+      raise ArtifactError, "bindings artifact #{path} is invalid: #{e.class}: #{e.message}"
+    end
+
+    attr_reader :path, :bindings_path
+
+    def initialize(path, bindings_path)
+      @path = path
+      @bindings_path = bindings_path
+      @loaded = nil
+      @lock = Mutex.new
+    end
+
+    # Points at other artifacts (mainly for tests); the next #fetch loads them.
+    def use(path, bindings_path)
+      @lock.synchronize do
+        @path = path.to_s
+        @bindings_path = bindings_path.to_s
+        @loaded = nil
+      end
+    end
+
+    # The loaded pair, loaded on first use.
+    def fetch
+      @lock.synchronize do
+        @loaded ||= begin
+          parse = self.class.load_parse(@path)
+          Loaded.new(parse, self.class.load_bindings(@bindings_path, parse))
+        end
+      end
+    end
+  end
+end

data/lib/umath/configuration.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Umath
+  # Fixed settings: the artifact entries, the engine names and where the
+  # bundled artifacts live.
+  module Configuration
+    # Decimal marker => artifact entry name.
+    DECIMAL_ENTRIES = {
+      "." => "dot",
+      "," => "comma",
+      "٫" => "arabic", # ARABIC DECIMAL SEPARATOR
+    }.freeze
+
+    ENGINES = %i[auto native ruby].freeze
+
+    ARTIFACT_DIR = File.expand_path("../../artifacts", __dir__)
+    DEFAULT_ARTIFACT_PATH = File.join(ARTIFACT_DIR, "umath.json")
+    DEFAULT_BINDINGS_PATH = File.join(ARTIFACT_DIR, "umath.bindings.ruby.json")
+    DATA_DIR = File.expand_path("../../data", __dir__)
+    SYMBOLS_PATH = File.join(DATA_DIR, "umath-symbols.json")
+
+    # The capture under which the declared bindings carry the raw tree.
+    TREE_CAPTURE = :umath_tree
+    # The binding path under which they carry the same tree as plain data,
+    # the input of the typed model's construction.
+    MODEL_BINDING = :model
+
+    # Deepest bracket nesting sent to the native engine off the main thread,
+    # where the machine stack is small.
+    THREAD_NATIVE_DEPTH = 25
+  end
+end

data/lib/umath/engine.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Umath
+  # Runs the grammar on the native or Ruby Parsanol engine, always with
+  # Parslet-compatible memo decisions (the legacy grammar's mode), maps
+  # failures to Umath errors and records the engine that produced the
+  # result per thread.
+  #
+  # Internal.
+  module Engine
+    LAST_ENGINE_KEY = :umath_last_engine
+    OPENING = "([{".chars.freeze
+    CLOSING = ")]}".chars.freeze
+
+    module_function
+
+    def last_engine
+      Thread.current[LAST_ENGINE_KEY]
+    end
+
+    def native_available?
+      Parsanol::Native.available?
+    rescue LoadError, StandardError
+      false
+    end
+
+    # The engine (:native or :ruby) that +engine+ (one of ENGINES) runs.
+    def resolve(engine)
+      case engine
+      when :auto then native_available? ? :native : :ruby
+      when :ruby then :ruby
+      when :native
+        return :native if native_available?
+
+        raise EngineUnavailable,
+              "engine: :native requested but the Parsanol native extension " \
+              "is not available on this platform (#{RUBY_PLATFORM}, Ruby #{RUBY_VERSION})"
+      else
+        raise ArgumentError,
+              "unknown engine #{engine.inspect} (use #{Configuration::ENGINES.map(&:inspect).join(', ')})"
+      end
+    end
+
+    # Parses +text+ from +entry+ of the parse artifact +artifact+ on +mode+
+    # and returns the parse shape. Under +fallback+ (engine: :auto) input
+    # too deep for the native engine is rerun on Ruby.
+    def run(artifact, entry, text, mode, fallback:)
+      shape, ran = run_with_fallback(artifact, entry, text, mode, fallback: fallback)
+      record(ran)
+      shape
+    end
+
+    def run_with_fallback(artifact, entry, text, mode, fallback:)
+      if mode == :native && too_deep_for_native_thread?(text)
+        record(:native)
+        unless fallback
+          raise native_too_deep(text, "nesting depth over #{Configuration::THREAD_NATIVE_DEPTH} off the main thread")
+        end
+
+        return [run_mode(artifact, entry, text, :ruby), :ruby]
+      end
+
+      [run_mode(artifact, entry, text, mode), mode]
+    rescue NativeRecursionLimit => e
+      record(:native)
+      raise native_too_deep(text, e.message) unless fallback
+
+      [run_mode(artifact, entry, text, :ruby), :ruby]
+    rescue NestingTooDeep
+      raise unless fallback && mode == :native
+
+      [run_mode(artifact, entry, text, :ruby), :ruby]
+    end
+
+    def too_deep_for_native_thread?(text)
+      return false if Thread.current.equal?(Thread.main)
+
+      depth = 0
+      max = 0
+      text.each_char do |char|
+        if OPENING.include?(char)
+          depth += 1
+          max = depth if depth > max
+        elsif CLOSING.include?(char)
+          depth -= 1 if depth.positive?
+        end
+      end
+      max > Configuration::THREAD_NATIVE_DEPTH
+    end
+
+    def native_too_deep(text, detail)
+      NestingTooDeep.new(
+        "UnicodeMath input nests deeper than the native engine's recursion limit " \
+        "(#{detail}); use engine: :ruby or engine: :auto",
+        input: text, byte_offset: nil, char_offset: nil,
+      )
+    end
+
+    def run_mode(artifact, entry, text, mode)
+      root = artifact.root_atom(entry)
+      if mode == :native
+        NativeRecursionGuard.watch do
+          Parsanol::Native.parse(root, text, compatibility: :parslet)
+        end
+      else
+        root.parse(text, compatibility: :parslet)
+      end
+    rescue Parsanol::ParseFailed => e
+      record(mode)
+      raise parse_error(e, root, text, mode)
+    rescue SystemStackError
+      record(mode)
+      raise NestingTooDeep.new(
+        "UnicodeMath input nests too deeply for the #{mode} engine (Ruby stack exhausted)",
+        input: text, byte_offset: nil, char_offset: nil,
+      )
+    rescue Parsanol::PARG::Error, Parsanol::GrammarError, Parsanol::Native::UnsupportedGrammar => e
+      raise ArtifactError, "the grammar artifact cannot be used: #{e.class}: #{e.message}"
+    end
+
+    # The legacy grammar runs on the native engine wherever it is available
+    # (Parsanol::Parser picks it for Parslet-compatible parses), so the
+    # position it reports is the native engine's deepest failure. The Ruby
+    # engine reports the same position through a Deepest reporter.
+    def parse_error(error, root, text, mode)
+      cause = mode == :ruby ? ruby_cause(root, text) : error.parse_failure_cause
+      byte = deepest_position(cause)
+      char = byte && text.byteslice(0, byte).force_encoding(Encoding::UTF_8).scrub.length
+      where = byte ? " at character #{char} (byte #{byte})" : ""
+      ParseError.new("UnicodeMath input rejected#{where}: #{error.message.lines.first.to_s.strip[0, 200]}",
+                     input: text, byte_offset: byte, char_offset: char)
+    end
+
+    def ruby_cause(root, text)
+      root.parse(text, compatibility: :parslet, reporter: Parsanol::ErrorReporter::Deepest.new)
+      nil
+    rescue Parsanol::ParseFailed => e
+      e.parse_failure_cause
+    rescue SystemStackError
+      nil
+    end
+
+    # Iterative: the cause tree of deeply nested input is as deep as the
+    # input.
+    def deepest_position(cause)
+      deepest = nil
+      stack = [cause].compact
+      until stack.empty?
+        node = stack.pop
+        deepest = node.position if node.position && (deepest.nil? || node.position > deepest)
+        stack.concat(node.children.compact)
+      end
+      deepest
+    end
+
+    def record(mode)
+      Thread.current[LAST_ENGINE_KEY] = mode
+    end
+
+    private_class_method :run_with_fallback, :native_too_deep, :run_mode, :parse_error,
+                         :ruby_cause, :deepest_position, :record, :too_deep_for_native_thread?
+  end
+end

data/lib/umath/errors.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Umath
+  # Base class for every error Umath raises on purpose, except
+  # ArgumentError for invalid arguments.
+  class Error < StandardError; end
+
+  # The grammar refused the input.
+  #
+  # +input+ is the text the grammar ran on and the offsets are zero-based
+  # positions in it: +byte_offset+ in UTF-8 bytes, +char_offset+ in
+  # characters. They are the position the legacy Plurimath grammar reports
+  # for the same text, on either engine.
+  class ParseError < Error
+    attr_reader :input, :byte_offset, :char_offset
+
+    def initialize(message, input:, byte_offset:, char_offset:)
+      super(message)
+      @input = input
+      @byte_offset = byte_offset
+      @char_offset = char_offset
+    end
+  end
+
+  # The engine that ran cannot handle the input's nesting depth: the native
+  # engine's recursion limit, or an exhausted Ruby stack. The offsets are
+  # nil; this does not claim that the input is invalid.
+  class NestingTooDeep < ParseError; end
+
+  # A parse or bindings artifact is missing, malformed, fails its checksum,
+  # declares the wrong target or kind, or does not pair with the other.
+  # Umath never falls back to another artifact.
+  class ArtifactError < Error; end
+
+  # engine: :native was requested but Parsanol's native extension is not
+  # available on this platform.
+  class EngineUnavailable < Error; end
+end