amath 0.1.0

data/lib/amath/errors.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Amath
+  # Base class for every error Amath raises on purpose.
+  class Error < StandardError; end
+
+  # The input is not valid AsciiMath for the selected decimal marker.
+  #
+  # Positions are zero-based and match what Plurimath's Parslet parser
+  # reported, on either engine: the deepest leaf of the tree of failures
+  # that caused the rejection. +byte_offset+ counts UTF-8 bytes into the
+  # input (Parsanol's native unit); +char_offset+ counts characters, the
+  # unit Parslet used.
+  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 input nests deeper than the engine that ran can handle: the native
+  # engine's recursion limit under +engine: :native+, or an exhausted Ruby
+  # stack. A ParseError so existing rescues keep working; the offsets are
+  # nil because no rejection position exists.
+  class NestingTooDeep < ParseError; end
+
+  # The compiled grammar artifact is missing, unreadable, malformed, fails
+  # its checksum, declares an unsupported shape, or cannot be compiled by the
+  # installed Parsanol. Amath never falls back to another grammar.
+  class ArtifactError < Error; end
+
+  # +engine: :native+ was requested but Parsanol's native extension is not
+  # available on this platform.
+  class EngineUnavailable < Error; end
+end

data/lib/amath/native_recursion_guard.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Amath
+  # Raised inside Parsanol's native error path when the native engine hit its
+  # recursion limit, before Parsanol's own interpreter reparse runs (that
+  # reparse can take minutes or exhaust the Ruby stack on deep input).
+  class NativeRecursionLimit < Error; end
+  private_constant :NativeRecursionLimit
+
+  # Parsanol::Native.raise_native_parse_error translates a native failure.
+  # For a recursion-limit failure (which carries no position) it reparses
+  # through the Ruby interpreter with a Deepest reporter. While amath's own
+  # native call is running on this thread, this hook turns that failure into
+  # NativeRecursionLimit instead; every other failure, and every other
+  # caller of Parsanol, is unaffected.
+  module NativeRecursionGuard
+    MESSAGE = /\A(?:Maximum recursion depth \(\d+\) exceeded|Recursion limit exceeded\b)/
+    KEY = :amath_native_recursion_guard
+
+    def self.watch
+      outer = Thread.current[KEY]
+      Thread.current[KEY] = true
+      yield
+    ensure
+      Thread.current[KEY] = outer
+    end
+
+    def self.installed?
+      Parsanol::Native.singleton_class.ancestors.include?(self)
+    end
+
+    def raise_native_parse_error(error, grammar, input)
+      if Thread.current[KEY] && error.message.match?(MESSAGE)
+        raise NativeRecursionLimit, error.message.lines.first.strip, cause: nil
+      end
+
+      super
+    end
+  end
+
+  if Parsanol::Native.singleton_class.method_defined?(:raise_native_parse_error)
+    Parsanol::Native.singleton_class.prepend(NativeRecursionGuard)
+  end
+end

data/lib/amath/parser.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Amath
+  # Checks the arguments of Amath.parse, picks the artifact entry for the
+  # decimal marker and hands the input to the engine.
+  module Parser
+    module_function
+
+    def parse(input, decimal:, engine:)
+      entry = entry_for(decimal)
+      text = normalize_input(input)
+      mode = Engine.resolve(engine)
+      tree = Engine.run(Amath.artifact, entry, text, mode,
+                        fallback: engine == :auto)
+      Renester.call(tree)
+    end
+
+    def entry_for(decimal)
+      Configuration::DECIMAL_ENTRIES.fetch(decimal) do
+        raise ArgumentError,
+              "unsupported decimal marker #{decimal.inspect} " \
+              "(supported: #{Configuration::DECIMAL_ENTRIES.keys.map(&:inspect).join(', ')})"
+      end
+    end
+
+    # +input+ as valid UTF-8, or an ArgumentError.
+    def normalize_input(input)
+      unless input.is_a?(String)
+        raise ArgumentError,
+              "input must be a String, got #{input.class}"
+      end
+
+      text = input.encoding == Encoding::UTF_8 ? input : input.encode(Encoding::UTF_8)
+      unless text.valid_encoding?
+        raise ArgumentError,
+              "input is not valid UTF-8"
+      end
+
+      text
+    rescue EncodingError => e
+      raise ArgumentError, "input cannot be converted to UTF-8: #{e.message}"
+    end
+  end
+end

data/lib/amath/renester.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Amath
+  # Rebuilds the nested tree of a flattened expression chain.
+  #
+  # The grammar parses a run of terms (a sum, a sequence) as a repetition
+  # instead of right recursion, so the engines need no stack depth
+  # proportional to the number of terms. It returns such a run as
+  #
+  #   {expr: {amath_chain: [{amath_step: part_1}, {amath_lr: part_2}, ...,
+  #                         {amath_step: part_n}, {amath_end: rest}]}}
+  #
+  # (the +amath_end+ item is optional), where the recursive rule returned
+  #
+  #   {expr: part_1 + {left_right: part_2 + ... {expr: part_n + rest}}}
+  #
+  # with + the parser's merge of sequence results: each +amath_step+ part
+  # becomes an :expr level and each +amath_lr+ part a :left_right level.
+  # The grammar already puts the chain node under its outermost level's
+  # key (:expr above), so sibling merges see the oracle's keys.
+  # Renester.call replaces every chain node with the value of that
+  # outermost level. It
+  # never recurses, so trees of any depth are safe. Every Hash and Array
+  # of the result is new; leaves are shared with the input tree.
+  module Renester
+    CHAIN = :amath_chain
+    FINAL = :amath_end
+    # Chain item key => key of the level it becomes.
+    LEVELS = { amath_step: :expr, amath_lr: :left_right }.freeze
+
+    module_function
+
+    # +tree+ with every chain node rebuilt.
+    def call(tree)
+      return tree unless container?(tree)
+
+      done = []
+      todo = [[tree, false]]
+      step(todo, done, *todo.pop) until todo.empty?
+      done.first
+    end
+
+    # One move of the post-order walk: a leaf is done; a container is
+    # rebuilt once its children are done, after queueing them first.
+    def step(todo, done, node, children_done)
+      if !container?(node)
+        done << node
+      elsif children_done
+        done << rebuild(node, done.pop(node.size))
+      else
+        todo << [node, true]
+        children = node.is_a?(Hash) ? node.values : node
+        children.reverse_each { |child| todo << [child, false] }
+      end
+    end
+
+    def container?(node)
+      node.instance_of?(Hash) || node.instance_of?(Array)
+    end
+
+    # A chain node ({amath_chain: items}, always alone in its Hash) becomes
+    # the value of its outermost level; any other container gets +values+
+    # (already rebuilt).
+    def rebuild(node, values)
+      return values unless node.is_a?(Hash)
+      return renest(values.first).each_value.first if node.key?(CHAIN)
+
+      node.keys.zip(values).to_h
+    end
+
+    # The nested tree of a chain's items, built from the innermost level
+    # outwards.
+    def renest(items)
+      last = items.last
+      rest = last.instance_of?(Hash) && last.key?(FINAL) ? last[FINAL] : ""
+      tree = rest
+      items.reverse_each do |item|
+        item.each do |key, part|
+          level = LEVELS[key]
+          tree = { level => fold(part, tree) } if level
+        end
+      end
+      tree
+    end
+
+    # Parsanol's result of a sequence whose (flattened) elements are +left+
+    # and +right+: nil elements are skipped, all nil is "", otherwise the
+    # two are merged.
+    def fold(left, right)
+      return right.nil? ? "" : right if left.nil?
+      return left if right.nil?
+
+      merge(left, right)
+    end
+
+    # Parsanol::Atoms::CanFlatten#merge_fold, without its duplicate-key
+    # warning.
+    def merge(left, right)
+      if left.instance_of?(right.class)
+        left.is_a?(Hash) ? left.merge(right) : left + right
+      elsif text?(left) || text?(right)
+        merge_text(left, right)
+      else
+        merge_list(left, right)
+      end
+    end
+
+    # A Hash and an Array: the Hash joins the Array.
+    def merge_list(left, right)
+      return left + [right] if right.instance_of?(Hash)
+      return [left] + right if left.instance_of?(Hash)
+
+      raise Error, "cannot merge #{left.class} with #{right.class}"
+    end
+
+    # At least one side is text: the other side wins over text, and a
+    # Slice wins over a String.
+    def merge_text(left, right)
+      return left unless text?(left)
+      return right unless text?(right)
+
+      right.instance_of?(Parsanol::Slice) ? right : left
+    end
+
+    def text?(value)
+      value.instance_of?(String) || value.instance_of?(Parsanol::Slice)
+    end
+
+    private_class_method :step, :container?, :rebuild,
+                         :renest, :fold, :merge, :merge_text, :merge_list,
+                         :text?
+  end
+end

data/lib/amath/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Amath
+  VERSION = "0.1.0"
+end

data/lib/amath.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "parsanol"
+
+# AsciiMath parser backed by a compiled Parsanol (PARG) grammar artifact.
+#
+# See docs/parser-contract.adoc for the full contract.
+module Amath
+  autoload :VERSION, "amath/version"
+  autoload :Error, "amath/errors"
+  autoload :ParseError, "amath/errors"
+  autoload :NestingTooDeep, "amath/errors"
+  autoload :ArtifactError, "amath/errors"
+  autoload :EngineUnavailable, "amath/errors"
+  autoload :Artifact, "amath/artifact"
+  autoload :Configuration, "amath/configuration"
+  autoload :Engine, "amath/engine"
+  autoload :ErrorPosition, "amath/error_position"
+  autoload :Parser, "amath/parser"
+  autoload :Renester, "amath/renester"
+
+  # Decimal marker => artifact entry name.
+  DECIMAL_ENTRIES = Configuration::DECIMAL_ENTRIES
+  ENGINES = Configuration::ENGINES
+  THREAD_NATIVE_DEPTH = Configuration::THREAD_NATIVE_DEPTH
+  OPENING = Configuration::OPENING
+  CLOSING = Configuration::CLOSING
+  DEFAULT_ARTIFACT_PATH = Configuration::DEFAULT_ARTIFACT_PATH
+
+  @artifact = Artifact.new(DEFAULT_ARTIFACT_PATH)
+
+  module_function
+
+  # Parse +input+ and return the Parsanol tree (Hash/Array of
+  # Parsanol::Slice leaves, or a plain "" for empty input).
+  #
+  # The engine that ran is available afterwards from Amath.last_engine.
+  def parse(input, decimal: ".", engine: :auto)
+    Parser.parse(input, decimal: decimal, engine: engine)
+  end
+
+  # The engine (:native or :ruby) that produced the result (tree or
+  # rejection) of the last Amath.parse call on the current thread that
+  # reached the parser; nil before any parse. Under engine: :auto this is
+  # :ruby when the native engine hit its recursion limit and amath reran
+  # the input on the Ruby engine.
+  def last_engine
+    Engine.last_engine
+  end
+
+  def native_available?
+    Engine.native_available?
+  end
+
+  def artifact_path
+    @artifact.path
+  end
+
+  # Point Amath at another artifact (mainly for tests). Clears the cache so
+  # the next parse loads it.
+  def artifact_path=(path)
+    @artifact.path = path
+  end
+
+  # The loaded Parsanol::PARG::Artifact, loaded and verified once.
+  def artifact
+    @artifact.fetch
+  end
+end
+
+# Installs a hook into Parsanol at load time, so it is required, not
+# autoloaded.
+require_relative "amath/native_recursion_guard"

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: amath
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ribose Inc.
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: parsanol
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.107
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.107
+description: |
+  AsciiMath parser that runs a compiled Parsanol grammar artifact and
+  returns a parse tree. Used by Plurimath.
+email:
+- open.source@ribose.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.md
+- README.adoc
+- artifacts/asciimath.checksums.txt
+- artifacts/asciimath.json
+- corpora/uncertainty-shared-exponent.yml
+- docs/parser-contract.adoc
+- lib/amath.rb
+- lib/amath/artifact.rb
+- lib/amath/configuration.rb
+- lib/amath/engine.rb
+- lib/amath/error_position.rb
+- lib/amath/errors.rb
+- lib/amath/native_recursion_guard.rb
+- lib/amath/parser.rb
+- lib/amath/renester.rb
+- lib/amath/version.rb
+homepage: https://github.com/plurimath/amath
+licenses:
+- BSD-2-Clause
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: AsciiMath parser by Plurimath.
+test_files: []