asciichem 0.3.0

data/lib/asciichem/cml/translator.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "chemicalml"
+
+module AsciiChem
+  module Cml
+    # Thin composition of the AsciiChem <-> canonical adapter
+    # (`AsciiChem::ModelAdapter`) and the canonical <-> CML adapter
+    # (`Chemicalml::Cml::Translator`). Owns no chemistry logic — just
+    # wiring, the schema-registration dance that chemicalml requires
+    # on first use, and the aci: extension namespace side-channel
+    # that carries AsciiChem-specific fields through CML round-trip.
+    class Translator
+      class << self
+        # AsciiChem::Model::Formula -> CML XML string.
+        def from_asciichem(formula)
+          ensure_schema_registered!
+          translation = AsciiChem::ModelAdapter.to_canonical_with_mapping(formula)
+          wire_doc = Chemicalml::Cml::Translator.from_canonical(translation.document)
+          xml = wire_doc.to_xml
+          xml = inject_atom_extensions(xml, translation.atom_mapping)
+          xml = inject_group_extensions(xml, translation.groups)
+          inject_top_level_extensions(xml, formula)
+        end
+
+        # CML XML string -> AsciiChem::Model::Formula.
+        def to_asciichem(xml)
+          ensure_schema_registered!
+          top_level = Extensions.extract_top_level(xml)
+          atom_extensions = Extensions.extract(xml)
+          group_extensions = GroupExtensions.extract(xml)
+          wire_doc = Chemicalml::Cml::Document.from_xml(xml)
+          canonical = Chemicalml::Cml::Translator.to_canonical(wire_doc)
+          formula = AsciiChem::ModelAdapter.from_canonical(canonical)
+          Extensions.restore(formula, canonical, atom_extensions)
+          GroupExtensions.restore(formula, canonical, group_extensions)
+          Extensions.restore_top_level(formula, top_level)
+          formula
+        end
+
+        private
+
+        def inject_atom_extensions(xml, atom_mapping)
+          extensions = Extensions.collect(atom_mapping)
+          Extensions.inject(xml, extensions)
+        end
+
+        def inject_group_extensions(xml, groups_by_molecule)
+          collected = GroupExtensions.collect(groups_by_molecule)
+          GroupExtensions.inject(xml, collected)
+        end
+
+        def inject_top_level_extensions(xml, formula)
+          top_level = Extensions.collect_top_level(formula)
+          Extensions.inject_top_level(xml, top_level)
+        end
+
+        # chemicalml registers wire classes into a lutaml-model
+        # TypeRegistry on first use. The registry call is idempotent
+        # (guarded by `@models_registered`) but must run before any
+        # `from_xml` so element types like `molecule` and `atom` are
+        # resolvable.
+        def ensure_schema_registered!
+          Chemicalml::Cml::Schema3.ensure_registered!
+        end
+      end
+    end
+  end
+end

data/lib/asciichem/cml.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  # CML (Chemical Markup Language) support for AsciiChem.
+  #
+  # Bidirectional conversion between the AsciiChem text world and the
+  # CML XML world. The pipeline is:
+  #
+  #   AsciiChem::Model <-> AsciiChem::ModelAdapter <-> Chemicalml::Model
+  #                                                        ^
+  #                                                        |
+  #                                              Chemicalml::Cml::Translator
+  #                                                        |
+  #                                                        v
+  #                                              Chemicalml::Cml::* (wire)
+  #
+  # The canonical model (Chemicalml::Model) is the format-agnostic
+  # hub. AsciiChem and CML each have their own adapter; the adapters
+  # never talk to each other directly. Adding a new format (SMILES,
+  # InChI, MOL) is a new adapter — none of the existing code changes.
+  #
+  # Public API:
+  #   AsciiChem::Cml.from_asciichem(formula)  # => CML XML string
+  #   AsciiChem::Cml.parse(xml)               # => AsciiChem::Model::Formula
+  module Cml
+    autoload :Extensions, "asciichem/cml/extensions"
+    autoload :GroupExtensions, "asciichem/cml/group_extensions"
+    autoload :Translator, "asciichem/cml/translator"
+
+    # Serialise an AsciiChem::Model::Formula to CML XML.
+    def self.from_asciichem(formula)
+      Translator.from_asciichem(formula)
+    end
+
+    # Parse CML XML into an AsciiChem::Model::Formula.
+    def self.parse(xml)
+      Translator.to_asciichem(xml)
+    end
+  end
+end

data/lib/asciichem/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  class Error < StandardError; end
+
+  class ParseError < Error; end
+
+  class FormatError < Error; end
+end

data/lib/asciichem/formatter/base.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Formatter
+    # Visitor base class. Subclasses implement one `visit_<node_name>`
+    # method per Model::Node subclass. Missing visits raise
+    # NotImplementedError so gaps surface at first use, not silently.
+    class Base
+      def render(node)
+        node.accept(self)
+      end
+
+      private
+
+      def not_implemented_for(node)
+        raise NotImplementedError,
+              "#{self.class} cannot render #{node.class.name}"
+      end
+    end
+  end
+end

data/lib/asciichem/formatter/html.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Formatter
+    # Renders a Model tree as inline HTML using `<sub>` and `<sup>` tags.
+    # Suitable for inline display in pages that don't want to load
+    # MathJax or render MathML.
+    #
+    # Example: `H_2O` -> <code>H<sub>2</sub>O</code>.
+    class Html < Base
+      def visit_formula(formula)
+        inner = formula.nodes.map { |n| render_node(n) }.join
+        "<span class=\"asciichem\">#{inner}</span>"
+      end
+
+      def visit_molecule(molecule)
+        prefix = molecule.coefficient.nil? || molecule.coefficient.to_s.empty? ? "" : "#{escape(molecule.coefficient)}"
+        stereo = molecule.stereo ? "(#{escape(molecule.stereo_letter)})-" : ""
+        body = molecule.nodes.map { |n| render_node(n) }.join
+        "#{stereo}#{prefix}#{body}"
+      end
+
+      def visit_atom(atom)
+        parts = []
+        parts << "<sup>#{escape(atom.isotope)}</sup>" if atom.isotope
+        parts << escape(atom.element)
+        parts << "<sub>#{escape(atom.subscript)}</sub>" if atom.subscript
+        parts << "<sup>#{escape(atom.superscript)}</sup>" if atom.superscript
+        parts << "<sup>#{escape(atom.charge)}</sup>" if atom.charge
+        if atom.oxidation_state
+          parts << "<sup>(#{escape(atom.oxidation_state)})</sup>"
+        end
+        parts << escape(atom.ring_closures) if atom.ring_closures
+        parts.join
+      end
+
+      def visit_group(group)
+        body = group.nodes.map { |n| render_node(n) }.join
+        suffix = group.multiplicity ? "<sub>#{escape(group.multiplicity)}</sub>" : ""
+        "#{escape(group.open_char)}#{body}#{escape(group.close_char)}#{suffix}"
+      end
+
+      def visit_bond(bond)
+        escape(bond.ascii)
+      end
+
+      def visit_reaction(reaction)
+        left = reaction.reactants.map { |n| render_node(n) }.join(" + ")
+        right = reaction.products.map { |n| render_node(n) }.join(" + ")
+        arrow = escape(reaction.arrow_entity)
+        conds = reaction.conditions
+        return "#{left} #{arrow} #{right}" unless conds
+
+        above = conds.above ? "<sup>#{escape(conds.above)}</sup>" : ""
+        below = conds.below ? "<sub>#{escape(conds.below)}</sub>" : ""
+        "#{left} #{above}#{arrow}#{below} #{right}"
+      end
+
+      def visit_reaction_cascade(cascade)
+        return "" if cascade.steps.empty?
+
+        head = cascade.steps.first
+        out = head.reactants.map { |n| render_node(n) }.join(" + ")
+        cascade.steps.each do |step|
+          arrow = escape(step.arrow_entity)
+          conds = step.conditions
+          if conds
+            above = conds.above ? "<sup>#{escape(conds.above)}</sup>" : ""
+            below = conds.below ? "<sub>#{escape(conds.below)}</sub>" : ""
+            out += " #{above}#{arrow}#{below}"
+          else
+            out += " #{arrow}"
+          end
+          out += " " + step.products.map { |n| render_node(n) }.join(" + ")
+        end
+        out
+      end
+
+      def visit_electron_configuration(ec)
+        ec.orbitals.map { |orb, occ| "#{escape(orb)}<sup>#{escape(occ)}</sup>" }.join(" ")
+      end
+
+      def visit_embedded_math(em)
+        em.formula.to_mathml
+      end
+
+      def visit_text(text)
+        escape(text.content)
+      end
+
+      private
+
+      def render_node(node)
+        node.accept(self)
+      end
+
+      # Minimal HTML escaper. The model content is plain text (digits,
+      # element symbols, conditions text) so we only need the four
+      # XML-mandated characters.
+      def escape(string)
+        return "" if string.nil?
+
+        string.to_s
+              .gsub("&", "&amp;")
+              .gsub("<", "&lt;")
+              .gsub(">", "&gt;")
+              .gsub('"', "&quot;")
+      end
+    end
+  end
+end

data/lib/asciichem/formatter/latex.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Formatter
+    # Renders a Model tree as LaTeX, wrapped in `mhchem`'s `\ce{...}` at
+    # the formula level only. Output requires `mhchem` in the LaTeX
+    # preamble:
+    #
+    #   \\usepackage[version=4]{mhchem}
+    #
+    # Example: `H_2O` -> `\ce{H2O}`.
+    class Latex < Base
+      def initialize
+        @inside_ce = false
+      end
+
+      def visit_formula(formula)
+        within_ce { "\\ce{" + formula.nodes.map { |n| render_node(n) }.join + "}" }
+      end
+
+      def visit_molecule(molecule)
+        prefix = blank?(molecule.coefficient) ? "" : molecule.coefficient.to_s
+        stereo = molecule.stereo ? "(#{molecule.stereo_letter})-" : ""
+        body = molecule.nodes.map { |n| render_node(n) }.join
+        if @inside_ce
+          "#{stereo}#{prefix}#{body}"
+        else
+          "\\ce{#{stereo}#{prefix}#{body}}"
+        end
+      end
+
+      def visit_atom(atom)
+        parts = []
+        parts << (":" * atom.lone_pairs) if atom.lone_pairs
+        parts << "^#{wrap(atom.isotope)}" if atom.isotope
+        parts << wrap(atom.element)
+        parts << mhchem_subscript(atom.subscript) if atom.subscript
+        if atom.charge
+          parts << "^#{wrap(atom.charge)}"
+        elsif atom.oxidation_state
+          parts << "^{(#{wrap(atom.oxidation_state)})}"
+        elsif atom.superscript
+          parts << "^#{wrap(atom.superscript)}"
+        end
+        parts << ("." * atom.radical_electrons) if atom.radical_electrons
+        parts << atom.ring_closures.to_s if atom.ring_closures
+        parts.join
+      end
+
+      def visit_group(group)
+        body = group.nodes.map { |n| render_node(n) }.join
+        open, close = bracket_chars(group.bracket)
+        suffix = group.multiplicity ? mhchem_subscript(group.multiplicity) : ""
+        "#{open}#{body}#{close}#{suffix}"
+      end
+
+      def visit_bond(bond)
+        case bond.kind
+        when :single then "-"
+        when :double then "="
+        when :triple then "\\\\equiv{}"
+        else bond.ascii
+        end
+      end
+
+      def visit_reaction(reaction)
+        left = reaction.reactants.map { |n| render_node(n) }.join(" + ")
+        right = reaction.products.map { |n| render_node(n) }.join(" + ")
+        arrow = arrow_for(reaction.arrow)
+        conds = reaction.conditions
+        return "#{left} #{arrow} #{right}" unless conds
+
+        above = conditions_bracket(conds.above)
+        below = conditions_bracket(conds.below)
+        "#{left} #{arrow}#{above}#{below} #{right}"
+      end
+
+      def visit_reaction_cascade(cascade)
+        return "" if cascade.steps.empty?
+
+        head = cascade.steps.first
+        out = head.reactants.map { |n| render_node(n) }.join(" + ")
+        cascade.steps.each do |step|
+          arrow = arrow_for(step.arrow)
+          conds = step.conditions
+          if conds
+            above = conditions_bracket(conds.above)
+            below = conditions_bracket(conds.below)
+            out += " #{arrow}#{above}#{below}"
+          else
+            out += " #{arrow}"
+          end
+          out += " " + step.products.map { |n| render_node(n) }.join(" + ")
+        end
+        out
+      end
+
+      def visit_electron_configuration(ec)
+        inner = ec.orbitals.map { |orb, occ| "#{wrap(orb)}^#{wrap(occ)}" }.join(" ")
+        "\\ce{#{inner}}"
+      end
+
+      def visit_embedded_math(em)
+        "$#{em.formula.to_latex}$"
+      end
+
+      def visit_text(text)
+        text.content
+      end
+
+      private
+
+      def render_node(node)
+        node.accept(self)
+      end
+
+      def within_ce
+        prev = @inside_ce
+        @inside_ce = true
+        yield
+      ensure
+        @inside_ce = prev
+      end
+
+      # mhchem accepts bare digits after an element as subscripts. Use
+      # bare form for digit-only values; brace form for anything else.
+      def mhchem_subscript(value)
+        s = value.to_s
+        return s if s.match?(/\A\d+\z/)
+
+        "_{#{s}}"
+      end
+
+      # mhchem accepts bare digits for multi-digit values (`^14`, `_12`).
+      # Use braces only for non-digit values to keep output idiomatic.
+      def wrap(value)
+        s = value.to_s
+        return s if s.match?(/\A[a-zA-Z0-9]+\z/)
+
+        "{#{s}}"
+      end
+
+      def blank?(value)
+        value.nil? || value.to_s.empty?
+      end
+
+      def bracket_chars(kind)
+        case kind
+        when :paren  then ["(", ")"]
+        when :square then ["[", "]"]
+        when :brace  then ["{", "}"]
+        else ["(", ")"]
+        end
+      end
+
+      def arrow_for(kind)
+        case kind
+        when :forward     then "->"
+        when :reverse     then "<-"
+        when :equilibrium then "<=>"
+        when :resonance   then "<->"
+        else "->"
+        end
+      end
+
+      def conditions_bracket(value)
+        return "" if value.nil? || value.to_s.empty?
+
+        "[#{value}]"
+      end
+    end
+  end
+end