plurimath 0.11.12 → 0.11.13

data/lib/plurimath/cli/render.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Plurimath
+  class Cli < Thor
+    # Standalone command object for `plurimath render`. Usable on its own:
+    #   Plurimath::Cli::Render.new(options).call
+    class Render
+      include Helpers
+
+      def call
+        text = input_string
+        warn_and_exit("missing generator argument --input or --file-input") unless text
+
+        output_path = options[:output]
+        configure_xml_engine(options[:input_format], "mathml")
+        bytes = Plurimath::Math.render(
+          text, options[:input_format],
+          format: render_format(output_path), **render_options
+        )
+        write_render_output(bytes, output_path)
+      rescue Plurimath::Error => e
+        warn_and_exit(e.message)
+      end
+
+      private
+
+      def write_render_output(bytes, output_path)
+        return File.binwrite(output_path, bytes) if output_path
+
+        $stdout.binmode
+        $stdout.write(bytes)
+      end
+
+      # Resolve the output image format. The --output extension is authoritative
+      # for a file (so `-o x.png` always writes PNG); --format applies when there
+      # is no usable extension (stdout, or an extensionless --output); otherwise
+      # svg. Math::Renderer validates the result and raises
+      # Errors::UnsupportedRenderFormat on an unsupported value.
+      def render_format(output_path)
+        extension = File.extname(output_path.to_s).delete_prefix(".")
+        return extension.downcase.to_sym unless extension.empty?
+
+        explicit = options[:format]
+        return explicit.to_s.downcase.to_sym if explicit && !explicit.to_s.strip.empty?
+
+        :svg
+      end
+
+      # Keyword options forwarded to Plurimath::Math.render. --display-style is
+      # passed only when given, so the formula's own display style is honored by
+      # default; nil-valued numeric options are dropped.
+      def render_options
+        opts = {}
+        opts[:display_style] = options[:display_style] unless options[:display_style].nil?
+        opts[:split_on_linebreak] = options[:split_on_linebreak] unless options[:split_on_linebreak].nil?
+        Plurimath::Math::Renderer::LASEM_OPTIONS.each do |key|
+          value = options[key]
+          opts[key] = value unless value.nil?
+        end
+        opts
+      end
+    end
+  end
+end

data/lib/plurimath/cli.rb

@@ -2,8 +2,14 @@
 
 require "thor"
 require_relative "../plurimath"
+require_relative "cli/helpers"
+require_relative "cli/convert"
+require_relative "cli/render"
 
 module Plurimath
+  # Thor entry point. Declares each command's options and delegates to an
+  # independent, standalone command object (Cli::Convert / Cli::Render) that can
+  # also be used directly: `Plurimath::Cli::Render.new(options).call`.
   class Cli < Thor
     desc "convert", "Convert between math formats"
 
@@ -48,65 +54,57 @@ module Plurimath
            desc: "XML engine to use for parsing and rendering (ox or oga)"
 
     def convert
-      input          = options[:input]
-      input_string   = options[:file_path] ? File.read(options[:file_path]) : input
-      warn_and_exit("missing generator argument --input or --file-input") unless input_string
-
-      input_format   = options[:input_format]
-      output_format  = options[:output_format]
-      configure_xml_engine(input_format, output_format)
-      formula = Plurimath::Math.parse(input_string, input_format)
-      return puts formula.to_display(output_format.to_sym) if options[:math_rendering].to_s == "true"
-
-      display_style  = options[:display_style]
-      split          = options[:split_on_linebreak]
-      style          = display_style.to_s.empty? ? "true" : display_style
-      output_text = case output_format
-                    when "unicodemath"
-                      formula.to_unicodemath
-                    when "asciimath"
-                      formula.to_asciimath
-                    when "mathml"
-                      formula.to_mathml(display_style: style,
-                                        split_on_linebreak: split)
-                    when "latex"
-                      formula.to_latex
-                    when "omml"
-                      formula.to_omml(display_style: style,
-                                      split_on_linebreak: split)
-                    else
-                      warn_and_exit("Invalid output format: #{output_format}")
-                    end
-
-      puts output_text
+      Convert.new(options).call
     end
 
-    no_commands do
-      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])
-      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
-
-      def warn_and_exit(message)
-        warn(message)
-        abort
-      end
+    desc "render", "Render math to an image (svg/png/pdf/ps) via the optional lasem gem"
+
+    option :input,
+           aliases: "-i",
+           desc: "Input value should be in quoted string"
+
+    option :input_format,
+           aliases: "-f",
+           default: "asciimath",
+           desc: "Input format should be in quoted string => \"asciimath\""
+
+    option :file_path,
+           aliases: "-p",
+           desc: "Reads input from a file instead of the command line input. Use this for larger inputs or when input contains special characters.",
+           force: :boolean
+
+    option :output,
+           aliases: "-o",
+           desc: "Output file path; the image format is taken from its extension (.svg/.png/.pdf/.ps). When omitted, the rendered bytes are written to stdout."
+
+    option :format,
+           aliases: "-r",
+           desc: "Image format (svg, png, pdf, ps). Used for stdout or when --output has no usable extension; a file's extension takes precedence. Defaults to svg."
+
+    option :display_style,
+           aliases: "-d",
+           desc: "DisplayStyle, Boolean only. Defaults to the parsed formula's display style.",
+           force: :boolean
+
+    option :split_on_linebreak,
+           aliases: "-s",
+           desc: "Splits into multiple equations. Note: lasem renders a single MathML document.",
+           force: :boolean
+
+    option :ppi, type: :numeric, desc: "Pixels per inch for raster output (lasem)"
+    option :zoom, type: :numeric, desc: "Render scale factor (lasem)"
+    option :width, type: :numeric, desc: "Explicit output width (lasem)"
+    option :height, type: :numeric, desc: "Explicit output height (lasem)"
+    option :offset_x, type: :numeric, desc: "Horizontal offset (lasem)"
+    option :offset_y, type: :numeric, desc: "Vertical offset (lasem)"
+
+    option :xml_engine,
+           aliases: "-e",
+           default: "ox",
+           desc: "XML engine to use for parsing and rendering (ox or oga)"
+
+    def render
+      Render.new(options).call
     end
   end
 end

data/lib/plurimath/documentation.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Plurimath
+  # Per-class documentation metadata for the function side of the catalog
+  # (see Plurimath::Catalog, which powers the plurimath.org "Functions" and
+  # "Symbols" pages). A documentable base class extends this module —
+  # TernaryFunction, BinaryFunction, UnaryFunction, Table, and Nary — and every
+  # descendant then inherits the shared, derivable machinery (name, type, the
+  # four renderings) while each concrete class "explains itself" with three
+  # declarations: DESCRIPTION, REFERENCE, and an EXAMPLE lambda. Table and Nary
+  # are themselves documented (the /functions/table and /functions/n-ary pages),
+  # not just bases. Symbols are documented separately by
+  # Plurimath::SymbolDocumentation, which derives everything.
+  module Documentation
+    # Slug for the /functions/<name>/ page and YAML filename, matching the
+    # lowercased, separator-free convention the site already uses:
+    # Sum -> "sum", PowerBase -> "powerbase". A class whose page slug can't be
+    # derived from its name declares CATALOG_NAME to override it (Nary ->
+    # "n-ary").
+    def catalog_name
+      declared_constant(:CATALOG_NAME) || name.split("::").last.downcase
+    end
+
+    # :unary / :binary / :ternary — declared once per base and inherited by
+    # every descendant.
+    def catalog_type
+      declared_constant(:CATALOG_TYPE, inherit: true)
+    end
+
+    def catalog_kind
+      :function
+    end
+
+    # The reference-page grouping, not the Ruby constructor's parameter count.
+    def catalog_arity
+      catalog_type
+    end
+
+    def description
+      declared_constant(:DESCRIPTION)
+    end
+
+    def reference
+      declared_constant(:REFERENCE)
+    end
+
+    # Builds the example fresh from the class's EXAMPLE lambda. Because EXAMPLE
+    # is deferred, nothing is constructed — and no sibling class referenced —
+    # until the catalog is generated. nil when the class declares no example.
+    def example_formula
+      block = declared_constant(:EXAMPLE)
+      return unless block
+
+      result = instance_exec(&block)
+      case result
+      when Math::Formula then result   # lambda already built one — don't re-wrap
+      when Array then expr(*result)    # splat a multi-part example
+      else expr(result)                # wrap a bare node
+      end
+    end
+
+    # Catalogued only when a class carries the full three-declaration contract —
+    # description, reference and example — so partially-documented classes never
+    # leak into the output.
+    def documented?
+      !name.nil? && !description.nil? && !reference.nil? &&
+        !declared_constant(:EXAMPLE).nil?
+    end
+
+    # The YAML-ready entry the docs consume: metadata plus the example rendered
+    # to every target format.
+    def catalog_entry
+      Catalog::Entry.build(
+        name: catalog_name, type: catalog_type, kind: catalog_kind,
+        arity: catalog_arity, description: description, reference: reference,
+        formula: example_formula,
+        limitations: declared_constant(:CATALOG_FORMAT_LIMITATIONS) || {}
+      )
+    end
+
+    private
+
+    # Reads an own constant (or an inherited one when inherit: true), else nil.
+    def declared_constant(name, inherit: false)
+      const_get(name, inherit) if const_defined?(name, inherit)
+    end
+
+    # Constructor helpers: sym() keeps the EXAMPLE lambda bodies readable, and
+    # expr() wraps each example result in a Formula (used by example_formula and
+    # available to lambdas that build multi-part examples).
+    def sym(value)
+      Math::Symbols::Symbol.new(value)
+    end
+
+    def expr(*parts)
+      Math::Formula.new(parts)
+    end
+  end
+end

data/lib/plurimath/errors/ambiguous_decimal_error.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Math
+    # An AsciiMath uncertainty call whose comma could be a decimal comma under
+    # the active locale. A ParseError, so Plurimath::Math.parse passes it on
+    # with its message intact.
+    class AmbiguousDecimalError < ParseError
+      def initialize(detail)
+        @detail = detail
+        super(detail, :asciimath)
+      end
+
+      def parsing_message
+        "[plurimath] #{@detail}"
+      end
+    end
+  end
+end

data/lib/plurimath/errors/invalid_uncertainty.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Errors
+    # Raised when an uncertainty (Math::Function::Uncertainty) is built from
+    # fields that do not form a valid reported result.
+    class InvalidUncertainty < Plurimath::Error
+      def initialize(detail)
+        @detail = detail
+        super(message)
+      end
+
+      def message
+        "[plurimath] Invalid uncertainty: #{@detail}."
+      end
+    end
+  end
+end

data/lib/plurimath/errors/missing_dependency_error.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Math
+    # Raised when a format's parser needs a gem that cannot be loaded. It is
+    # a ParseError, so Math.parse passes it through with this message instead
+    # of the generic one, and callers rescuing ParseError still catch it.
+    class MissingDependencyError < ParseError
+      def initialize(type, format_name:, gem_name:, gemfile_line:)
+        @format_name = format_name
+        @gem_name = gem_name
+        @gemfile_line = gemfile_line
+        super(nil, type)
+      end
+
+      def parsing_message
+        "[plurimath] #{@format_name} parsing needs the #{@gem_name} gem, " \
+          "which could not be loaded; add #{@gemfile_line} to your Gemfile " \
+          "and run `bundle install`."
+      end
+    end
+  end
+end

data/lib/plurimath/errors/rendering_failed.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Errors
+    class RenderingFailed < Plurimath::Error
+      def initialize(format, cause)
+        @format = format
+        @failure = cause
+        super(message)
+      end
+
+      def message
+        "[plurimath] Failed to render MathML to #{@format}: #{@failure.message}."
+      end
+    end
+  end
+end

data/lib/plurimath/errors/rendering_unavailable.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Errors
+    class RenderingUnavailable < Plurimath::Error
+      def initialize(load_error = nil)
+        @load_error = load_error
+        super(message)
+      end
+
+      def message
+        text =
+          "[plurimath] Image rendering requires the optional `lasem` gem with " \
+          "its native extension, which is unavailable here (it is never " \
+          "available under Opal/plurimath-js). Add `gem \"lasem\"` to your " \
+          "Gemfile, then run `bundle exec lasem-doctor` to diagnose missing " \
+          "system libraries (cairo, pango, the Lasem C library) and rebuild " \
+          "the extension."
+        return text unless @load_error
+
+        "#{text} Underlying load error: #{@load_error.message}"
+      end
+    end
+  end
+end

data/lib/plurimath/errors/unsupported_render_format.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Errors
+    class UnsupportedRenderFormat < Plurimath::Error
+      def initialize(format, supported)
+        @format = format
+        @supported = supported.map(&:inspect).join(", ")
+        super(message)
+      end
+
+      def message
+        "[plurimath] Unsupported render format #{@format.inspect}. " \
+          "Supported formats are: #{@supported}."
+      end
+    end
+  end
+end

data/lib/plurimath/errors/unsupported_semantic_tree_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Errors
+    # A display-only diagnostic; numeric evaluation has its own error contract.
+    class UnsupportedSemanticTreeError < Plurimath::Error
+      def initialize(construct)
+        super("Unsupported semantic tree construct: #{construct}")
+      end
+    end
+  end
+end

data/lib/plurimath/errors.rb

@@ -3,8 +3,13 @@
 module Plurimath
   module Errors
     autoload :Evaluation, "#{__dir__}/errors/evaluation"
+    autoload :UnsupportedSemanticTreeError, "#{__dir__}/errors/unsupported_semantic_tree_error"
     autoload :InvalidNumber, "#{__dir__}/errors/invalid_number"
+    autoload :RenderingFailed, "#{__dir__}/errors/rendering_failed"
+    autoload :RenderingUnavailable, "#{__dir__}/errors/rendering_unavailable"
+    autoload :InvalidUncertainty, "#{__dir__}/errors/invalid_uncertainty"
     autoload :UnsupportedBase, "#{__dir__}/errors/unsupported_base"
     autoload :UnsupportedLocale, "#{__dir__}/errors/unsupported_locale"
+    autoload :UnsupportedRenderFormat, "#{__dir__}/errors/unsupported_render_format"
   end
 end

data/lib/plurimath/math/evaluation/evaluator.rb

@@ -54,6 +54,54 @@ module Plurimath
           bindings[name]
         end
 
+        # ExpressionParser delegates its folds to a backend. These operations
+        # retain the numeric contract; the semantic display uses the same
+        # precedence ladder with a backend that only builds a render view.
+        def normalize_tokens(tokens)
+          tokens
+        end
+
+        def relation_operator?(_node)
+          false
+        end
+
+        def add(left, right)
+          left + right
+        end
+
+        def subtract(left, right)
+          left - right
+        end
+
+        def multiply(left, right, implicit:)
+          left * right
+        end
+
+        def positive(value)
+          value
+        end
+
+        def negate(value)
+          -value
+        end
+
+        def negated_mod(node)
+          node.evaluate_negated(self)
+        end
+
+        def group(value)
+          value
+        end
+
+        def nary_function?(node)
+          (node.is_a?(Function::Sum) || node.is_a?(Function::Prod)) &&
+            node.parameter_one && node.parameter_two
+        end
+
+        def log_argument(node, argument)
+          real_result(node.evaluate_with_argument(self, argument))
+        end
+
         def divide(dividend, divisor)
           raise Errors::Evaluation::DivisionByZeroError if divisor.zero?
 

data/lib/plurimath/math/evaluation/expression_parser.rb

@@ -4,22 +4,23 @@ module Plurimath
   module Math
     module Evaluation
       # Resolves operator precedence over the flat token sequences stored in
-      # Formula#value, delegating node evaluation back to the evaluator.
+      # Formula#value, delegating operands and folds to a backend. The numeric
+      # evaluator computes values; the semantic display builds a transient view.
       #
       # Standard recursive-descent precedence ladder — each level parses its
       # operands at the next-tighter level, so the operands of `+`/`-` are
       # whole multiplicative expressions, and so on down to single operands:
-      #   parse_additive -> parse_multiplicative -> parse_unary
+      #   parse_relation -> parse_additive -> parse_multiplicative -> parse_unary
       #     -> parse_power -> parse_operand
       class ExpressionParser
         def initialize(evaluator, tokens)
           @evaluator = evaluator
-          @tokens = tokens
+          @tokens = evaluator.normalize_tokens(tokens)
           @index = 0
         end
 
         def parse
-          result = parse_additive
+          result = parse_relation
           evaluator.unsupported(current) unless eof?
 
           result
@@ -29,13 +30,22 @@ module Plurimath
 
         attr_reader :evaluator, :tokens
 
+        def parse_relation
+          result = parse_additive
+          while evaluator.relation_operator?(current)
+            operator = next_token
+            result = evaluator.relation(operator, result, parse_additive)
+          end
+          result
+        end
+
         def parse_additive
           result = parse_multiplicative
           loop do
             if take?(:plus_operator?)
-              result += parse_multiplicative
+              result = evaluator.add(result, parse_multiplicative)
             elsif take?(:minus_operator?)
-              result -= parse_multiplicative
+              result = evaluator.subtract(result, parse_multiplicative)
             else
               break result
             end
@@ -46,11 +56,11 @@ module Plurimath
           result = parse_unary
           loop do
             if take?(:multiply_operator?)
-              result *= parse_unary
+              result = evaluator.multiply(result, parse_unary, implicit: false)
             elsif take?(:divide_operator?)
               result = evaluator.divide(result, parse_unary)
             elsif implicit_multiplication?
-              result *= parse_power
+              result = evaluator.multiply(result, parse_power, implicit: true)
             else
               break result
             end
@@ -59,7 +69,7 @@ module Plurimath
 
         def parse_unary
           if take?(:plus_operator?)
-            parse_unary
+            evaluator.positive(parse_unary)
           elsif take?(:minus_operator?)
             negated_unary
           else
@@ -70,9 +80,9 @@ module Plurimath
         # Unary minus binds tighter than `mod`, so `-7 mod 3` negates the
         # dividend, not the result: `(-7) mod 3 == 2`, not `-(7 mod 3)`.
         def negated_unary
-          return next_token.evaluate_negated(evaluator) if current.is_a?(Function::Mod)
+          return evaluator.negated_mod(next_token) if current.is_a?(Function::Mod)
 
-          -parse_unary
+          evaluator.negate(parse_unary)
         end
 
         # Chained powers evaluate left-to-right, matching the left-nested
@@ -85,7 +95,7 @@ module Plurimath
 
         def parse_exponent
           if take?(:plus_operator?)
-            parse_exponent
+            evaluator.positive(parse_exponent)
           elsif take?(:minus_operator?)
             negated_exponent
           else
@@ -94,9 +104,9 @@ module Plurimath
         end
 
         def negated_exponent
-          return next_token.evaluate_negated(evaluator) if current.is_a?(Function::Mod)
+          return evaluator.negated_mod(next_token) if current.is_a?(Function::Mod)
 
-          -parse_exponent
+          evaluator.negate(parse_exponent)
         end
 
         def parse_operand
@@ -115,11 +125,11 @@ module Plurimath
         # "unmatched parenthesis" is reserved for true end-of-input.
         def parse_group
           advance
-          result = parse_additive
+          result = parse_relation
           evaluator.unsupported(current || "unmatched parenthesis") unless close_paren?(current)
 
           advance
-          result
+          evaluator.group(result)
         end
 
         # Unary functions and `log` parse separately from their argument in
@@ -137,9 +147,8 @@ module Plurimath
         # the following sibling token; AsciiMath binds a single operand as the
         # body, so we match by adopting the next operand as parameter_three.
         def nary_body?(node)
-          (node.is_a?(Function::Sum) || node.is_a?(Function::Prod)) &&
+          evaluator.nary_function?(node) &&
             node.parameter_three.nil? &&
-            node.parameter_one && node.parameter_two &&
             !eof? && operand_start?(current)
         end
 
@@ -157,7 +166,7 @@ module Plurimath
         end
 
         def bind_log_argument(node)
-          evaluator.real_result(node.evaluate_with_argument(evaluator, next_token))
+          evaluator.log_argument(node, next_token)
         end
 
         # Adjacent operands multiply by juxtaposition (`2a`, `2(a+b)`), except
@@ -169,7 +178,7 @@ module Plurimath
         end
 
         def operand_start?(node)
-          return false if node.nil? || node.operator?
+          return false if node.nil? || node.operator? || evaluator.relation_operator?(node)
 
           !close_paren?(node)
         end