asciichem 0.28.2 → 0.29.1

data/lib/asciichem/engine/parsanol_engine.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+# Opt-in soft dependency: fail with guidance, never silently.
+begin
+  require 'parsanol/parslet'
+  # parsanol-ruby 1.3.16's native.rb references
+  # Parsanol::Native::Dynamic from the serializer without loading it
+  # (parsanol-ruby#25).
+  require 'parsanol/native/dynamic'
+rescue LoadError => e
+  raise AsciiChem::Engine::NotAvailableError,
+        'the parsanol engine requires the parsanol gem — add gem "parsanol", "~> 1.3.16" ' \
+        "to your Gemfile (#{e.message})"
+end
+
+module AsciiChem
+  module Engine
+    # The Parsanol engine: the SAME rules (GrammarRules /
+    # TransformRules) over Parsanol's Rust-backed parslet-compat
+    # layer. Corpus-identical to :parslet (221/221 byte-for-byte,
+    # benchmarks/parsanol_recheck.rb) at ~3x parse speed.
+    class ParsanolEngine
+      # Backend twins of the reference classes; the shared rules
+      # modules are the single source of grammar truth.
+      class Grammar < ::Parsanol::Parslet::Parser
+        include AsciiChem::GrammarRules
+      end
+
+      # Transform twin; #apply normalizes the engine's merged sibling
+      # captures before the shared rules run (see split_merged_formula).
+      class Transform < ::Parsanol::Parslet::Transform
+        include AsciiChem::TransformRules
+
+        # Engine divergence seam: parslet yields repeated sibling
+        # node captures as an array of single-key hashes; parsanol
+        # merges them into one hash, which no rule can match. Split
+        # the merged form back before the shared rules run, so the
+        # rules stay engine-agnostic (single source of truth).
+        def apply(tree, context = nil)
+          super(ParsanolEngine.split_merged_formula(tree), context)
+        end
+      end
+
+      class << self
+        # NODE_STARTERS mirrors the grammar's `node` alternatives
+        # (grammar_rules.rb): the capture key each alternative
+        # produces FIRST. A new node group begins at each starter;
+        # continuation keys (arrow/products, coefficient/annotations,
+        # crystal_name/params/body, ...) attach to the current group.
+        NODE_STARTERS = %i[
+          cascade reactants electron_config crystal_node spectrum_node
+          calc_node zmatrix_node mechanism_node mol units math_source text_run
+        ].freeze
+
+        # Grammar truth: a molecule node is {coefficient? stereo? units}
+        # — coefficient/stereo may LEGITIMATELY precede :units in one
+        # node. They are prefixes, not new-node markers.
+        PREFIX_KEYS = %i[coefficient stereo].freeze
+
+        def split_merged_formula(node)
+          case node
+          when Hash
+            node.to_h { |key, value| [key, split_formula_value(key, value)] }
+          when Array
+            node.map { |member| split_merged_formula(member) }
+          else
+            node
+          end
+        end
+
+        def grammar
+          Grammar
+        end
+
+        def transform
+          Transform
+        end
+
+        def parse_failed
+          ::Parsanol::ParseFailed
+        end
+
+        def grammar_instance
+          @grammar_instance ||= grammar.new
+        end
+
+        def transform_instance
+          @transform_instance ||= transform.new
+        end
+
+        private
+
+        def split_formula_value(key, value)
+          if key == :formula && value.is_a?(Hash) && value.length > 1
+            groups = []
+            value.each do |k, v|
+              groups << {} if new_group?(groups, k)
+              groups.last[k] = split_merged_formula(v)
+            end
+            groups.length == 1 ? groups.first : groups
+          else
+            split_merged_formula(value)
+          end
+        end
+
+        def new_group?(groups, key)
+          return true if groups.empty?
+
+          return false unless NODE_STARTERS.include?(key)
+
+          # :units continues a group that so far holds only molecule
+          # prefixes ({coefficient:...} / {stereo:...}).
+          !(key == :units && groups.last.keys.all? { |pk| PREFIX_KEYS.include?(pk) })
+        end
+      end
+    end
+  end
+end

data/lib/asciichem/engine/parslet_engine.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Engine
+    # The reference engine: pure-Ruby parslet. Zero extra
+    # dependencies; Grammar and Transform as always.
+    class ParsletEngine
+      class << self
+        def grammar
+          Grammar
+        end
+
+        def transform
+          Transform
+        end
+
+        def parse_failed
+          Parslet::ParseFailed
+        end
+
+        # Engines memoize their grammar/transform instances — they are
+        # stateless and expensive to construct (benchmark: ~15%
+        # throughput on repeated parses).
+        def grammar_instance
+          @grammar_instance ||= grammar.new
+        end
+
+        def transform_instance
+          @transform_instance ||= transform.new
+        end
+      end
+    end
+  end
+end

data/lib/asciichem/engine.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  # Parsing engine selector (TODO.impl 63/64; parsanol-ruby#25).
+  #
+  # The reference engine is :parslet (pure Ruby, zero extra
+  # dependencies) and remains the default. The :parsanol engine runs
+  # the SAME rules (GrammarRules/TransformRules) over Parsanol's
+  # Rust-backed parslet-compat layer — the shared corpus passes
+  # byte-for-byte (221/221) at ~3x parslet speed.
+  #
+  # Parsanol is an opt-in soft dependency; the gemspec is unchanged:
+  #
+  #   # Gemfile
+  #   gem "parsanol", "~> 1.3.16"
+  #
+  #   require "asciichem/engine/parsanol_engine"
+  #   AsciiChem::Engine.use(:parsanol)
+  #   AsciiChem.parse("H_2O")   # parsed by the Rust core
+  #
+  # The active engine may also be selected via ASCIICHEM_ENGINE
+  # (a testing seam, mirroring ASCIICHEM_CORPUS):
+  #
+  #   ASCIICHEM_ENGINE=parsanol bundle exec rspec
+  #
+  module Engine
+    class Error < AsciiChem::Error; end
+
+    # The named engine exists but its gem is not installed.
+    class NotAvailableError < Error; end
+
+    autoload :ParsletEngine, 'asciichem/engine/parslet_engine'
+    autoload :ParsanolEngine, 'asciichem/engine/parsanol_engine'
+
+    class << self
+      # Selects the engine by name. Returns the engine class.
+      def use(name)
+        @current = engine_for(name)
+      end
+
+      # The active engine. Defaults to :parslet, overridable once via
+      # ASCIICHEM_ENGINE at first use.
+      def current
+        @current ||= engine_for(ENV.fetch('ASCIICHEM_ENGINE', 'parslet'))
+      end
+
+      private
+
+      def engine_for(name)
+        case name.to_s
+        when 'parslet' then ParsletEngine
+        when 'parsanol' then ParsanolEngine
+        else
+          raise Error, "unknown engine #{name.inspect} (available: parslet, parsanol)"
+        end
+      end
+    end
+  end
+end

data/lib/asciichem/grammar.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "parslet"
+require 'parslet'
 
 module AsciiChem
   # Parslet grammar for AsciiChem v1.
@@ -17,461 +17,6 @@ module AsciiChem
   #   ONLY the value, not the leading `_` or `^`. The literal prefix is
   #   consumed by the rule but not included in the named capture.
   class Grammar < Parslet::Parser
-    root :formula
-
-    # -- top level ---------------------------------------------------------
-
-    rule(:formula) do
-      spaces? >> nodes.as(:formula) >> spaces?
-    end
-
-    rule(:nodes) { node >> (spaces? >> node).repeat }
-
-    rule(:node)  { reaction_cascade | reaction | electron_config | crystal | spectrum | calculation | zmatrix | mechanism | annotated_molecule | molecule | embedded_math | text_run.as(:text_run) }
-
-    # -- crystallography -------------------------------------------------
-
-    # crystal[Name](a=X,b=Y,...,sg=SG){atoms with @f(x,y,z)}
-    rule(:crystal) do
-      (str('crystal') >>
-        crystal_name.maybe >>
-        crystal_params.maybe >>
-        crystal_body.maybe).as(:crystal_node)
-    end
-
-    rule(:crystal_name) do
-      str('[') >> (str(']').absent? >> any).repeat.as(:crystal_name) >> str(']')
-    end
-
-    rule(:crystal_params) do
-      str('(') >> (str(')').absent? >> any).repeat.as(:crystal_params) >> str(')')
-    end
-
-    rule(:crystal_body) do
-      str('{') >> (str('}').absent? >> any).repeat.as(:crystal_body) >> str('}')
-    end
-
-    # -- spectroscopy ---------------------------------------------------
-
-    # spectrum[type](params){peak data}
-    rule(:spectrum) do
-        (str('spectrum') >>
-        spectrum_type.maybe >>
-        spectrum_params.maybe >>
-        spectrum_body.maybe).as(:spectrum_node)
-    end
-
-    rule(:spectrum_type) do
-      str('[') >> (str(']').absent? >> any).repeat.as(:spectrum_type) >> str(']')
-    end
-
-    rule(:spectrum_params) do
-      str('(') >> (str(')').absent? >> any).repeat.as(:spectrum_params) >> str(')')
-    end
-
-    rule(:spectrum_body) do
-      str('{') >> (str('}').absent? >> any).repeat.as(:spectrum_body) >> str('}')
-    end
-
-    # -- computational chemistry ----------------------------------------
-
-    # calc(method/basis){key: value units}
-    rule(:calculation) do
-      (str('calc') >>
-        calc_params.maybe >>
-        calc_body.maybe).as(:calc_node)
-    end
-
-    rule(:calc_params) do
-      str('(') >> (str(')').absent? >> any).repeat.as(:calc_params) >> str(')')
-    end
-
-    rule(:calc_body) do
-      str('{') >> (str('}').absent? >> any).repeat.as(:calc_body) >> str('}')
-    end
-
-    # -- Z-Matrix -------------------------------------------------------
-
-    rule(:zmatrix) do
-      (str('zmatrix') >>
-        zmatrix_body.maybe).as(:zmatrix_node)
-    end
-
-    rule(:zmatrix_body) do
-      str('{') >> (str('}').absent? >> any).repeat.as(:zmatrix_body) >> str('}')
-    end
-
-    # -- reaction mechanisms --------------------------------------------
-
-    rule(:mechanism) do
-      (str('mechanism') >>
-        mechanism_body.maybe).as(:mechanism_node)
-    end
-
-    rule(:mechanism_body) do
-      str('{') >> (str('}').absent? >> any).repeat.as(:mechanism_body) >> str('}')
-    end
-
-    # Annotated molecule: a molecule followed by one or more
-    # `@key("value")` annotations for CML metadata (names,
-    # identifiers, title, formula, labels).
-    rule(:annotated_molecule) do
-      molecule.as(:mol) >> molecule_annotation.repeat(1).as(:annotations)
-    end
-
-    rule(:molecule_annotation) do
-      spaces?.maybe >>
-      (metadata_annotation | simple_annotation)
-    end
-
-    # Metadata: @meta("key","value") — two quoted args, comma-separated.
-    # Produces CML <metadata name="key" content="value"/>.
-    # Uses distinct capture keys (meta_key/meta_value) so the transform
-    # can distinguish metadata from regular @key("value") annotations.
-    rule(:metadata_annotation) do
-      str('@meta(') >> str('"') >>
-      (str('"').absent? >> any).repeat.as(:meta_key) >> str('"') >>
-      str(',') >> str('"') >>
-      (str('"').absent? >> any).repeat.as(:meta_value) >> str('"') >>
-      str(')')
-    end
-
-    # Simple annotation: @key("value") — one quoted arg.
-    # Known types (name, inchi, etc.) are handled specially by the
-    # transform. Unknown types become properties.
-    rule(:simple_annotation) do
-      str('@') >> annotation_type.as(:ann_type) >>
-      str('(') >> str('"') >>
-      (str('"').absent? >> any).repeat.as(:ann_value) >>
-      str('"') >> str(')')
-    end
-
-    # Known annotation types first; property_name is a catch-all so
-    # any lowercase word (e.g. "mw", "density", "logP") becomes a
-    # property annotation.
-    rule(:annotation_type) do
-      str('name') | str('title') | str('formula') | str('label') |
-      str('inchi') | str('smiles') | str('cas') | str('iupac') |
-      str('cid') | str('chebi') |
-      property_name
-    end
-
-    rule(:property_name) do
-      match('[a-z]').repeat(1)
-    end
-
-    # -- reactions ---------------------------------------------------------
-
-    # A reaction cascade is two or more reactions chained together:
-    # the products of step N become the reactants of step N+1, with
-    # an arrow between them. The grammar reuses `reaction` for the
-    # first leg and `arrow >> terms` for each subsequent leg; the
-    # transform promotes the whole chain to a `ReactionCascade`.
-    rule(:reaction_cascade) do
-      (reaction.as(:first) >>
-        (arrow.as(:arrow) >> spaces? >> terms.as(:products)).repeat(1)).as(:cascade)
-    end
-
-    rule(:reaction) do
-      terms.as(:reactants) >>
-        arrow.as(:arrow) >>
-        spaces? >>
-        terms.as(:products)
-    end
-
-    rule(:terms) do
-      molecule >> (spaces? >> plus >> spaces? >> molecule).repeat
-    end
-
-    rule(:plus) { str("+") }
-
-    rule(:arrow) do
-      spaces? >>
-        arrow_token.as(:kind) >>
-        condition.maybe.as(:above) >>
-        condition.maybe.as(:below)
-    end
-
-    rule(:condition) do
-      str("[") >> (str("]").absent? >> any).repeat.as(:text) >> str("]")
-    end
-
-    rule(:arrow_token) do
-      str("<=>") | str("<->") | str("->") | str("<-")
-    end
-
-    # -- molecules ---------------------------------------------------------
-
-    rule(:molecule) do
-      stereo_prefix.maybe >> coefficient.maybe >> units.as(:units)
-    end
-
-    # Stereochemistry prefix: `(R)-`, `(S)-`, `(E)-`, `(Z)-`,
-    # `(a)-`/`(α)-` (alpha), `(b)-`/`(β)-` (beta). Tried before
-    # `coefficient` so the lookahead-via-failure on the closed letter
-    # set disambiguates from a parenthesised group: `(R)` matches
-    # because `R` is in the stereo set; `(OH)` fails because `OH` is
-    # not a single stereo letter, and the molecule rule falls through
-    # to the regular group parse.
-    rule(:stereo_prefix) do
-      str("(") >> stereo_letter.as(:stereo) >> str(")") >> str("-")
-    end
-
-    rule(:stereo_letter) do
-      str("alpha") | str("beta") |
-        str("R") | str("S") | str("E") | str("Z") |
-        str("α") | str("β") |
-        str("a") | str("b")
-    end
-
-    rule(:units) { (unit | bond).repeat(1) }
-    rule(:unit)  { prefixed_atom | group | hydrogen_atom | plain_atom }
-
-    # Hydrogen special case: H cannot form ring closures (only 1 bond),
-    # so bare digits after H are unambiguously subscripts. This lets
-    # users write `H2O` instead of `H_2O` for the common formula case
-    # without conflicting with SMILES-style ring closures on other
-    # elements (`C1-C-C1` is still cyclohexane-style).
-    #
-    # The `match('[a-z]').absent?` lookahead prevents this rule from
-    # stealing the H from `He`, `Ho`, etc. — those fall through to
-    # plain_atom which matches the full element symbol greedily.
-    rule(:hydrogen_atom) do
-      (lewis_prefix.maybe >>
-        str('H').as(:element) >>
-        match('[a-z]').absent? >>
-        h_subscript.maybe.as(:subscript) >>
-        superscript_marker.maybe.as(:superscript) >>
-        lewis_radicals.maybe >>
-        atom_annotation).as(:atom)
-    end
-
-    # Subscript on hydrogen: explicit `_digits` OR bare `digits`
-    # (implicit). Both produce the same `:subscript` capture. Bare
-    # digits are safe here because H can't ring-close.
-    rule(:h_subscript) do
-      (str('_') >> subscript_value) | digits
-    end
-
-    # Bonds appear inside molecules as separators between units.
-    # Supported kinds, in alternation order (longest match first to
-    # avoid `>-` shadowing `-`):
-    #   single    `-`
-    #   double    `=`
-    #   triple    `#`
-    #   quadruple `##`
-    #   wedge     `>-`  (solid wedge toward viewer)
-    #   hash      `-<`  (hashed wedge away from viewer)
-    #   dative    `~>`  (electron-pair donor → acceptor; `->` is taken
-    #                    by the reaction arrow)
-    #   wavy      `~~`  (resonance / delocalised)
-    rule(:bond) do
-      str("##").as(:quadruple) |
-        str(">-").as(:wedge) |
-        str("-<").as(:hash) |
-        str("~>").as(:dative) |
-        str("~~").as(:wavy) |
-        str("#").as(:triple) |
-        str("=").as(:double) |
-        str("-").as(:single)
-    end
-
-    rule(:coefficient) do
-      (digits.as(:value) >> (element_symbol | open_bracket).present?).as(:coefficient)
-    end
-
-    rule(:open_bracket) { str("(") | str("[") | str("{") }
-
-    # -- atoms -------------------------------------------------------------
-
-    rule(:prefixed_atom) do
-      (lewis_prefix.maybe >>
-        isotope_marker.as(:isotope) >>
-        element_symbol.as(:element) >>
-        atom_suffix >>
-        lewis_radicals.maybe >>
-        ring_closures.maybe.as(:ring_closures) >>
-        atom_annotation).as(:atom)
-    end
-
-    rule(:plain_atom) do
-      (lewis_prefix.maybe >>
-        element_symbol.as(:element) >>
-        atom_suffix >>
-        lewis_radicals.maybe >>
-        ring_closures.maybe.as(:ring_closures) >>
-        atom_annotation).as(:atom)
-    end
-
-    # Atom annotations: each is independently optional via .maybe.
-    # Order matters: @(x,y) → @R/@S → @m(N) → @t("...") → @f(x,y,z).
-    # Example: C@(10,20)@R@m(2)@t("C1")@f(0.5,0.5,0.5)
-    rule(:atom_annotation) do
-      coordinate_annotation.maybe >>
-      parity_annotation.maybe >>
-      multiplicity_annotation.maybe >>
-      atom_title_annotation.maybe >>
-      fractional_annotation.maybe
-    end
-
-    rule(:parity_annotation) do
-      str('@') >> (str('R') | str('S')).as(:atom_parity)
-    end
-
-    rule(:coordinate_annotation) do
-      str('@(') >>
-        float_number.as(:x2) >> str(',') >>
-        float_number.as(:y2) >>
-        (str(',') >> float_number.as(:z2)).maybe >>
-        str(')')
-    end
-
-    # Spin multiplicity: @m(2) for doublet, @m(1) for singlet
-    rule(:multiplicity_annotation) do
-      str('@m(') >> match('[0-9]').repeat(1).as(:spin_multiplicity) >> str(')')
-    end
-
-    # Atom title/label: @t("C1")
-    rule(:atom_title_annotation) do
-      str('@t(') >> str('"') >>
-      (str('"').absent? >> any).repeat.as(:atom_title) >>
-      str('"') >> str(')')
-    end
-
-    # Fractional coordinates (crystallographic): @f(0.5,0.25,0.75)
-    rule(:fractional_annotation) do
-      str('@f(') >>
-        float_number.as(:x_fract) >> str(',') >>
-        float_number.as(:y_fract) >> str(',') >>
-        float_number.as(:z_fract) >>
-      str(')')
-    end
-
-    rule(:float_number) do
-      str('-').maybe >> match('[0-9]').repeat(1) >> (str('.') >> match('[0-9]').repeat(0)).maybe
-    end
-
-    # Ring closure digits (SMILES-style). A digit suffix on an atom
-    # opens or closes a ring; two atoms with the same digit become
-    # bonded. Captured as a string (e.g. "1", "12") so multiple
-    # closures on one atom are preserved.
-    rule(:ring_closures) do
-      match('[0-9]').repeat(1)
-    end
-
-    rule(:atom_suffix) do
-      subscript_marker.maybe.as(:subscript) >>
-        superscript_marker.maybe.as(:superscript)
-    end
-
-    # Lewis markers. Prefix `:` count = lone_pairs (binds to following
-    # atom, like the isotope prefix). Suffix `.` count = radical
-    # electrons. Position-specific lone pairs (`:O:` style) collapse
-    # into a total count — the renderer decides layout.
-    rule(:lewis_prefix) { str(":").repeat(1).as(:lone_pairs) }
-    rule(:lewis_radicals) { str(".").repeat(1).as(:radical_electrons) }
-
-    # Markers consume the leading `_` / `^` but capture only the value.
-    rule(:isotope_marker) do
-      (str("^") | str("_")) >> digits
-    end
-
-    rule(:subscript_marker) do
-      str("_") >> subscript_value
-    end
-
-    rule(:superscript_marker) do
-      str("^") >> superscript_value
-    end
-
-    rule(:element_symbol) do
-      match("[A-Z]") >> match("[a-z]").maybe
-    end
-
-    rule(:subscript_value) do
-      (str("{") >> (str("}").absent? >> any).repeat >> str("}")) |
-        digits
-    end
-
-    rule(:superscript_value) do
-      oxidation_state | charge | braced_or_bare
-    end
-
-    rule(:charge) do
-      (digits >> match("[+-]")) |
-        (match("[+-]") >> digits.maybe) |
-        digits
-    end
-
-    rule(:oxidation_state) do
-      str("(") >> roman_numeral >> str(")")
-    end
-
-    rule(:roman_numeral) { match("[IVXLCDM]").repeat(1) }
-
-    rule(:braced_or_bare) do
-      (str("{") >> (str("}").absent? >> any).repeat >> str("}")) |
-        match("[0-9a-zA-Z]").repeat(1)
-    end
-
-    # -- groups ------------------------------------------------------------
-
-    rule(:group) do
-      group_open.as(:open_bracket) >>
-        group_nodes >>
-        group_close.as(:close_bracket) >>
-        multiplicity.maybe.as(:multiplicity)
-    end
-
-    # `group_nodes` is a separate rule so we can carve out the closing
-    # bracket from `node`'s text fallback. Without this, `text_run`
-    # would consume the closing bracket and the group never terminates.
-    rule(:group_nodes) do
-      group_node.repeat(1).as(:group_nodes)
-    end
-
-    rule(:group_node) do
-      reaction | electron_config | molecule | embedded_math | group_text_run
-    end
-
-    rule(:group_text_run) do
-      str('"') >> (str('"').absent? >> any).repeat >> str('"')
-    end
-
-    rule(:group_open)  { str("(") | str("[") | str("{") }
-    rule(:group_close) { str(")") | str("]") | str("}") }
-
-    rule(:multiplicity) { str("_") >> digits }
-
-    # -- electron configuration -------------------------------------------
-
-    rule(:electron_config) do
-      (orbital.as(:orbital) >> str("^") >> digits.as(:occupancy) >> spaces?.maybe).repeat(2).as(:electron_config)
-    end
-
-    rule(:orbital) { digits >> match("[spdfgh]") }
-
-    # -- embedded math ----------------------------------------------------
-
-    rule(:embedded_math) do
-      str("`") >>
-        (str("`").absent? >> any).repeat.as(:math_source) >>
-        str("`")
-    end
-
-    # -- text (top level) -------------------------------------------------
-
-    # Free-form text uses `"..."` delimiters, matching AsciiMath's
-    # convention. The quoted content becomes a Text node with the
-    # surrounding quotes stripped (handled by the transform).
-    rule(:text_run) do
-      str('"') >> (str('"').absent? >> any).repeat >> str('"')
-    end
-
-    # -- primitives -------------------------------------------------------
-
-    rule(:digits)   { match("[0-9]").repeat(1) }
-    rule(:spaces)   { match(/\s/).repeat(1) }
-    rule(:spaces?)  { spaces.maybe }
+    include GrammarRules
   end
 end