plurimath 0.11.12 → 0.11.13

data/lib/plurimath/asciimath/transform.rb

@@ -1172,6 +1172,224 @@ module Plurimath
           Utility.asciimath_symbol_object(right),
         )
       end
+
+      # ustd(...), uexp(...) and ucov(...) (plurimath#493); the tree shape
+      # is docs/uncertainty-asciimath-tree.md.
+      rule(uncertainty: subtree(:uncertainty)) do
+        UncertaintyTree.node(uncertainty)
+      end
+
+      # `sqrt ustd(1,2)`, `sin ustd(1,2)`: the unary rule splices its
+      # unnamed operand next to `unary_class`, so the uncertainty tree is a
+      # sibling key. Built like `sqrt x` (`unary_class` + `symbol`).
+      rule(unary_class: simple(:function),
+           uncertainty: subtree(:uncertainty)) do
+        Utility.get_class(function).new(UncertaintyTree.node(uncertainty))
+      end
+
+      # Parslet::Transform#apply, without recursion: it transforms every
+      # child left to right, then the node itself, exactly as Parslet does,
+      # but keeps its own stack. A long AsciiMath sum is a tree about two
+      # levels deep per term, which overflows a small (1 MiB, as on Windows)
+      # stack when each level is a Ruby call.
+      def apply(obj, context = nil)
+        return transform_elt(obj, context) unless obj.is_a?(Hash) || obj.is_a?(Array)
+
+        stack = [apply_frame(obj)]
+        loop do
+          frame = stack.last
+          if frame[:index] < frame[:items].size
+            key, value = frame[:items][frame[:index]]
+            frame[:index] += 1
+            next stack.push(apply_frame(value, key)) if value.is_a?(Hash) || value.is_a?(Array)
+
+            store_applied(frame[:out], key, transform_elt(value, context))
+          else
+            stack.pop
+            result = transform_elt(frame[:out], context)
+            return result if stack.empty?
+
+            store_applied(stack.last[:out], frame[:key], result)
+          end
+        end
+      end
+
+      def apply_frame(node, key = nil)
+        items = node.is_a?(Hash) ? node.to_a : node.each_with_index.map { |v, i| [i, v] }
+        { items: items, out: node.is_a?(Hash) ? {} : [], index: 0, key: key }
+      end
+
+      def store_applied(out, key, value)
+        out.is_a?(Hash) ? out[key] = value : out << value
+      end
+
+      private :apply_frame, :store_applied
+
+      # A hash that comes back from Parslet::Transform#transform_elt matched no
+      # rule. One that still holds an uncertainty tree or node would reach
+      # the Formula as a raw Hash and fail only on output, so it is
+      # rejected here instead. This hook runs after child traversal, once per
+      # node, as #apply calls it.
+      def transform_elt(obj, context)
+        result = super
+        UncertaintyTree.stranded!(result) if result.is_a?(Hash)
+        result
+      end
+
+      # Builds Math::Function::Uncertainty from the fields of an
+      # `uncertainty:` tree. Every leaf is the text exactly as written; the
+      # node's constructor does all validation of numbers and categories.
+      module UncertaintyTree
+        CATEGORIES = {
+          "ustd" => :standard,
+          "uexp" => :expanded,
+          "ucov" => :coverage_interval,
+        }.freeze
+
+        FIELDS = {
+          standard: %i[value magnitude concise_digits unit],
+          expanded: %i[value magnitude coverage_factor coverage_probability
+                       unit],
+          coverage_interval: %i[value lower upper coverage_probability
+                                interval_kind unit],
+        }.freeze
+
+        NUMBER_FIELDS = %i[magnitude coverage_factor coverage_probability
+                           lower upper].freeze
+        SCALED_FIELDS = %i[magnitude lower upper].freeze
+        MAX_SCALED_DECIMAL_LENGTH = 1_000_000
+
+        # `probabilistically-symmetric` would read as a subtraction in
+        # AsciiMath, so it is spelled `symmetric` there.
+        INTERVAL_KINDS = {
+          "shortest" => :shortest,
+          "symmetric" => :probabilistically_symmetric,
+        }.freeze
+
+        module_function
+
+        def node(tree)
+          fields = leaves(tree)
+          category = CATEGORIES[fields.delete(:uncertainty_class)]
+          invalid!("unknown uncertainty class in #{tree.inspect}") unless category
+          exponent = fields.delete(:shared_exponent)
+          unknown = fields.keys - FIELDS[category]
+          invalid!("unexpected #{unknown.join(', ')} in #{tree.inspect}") unless unknown.empty?
+
+          # Concise digits describe the unscaled value's last decimal place.
+          # Derive their magnitude before moving either decimal point.
+          attributes = options(fields)
+          value = number(fields[:value])
+          if exponent
+            invalid!("invalid shared exponent #{exponent.inspect}") unless exponent.match?(/\A[+-]?[0-9]+\z/)
+            power = Integer(exponent, 10)
+            value = scale_number(value, power)
+            SCALED_FIELDS.each do |field|
+              attributes[field] = scale_number(attributes[field], power)
+            end
+          end
+          Math::Function::Uncertainty.new(
+            value,
+            category: category,
+            **attributes,
+          )
+        end
+
+        # Keep the model's plain-decimal contract. A shared exponent changes
+        # text positions only; coverage factors/probabilities never pass here.
+        def scale_number(node, power)
+          return node if node.nil? || power.zero?
+
+          match = node.value.match(/\A(-?)([0-9]+)(?:\.([0-9]+))?\z/)
+          invalid!("invalid scaled decimal #{node.value.inspect}") unless match
+          sign, whole, fraction = match.captures
+          digits = whole + fraction.to_s
+          point = whole.length + power
+          length = if point <= 0
+                     2 - point + digits.length
+                   elsif point >= digits.length
+                     point
+                   else
+                     digits.length + 1
+                   end
+          if length + sign.length > MAX_SCALED_DECIMAL_LENGTH
+            invalid!("shared exponent expands beyond #{MAX_SCALED_DECIMAL_LENGTH} decimal characters")
+          end
+          text = if point <= 0
+                   "0.#{'0' * -point}#{digits}"
+                 elsif point >= digits.length
+                   digits + "0" * (point - digits.length)
+                 else
+                   "#{digits[0...point]}.#{digits[point..]}"
+                 end
+          number(sign + text.sub(/\A0+(?=[0-9])/, ""))
+        end
+
+        def leaves(tree)
+          valid = tree.is_a?(Hash) &&
+            tree.values.all? { |leaf| leaf.is_a?(Parslet::Slice) || leaf.is_a?(String) }
+          invalid!("expected a hash of text fields, got #{tree.inspect}") unless valid
+
+          tree.transform_values(&:to_s)
+        end
+
+        def options(fields)
+          options = NUMBER_FIELDS.to_h { |field| [field, number(fields[field])] }
+          options[:interval_kind] = interval_kind(fields[:interval_kind])
+          options[:unit] = fields[:unit] && Math::Function::Unitsml.new(fields[:unit])
+          concise!(options, fields) if fields.key?(:concise_digits)
+          options
+        end
+
+        def interval_kind(name)
+          return if name.nil?
+
+          INTERVAL_KINDS.fetch(name) { invalid!("unknown interval kind #{name.inspect}") }
+        end
+
+        # ustd(1.230(4)): the digits count in units of the value's last
+        # decimal place, so 4 after 1.230 is 0.004.
+        def concise!(options, fields)
+          invalid!("ustd takes a magnitude or concise digits, not both") if fields.key?(:magnitude)
+          digits = fields[:concise_digits]
+          invalid!("concise digits #{digits.inspect} must be digits only") unless digits.match?(/\A[0-9]+\z/)
+
+          options[:magnitude] = number(concise_magnitude(fields[:value].to_s, digits))
+          options[:notation] = :concise
+        end
+
+        def concise_magnitude(value, digits)
+          places = value.include?(".") ? value.split(".", 2).last.length : 0
+          padded = digits.rjust(places + 1, "0")
+          whole = padded[0, padded.length - places].sub(/\A0+(?=[0-9])/, "")
+          places.zero? ? whole : "#{whole}.#{padded[-places..]}"
+        end
+
+        def number(text)
+          text && Math::Number.new(text)
+        end
+
+        def stranded!(hash)
+          return unless holds_uncertainty?(hash)
+
+          invalid!("no AsciiMath rule takes an uncertainty in #{hash.inspect}")
+        end
+
+        def holds_uncertainty?(tree)
+          case tree
+          when Hash
+            tree.key?(:uncertainty) || tree.each_value.any? { |v| holds_uncertainty?(v) }
+          when Array
+            tree.any? { |v| holds_uncertainty?(v) }
+          else
+            tree.is_a?(Math::Function::Uncertainty)
+          end
+        end
+
+        def invalid!(detail)
+          raise Errors::InvalidUncertainty.new(detail)
+        end
+      end
     end
   end
 end

data/lib/plurimath/asciimath.rb

@@ -5,6 +5,7 @@ module Plurimath
     autoload :Constants, "#{__dir__}/asciimath/constants"
     autoload :Parse, "#{__dir__}/asciimath/parse"
     autoload :Parser, "#{__dir__}/asciimath/parser"
+    autoload :SliceAdapter, "#{__dir__}/asciimath/slice_adapter"
     autoload :Transform, "#{__dir__}/asciimath/transform"
     autoload :Utility, "#{__dir__}/asciimath/utility"
 

data/lib/plurimath/catalog/entry.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Catalog
+    # Builds YAML-ready entries without changing the legacy rendering fields.
+    module Entry
+      RENDERERS = {
+        "asciimath" => :to_asciimath,
+        "latexmath" => :to_latex,
+        "mathml" => :to_mathml,
+        "omml" => :to_omml,
+      }.freeze
+      EMPTY_OUTPUT_NOTE = "The serializer returned no output."
+      METADATA_FIELDS = %i[name type kind arity description reference].freeze
+
+      module_function
+
+      def build(formula:, limitations: {}, **attributes)
+        entry = metadata(attributes)
+        Validation.validate_metadata!(entry)
+        declarations = normalize_limitations(limitations)
+        unless RENDERERS.values.all? { |method| formula.respond_to?(method) }
+          raise InvalidEntryError, "#{entry['name']}: example must support all four serializers"
+        end
+
+        formats = {}
+        RENDERERS.each do |format, method|
+          entry[format] = formula.public_send(method)
+          formats[format] = format_metadata(entry[format], declarations[format])
+        end
+        entry["formats"] = formats
+        Validation.validate!(entry)
+        entry
+      end
+
+      def metadata(attributes)
+        unless (attributes.keys - METADATA_FIELDS).empty?
+          raise InvalidEntryError, "Unknown catalog metadata fields"
+        end
+
+        entry = {
+          "name" => attributes[:name], "type" => label(attributes[:type]),
+          "kind" => label(attributes[:kind]), "arity" => label(attributes[:arity])
+        }
+        if entry["kind"] == "function"
+          entry["description"] = attributes[:description]
+          entry["reference"] = attributes[:reference]
+        end
+        entry
+      end
+
+      def normalize_limitations(limitations)
+        unless limitations.is_a?(Hash)
+          raise InvalidEntryError, "CATALOG_FORMAT_LIMITATIONS must be a Hash"
+        end
+
+        limitations.each_with_object({}) do |(format, declaration), result|
+          key = label(format)
+          unless RENDERERS.key?(key) && !result.key?(key)
+            raise InvalidEntryError, "Unknown or duplicate limitation format: #{format.inspect}"
+          end
+
+          result[key] = normalize_declaration(declaration, key)
+        end
+      end
+
+      def normalize_declaration(declaration, format)
+        unless declaration.is_a?(Hash)
+          raise InvalidEntryError, "#{format} limitation must be a Hash"
+        end
+
+        normalized = declaration.transform_keys { |key| label(key) }
+        unless normalized.keys.all?(String) && normalized.keys.sort == %w[notes status] &&
+            normalized.size == declaration.size
+          raise InvalidEntryError, "#{format} limitation requires only status and notes"
+        end
+
+        status = label(normalized["status"])
+        unless %w[limited unavailable].include?(status)
+          raise InvalidEntryError, "#{format} limitation status must be limited or unavailable"
+        end
+
+        Validation.validate_notes!(normalized["notes"], format, required: true)
+        { "status" => status, "notes" => normalized["notes"].map(&:dup) }
+      end
+
+      def format_metadata(output, declaration)
+        result = declaration || { "status" => "available", "notes" => [] }
+        if output.is_a?(String) && output.strip.empty?
+          result = {
+            "status" => "unavailable",
+            "notes" => (result["notes"] + [EMPTY_OUTPUT_NOTE]).uniq,
+          }
+        end
+        result
+      end
+
+      def label(value)
+        return if value.nil?
+        return value.to_s if value.is_a?(String) || value.is_a?(Symbol)
+
+        raise InvalidEntryError, "Catalog labels must be strings or symbols"
+      end
+
+      private_class_method :metadata, :normalize_limitations,
+                           :normalize_declaration, :format_metadata, :label
+    end
+  end
+end

data/lib/plurimath/catalog/validation.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Catalog
+    # Validates the public data contract independently of class discovery.
+    module Validation
+      FORMATS = %w[asciimath latexmath mathml omml].freeze
+      ARITIES = %w[unary binary ternary].freeze
+      STATUSES = %w[available limited unavailable].freeze
+      COMMON_KEYS = %w[name type kind arity formats].freeze
+
+      module_function
+
+      def validate_all!(entries)
+        unless entries.is_a?(Array)
+          raise InvalidEntryError, "Catalog entries must be an Array"
+        end
+
+        seen = {}
+        entries.each do |entry|
+          validate!(entry)
+          identity = entry.values_at("kind", "name")
+          if seen[identity]
+            raise InvalidEntryError, "Duplicate catalog identity: #{identity.join('/')}"
+          end
+
+          seen[identity] = true
+        end
+        entries
+      end
+
+      def validate!(entry)
+        validate_metadata!(entry)
+        expected = COMMON_KEYS + FORMATS
+        expected += %w[description reference] if entry["kind"] == "function"
+        unless entry.keys.all?(String) && entry.keys.sort == expected.sort
+          raise InvalidEntryError, "#{entry['name']}: unexpected or missing entry fields"
+        end
+
+        formats = entry["formats"]
+        unless formats.is_a?(Hash) && formats.keys.all?(String) &&
+            formats.keys.sort == FORMATS.sort
+          raise InvalidEntryError, "#{entry['name']}: formats must contain all four formats"
+        end
+
+        FORMATS.each { |format| validate_format!(entry, format) }
+        entry
+      end
+
+      def validate_metadata!(entry)
+        unless entry.is_a?(Hash) && entry["name"].is_a?(String) &&
+            entry["name"].match?(/\A[a-z0-9][a-z0-9_-]*\z/)
+          raise InvalidEntryError, "Catalog name must be a nonempty, safe lowercase slug"
+        end
+
+        case entry["kind"]
+        when "function" then validate_function!(entry)
+        when "symbol"
+          unless entry["type"] == "symbol" && entry["arity"].nil?
+            raise InvalidEntryError, "#{entry['name']}: symbol type must be symbol and arity nil"
+          end
+        else
+          raise InvalidEntryError, "#{entry['name']}: kind must be function or symbol"
+        end
+        entry
+      end
+
+      def validate_notes!(notes, format, required:)
+        unless notes.is_a?(Array) && notes.all? { |note| present_string?(note) } &&
+            (!required || !notes.empty?)
+          raise InvalidEntryError, "#{format}: notes must be nonempty strings#{' with a reason' if required}"
+        end
+      end
+
+      def validate_function!(entry)
+        unless ARITIES.include?(entry["arity"]) && entry["type"] == entry["arity"]
+          raise InvalidEntryError, "#{entry['name']}: function type and reference arity must agree"
+        end
+        unless present_string?(entry["description"]) &&
+            entry["reference"].is_a?(String) && entry["reference"].match?(%r{\Ahttps?://[^\s/?#]+(?:[/?#]\S*)?\z})
+          raise InvalidEntryError, "#{entry['name']}: function requires a description and HTTP(S) reference"
+        end
+      end
+
+      def validate_format!(entry, format)
+        output = entry[format]
+        record = entry["formats"][format]
+        unless output.is_a?(String) && record.is_a?(Hash) &&
+            record.keys.all?(String) &&
+            record.keys.sort == %w[notes status] && STATUSES.include?(record["status"])
+          raise InvalidEntryError, "#{entry['name']}/#{format}: invalid output or format metadata"
+        end
+
+        unavailable = record["status"] == "unavailable"
+        if output.strip.empty? && !unavailable
+          raise InvalidEntryError, "#{entry['name']}/#{format}: empty output must be unavailable"
+        end
+
+        validate_notes!(record["notes"], format, required: record["status"] != "available")
+      end
+
+      def present_string?(value)
+        value.is_a?(String) && !value.strip.empty?
+      end
+
+      private_class_method :validate_function!, :validate_format!, :present_string?
+    end
+  end
+end

data/lib/plurimath/catalog.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Plurimath
+  # The documented symbol/function catalog that plurimath.org generates its
+  # reference pages from. Each entry carries a name, a type, and the example
+  # rendered to AsciiMath, LaTeX, MathML and OMML; function entries also carry a
+  # description and reference. See Plurimath::Documentation (functions) and
+  # Plurimath::SymbolDocumentation (symbols).
+  #
+  #   Plurimath::Catalog.entries.each do |e|
+  #     dir = e["type"] == "symbol" ? "symbols" : "functions"
+  #     File.write("_data/#{dir}/#{e['name']}.yaml", e.to_yaml)
+  #   end
+  module Catalog
+    autoload :Entry, "plurimath/catalog/entry"
+    autoload :Validation, "plurimath/catalog/validation"
+
+    class InvalidEntryError < ArgumentError; end
+
+    module_function
+
+    # Every documented class, sorted by catalog name — with catalog type as a
+    # tiebreaker, since a symbol and a function can share a name (e.g. `bar`) —
+    # for stable, totally-ordered output.
+    # descendants_of returns a base's descendants but not the base itself, so
+    # each base is enumerated alongside them — otherwise a base that is itself
+    # documentable is missed (Table's own `table` page; Nary, which is both
+    # documentable and has no descendants). Abstract bases are dropped by
+    # documented?: the arity classes declare no example, and the Symbol and
+    # Paren bases render nothing.
+    def classes
+      ensure_documentable_classes_loaded
+      documentable_bases
+        .flat_map { |base| [base, *descendants_of(base)] }
+        .uniq
+        .select(&:documented?)
+        .sort_by { |klass| [klass.catalog_name, klass.catalog_type.to_s] }
+    end
+
+    def each(&block)
+      classes.each(&block)
+    end
+
+    # YAML-ready hashes, one per documented class.
+    def entries
+      result = classes.map(&:catalog_entry)
+      Validation.validate_all!(result)
+      result
+    end
+
+    # Base classes whose documented descendants (and the bases themselves) are
+    # catalogued: the function arities, the table/n-ary bases, and the symbol tree.
+    def documentable_bases
+      [
+        Math::Function::TernaryFunction,
+        Math::Function::BinaryFunction,
+        Math::Function::UnaryFunction,
+        Math::Function::Table,
+        Math::Function::Nary,
+        Math::Symbols::Symbol,
+      ]
+    end
+
+    # descendants only sees loaded classes, so require the source files of every
+    # documentable base before enumerating — the function tree and the symbol
+    # tree. Memoized so repeated catalog calls don't re-glob.
+    def ensure_documentable_classes_loaded
+      return if @documentable_classes_loaded
+
+      # Dir.glob/require need a filesystem; under Opal the trees are build-loaded,
+      # so skip enumeration there rather than crash (mirrors symbols.rb).
+      if RUBY_ENGINE != "opal"
+        # math/symbols.rb loads the Symbol base (and nested bases) before their
+        # subclasses; a raw sorted Dir.glob would require symbols/alpha before
+        # symbols/symbol and raise NameError. The function tree loads its bases
+        # first, so glob it directly.
+        require File.join(__dir__, "math", "symbols")
+        Dir.glob(File.join(__dir__, "math", "function", "**", "*.rb")).each do |file|
+          require file
+        end
+      end
+      @documentable_classes_loaded = true
+    end
+
+    # descendants lists only direct subclasses, so walk the whole subtree —
+    # nested families (FontStyle's styles, the Paren delimiters) live below
+    # their group base.
+    def descendants_of(klass)
+      Array(klass.descendants)
+        .flat_map { |descendant| [descendant, *descendants_of(descendant)] }
+    end
+
+    private_class_method :documentable_bases, :ensure_documentable_classes_loaded,
+                         :descendants_of
+  end
+end

data/lib/plurimath/cli/convert.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Plurimath
+  class Cli < Thor
+    # Standalone command object for `plurimath convert`. Usable on its own:
+    #   Plurimath::Cli::Convert.new(options).call
+    class Convert
+      include Helpers
+
+      def call
+        text = input_string
+        warn_and_exit("missing generator argument --input or --file-input") unless text
+
+        input_format  = options[:input_format]
+        output_format = options[:output_format]
+        configure_xml_engine(input_format, output_format)
+        formula = Plurimath::Math.parse(text, input_format)
+        return puts formula.to_display(output_format.to_sym) if options[:math_rendering].to_s == "true"
+
+        puts convert_formula(formula, output_format)
+      end
+
+      private
+
+      def convert_formula(formula, output_format)
+        display_style = options[:display_style]
+        split         = options[:split_on_linebreak]
+        style         = display_style.to_s.empty? ? "true" : display_style
+        case output_format
+        when "unicodemath" then formula.to_unicodemath
+        when "asciimath"   then formula.to_asciimath
+        when "mathml"      then formula.to_mathml(display_style: style, split_on_linebreak: split)
+        when "latex"       then formula.to_latex
+        when "omml"        then formula.to_omml(display_style: style, split_on_linebreak: split)
+        else warn_and_exit("Invalid output format: #{output_format}")
+        end
+      end
+    end
+  end
+end

data/lib/plurimath/cli/helpers.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Plurimath
+  class Cli < Thor
+    # Shared behavior for CLI command objects (Cli::Convert, Cli::Render):
+    # holds the parsed Thor +options+ and the helpers both commands need.
+    module Helpers
+      attr_reader :options
+
+      def initialize(options)
+        super()
+        @options = options
+      end
+
+      # Resolve the raw input string from either --file-path or --input.
+      def input_string
+        options[:file_path] ? File.read(options[:file_path]) : options[:input]
+      end
+
+      def configure_xml_engine(input_format, output_format)
+        xml_formats = %w[mathml omml]
+        return unless xml_formats.include?(input_format) || xml_formats.include?(output_format)
+
+        set_xml_engine(options[:xml_engine] || "ox")
+      end
+
+      def set_xml_engine(engine)
+        engine_class = case engine
+                       when "ox"
+                         require_relative "../setup/ox_engine"
+                         Plurimath::XmlEngine::OxEngine
+                       when "oga"
+                         require_relative "../setup/oga"
+                         Plurimath::XmlEngine::Oga
+                       else
+                         warn_and_exit("Invalid XML engine: #{engine}. Use 'ox' or 'oga'.")
+                       end
+        Plurimath.xml_engine = engine_class
+      end
+
+      # Print a message and exit non-zero. Uses exit(1) rather than abort so a
+      # rescued exception is not re-printed as a SystemExit cause backtrace.
+      def warn_and_exit(message)
+        warn(message)
+        exit(1)
+      end
+    end
+  end
+end