asciichem 0.20.0 → 0.22.0

data/lib/asciichem/smiles/parser.rb

@@ -0,0 +1,302 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Smiles
+    # Recursive-descent parser for the supported SMILES subset.
+    # SMILES is a linear grammar, so a direct parser is clearer than
+    # a parse-tree + transform round trip; it builds the model
+    # through the shared Structure::Linearizer.
+    #
+    # v1 subset (each deferral raises an actionable ParseError):
+    # chirality `@`/`@@`, E/Z bond directions `/` `\`, wildcard `*`,
+    # reaction atom maps, queries.
+    class Parser
+      ORGANIC = %w[Cl Br B C N O P S F I].freeze
+      AROMATIC = %w[se as b c n o p s].freeze
+
+      def initialize(source)
+        @source = source
+        @pos = 0
+      end
+
+      # Returns a Model::Formula with one Molecule per dot component.
+      def parse
+        molecules = [component]
+        molecules << component while eat(".")
+        unless @pos == @source.length
+          raise ParseError,
+                "unexpected character #{peek.inspect} at position #{@pos} in #{@source.inspect}"
+        end
+        Model::Formula.new(nodes: molecules)
+      end
+
+      private
+
+      def component
+        @atoms = []
+        @adjacency = []
+        @open_rings = {}
+        @parent = nil
+        @pending_kind = nil
+
+        chain
+
+        unless @open_rings.empty?
+          raise ParseError,
+                "unclosed ring bond digit(s): #{@open_rings.keys.sort.join(', ')} in #{@source.inspect}"
+        end
+
+        edges = []
+        @adjacency.each_with_index do |neighbors, index|
+          neighbors.each { |to, kind| edges << Structure::Graph::Edge.new(from: index, to: to, kind: kind) if to > index }
+        end
+        Model::Molecule.new(nodes: Structure::Linearizer.new(atoms: @atoms, edges: edges).nodes)
+      end
+
+      # chain := atom (bond? atom | branch | ringbond)*
+      # Bare adjacency (no bond token) means a default bond.
+      def chain
+        atom_token
+        until eoc?
+          if peek == "("
+            branch
+          elsif bond_start?
+            kind = bond_token
+            if peek == "("
+              branch(kind)
+            elsif digit_start?
+              ringbond(kind)
+            else
+              @pending_kind = kind
+              atom_token
+            end
+          elsif digit_start?
+            ringbond(nil)
+          else
+            @pending_kind = nil
+            atom_token
+          end
+        end
+      end
+
+      def branch(kind = nil)
+        expect("(")
+        # The bond may lead the branch ("C-(O)") or open it ("C(=O)").
+        kind = bond_token if kind.nil? && bond_start?
+        saved_parent = @parent
+        saved_pending = @pending_kind
+        @pending_kind = kind
+        chain
+        expect(")")
+        @parent = saved_parent
+        @pending_kind = saved_pending
+      end
+
+      def ringbond(kind)
+        digit = ring_digit
+        if @open_rings.key?(digit)
+          opener = @open_rings.delete(digit)
+          # The model's ring-closure digits carry no bond kind, so an
+          # explicit kind that differs from the default (aromatic
+          # between aromatic atoms, otherwise single) cannot be
+          # represented — reject rather than silently downgrade.
+          if kind && kind != default_kind(opener, @parent)
+            raise ParseError,
+                  "bonded ring closures (#{kind}) are not representable in the model's ring-closure form"
+          end
+          add_edge(opener, @parent, kind)
+        else
+          @open_rings[digit] = @parent
+        end
+      end
+
+      def atom_token
+        atom = read_atom
+        index = @atoms.length
+        @atoms << atom
+        @adjacency[index] = {}
+        add_edge(@parent, index, @pending_kind) if @parent
+        @parent = index
+        @pending_kind = nil
+      end
+
+      def add_edge(from, to, explicit)
+        kind = explicit || default_kind(from, to)
+        @adjacency[from][to] = kind
+        @adjacency[to][from] = kind
+      end
+
+      def default_kind(from, to)
+        @atoms[from].aromatic && @atoms[to].aromatic ? :aromatic : :single
+      end
+
+      # -- tokens ----------------------------------------------------------
+
+      def read_atom
+        return bracket_atom if peek == "["
+
+        two = @source[@pos, 2].to_s
+        if (symbol = ORGANIC.find { |s| two.start_with?(s) })
+          @pos += symbol.length
+          return Model::Atom.new(element: symbol)
+        end
+        if (symbol = AROMATIC.find { |s| two.start_with?(s) } || AROMATIC.find { |s| peek == s })
+          @pos += symbol.length
+          return Model::Atom.new(element: symbol.capitalize, aromatic: true)
+        end
+
+        raise ParseError, "unexpected character #{peek.inspect} at position #{@pos} in #{@source.inspect}"
+      end
+
+      def bracket_atom
+        expect("[")
+        isotope = digits
+        symbol = bracket_symbol
+        reject_chirality
+        hydrogens = hcount
+        charge = bracket_charge
+        skip_class
+        expect("]")
+        Model::Atom.new(
+          element: symbol.capitalize,
+          isotope: isotope,
+          charge: charge,
+          hydrogens: hydrogens,
+          aromatic: symbol.match?(/\A[a-z]/) || nil
+        )
+      end
+
+      AROMATIC_TWO_CHAR = %w[se as].freeze
+
+      def bracket_symbol
+        two = @source[@pos, 2].to_s
+        if AROMATIC_TWO_CHAR.include?(two)
+          @pos += 2
+          return two
+        end
+        if @source[@pos] =~ /[bcnops]/
+          sym = @source[@pos]
+          @pos += 1
+          return sym
+        end
+        if @source[@pos] =~ /[A-Z]/
+          sym = @source[@pos]
+          sym += @source[@pos + 1] if @source[@pos + 1] =~ /[a-z]/
+          @pos += sym.length
+          return sym
+        end
+        raise ParseError, "expected an element symbol at position #{@pos} in #{@source.inspect}"
+      end
+
+      def reject_chirality
+        return unless peek == "@"
+
+        token = @source[@pos, 2] == "@@" ? "'@@'" : "'@'"
+        raise ParseError, "chirality #{token} is not supported in the v1 subset"
+      end
+
+      def hcount
+        return nil unless peek == "H"
+
+        @pos += 1
+        count = digits
+        count ? count.to_i : 1
+      end
+
+      # "+" | "++" | "+n" | "-" | "--" | "-n" → number-then-sign.
+      def bracket_charge
+        sign = peek
+        return nil unless sign == "+" || sign == "-"
+
+        @pos += 1
+        second = @source[@pos].to_s
+        count =
+          if second == sign
+            @pos += 1
+            2
+          elsif second =~ /[0-9]/
+            digits.to_i
+          end
+        count&.positive? ? "#{count}#{sign}" : sign
+      end
+
+      def skip_class
+        return unless peek == ":"
+
+        @pos += 1
+        digits
+      end
+
+      def bond_token
+        ch = peek
+        kind = { "-" => :single, "=" => :double, "#" => :triple, "$" => :quadruple,
+                 ":" => :aromatic }[ch]
+        unless kind
+          if ch == "/" || ch == "\\"
+            raise ParseError,
+                  "bond direction #{ch.inspect} (E/Z stereo) is not supported in the v1 subset"
+          end
+          raise ParseError, "expected a bond or atom at position #{@pos} in #{@source.inspect}"
+        end
+        @pos += 1
+        kind
+      end
+
+      def ring_digit
+        if peek == "%"
+          @pos += 1
+          digit = @source[@pos, 2].to_s
+          raise ParseError, "malformed %nn ring closure" unless digit.match?(/\A\d\d\z/)
+
+          @pos += 2
+          digit
+        else
+          d = peek
+          raise ParseError, "expected ring digit at position #{@pos}" unless d =~ /[0-9]/
+
+          @pos += 1
+          d
+        end
+      end
+
+      # -- character helpers -------------------------------------------------
+
+      def peek
+        @source[@pos]
+      end
+
+      def digits
+        start = @pos
+        @pos += 1 while @source[@pos] =~ /[0-9]/
+        @pos == start ? nil : @source[start...@pos]
+      end
+
+      def bond_start?
+        %w[- = # $ : / \\].include?(peek)
+      end
+
+      def digit_start?
+        peek =~ /[0-9%]/
+      end
+
+      def eoc?
+        peek.nil? || %w[. )].include?(peek)
+      end
+
+      def eat(char)
+        return false unless peek == char
+
+        @pos += 1
+        true
+      end
+
+      def expect(char)
+        unless peek == char
+          raise ParseError, "expected #{char.inspect} at position #{@pos} in #{@source.inspect}"
+        end
+
+        @pos += 1
+      end
+    end
+  end
+end

data/lib/asciichem/smiles/writer.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Smiles
+    # Model molecule → deterministic SMILES.
+    #
+    # Deterministic rules (not a canonical-rank algorithm):
+    # - DFS from the first atom.
+    # - At each atom: ring-closure digits first, then branches
+    #   (sorted), then the continuation chain.
+    # - The continuation child is chosen by: single/aromatic bond
+    #   first (multiple bonds become branches, the way chemists write
+    #   SMILES), then the largest unvisited subtree, then the lowest
+    #   index.
+    # - Ring digits are assigned in encounter order (1..9).
+    #
+    # The stability property `write(parse(write(x))) == write(x)` and
+    # structural round-tripping are spec'd. Wedge/hash/dative/wavy
+    # bonds and formula-only molecules raise.
+    class Writer
+      LOWERCASE_AROMATIC = %w[C N O S P B Se As].freeze
+      ORGANIC = %w[B C N O P S F Cl Br I].freeze
+      BOND_TOKENS = {
+        single: "-", double: "=", triple: "#", quadruple: "$", aromatic: ":"
+      }.freeze
+      CONTINUATION_BONDS = %i[single aromatic].freeze
+
+      def initialize(molecule)
+        @molecule = molecule
+      end
+
+      def write
+        atoms, edges = Structure::Graph.build(@molecule)
+        # A single-atom component is valid SMILES (water "O", ions);
+        # multiple atoms with no bonds is a formula, not a structure.
+        if edges.empty? && atoms.length > 1
+          raise ParseError, "molecule has no bonds — a formula is not a structure"
+        end
+
+        @atoms = atoms
+        build_adjacency(edges)
+        @visited = {}
+        @digits = Array.new(atoms.length) { [] }
+        @digit_by_edge = {}
+        @next_digit = 1
+        # Emission builds ordered units (atoms, literals); ring digits
+        # attach to per-atom lists so both endpoints carry them
+        # without string surgery.
+        @units = []
+        @tree_children = Array.new(atoms.length) { [] }
+        @closures = Array.new(atoms.length) { [] }
+        @tree_size = Array.new(atoms.length, 1)
+
+        build_tree(0, nil)
+        compute_tree_size(0)
+        emit(0, nil, nil)
+
+        @units.map do |unit|
+          if unit.first == :atom
+            index = unit.last
+            atom_token(index) + @digits[index].join
+          else
+            unit.last
+          end
+        end.join
+      end
+
+      private
+
+      def build_adjacency(edges)
+        @adjacency = Array.new(@atoms.length) { {} }
+        edges.each do |edge|
+          @adjacency[edge.from][edge.to] = edge.kind
+          @adjacency[edge.to][edge.from] = edge.kind
+        end
+      end
+
+      # Post-order subtree sizes within the DFS tree.
+      def compute_tree_size(index)
+        @tree_children[index].each { |child| compute_tree_size(child) }
+        @tree_size[index] = 1 + @tree_children[index].sum { |child| @tree_size[child] }
+      end
+
+      # First pass: a deterministic DFS tree. Children are visited in
+      # index order; edges to already-visited atoms become closure
+      # digits. Recording the tree first means a branch can never
+      # walk around a ring and swallow the continuation atom.
+      def build_tree(index, parent)
+        @visited[index] = true
+        @adjacency[index].keys.sort.each do |nb|
+          if nb != parent && @visited[nb]
+            @closures[index] << nb
+          else
+            next if @visited[nb]
+
+            @tree_children[index] << nb
+            build_tree(nb, index)
+          end
+        end
+      end
+
+      def emit(index, parent, incoming_kind)
+        @units << [:literal, bond_token(incoming_kind, parent, index)] if parent
+        @units << [:atom, index]
+        @closures[index].each { |nb| ring_digit_for(index, nb) }
+
+        children = @tree_children[index]
+        return if children.empty?
+
+        ordered = children.sort_by { |child| continuation_rank(index, child) }
+        continuation, *branches = ordered
+
+        branches.each do |child|
+          @units << [:literal, "("]
+          emit(child, index, @adjacency[index][child])
+          @units << [:literal, ")"]
+        end
+        emit(continuation, index, @adjacency[index][continuation])
+      end
+
+      # Lower sorts first: single/aromatic bonds continue the chain,
+      # then larger subtrees, then the lexicographically smallest atom
+      # token (order-independent, so the canonical form does not
+      # depend on how the input happened to number the atoms).
+      def continuation_rank(index, child)
+        kind = @adjacency[index][child]
+        priority = CONTINUATION_BONDS.include?(kind) ? 0 : 1
+        [priority, -@tree_size[child], atom_token(child)]
+      end
+
+      def ring_digit_for(a, b)
+        key = [a, b].minmax
+        digit = @digit_by_edge[key]
+        return digit if digit
+
+        raise ParseError, "too many ring closures for SMILES output" if @next_digit > 9
+
+        digit = @next_digit.to_s
+        @next_digit += 1
+        @digit_by_edge[key] = digit
+        # Both atom tokens carry the digit; each endpoint's list
+        # receives it in encounter order.
+        @digits[key.first] << digit
+        @digits[key.last] << digit
+        digit
+      end
+
+
+      def bond_token(kind, from, to)
+        token = BOND_TOKENS[kind]
+        raise ParseError, "#{kind} bonds have no SMILES form (v1 subset)" unless token
+
+        return token if kind != :single && kind != :aromatic
+
+        # Explicit only when the short form would change the meaning:
+        # a single bond between two aromatic atoms must be written;
+        # an aromatic bond is implicit between two aromatic atoms.
+        if kind == :single
+          aromatic?(from) && aromatic?(to) ? token : ""
+        else
+          aromatic?(from) && aromatic?(to) ? "" : token
+        end
+      end
+
+      def atom_token(index)
+        @atom_tokens ||= {}
+        @atom_tokens[index] ||= begin
+          atom = @atoms[index]
+          aromatic = atom.aromatic == true
+          lowercase = aromatic && LOWERCASE_AROMATIC.include?(atom.element)
+          needs_bracket =
+            atom.charge || atom.isotope || atom.hydrogens ||
+            (!ORGANIC.include?(atom.element) && !lowercase) ||
+            (aromatic && !lowercase)
+          unless needs_bracket
+            bare_symbol(atom, lowercase)
+          else
+            symbol = lowercase ? atom.element.downcase : atom.element
+            token = +"["
+            token << atom.isotope if atom.isotope
+            token << symbol
+            if atom.hydrogens
+              token << "H"
+              token << atom.hydrogens.to_s if atom.hydrogens > 1
+            end
+            token << charge_suffix(atom.charge) if atom.charge
+            token << "]"
+          end
+        end
+      end
+
+      def bare_symbol(atom, lowercase)
+        lowercase ? atom.element.downcase : atom.element
+      end
+
+      # The model's number-then-sign charge ("2+") → SMILES ("+2").
+      def charge_suffix(charge)
+        count = charge[/\A\d+/]
+        sign = charge[-1]
+        return sign unless count && count.to_i > 1
+
+        "#{sign}#{count}"
+      end
+
+      def aromatic?(index)
+        @atoms[index].aromatic == true
+      end
+    end
+  end
+end

data/lib/asciichem/smiles.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "parslet"
+
+module AsciiChem
+  # SMILES ingestion and emission for the semantic model
+  # (TODO.v2 09; TODO.impl 57). SMILES is an input syntax for the one
+  # semantic model — parsed molecules are ordinary `Model::Molecule`s
+  # with explicit bonds and ring closures, renderable by every
+  # formatter.
+  #
+  # v1 subset (each deferral has a rejecting spec with an actionable
+  # message): chirality `@`/`@@` and E/Z bond directions `/` `\` are
+  # not parsed; reaction atom maps, queries, and S-groups are out of
+  # scope.
+  module Smiles
+    autoload :Parser, "asciichem/smiles/parser"
+    autoload :Writer, "asciichem/smiles/writer"
+
+    class << self
+      # Parses a SMILES string into a Model::Formula with one
+      # Molecule per dot-disconnected component.
+      def parse(smiles)
+        Parser.new(smiles).parse
+      end
+
+      # Emits deterministic SMILES (DFS from the first atom,
+      # neighbours in creation order, ring digits assigned in
+      # encounter order). Not a canonical-rank algorithm; the
+      # stability property `write(parse(write(x))) == write(x)`
+      # holds and is spec'd.
+      def write(node)
+        case node
+        when AsciiChem::Model::Formula
+          node.nodes.map { |m| Writer.new(m).write }.join(".")
+        when AsciiChem::Model::Molecule
+          Writer.new(node).write
+        else
+          raise AsciiChem::ParseError,
+                "#{node.class} has no SMILES form (molecules and formulas of molecules only)"
+        end
+      end
+    end
+  end
+end

data/lib/asciichem/structure/graph.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Structure
+    # Model molecule → neutral graph. Bond tokens between consecutive
+    # atoms become edges (pending-bond semantics, same as the Layout
+    # walker); ring-closure digits become edges via AsciiChem::RingBonds.
+    module Graph
+      Edge = Struct.new(:from, :to, :kind, keyword_init: true)
+
+      class << self
+        # Returns [atoms, edges] where atoms is the atom array in
+        # walk order and edges is an array of Edge with array indexes.
+        def build(molecule)
+          atoms = []
+          edges = []
+          index_by_object_id = {}
+          pending = nil
+          last = nil
+
+          walk = lambda do |nodes|
+            nodes.each do |node|
+              case node
+              when AsciiChem::Model::Atom
+                index = atoms.length
+                # Atoms override == with value equality (benzene's
+                # carbons are all equal), so identity is by object_id —
+                # same as the Layout walker.
+                index_by_object_id[node.object_id] = index
+                atoms << node
+                if pending && last
+                  edges << Edge.new(from: last, to: index, kind: pending.kind)
+                end
+                last = index
+                pending = nil
+              when AsciiChem::Model::Bond
+                pending = node
+              when AsciiChem::Model::Group, AsciiChem::Model::Molecule
+                walk.call(node.nodes)
+              end
+            end
+          end
+          walk.call(molecule.nodes)
+
+          AsciiChem::RingBonds.each_in(molecule) do |ring|
+            from = index_by_object_id[ring.from_atom.object_id]
+            to = index_by_object_id[ring.to_atom.object_id]
+            next unless from && to
+
+            # Ring-closure digits carry no kind; the default bond rule
+            # (aromatic between aromatic atoms, otherwise single)
+            # applies — the same rule the SMILES parser uses.
+            kind = ring.from_atom.aromatic && ring.to_atom.aromatic ? :aromatic : :single
+            edges << Edge.new(from: from, to: to, kind: kind)
+          end
+
+          [atoms, edges]
+        end
+      end
+    end
+  end
+end

data/lib/asciichem/structure/linearizer.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Structure
+    # Adjacency → linear model nodes. Atoms are emitted in the
+    # caller's creation order (a DFS order for parsers that walk
+    # depth-first). An edge between consecutive atoms becomes a
+    # `Bond` token; every other edge becomes a pair of matching ring
+    # closure digits — exactly the mechanism AsciiChem's own ring
+    # syntax uses, so downstream walkers (`RingBonds`, Layout,
+    # ModelAdapter) see the graph with no new machinery.
+    #
+    # Ring digits are allocated 1..9 and reused only once the
+    # previous interval (first endpoint .. second endpoint, in atom
+    # order) has closed: `RingBonds` pairs digits by occurrence order
+    # across the molecule, so overlapping intervals must never share
+    # a digit.
+    class Linearizer
+      MAX_DIGIT = 9
+
+      def initialize(atoms:, edges:)
+        @atoms = atoms
+        @edges = edges
+        @close_at = Array.new(MAX_DIGIT, -1)
+        @digits_for = Array.new(@atoms.length) { "" }
+        @token_before = {}
+      end
+
+      # Returns the node array (Atoms and Bonds interleaved) and
+      # mutates the atoms' `ring_closures` with the allocated digits.
+      def nodes
+        @edges.each do |edge|
+          first, last = [edge.from, edge.to].minmax
+          if last - first == 1
+            @token_before[last] = edge.kind
+          else
+            digit = allocate_digit(first, last)
+            @digits_for[first] += digit
+            @digits_for[last] += digit
+          end
+        end
+
+        result = []
+        @atoms.each_with_index do |atom, index|
+          kind = @token_before[index]
+          result << AsciiChem::Model::Bond.new(kind: kind || :single) if index.positive? && kind
+          atom.ring_closures = @digits_for[index] unless @digits_for[index].empty?
+          result << atom
+        end
+        result
+      end
+
+      private
+
+      def allocate_digit(first, last)
+        digit_index = (0...MAX_DIGIT).find { |d| @close_at[d] <= first }
+        unless digit_index
+          raise AsciiChem::ParseError,
+                "more than #{MAX_DIGIT} overlapping non-adjacent bonds — " \
+                "beyond the model's ring-closure digit capacity"
+        end
+        @close_at[digit_index] = last
+        (digit_index + 1).to_s
+      end
+    end
+  end
+end

data/lib/asciichem/structure.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  # Shared structure plumbing for the interchange formats (SMILES,
+  # molfile). Two MECE concerns:
+  #
+  # - `Structure::Graph.build(molecule)` — model molecule → neutral
+  #   atom list + bond list (adjacency), using the same pending-bond
+  #   walk semantics as the Layout walker plus `RingBonds` closure
+  #   edges.
+  # - `Structure::Linearizer` — adjacency → linear model nodes (atoms
+  #   in creation order, `Bond` tokens for consecutive edges, ring
+  #   closure digits for non-consecutive edges). This is what lets an
+  #   arbitrary graph from a database live inside the existing model
+  #   and render through every existing formatter.
+  module Structure
+    autoload :Graph, "asciichem/structure/graph"
+    autoload :Linearizer, "asciichem/structure/linearizer"
+  end
+end