asciichem 0.3.0

data/lib/asciichem/cml/extensions.rb

@@ -0,0 +1,360 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+
+module AsciiChem
+  module Cml
+    # Carries AsciiChem-specific fields through CML round-trip via an
+    # `aci:` (AsciiChem extension) namespace. CML's standard wire
+    # format covers element, isotope, charge, count, hydrogen count,
+    # and spin multiplicity — but not oxidation state, lone pairs,
+    # radical electrons, or anything else AsciiChem might add. Without
+    # this side channel, those fields are silently dropped on
+    # AsciiChem → CML → AsciiChem round-trip.
+    #
+    # The mechanism: post-process the CML XML emitted by chemicalml
+    # to add `aci:` attributes for atoms that carry extension data.
+    # On parse, read the `aci:` attributes back. CML tools that don't
+    # recognise the namespace simply ignore the attributes — schema
+    # validity is preserved.
+    #
+    # Adding a new extension field is one entry in `FIELDS` and one
+    # writer/reader pair. No other code changes. This is the OCP
+    # extension point for "fields CML doesn't natively carry".
+    module Extensions
+      NAMESPACE = 'https://asciichem.org/cml-ext'
+      PREFIX = 'aci'
+      CML_NS = 'http://www.xml-cml.org/schema'
+
+      # Map of AsciiChem::Model::Atom attribute name (Symbol) to the
+      # wire attribute name (without prefix). Each entry produces a
+      # corresponding `aci:<wire_name>` attribute in the CML output.
+      FIELDS = {
+        oxidation_state: 'oxidationState',
+        lone_pairs: 'lonePairs',
+        radical_electrons: 'radicalElectrons',
+        ring_closures: 'ringClosures',
+        atom_parity: 'atomParity'
+      }.freeze
+
+      # -- AsciiChem -> CML ------------------------------------------
+
+      # Build the extensions map: `{ atom_id => { field: value } }`.
+      # Values are Ruby-native (Integer for counts, String for
+      # oxidation state). Atoms without extension data are omitted
+      # from the map (so the CML output stays clean for plain atoms).
+      def self.collect(atom_mapping)
+        atom_mapping.each_with_object({}) do |(atom_id, source_atom), memo|
+          data = build_entry(source_atom)
+          memo[atom_id] = data unless data.empty?
+        end
+      end
+
+      def self.build_entry(atom)
+        FIELDS.each_with_object({}) do |(attr_name, _wire_name), entry|
+          value = atom.public_send(attr_name)
+          entry[attr_name] = value if value
+        end
+      end
+      private_class_method :build_entry
+
+      # Inject aci: attributes into a CML XML string. Returns the
+      # modified XML. No-op if the extensions map is empty.
+      def self.inject(xml, extensions)
+        return xml if extensions.empty?
+
+        doc = Nokogiri::XML(xml)
+        root = doc.root
+        root.add_namespace(PREFIX, NAMESPACE) unless namespace_declared?(root)
+
+        extensions.each do |atom_id, entry|
+          atom_el = root.at_xpath("//cml:atom[@id='#{atom_id}']", cml: CML_NS)
+          next unless atom_el
+
+          entry.each do |attr_name, value|
+            wire_name = FIELDS.fetch(attr_name)
+            atom_el["#{PREFIX}:#{wire_name}"] = value.to_s
+          end
+        end
+
+        doc.to_xml
+      end
+
+      def self.namespace_declared?(root)
+        root.namespaces.value?(NAMESPACE)
+      end
+      private_class_method :namespace_declared?
+
+      # -- CML -> AsciiChem ------------------------------------------
+
+      # Extract aci: attributes from a CML XML string. Returns a map
+      # `{ atom_id => { field: value } }` with Ruby-native types
+      # (Integer for counts, String for oxidation state). Empty if no
+      # aci: attributes are present.
+      def self.extract(xml)
+        doc = Nokogiri::XML(xml)
+        result = {}
+        doc.xpath('//cml:atom', cml: CML_NS).each do |atom_el|
+          atom_id = atom_el['id']
+          next unless atom_id
+
+          entry = read_entry(atom_el)
+          result[atom_id] = entry unless entry.empty?
+        end
+        result
+      end
+
+      def self.read_entry(atom_el)
+        FIELDS.each_with_object({}) do |(attr_name, wire_name), entry|
+          value = atom_el["#{PREFIX}:#{wire_name}"]
+          entry[attr_name] = cast_from_xml(attr_name, value) if value
+        end
+      end
+      private_class_method :read_entry
+
+      # Cast an XML string back to its Ruby form. Integer counts
+      # become Integers; everything else stays a string.
+      def self.cast_from_xml(attr_name, value)
+        case attr_name
+        when :lone_pairs, :radical_electrons then value.to_i
+        else value
+        end
+      end
+      private_class_method :cast_from_xml
+
+      # -- Round-trip restore ----------------------------------------
+
+      # Apply extracted extension data to a freshly-parsed
+      # AsciiChem::Model::Formula. The `canonical_doc` is the
+      # canonical document that produced the formula; it provides
+      # the atom-id ordering. Atoms are walked in parallel.
+      def self.restore(formula, canonical_doc, extensions)
+        return formula if extensions.empty?
+
+        canonical_atoms = flatten_canonical_atoms(canonical_doc)
+        formula_atoms = flatten_formula_atoms(formula)
+
+        canonical_atoms.each_with_index do |canon_atom, idx|
+          entry = extensions[canon_atom.id]
+          next unless entry
+
+          target = formula_atoms[idx]
+          next unless target
+
+          apply_entry(target, entry)
+        end
+        formula
+      end
+
+      def self.apply_entry(atom, entry)
+        entry.each do |attr_name, value|
+          atom.public_send(:"#{attr_name}=", value)
+        end
+      end
+      private_class_method :apply_entry
+
+      # Flatten the canonical document's atoms into a single list,
+      # in the same order ToCanonical walked them: top-level molecules,
+      # then reaction reactants+products, then cascade reactions.
+      def self.flatten_canonical_atoms(canonical_doc)
+        atoms = []
+        canonical_doc.molecules.each { |m| atoms.concat(m.atoms) }
+        canonical_doc.reactions.each do |reaction|
+          atoms.concat(flatten_reaction_atoms(reaction))
+        end
+        canonical_doc.reaction_lists.each do |list|
+          list.reactions.each { |r| atoms.concat(flatten_reaction_atoms(r)) }
+        end
+        atoms
+      end
+
+      def self.flatten_reaction_atoms(reaction)
+        atoms = []
+        reactants = reaction.reactant_list
+        products = reaction.product_list
+        reactants&.reactants&.each { |r| atoms.concat(r.substance.molecule.atoms) }
+        products&.products&.each { |p| atoms.concat(p.substance.molecule.atoms) }
+        atoms
+      end
+      private_class_method :flatten_reaction_atoms
+
+      # Flatten the AsciiChem::Model::Formula's atoms in the same
+      # order ToCanonical walks them. Matches `flatten_canonical_atoms`
+      # one-for-one so parallel iteration by index works.
+      def self.flatten_formula_atoms(formula)
+        formula.nodes.each_with_object([]) do |node, memo|
+          case node
+          when AsciiChem::Model::Molecule
+            memo.concat(flatten_molecule_atoms(node))
+          when AsciiChem::Model::Reaction
+            memo.concat(reaction_atoms(node))
+          when AsciiChem::Model::ReactionCascade
+            node.steps.each { |step| memo.concat(reaction_atoms(step)) }
+          end
+        end
+      end
+
+      def self.reaction_atoms(reaction)
+        atoms = []
+        reaction.reactants.each { |m| atoms.concat(flatten_molecule_atoms(m)) }
+        reaction.products.each { |m| atoms.concat(flatten_molecule_atoms(m)) }
+        atoms
+      end
+      private_class_method :reaction_atoms
+
+      def self.flatten_molecule_atoms(molecule)
+        molecule.nodes.each_with_object([]) do |node, memo|
+          case node
+          when AsciiChem::Model::Atom
+            memo << node
+          when AsciiChem::Model::Group, AsciiChem::Model::Molecule
+            memo.concat(flatten_molecule_atoms(node))
+          end
+        end
+      end
+      private_class_method :flatten_molecule_atoms
+
+      # -- Top-level extensions --------------------------------------
+      #
+      # AsciiChem::Model node classes that have no canonical equivalent
+      # (ElectronConfiguration, EmbeddedMath) ride as `aci:` elements
+      # inside `<cml>`. Position in the original formula's node list is
+      # preserved via a `position` attribute so restore can re-insert
+      # at the right index. The wire format for each handler is the
+      # AsciiChem text rendering — round-trip-safe by construction.
+
+      # Registry of top-level handlers. Each handler is a Struct with
+      # `node_class`, `element_name`, `serialize`, `deserialize`.
+      # Adding a new top-level extension is one handler entry.
+      TopLevelHandler = Struct.new(:node_class, :element_name,
+                                   :serialize, :deserialize, keyword_init: true)
+
+      TOP_LEVEL_HANDLERS = [
+        TopLevelHandler.new(
+          node_class: AsciiChem::Model::ElectronConfiguration,
+          element_name: 'electronConfiguration',
+          serialize: ->(node) { text_render(node) },
+          deserialize: ->(content) { AsciiChem.parse(content).nodes.first }
+        ),
+        TopLevelHandler.new(
+          node_class: AsciiChem::Model::EmbeddedMath,
+          element_name: 'embeddedMath',
+          serialize: ->(node) { node.source.to_s },
+          deserialize: ->(content) { AsciiChem.parse("`#{content}`").nodes.first }
+        ),
+        TopLevelHandler.new(
+          node_class: AsciiChem::Model::Text,
+          element_name: 'text',
+          # Text formatter emits `"content"` (with quotes). Re-parsing
+          # that yields the original Text node — round-trip-safe by
+          # construction.
+          serialize: ->(node) { text_render(node) },
+          deserialize: ->(content) { AsciiChem.parse(content).nodes.first }
+        )
+      ].freeze
+
+      # Build the top-level extensions list from a formula. Returns an
+      # array of `{ position:, element_name:, content: }` hashes. The
+      # position is the index in the original formula's node list.
+      def self.collect_top_level(formula)
+        handlers_by_class = top_level_handlers_by_class
+        formula.nodes.each_with_index.with_object([]) do |(node, idx), memo|
+          handler = handlers_by_class[node.class]
+          next unless handler
+
+          memo << {
+            position: idx,
+            element_name: handler.element_name,
+            content: handler.serialize.call(node)
+          }
+        end
+      end
+
+      # Inject top-level extensions into CML XML as `aci:` elements
+      # inside `<cml>`. No-op if the list is empty.
+      def self.inject_top_level(xml, top_level)
+        return xml if top_level.empty?
+
+        doc = Nokogiri::XML(xml)
+        root = doc.root
+        ensure_namespace(root)
+        top_level.each { |entry| insert_top_level_element(doc, root, entry) }
+        doc.to_xml
+      end
+
+      def self.ensure_namespace(root)
+        root.add_namespace(PREFIX, NAMESPACE) unless namespace_declared?(root)
+      end
+      private_class_method :ensure_namespace
+
+      def self.insert_top_level_element(doc, root, entry)
+        element = doc.create_element("#{PREFIX}:#{entry[:element_name]}")
+        element['position'] = entry[:position].to_s
+        element.content = entry[:content]
+        # Insert before existing children so extensions appear at the
+        # top of <cml>, which reads more naturally than appended.
+        root.children.first&.add_previous_sibling(element) || root.add_child(element)
+      end
+      private_class_method :insert_top_level_element
+
+      # Extract `aci:` top-level elements from CML XML. Returns an
+      # array of `{ position:, element_name:, content: }` hashes in
+      # ascending position order.
+      def self.extract_top_level(xml)
+        doc = Nokogiri::XML(xml)
+        result = []
+        element_names = TOP_LEVEL_HANDLERS.map(&:element_name)
+        element_names.each do |name|
+          doc.xpath("//#{PREFIX}:#{name}", PREFIX => NAMESPACE).each do |el|
+            result << {
+              position: (el['position'] || 0).to_i,
+              element_name: name,
+              content: el.content
+            }
+          end
+        end
+        result.sort_by { |entry| entry[:position] }
+      end
+
+      # Restore top-level extension nodes into a freshly-parsed
+      # formula. Inserts each node at its original position; nodes
+      # are inserted in ascending position order so earlier inserts
+      # don't shift later positions.
+      def self.restore_top_level(formula, top_level)
+        handlers_by_element = top_level_handlers_by_element
+        top_level.sort_by { |entry| entry[:position] }.each do |entry|
+          handler = handlers_by_element[entry[:element_name]]
+          next unless handler
+
+          node = handler.deserialize.call(entry[:content])
+          next unless node
+
+          pos = [entry[:position], formula.nodes.length].min
+          formula.nodes.insert(pos, node)
+        end
+        formula
+      end
+
+      def self.top_level_handlers_by_class
+        TOP_LEVEL_HANDLERS.to_h do |h|
+          [h.node_class, h]
+        end
+      end
+      private_class_method :top_level_handlers_by_class
+
+      def self.top_level_handlers_by_element
+        TOP_LEVEL_HANDLERS.to_h do |h|
+          [h.element_name, h]
+        end
+      end
+      private_class_method :top_level_handlers_by_element
+
+      # Render a node using the AsciiChem Text formatter. The output
+      # is round-trip-safe by construction (Text is the canonicaliser).
+      def self.text_render(node)
+        AsciiChem::Formatter.render(:text, node)
+      end
+      private_class_method :text_render
+    end
+  end
+end

data/lib/asciichem/cml/group_extensions.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+
+module AsciiChem
+  module Cml
+    # Preserves AsciiChem::Model::Group structure through CML round-trip.
+    #
+    # CML has no native group concept — the canonical model flattens
+    # `(OH)_2` to `<atom elementType="O" count="2"/><atom elementType="H" count="2"/>`.
+    # The aci: namespace records the original grouping so AsciiChem
+    # can rebuild it on parse:
+    #
+    #   <molecule id="m1">
+    #     <atomArray>
+    #       <atom id="a1" elementType="O" count="2"/>
+    #       <atom id="a2" elementType="H" count="2"/>
+    #     </atomArray>
+    #     <aci:group multiplicity="2" bracket="paren" atomRefs="a1 a2"/>
+    #   </molecule>
+    #
+    # The mechanism parallels `Extensions` (atom attributes) and the
+    # top-level handlers, but operates at molecule scope: each
+    # `<aci:group>` lives inside its parent `<molecule>` and references
+    # atoms by ID. Nested groups in AsciiChem produce multiple
+    # `<aci:group>` elements with overlapping `atomRefs` — the parent
+    # group's refs include the inner group's atoms.
+    #
+    # On restore, the canonical adapter has already applied the
+    # multiplicity to atom counts. GroupExtensions reverses this:
+    # divides each referenced atom's count by the group's multiplicity
+    # (rounding to nil when the result is 1) and wraps the atoms in an
+    # AsciiChem::Model::Group.
+    module GroupExtensions
+      NAMESPACE = 'https://asciichem.org/cml-ext'
+      PREFIX = 'aci'
+      CML_NS = 'http://www.xml-cml.org/schema'
+
+      # AsciiChem bracket symbols → wire strings.
+      BRACKET_TO_WIRE = { paren: 'paren', square: 'square', brace: 'brace' }.freeze
+      WIRE_TO_BRACKET = BRACKET_TO_WIRE.invert.freeze
+
+      # -- AsciiChem -> CML ------------------------------------------
+
+      # Build the group extensions map: `{ molecule_id => [group_record, ...] }`.
+      # Molecules without groups are omitted (keeps the CML clean for
+      # ungrouped molecules).
+      def self.collect(groups_by_molecule)
+        groups_by_molecule.reject { |_, groups| groups.empty? }
+      end
+
+      # Inject `<aci:group>` elements into each referenced molecule.
+      # No-op when the map is empty.
+      def self.inject(xml, groups_by_molecule)
+        return xml if groups_by_molecule.empty?
+
+        doc = Nokogiri::XML(xml)
+        root = doc.root
+        root.add_namespace(PREFIX, NAMESPACE) unless namespace_declared?(root)
+
+        groups_by_molecule.each do |molecule_id, groups|
+          molecule_el = root.at_xpath("//cml:molecule[@id='#{molecule_id}']", cml: CML_NS)
+          next unless molecule_el
+
+          groups.each { |record| molecule_el.add_child(build_group_element(doc, record)) }
+        end
+
+        doc.to_xml
+      end
+
+      def self.build_group_element(doc, record)
+        el = doc.create_element("#{PREFIX}:group")
+        el['multiplicity'] = record.multiplicity.to_s if record.multiplicity
+        el['bracket'] = BRACKET_TO_WIRE.fetch(record.bracket, 'paren')
+        el['atomRefs'] = record.atom_ids.join(' ')
+        el
+      end
+      private_class_method :build_group_element
+
+      def self.namespace_declared?(root)
+        root.namespaces.value?(NAMESPACE)
+      end
+      private_class_method :namespace_declared?
+
+      # -- CML -> AsciiChem ------------------------------------------
+
+      # Extract `<aci:group>` elements, keyed by their parent
+      # molecule's ID. Each value is an array of record hashes:
+      # `{ multiplicity:, bracket:, atom_ids: }`.
+      def self.extract(xml)
+        doc = Nokogiri::XML(xml)
+        result = Hash.new { |h, k| h[k] = [] }
+        doc.xpath('//cml:molecule', cml: CML_NS).each do |mol_el|
+          group_els = mol_el.xpath("./#{PREFIX}:group", PREFIX => NAMESPACE)
+          next if group_els.empty?
+
+          mol_el['id']&.then do |molecule_id|
+            group_els.each { |g| result[molecule_id] << read_group(g) }
+          end
+        end
+        result
+      end
+
+      def self.read_group(el)
+        atom_ids = (el['atomRefs'] || '').split
+        {
+          multiplicity: el['multiplicity'],
+          bracket: WIRE_TO_BRACKET.fetch(el['bracket'], :paren),
+          atom_ids: atom_ids
+        }
+      end
+      private_class_method :read_group
+
+      # -- Round-trip restore ----------------------------------------
+      #
+      # Walks the rebuilt AsciiChem::Model::Formula's molecules. For
+      # each molecule that has group records, rebuilds the Group nodes
+      # from the flattened atom list. Atom positions in the rebuilt
+      # molecule match the canonical order (a1, a2, ...), so the
+      # atom_ids in each record map directly to indices.
+
+      def self.restore(formula, canonical_doc, groups_by_molecule)
+        return formula if groups_by_molecule.empty?
+
+        canonical_molecules = flatten_canonical_molecules(canonical_doc)
+        formula_molecules = flatten_formula_molecules(formula)
+
+        canonical_molecules.each_with_index do |canon_mol, idx|
+          groups = groups_by_molecule[canon_mol.id]
+          next unless groups
+
+          target = formula_molecules[idx]
+          next unless target
+
+          rebuild_groups_in_molecule(target, groups)
+        end
+        formula
+      end
+
+      # Rebuilds groups inside a single molecule. Processes records in
+      # reverse-entry order so inner groups rebuild before their outer
+      # parents — the walker adds outer groups to its @groups array
+      # before entering inner groups, so reverse gives innermost-first.
+      # For sibling groups (no nesting), reverse order is equivalent.
+      def self.rebuild_groups_in_molecule(molecule, groups)
+        groups.reverse_each { |record| rebuild_one_group(molecule, record) }
+      end
+      private_class_method :rebuild_groups_in_molecule
+
+      def self.rebuild_one_group(molecule, record)
+        target_nodes = find_target_nodes(molecule.nodes, record[:atom_ids])
+        return if target_nodes.empty?
+
+        apply_multiplicity_to_atoms(target_nodes, record[:multiplicity])
+        splice_group_into(molecule.nodes, target_nodes, record)
+      end
+      private_class_method :rebuild_one_group
+
+      # Walks `nodes` in canonical-walk order, tracking which canonical
+      # atom ID each position covers. Returns ALL nodes (Atoms, Bonds,
+      # AND Groups) between the first and last target atom inclusive.
+      # Including Bonds preserves the chain inside the Group.
+      def self.find_target_nodes(nodes, atom_ids)
+        target_array = atom_ids.to_a
+        return [] if target_array.empty?
+
+        first_pos = nil
+        last_pos = nil
+        canonical_idx = 0
+        nodes.each_with_index do |node, idx|
+          atom_count = count_atoms_recursively(node)
+          covered_ids = (1..atom_count).map { |i| "a#{canonical_idx + i}" }
+          if covered_ids.intersect?(target_array)
+            first_pos ||= idx
+            last_pos = idx
+          end
+          canonical_idx += atom_count
+        end
+        return [] unless first_pos && last_pos
+
+        nodes[first_pos..last_pos]
+      end
+      private_class_method :find_target_nodes
+
+      # Counts the atoms transitively contained in a node. Atoms count
+      # as 1; Groups/Molecules recurse and sum.
+      def self.count_atoms_recursively(node)
+        case node
+        when AsciiChem::Model::Atom
+          1
+        when AsciiChem::Model::Group, AsciiChem::Model::Molecule
+          node.nodes.sum { |n| count_atoms_recursively(n) }
+        else
+          0
+        end
+      end
+      private_class_method :count_atoms_recursively
+
+      # Divide each Atom's subscript by the multiplicity. Atoms inside
+      # an inner Group have already been divided when the inner Group
+      # was processed — leave them alone. Subscripts of 1 (after
+      # division) become nil (the default).
+      def self.apply_multiplicity_to_atoms(target_nodes, multiplicity)
+        return unless multiplicity
+
+        divisor = multiplicity.to_i
+        return unless divisor.positive?
+
+        target_nodes.each do |node|
+          next unless node.is_a?(AsciiChem::Model::Atom)
+          next unless node.subscript
+
+          new_sub = node.subscript.to_i / divisor
+          node.subscript = (new_sub == 1 ? nil : new_sub.to_s)
+        end
+      end
+      private_class_method :apply_multiplicity_to_atoms
+
+      # Replaces the collected target nodes (which must be contiguous
+      # in `nodes`) with a single new Group containing them. Uses
+      # identity (`equal?`) for position lookup so duplicate Bonds
+      # (same kind → `==` equal) aren't confused.
+      def self.splice_group_into(nodes, target_nodes, record)
+        return if target_nodes.empty?
+
+        positions = target_nodes.map do |target|
+          found = nodes.each_with_index.find { |node, _| node.equal?(target) }
+          found&.last
+        end.compact
+        return if positions.empty?
+
+        group = AsciiChem::Model::Group.new(
+          nodes: target_nodes,
+          multiplicity: record[:multiplicity],
+          bracket: record[:bracket]
+        )
+
+        first_pos = positions.min
+        nodes[first_pos] = group
+        # Remove remaining positions in descending order so earlier
+        # positions don't shift before deletion.
+        positions.reject { |p| p == first_pos }.sort.reverse.each do |pos|
+          nodes.delete_at(pos)
+        end
+      end
+      private_class_method :splice_group_into
+
+      # Flatten the canonical document's molecules (top-level +
+      # reaction reactants/products + cascade reactions) into a list,
+      # in the same order ToCanonical walked them.
+      def self.flatten_canonical_molecules(canonical_doc)
+        mols = canonical_doc.molecules.dup
+        canonical_doc.reactions.each { |r| mols.concat(flatten_reaction_molecules(r)) }
+        canonical_doc.reaction_lists.each do |list|
+          list.reactions.each { |r| mols.concat(flatten_reaction_molecules(r)) }
+        end
+        mols
+      end
+      private_class_method :flatten_canonical_molecules
+
+      def self.flatten_reaction_molecules(reaction)
+        mols = []
+        reaction.reactant_list&.reactants&.each { |r| mols << r.substance.molecule }
+        reaction.product_list&.products&.each { |p| mols << p.substance.molecule }
+        mols
+      end
+      private_class_method :flatten_reaction_molecules
+
+      def self.flatten_formula_molecules(formula)
+        mols = []
+        formula.nodes.each do |node|
+          case node
+          when AsciiChem::Model::Molecule
+            mols << node
+          when AsciiChem::Model::Reaction
+            mols.concat(node.reactants)
+            mols.concat(node.products)
+          when AsciiChem::Model::ReactionCascade
+            node.steps.each do |step|
+              mols.concat(step.reactants)
+              mols.concat(step.products)
+            end
+          end
+        end
+        mols
+      end
+      private_class_method :flatten_formula_molecules
+    end
+  end
+end