asciichem 0.20.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a77da515ac52e848a4ff0f5855a595cb81d71a36c18b4991d875d682d2c3598
-  data.tar.gz: 70c14be9ddec1e767ddddef09a1ad91a02f996f1fdd22645d0269c4de7e96020
+  metadata.gz: 2dee0024c277879fed3b5695a76e336067660467724663c4a67f71ec87215e80
+  data.tar.gz: 50d5a53fd8d4f64a0d3969c586e81552faed9221a8f209932cd6823a2a966327
 SHA512:
-  metadata.gz: b71e29edd758d5d4393d750a95676dc8007c5850f830b414ca83a2d21e99c1ff39fa88f5f66b54198e442e7d29b9010639c4a55138567cd9dee8160d5b2be3dc
-  data.tar.gz: f08f835457ce6d58b70ff0b3bc502f84f4404684a13ae60ad52bbae44a790dfd66621c15bba73ed2843e0d76ba4ef47545a37e838867b54d12eb9246f11277b6
+  metadata.gz: 3afdd1db8e99729ca9a1a49be7a748fd56d1fdb666b5bfe10bb03a08c6d7db440ca82b3c900b6f22f09ac66901d7c086913a2a3e8c142bc6c7d776f21959c629
+  data.tar.gz: ba3091db4ea3a3d7ba8dcd28f9689df323b135e1e1e4f0a3f3573f14350448461f9f3ade4e20fe4e7af9408d0ce40c1764bba4d609a05bd770705be431ca497b

data/CHANGELOG.md

@@ -3,6 +3,29 @@
 All notable changes to AsciiChem are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.21.0] - 2026-09-12
+
+### Added
+- Structure interchange (TODO.v2 09, TODO.impl 57): SMILES and
+  molfile (CTfile V2000) ingestion and emission as modules of the one
+  semantic model — `AsciiChem.parse_smiles` / `parse_molfile`,
+  `to_smiles` / `to_molfile`. Ingested molecules are ordinary
+  `Model::Molecule`s: graphs linearise into atoms + bond tokens +
+  ring-closure digits (`Structure::Linearizer`), so every existing
+  renderer, linter, and wire form works unchanged. The SMILES writer
+  is deterministic (DFS, single-bond continuations, order-independent
+  tie-breaks); aspirin and naphthalene round-trip exactly. v1
+  deferrals, each with an actionable `ParseError`: chirality `@`/`@@`,
+  E/Z directions `/` `\`, wildcard atoms, bonded ring closures.
+- `Model::Atom#aromatic` / `#hydrogens` and an `aromatic` bond kind
+  (asciichem-model 0.4.0 fields): lowercase SMILES atoms, bracket
+  H-counts, molfile type-4 bonds (aromatic atoms marked from bonds).
+- `AsciiChem::Structure` — shared graph walk + adjacency linearizer
+  for the interchange formats; `StructuralSvg` renders aromatic bonds
+  dashed; wire form carries the new fields both ways.
+- Corpus levels: asciichem-tests v0.3.0 `structure/smiles/*` and
+  `structure/molfile/*` fixtures at 100% (37 + 6 cases).
+
 ## [0.20.0] - 2026-09-12
 
 ### Added
@@ -363,7 +386,8 @@ This project follows [Semantic Versioning](https://semver.org/).
   `version`.
 - Comprehensive RSpec suite with round-trip conformance.
 
-[Unreleased]: https://github.com/asciichem/asciichem-ruby/compare/v0.20.0...HEAD
+[Unreleased]: https://github.com/asciichem/asciichem-ruby/compare/v0.21.0...HEAD
+[0.21.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.20.0...v0.21.0
 [0.20.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.19.0...v0.20.0
 [0.18.1]: https://github.com/asciichem/asciichem-ruby/compare/v0.18.0...v0.18.1
 [0.18.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.17.0...v0.18.0

data/lib/asciichem/formatter/structural_svg.rb

@@ -258,6 +258,14 @@ module AsciiChem
         RENDERERS = {
           single: ->(r) { [r.base_line] },
 
+          # Aromatic bonds render as dashed lines (the inner-ring
+          # circle is a renderer nicety left for a later iteration).
+          aromatic: lambda do |r|
+            line = r.base_line
+            line['stroke-dasharray'] = '4 2.5'
+            [line]
+          end,
+
           double: ->(r) { [-SPACING, 0, SPACING].map { |d| r.offset_line(d) }.compact },
 
           triple: ->(r) { [0, -SPACING * 1.5, SPACING * 1.5].map { |d| r.offset_line(d) }.compact },

data/lib/asciichem/model/atom.rb

@@ -34,7 +34,7 @@ module AsciiChem
       attr_accessor :element, :isotope, :subscript, :superscript,
                     :charge, :oxidation_state,
                     :lone_pairs, :radical_electrons,
-                    :ring_closures,
+                    :ring_closures, :aromatic, :hydrogens,
                     :x2, :y2, :z2, :atom_parity,
                     :spin_multiplicity, :atom_title,
                     :x_fract, :y_fract, :z_fract
@@ -58,7 +58,7 @@ module AsciiChem
       def initialize(element:, isotope: nil, subscript: nil,
                      superscript: nil, charge: nil, oxidation_state: nil,
                      lone_pairs: nil, radical_electrons: nil,
-                     ring_closures: nil,
+                     ring_closures: nil, aromatic: nil, hydrogens: nil,
                      x2: nil, y2: nil, z2: nil, atom_parity: nil,
                      spin_multiplicity: nil, atom_title: nil,
                      x_fract: nil, y_fract: nil, z_fract: nil)
@@ -71,6 +71,8 @@ module AsciiChem
         @lone_pairs = lone_pairs
         @radical_electrons = radical_electrons
         @ring_closures = ring_closures
+        @aromatic = aromatic
+        @hydrogens = hydrogens
         @x2 = x2
         @y2 = y2
         @z2 = z2
@@ -87,7 +89,8 @@ module AsciiChem
           superscript: superscript, charge: charge,
           oxidation_state: oxidation_state,
           lone_pairs: lone_pairs, radical_electrons: radical_electrons,
-          ring_closures: ring_closures,
+          ring_closures: ring_closures, aromatic: aromatic,
+          hydrogens: hydrogens,
           x2: x2, y2: y2, z2: z2, atom_parity: atom_parity,
           spin_multiplicity: spin_multiplicity, atom_title: atom_title,
           x_fract: x_fract, y_fract: y_fract, z_fract: z_fract }
@@ -108,6 +111,8 @@ module AsciiChem
         parts << "^(#{oxidation_state})" if oxidation_state
         parts << ".#{radical_electrons}" if radical_electrons
         parts << ring_closures.to_s if ring_closures
+        parts << "aromatic" if aromatic
+        parts << "H#{hydrogens}" if hydrogens
         "Atom(#{parts.join})"
       end
     end

data/lib/asciichem/model/bond.rb

@@ -14,7 +14,8 @@ module AsciiChem
         wedge:     { ascii: ">-", mathml_entity: "↑" },
         hash:      { ascii: "-<", mathml_entity: "↓" },
         dative:    { ascii: "~>", mathml_entity: "→" },
-        wavy:      { ascii: "~~", mathml_entity: "∼" }
+        wavy:      { ascii: "~~", mathml_entity: "∼" },
+        aromatic:  { ascii: ":",  mathml_entity: ":" }
       }.freeze
 
       # CML wire order codes per bond kind. Single source of truth

data/lib/asciichem/model/node.rb

@@ -70,6 +70,18 @@ module AsciiChem
         AsciiChem::WireAdapter.to_model_json(self)
       end
 
+      # Deterministic SMILES for a Molecule (or dot-joined components
+      # for a Formula). Raises for constructs with no SMILES form.
+      def to_smiles
+        AsciiChem::Smiles.write(self)
+      end
+
+      # Molfile V2000 for a Molecule. Authored coordinates win; a
+      # deterministic 2D layout is computed otherwise.
+      def to_molfile(name: nil)
+        AsciiChem::Molfile.write(self, name: name)
+      end
+
       # Subclasses override to expose the attributes that participate in
       # equality. Default: empty (so two bare Nodes are equal).
       def value_attributes

data/lib/asciichem/molfile/parser.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Molfile
+    # V2000 molfile → Model::Molecule. Fixed-format blocks: header
+    # (3 lines), counts line, atom block, bond block, property block.
+    # Charges come from `M  CHG`, isotopes from the mass-difference
+    # field or `M  ISO`, bond stereo codes 1/6 become wedge/hash.
+    class Parser
+      def initialize(text)
+        @lines = text.lines.map(&:chomp)
+      end
+
+      def parse
+        raise ParseError, "molfile too short" if @lines.length < 5
+
+        atom_field = field(3, 0, 3)
+        bond_field = field(3, 3, 3)
+        unless atom_field.match?(/\A\d+\z/) && bond_field.match?(/\A\d+\z/)
+          raise ParseError, "malformed counts line: #{@lines[3].inspect}"
+        end
+        atom_count = atom_field.to_i
+        bond_count = bond_field.to_i
+
+        atoms = parse_atoms(atom_count)
+        bonds = parse_bonds(bond_count)
+        properties = parse_properties
+
+        apply_legacy_charge!(atoms)
+        apply_charges!(atoms, properties[:charges])
+        apply_isotopes!(atoms, properties[:isotopes])
+
+        adjacency = Array.new(atoms.length) { {} }
+        bonds.each do |bond|
+          adjacency[bond[:from]][bond[:to]] = bond[:kind]
+          adjacency[bond[:to]][bond[:from]] = bond[:kind]
+        end
+
+        # V2000 carries aromaticity on bonds (type 4); the model
+        # carries it on atoms and bonds, so atoms touching an
+        # aromatic bond are marked aromatic.
+        bonds.each do |bond|
+          next unless bond[:kind] == :aromatic
+
+          atoms[bond[:from]].aromatic = true
+          atoms[bond[:to]].aromatic = true
+        end
+
+        Model::Molecule.new(
+          nodes: Structure::Linearizer.new(atoms: atoms, edges: adjacency_to_edges(adjacency)).nodes
+        )
+      end
+
+      private
+
+      def field(line_index, start, length)
+        (@lines[line_index] || "")[start, length].to_s.strip
+      end
+
+      def parse_atoms(count)
+        (1..count).map do |i|
+          line_index = 3 + i
+          line = @lines[line_index]
+          raise ParseError, "truncated atom block (expected #{count} atoms)" if line.nil?
+
+          x = line[0, 10].to_f
+          y = line[10, 10].to_f
+          z = line[20, 10].to_f
+          element = line[31, 3].to_s.strip
+          mass_diff = line[34, 2].to_i
+          raise ParseError, "atom #{i} has no element symbol" if element.empty?
+
+          Model::Atom.new(
+            element: element,
+            x2: x, y2: y, z2: z,
+            isotope: isotope_from_mass_diff(element, mass_diff)
+          )
+        end
+      end
+
+      def parse_bonds(count)
+        (1..count).map do |i|
+          line = @lines[3 + atoms_count + i]
+          raise ParseError, "truncated bond block (expected #{count} bonds)" if line.nil?
+
+          from = line[0, 3].to_i - 1
+          to = line[3, 3].to_i - 1
+          type = line[6, 3].to_i
+          stereo = line[9, 3].to_i
+          raise ParseError, "bond #{i} has out-of-range atom indexes" if from.negative? || to.negative?
+
+          { from: from, to: to, kind: bond_kind(type, stereo) }
+        end
+      end
+
+      def parse_properties
+        charges = {}
+        isotopes = {}
+        @lines.each do |line|
+          if line.start_with?("M  CHG")
+            parts = line[6..].split
+            _count = parts[0].to_i
+            parts[1..].each_slice(2) do |idx, charge|
+              charges[idx.to_i - 1] = charge.to_i if idx && charge
+            end
+          elsif line.start_with?("M  ISO")
+            parts = line[6..].split
+            parts[1..].each_slice(2) do |idx, mass|
+              isotopes[idx.to_i - 1] = mass.to_i if idx && mass
+            end
+          end
+        end
+        { charges: charges, isotopes: isotopes }
+      end
+
+      def bond_kind(type, stereo)
+        return :wedge if stereo == 1
+        return :hash if stereo == 6
+
+        { 1 => :single, 2 => :double, 3 => :triple, 4 => :aromatic }[type] ||
+          raise(ParseError, "unsupported molfile bond type #{type}")
+      end
+
+      # Pre-CHG charge column (0-based 36, 3): nonzero values 1..4
+      # mean +1..+4, 5..7 mean -1..-3. `M  CHG` overrides.
+      def apply_legacy_charge!(atoms)
+        (1..field(3, 0, 3).to_i).each do |i|
+          code = field(3 + i, 36, 3).to_i
+          next if code.zero?
+
+          charge = code <= 4 ? code : 4 - code
+          sign = charge.negative? ? "-" : "+"
+          atoms[i - 1].charge = charge.abs == 1 ? sign : "#{charge.abs}#{sign}"
+        end
+      end
+
+      def apply_charges!(atoms, charges)
+        charges.each do |index, value|
+          sign = value.negative? ? "-" : "+"
+          atoms[index].charge = value.abs == 1 ? sign : "#{value.abs}#{sign}"
+        end
+      end
+
+      def apply_isotopes!(atoms, isotopes)
+        isotopes.each do |index, mass|
+          atoms[index].isotope = mass.to_s
+        end
+      end
+
+      # Mass difference encodes isotopes relative to the rounded
+      # average mass; mapping it unambiguously requires isotope
+      # tables, so v1 defers isotopes to the explicit `M  ISO` block.
+      def isotope_from_mass_diff(_element, mass_diff)
+        nil
+      end
+      def atoms_count
+        field(3, 0, 3).to_i
+      end
+
+      def adjacency_to_edges(adjacency)
+        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
+        edges
+      end
+    end
+  end
+end

data/lib/asciichem/molfile/writer.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Molfile
+    # Model molecule → V2000 molfile. Authored x2/y2 coordinates are
+    # used when present; otherwise a deterministic 2D layout is
+    # computed (Layout walks atoms in the same order as
+    # Structure::Graph, so positions map by index). Charges and
+    # isotopes are emitted as `M  CHG` / `M  ISO` property lines.
+    class Writer
+      BOND_TYPES = {
+        single: 1, double: 2, triple: 3, aromatic: 4,
+        wedge: 1, hash: 1
+      }.freeze
+      BOND_STEREO = { wedge: 1, hash: 6 }.freeze
+
+      def initialize(molecule, name: nil)
+        @molecule = molecule
+        @name = name
+      end
+
+      def write
+        atoms, edges = Structure::Graph.build(@molecule)
+        raise ParseError, "molecule has no bonds — a formula is not a structure" if edges.empty?
+
+        lines = []
+        lines << @name.to_s
+        lines << "  AsciiChem"
+        lines << ""
+        lines << format("%3d%3d  0  0  0  0  0  0  0  0999 V2000", atoms.length, edges.length)
+
+        layout = nil
+        atoms.each_with_index do |atom, index|
+          x, y = coordinates(atom, index, atoms)
+          lines << format("%10.4f%10.4f%10.4f %-3s 0  0  0  0  0  0  0  0  0  0  0  0",
+                          x, y, atom.z2 || 0.0, atom.element)
+        end
+
+        edges.each do |edge|
+          type = BOND_TYPES.fetch(edge.kind) do
+            raise ParseError, "#{edge.kind} bonds have no molfile V2000 type"
+          end
+          stereo = BOND_STEREO.fetch(edge.kind, 0)
+          lines << format("%3d%3d%3d%3d  0  0  0  0  0  0  0",
+                          edge.from + 1, edge.to + 1, type, stereo)
+        end
+
+        lines << property_line("M  CHG", charge_pairs(atoms))
+        lines << property_line("M  ISO", isotope_pairs(atoms))
+        lines << "M  END"
+        lines.compact.join("\n") << "\n"
+      end
+
+      private
+
+      # Authored coordinates win; otherwise positions from the
+      # deterministic 2D layout (same walk order as the graph).
+      def coordinates(atom, index, atoms)
+        return [atom.x2, atom.y2] if atom.x2 && atom.y2
+
+        @layout ||= AsciiChem::Layout.layout(@molecule)
+        placed = @layout.atoms[index]
+        placed ? [placed.x, placed.y] : [0.0, 0.0]
+      end
+
+      def charge_pairs(atoms)
+        atoms.each_with_index
+             .filter_map { |atom, i| [i + 1, charge_value(atom.charge)] if atom.charge }
+      end
+
+      def isotope_pairs(atoms)
+        atoms.each_with_index
+             .filter_map { |atom, i| [i + 1, atom.isotope.to_i] if atom.isotope }
+      end
+
+      # The model's number-then-sign charge ("2+") → signed integer.
+      def charge_value(charge)
+        count = charge[/\A\d+/]&.to_i || 1
+        charge.end_with?("-") ? -count : count
+      end
+
+      def property_line(prefix, pairs)
+        return nil if pairs.empty?
+
+        pairs.reduce(+"#{prefix}%3d" % pairs.length) do |line, (idx, value)|
+          line << format("%4d%4d", idx, value)
+        end
+      end
+    end
+  end
+end

data/lib/asciichem/molfile.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  # Molfile (CTfile V2000) ingestion and emission (TODO.v2 09;
+  # TODO.impl 57). Molfile is the highest-fidelity structure path:
+  # atom coordinates are preserved on the model (x2/y2/z2), charges
+  # via the CHG property block, isotopes via mass difference or the
+  # ISO block, bond stereo codes 1/6 map to wedge/hash bonds.
+  module Molfile
+    autoload :Parser, "asciichem/molfile/parser"
+    autoload :Writer, "asciichem/molfile/writer"
+
+    class << self
+      # Parses a V2000 molfile into a Model::Molecule.
+      def parse(text)
+        Parser.new(text).parse
+      end
+
+      # Emits a V2000 molfile. Uses authored x2/y2 coordinates;
+      # computes a 2D layout otherwise.
+      def write(molecule, name: nil)
+        Writer.new(molecule, name: name).write
+      end
+    end
+  end
+end

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

data/lib/asciichem/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AsciiChem
-  VERSION = "0.20.0"
+  VERSION = "0.21.0"
 end

data/lib/asciichem/wire/core.rb

@@ -16,6 +16,8 @@ module AsciiChem
       attribute :lone_pairs, :integer
       attribute :radical_electrons, :integer
       attribute :ring_closures, :string
+      attribute :aromatic, :boolean
+      attribute :hydrogens, :integer
       json do
         map "element", to: :element
         map "isotope", to: :isotope
@@ -25,6 +27,8 @@ module AsciiChem
         map "lonePairs", to: :lone_pairs
         map "radicalElectrons", to: :radical_electrons
         map "ringClosures", to: :ring_closures
+        map "aromatic", to: :aromatic
+        map "hydrogens", to: :hydrogens
       end
     end
 

data/lib/asciichem/wire_adapter.rb

@@ -105,7 +105,9 @@ module AsciiChem
           oxidation_state: str_or_nil(atom.oxidation_state),
           lone_pairs: int_or_nil(atom.lone_pairs),
           radical_electrons: int_or_nil(atom.radical_electrons),
-          ring_closures: str_or_nil(atom.ring_closures)
+          ring_closures: str_or_nil(atom.ring_closures),
+          aromatic: bool_or_nil(atom.aromatic),
+          hydrogens: int_or_nil(atom.hydrogens)
         )
       end
 
@@ -121,6 +123,10 @@ module AsciiChem
         value.is_a?(String) ? value : nil
       end
 
+      def bool_or_nil(value)
+        value.nil? ? nil : !!value
+      end
+
       def int_or_nil(value)
         value.is_a?(Integer) ? value : nil
       end
@@ -280,7 +286,8 @@ module AsciiChem
           element: wire.element, isotope: wire.isotope, subscript: wire.subscript,
           charge: wire.charge, oxidation_state: wire.oxidation_state,
           lone_pairs: wire.lone_pairs, radical_electrons: wire.radical_electrons,
-          ring_closures: wire.ring_closures
+          ring_closures: wire.ring_closures,
+          aromatic: wire.aromatic, hydrogens: wire.hydrogens
         )
       end
 

data/lib/asciichem.rb

@@ -22,9 +22,12 @@ module AsciiChem
   autoload :Linter, "asciichem/linter"
   autoload :Model, "asciichem/model"
   autoload :ModelAdapter, "asciichem/model_adapter"
+  autoload :Molfile, "asciichem/molfile"
   autoload :Parser, "asciichem/parser"
   autoload :PeriodicTable, "asciichem/periodic_table"
   autoload :RingBonds, "asciichem/ring_bonds"
+  autoload :Smiles, "asciichem/smiles"
+  autoload :Structure, "asciichem/structure"
   autoload :Transform, "asciichem/transform"
   autoload :VERSION, "asciichem/version"
   autoload :Wire, "asciichem/wire"
@@ -41,4 +44,17 @@ module AsciiChem
   def self.from_model_json(json)
     WireAdapter.from_model_json(json)
   end
+
+  # Ingests a SMILES string into the semantic model (TODO.v2 09):
+  # one Model::Molecule per dot-disconnected component, explicit
+  # bonds and ring closures, renderable by every formatter.
+  def self.parse_smiles(smiles)
+    Smiles.parse(smiles)
+  end
+
+  # Ingests a molfile (CTfile V2000) into a Model::Molecule,
+  # preserving atom coordinates.
+  def self.parse_molfile(text)
+    Molfile.parse(text)
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asciichem
 version: !ruby/object:Gem::Version
-  version: 0.20.0
+  version: 0.21.0
 platform: ruby
 authors:
 - Ribose Inc.
@@ -223,9 +223,18 @@ files:
 - lib/asciichem/model_adapter.rb
 - lib/asciichem/model_adapter/from_canonical.rb
 - lib/asciichem/model_adapter/to_canonical.rb
+- lib/asciichem/molfile.rb
+- lib/asciichem/molfile/parser.rb
+- lib/asciichem/molfile/writer.rb
 - lib/asciichem/parser.rb
 - lib/asciichem/periodic_table.rb
 - lib/asciichem/ring_bonds.rb
+- lib/asciichem/smiles.rb
+- lib/asciichem/smiles/parser.rb
+- lib/asciichem/smiles/writer.rb
+- lib/asciichem/structure.rb
+- lib/asciichem/structure/graph.rb
+- lib/asciichem/structure/linearizer.rb
 - lib/asciichem/transform.rb
 - lib/asciichem/version.rb
 - lib/asciichem/wire.rb