asciichem 0.3.0

data/lib/asciichem/formatter/svg.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Formatter
+    # Renders a Model tree as a linear SVG. The SVG draws the formula
+    # along a horizontal baseline with elements at fixed spacing.
+    #
+    # This is the v1 fallback for environments that want a self-contained
+    # vector output without MathML. True 2D structural diagrams (skeletal
+    # formulae, rings, stereo wedges) require `mn/elk-rb` integration
+    # (TODO 13); this formatter does not attempt that.
+    class Svg < Base
+      LINE_HEIGHT = 40
+      CHAR_WIDTH  = 14
+      BASELINE    = 30
+
+      def visit_formula(formula)
+        nodes = formula.nodes
+        rows = layout_rows(nodes)
+        width = rows.map { |r| layout_width(r) }.max
+        height = rows.size * LINE_HEIGHT + 10
+        render_svg(width, height, rows)
+      end
+
+      def visit_molecule(molecule)
+        prefix = molecule.coefficient.nil? || molecule.coefficient.to_s.empty? ? "" : molecule.coefficient.to_s
+        stereo = molecule.stereo ? "(#{molecule.stereo_letter})-" : ""
+        body = molecule.nodes.map { |n| render_node(n) }.join
+        "#{stereo}#{prefix}#{body}"
+      end
+
+      def visit_atom(atom)
+        parts = []
+        parts << "^#{atom.isotope}" if atom.isotope
+        parts << atom.element
+        parts << "_#{atom.subscript}" if atom.subscript
+        if atom.charge
+          parts << "^#{atom.charge}"
+        elsif atom.oxidation_state
+          parts << "^(#{atom.oxidation_state})"
+        elsif atom.superscript
+          parts << "^#{atom.superscript}"
+        end
+        parts << atom.ring_closures.to_s if atom.ring_closures
+        parts.join
+      end
+
+      def visit_group(group)
+        body = group.nodes.map { |n| render_node(n) }.join
+        suffix = group.multiplicity ? "_#{group.multiplicity}" : ""
+        "#{group.open_char}#{body}#{group.close_char}#{suffix}"
+      end
+
+      def visit_bond(bond)
+        bond.ascii
+      end
+
+      def visit_reaction(reaction)
+        left = reaction.reactants.map { |n| render_node(n) }.join(" + ")
+        right = reaction.products.map { |n| render_node(n) }.join(" + ")
+        arrow = reaction.arrow_ascii
+        conds = reaction.conditions
+        return "#{left} #{arrow} #{right}" unless conds
+
+        above = conds.above ? "[#{conds.above}]" : ""
+        below = conds.below ? "[#{conds.below}]" : ""
+        "#{left} #{arrow}#{above}#{below} #{right}"
+      end
+
+      def visit_reaction_cascade(cascade)
+        return "" if cascade.steps.empty?
+
+        head = cascade.steps.first
+        out = head.reactants.map { |n| render_node(n) }.join(" + ")
+        cascade.steps.each do |step|
+          arrow = step.arrow_ascii
+          conds = step.conditions
+          if conds
+            above = conds.above ? "[#{conds.above}]" : ""
+            below = conds.below ? "[#{conds.below}]" : ""
+            out += " #{arrow}#{above}#{below}"
+          else
+            out += " #{arrow}"
+          end
+          out += " " + step.products.map { |n| render_node(n) }.join(" + ")
+        end
+        out
+      end
+
+      def visit_electron_configuration(ec)
+        ec.orbitals.map { |orb, occ| "#{orb}^#{occ}" }.join(" ")
+      end
+
+      def visit_embedded_math(em)
+        em.source.to_s
+      end
+
+      def visit_text(text)
+        text.content
+      end
+
+      private
+
+      def render_node(node)
+        node.accept(self)
+      end
+
+      def layout_rows(nodes)
+        # v1: one row. Multi-row layout deferred until 2D structural
+        # support arrives (TODO 13).
+        [nodes.map { |n| render_node(n) }.join]
+      end
+
+      def layout_width(row)
+        row.length * CHAR_WIDTH + 20
+      end
+
+      def render_svg(width, height, rows)
+        title = rows.join(" ").gsub(/[<>&]/, "" => "")
+        lines = []
+        lines << %(<?xml version="1.0" encoding="UTF-8"?>)
+        lines << %(<svg xmlns="http://www.w3.org/2000/svg" width="#{width}" height="#{height}" viewBox="0 0 #{width} #{height}" role="img" aria-label="#{escape(title)}">)
+        lines << %(  <title>#{escape(title)}</title>)
+        lines << %(  <rect width="100%" height="100%" fill="transparent"/>)
+        rows.each_with_index do |row, idx|
+          y = BASELINE + (idx * LINE_HEIGHT)
+          lines << %(  <text x="10" y="#{y}" font-family="serif" font-size="20" fill="currentColor">#{escape(row)}</text>)
+        end
+        lines << %(</svg>)
+        lines.join("\n")
+      end
+
+      def escape(string)
+        string.to_s
+              .gsub("&", "&amp;")
+              .gsub("<", "&lt;")
+              .gsub(">", "&gt;")
+      end
+    end
+  end
+end

data/lib/asciichem/formatter/text.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Formatter
+    # Renders a Model tree as canonical AsciiChem text. Round-trip
+    # conformance: `AsciiChem.parse(s).to_text == s` for any conformant
+    # `s`. The formatter is the canonicaliser — equivalent inputs map
+    # to the same output.
+    #
+    # Canonicalisation rules (v1):
+    # - Explicit subscript marker: `H_2`, not `H2`.
+    # - Coefficient before molecule: `2H_2O`.
+    # - Isotope binds to atom: `^14C` (no `{}` carrier).
+    # - Charge is number-then-sign per IUPAC: `Ca^2+`.
+    # - Oxidation state in roman numerals with parens: `Fe^(III)`.
+    # - Group brackets preserved from input.
+    # - Reaction arrows use the canonical ASCII spelling (`->`, `<-`,
+    #   `<=>`, `<->`).
+    class Text < Base
+      def visit_formula(formula)
+        formula.nodes.map { |n| render_node(n) }.join(" ")
+      end
+
+      def visit_molecule(molecule)
+        prefix = molecule.coefficient.nil? || molecule.coefficient.empty? ? "" : molecule.coefficient.to_s
+        stereo = molecule.stereo ? "(#{molecule.stereo_letter})-" : ""
+        body = molecule.nodes.map { |n| render_node(n) }.join
+        annotations = molecule_annotations(molecule)
+        "#{stereo}#{prefix}#{body}#{annotations}"
+      end
+
+      def molecule_annotations(molecule)
+        parts = []
+        molecule.names.each { |n| parts << %(@name("#{n.content}")) }
+        molecule.identifiers.each { |i| parts << %(@#{i.convention}("#{i.value}")) }
+        parts << %(@title("#{molecule.title}")) if molecule.title
+        molecule.formulas.each { |f| parts << %(@formula("#{f[:concise]}")) if f[:concise] }
+        molecule.labels.each { |l| parts << %(@label("#{l[:value]}")) if l[:value] }
+        molecule.properties.each { |p| parts << %(@#{p[:title]}("#{p[:value]}")) if p[:title] && p[:value] }
+        molecule.metadata.each { |m| parts << %(@meta("#{m[:name]}","#{m[:content]}")) }
+        parts.empty? ? "" : " #{parts.join}"
+      end
+
+      def visit_atom(atom)
+        parts = []
+        parts << (":" * atom.lone_pairs) if atom.lone_pairs
+        parts << "^#{atom.isotope}"        if atom.isotope
+        parts << atom.element
+        parts << "_#{atom.subscript}"      if atom.subscript
+        parts << "^#{atom.superscript}"    if atom.superscript
+        parts << "^#{atom.charge}"         if atom.charge
+        parts << "^(#{atom.oxidation_state})" if atom.oxidation_state
+        parts << ("." * atom.radical_electrons) if atom.radical_electrons
+        parts << atom.ring_closures.to_s if atom.ring_closures
+        parts << atom_annotation(atom)
+        parts.join
+      end
+
+      def atom_annotation(atom)
+        annotation = +""
+        if atom.x2 && atom.y2
+          annotation << "@(#{format_coord(atom.x2)},#{format_coord(atom.y2)}"
+          annotation << ",#{format_coord(atom.z2)}" if atom.z2
+          annotation << ")"
+        elsif atom.atom_parity
+          annotation << "@#{atom.atom_parity}"
+        end
+        annotation
+      end
+
+      def format_coord(value)
+        value == value.to_i ? value.to_i.to_s : value.to_s
+      end
+
+      def visit_group(group)
+        body = group.nodes.map { |n| render_node(n) }.join
+        suffix = group.multiplicity ? "_#{group.multiplicity}" : ""
+        "#{group.open_char}#{body}#{group.close_char}#{suffix}"
+      end
+
+      def visit_bond(bond)
+        bond.ascii
+      end
+
+      def visit_reaction(reaction)
+        left = reaction.reactants.map { |n| render_node(n) }.join(" + ")
+        right = reaction.products.map { |n| render_node(n) }.join(" + ")
+        arrow = reaction.arrow_ascii
+        conds = reaction.conditions
+        return "#{left} #{arrow} #{right}" unless conds
+
+        above = conds.above ? "[#{conds.above}]" : ""
+        below = conds.below ? "[#{conds.below}]" : ""
+        "#{left} #{arrow}#{above}#{below} #{right}"
+      end
+
+      def visit_reaction_cascade(cascade)
+        return "" if cascade.steps.empty?
+
+        head = cascade.steps.first
+        out = "#{render_terms(head.reactants)} #{render_arrow_with_conditions(head)} #{render_terms(head.products)}"
+        cascade.steps.drop(1).each do |step|
+          out += " #{render_arrow_with_conditions(step)} #{render_terms(step.products)}"
+        end
+        out
+      end
+
+      def visit_electron_configuration(ec)
+        parts = ec.orbitals.map { |orb, occ| "#{orb}^#{occ}" }
+        parts << ec.term_symbol.to_s if ec.term_symbol
+        parts.join(" ")
+      end
+
+      def visit_embedded_math(em)
+        "`#{em.source}`"
+      end
+
+      def visit_text(text)
+        %("#{text.content}")
+      end
+
+      private
+
+      def render_node(node)
+        node.accept(self)
+      end
+
+      def render_terms(terms)
+        terms.map { |n| render_node(n) }.join(" + ")
+      end
+
+      def render_arrow_with_conditions(reaction)
+        arrow = reaction.arrow_ascii
+        conds = reaction.conditions
+        return arrow unless conds
+
+        above = conds.above ? "[#{conds.above}]" : ""
+        below = conds.below ? "[#{conds.below}]" : ""
+        "#{arrow}#{above}#{below}"
+      end
+    end
+  end
+end

data/lib/asciichem/formatter.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  # Format registry. Each output (MathML, Text, HTML, LaTeX, SVG) is a
+  # class under this module. The model's `to_<name>` shortcuts route
+  # through `Formatter[<name>].new.render(node)`.
+  #
+  # To add a new formatter:
+  #   1. Create `lib/asciichem/formatter/<name>.rb` with a class
+  #      `AsciiChem::Formatter::<ClassCamel> < Base`.
+  #   2. Add `autoload :<ClassCamel>, "asciichem/formatter/<name>"` to
+  #      this file.
+  #   3. Add `def to_<name>` to `Model::Node` if a shortcut is desired.
+  #
+  # No edits to existing formatters — OCP.
+  module Formatter
+    autoload :Base, "asciichem/formatter/base"
+    autoload :Html, "asciichem/formatter/html"
+    autoload :Latex, "asciichem/formatter/latex"
+    autoload :Mathml, "asciichem/formatter/mathml"
+    autoload :StructuralSvg, "asciichem/formatter/structural_svg"
+    autoload :Svg, "asciichem/formatter/svg"
+    autoload :Text, "asciichem/formatter/text"
+
+    # Lookup by format name. Triggers autoload; raises FormatError if
+    # the name is not registered. Accepts either snake_case
+    # (`:structural_svg`) or camelCase (`:mathml`) — both resolve to
+    # the matching constant.
+    def self.[](name)
+      const_get(camelize(name.to_s))
+    rescue NameError => e
+      raise AsciiChem::FormatError, "unknown formatter #{name.inspect}: #{e.message}"
+    end
+
+    def self.render(name, node)
+      self[name].new.render(node)
+    end
+
+    private_class_method def self.camelize(string)
+      string.split("_").map(&:capitalize).join
+    end
+  end
+end

data/lib/asciichem/grammar.rb

@@ -0,0 +1,344 @@
+# frozen_string_literal: true
+
+require "parslet"
+
+module AsciiChem
+  # Parslet grammar for AsciiChem v1.
+  #
+  # Design notes:
+  #
+  # - Leaf rules return strings; `.as(:name)` is applied at the
+  #   combination site so the parse tree is a flat hash of named strings
+  #   wherever practical.
+  # - The prefix-isotope binding (`^14C`) is enforced structurally: the
+  #   `prefixed_atom` production consumes `^digits element` as a unit.
+  #   A bare `^digits` without an element is rejected.
+  # - Marker rules (`subscript_marker`, `superscript_marker`) capture
+  #   ONLY the value, not the leading `_` or `^`. The literal prefix is
+  #   consumed by the rule but not included in the named capture.
+  class Grammar < Parslet::Parser
+    root :formula
+
+    # -- top level ---------------------------------------------------------
+
+    rule(:formula) do
+      spaces? >> nodes.as(:formula) >> spaces?
+    end
+
+    rule(:nodes) { node >> (spaces? >> node).repeat }
+
+    rule(:node)  { reaction_cascade | reaction | electron_config | annotated_molecule | molecule | embedded_math | text_run.as(:text_run) }
+
+    # Annotated molecule: a molecule followed by one or more
+    # `@key("value")` annotations for CML metadata (names,
+    # identifiers, title, formula, labels).
+    rule(:annotated_molecule) do
+      molecule.as(:mol) >> molecule_annotation.repeat(1).as(:annotations)
+    end
+
+    rule(:molecule_annotation) do
+      spaces?.maybe >>
+      (metadata_annotation | simple_annotation)
+    end
+
+    # Metadata: @meta("key","value") — two quoted args, comma-separated.
+    # Produces CML <metadata name="key" content="value"/>.
+    # Uses distinct capture keys (meta_key/meta_value) so the transform
+    # can distinguish metadata from regular @key("value") annotations.
+    rule(:metadata_annotation) do
+      str('@meta(') >> str('"') >>
+      (str('"').absent? >> any).repeat.as(:meta_key) >> str('"') >>
+      str(',') >> str('"') >>
+      (str('"').absent? >> any).repeat.as(:meta_value) >> str('"') >>
+      str(')')
+    end
+
+    # Simple annotation: @key("value") — one quoted arg.
+    # Known types (name, inchi, etc.) are handled specially by the
+    # transform. Unknown types become properties.
+    rule(:simple_annotation) do
+      str('@') >> annotation_type.as(:ann_type) >>
+      str('(') >> str('"') >>
+      (str('"').absent? >> any).repeat.as(:ann_value) >>
+      str('"') >> str(')')
+    end
+
+    # Known annotation types first; property_name is a catch-all so
+    # any lowercase word (e.g. "mw", "density", "logP") becomes a
+    # property annotation.
+    rule(:annotation_type) do
+      str('name') | str('title') | str('formula') | str('label') |
+      str('inchi') | str('smiles') | str('cas') | str('iupac') |
+      str('cid') | str('chebi') |
+      property_name
+    end
+
+    rule(:property_name) do
+      match('[a-z]').repeat(1)
+    end
+
+    # -- reactions ---------------------------------------------------------
+
+    # A reaction cascade is two or more reactions chained together:
+    # the products of step N become the reactants of step N+1, with
+    # an arrow between them. The grammar reuses `reaction` for the
+    # first leg and `arrow >> terms` for each subsequent leg; the
+    # transform promotes the whole chain to a `ReactionCascade`.
+    rule(:reaction_cascade) do
+      (reaction.as(:first) >>
+        (arrow.as(:arrow) >> spaces? >> terms.as(:products)).repeat(1)).as(:cascade)
+    end
+
+    rule(:reaction) do
+      terms.as(:reactants) >>
+        arrow.as(:arrow) >>
+        spaces? >>
+        terms.as(:products)
+    end
+
+    rule(:terms) do
+      molecule >> (spaces? >> plus >> spaces? >> molecule).repeat
+    end
+
+    rule(:plus) { str("+") }
+
+    rule(:arrow) do
+      spaces? >>
+        arrow_token.as(:kind) >>
+        condition.maybe.as(:above) >>
+        condition.maybe.as(:below)
+    end
+
+    rule(:condition) do
+      str("[") >> (str("]").absent? >> any).repeat.as(:text) >> str("]")
+    end
+
+    rule(:arrow_token) do
+      str("<=>") | str("<->") | str("->") | str("<-")
+    end
+
+    # -- molecules ---------------------------------------------------------
+
+    rule(:molecule) do
+      stereo_prefix.maybe >> coefficient.maybe >> units.as(:units)
+    end
+
+    # Stereochemistry prefix: `(R)-`, `(S)-`, `(E)-`, `(Z)-`,
+    # `(a)-`/`(α)-` (alpha), `(b)-`/`(β)-` (beta). Tried before
+    # `coefficient` so the lookahead-via-failure on the closed letter
+    # set disambiguates from a parenthesised group: `(R)` matches
+    # because `R` is in the stereo set; `(OH)` fails because `OH` is
+    # not a single stereo letter, and the molecule rule falls through
+    # to the regular group parse.
+    rule(:stereo_prefix) do
+      str("(") >> stereo_letter.as(:stereo) >> str(")") >> str("-")
+    end
+
+    rule(:stereo_letter) do
+      str("alpha") | str("beta") |
+        str("R") | str("S") | str("E") | str("Z") |
+        str("α") | str("β") |
+        str("a") | str("b")
+    end
+
+    rule(:units) { (unit | bond).repeat(1) }
+    rule(:unit)  { prefixed_atom | group | plain_atom }
+
+    # Bonds appear inside molecules as separators between units.
+    # Supported kinds, in alternation order (longest match first to
+    # avoid `>-` shadowing `-`):
+    #   single    `-`
+    #   double    `=`
+    #   triple    `#`
+    #   quadruple `##`
+    #   wedge     `>-`  (solid wedge toward viewer)
+    #   hash      `-<`  (hashed wedge away from viewer)
+    #   dative    `~>`  (electron-pair donor → acceptor; `->` is taken
+    #                    by the reaction arrow)
+    #   wavy      `~~`  (resonance / delocalised)
+    rule(:bond) do
+      str("##").as(:quadruple) |
+        str(">-").as(:wedge) |
+        str("-<").as(:hash) |
+        str("~>").as(:dative) |
+        str("~~").as(:wavy) |
+        str("#").as(:triple) |
+        str("=").as(:double) |
+        str("-").as(:single)
+    end
+
+    rule(:coefficient) do
+      (digits.as(:value) >> (element_symbol | open_bracket).present?).as(:coefficient)
+    end
+
+    rule(:open_bracket) { str("(") | str("[") | str("{") }
+
+    # -- atoms -------------------------------------------------------------
+
+    rule(:prefixed_atom) do
+      (lewis_prefix.maybe >>
+        isotope_marker.as(:isotope) >>
+        element_symbol.as(:element) >>
+        atom_suffix >>
+        lewis_radicals.maybe >>
+        ring_closures.maybe.as(:ring_closures) >>
+        atom_annotation.maybe).as(:atom)
+    end
+
+    rule(:plain_atom) do
+      (lewis_prefix.maybe >>
+        element_symbol.as(:element) >>
+        atom_suffix >>
+        lewis_radicals.maybe >>
+        ring_closures.maybe.as(:ring_closures) >>
+        atom_annotation.maybe).as(:atom)
+    end
+
+    # Atom annotations: stereo parity (@R / @S) or 2D/3D coordinates
+    # (@(x,y) / @(x,y,z)). Both use the `@` prefix. An atom can carry
+    # at most one annotation in the grammar; multiple annotations
+    # would require compound syntax (deferred).
+    rule(:atom_annotation) do
+      coordinate_annotation | parity_annotation
+    end
+
+    rule(:parity_annotation) do
+      str('@') >> (str('R') | str('S')).as(:atom_parity)
+    end
+
+    rule(:coordinate_annotation) do
+      str('@(') >>
+        float_number.as(:x2) >> str(',') >>
+        float_number.as(:y2) >>
+        (str(',') >> float_number.as(:z2)).maybe >>
+        str(')')
+    end
+
+    rule(:float_number) do
+      str('-').maybe >> match('[0-9]').repeat(1) >> (str('.') >> match('[0-9]').repeat(0)).maybe
+    end
+
+    # Ring closure digits (SMILES-style). A digit suffix on an atom
+    # opens or closes a ring; two atoms with the same digit become
+    # bonded. Captured as a string (e.g. "1", "12") so multiple
+    # closures on one atom are preserved.
+    rule(:ring_closures) do
+      match('[0-9]').repeat(1)
+    end
+
+    rule(:atom_suffix) do
+      subscript_marker.maybe.as(:subscript) >>
+        superscript_marker.maybe.as(:superscript)
+    end
+
+    # Lewis markers. Prefix `:` count = lone_pairs (binds to following
+    # atom, like the isotope prefix). Suffix `.` count = radical
+    # electrons. Position-specific lone pairs (`:O:` style) collapse
+    # into a total count — the renderer decides layout.
+    rule(:lewis_prefix) { str(":").repeat(1).as(:lone_pairs) }
+    rule(:lewis_radicals) { str(".").repeat(1).as(:radical_electrons) }
+
+    # Markers consume the leading `_` / `^` but capture only the value.
+    rule(:isotope_marker) do
+      (str("^") | str("_")) >> digits
+    end
+
+    rule(:subscript_marker) do
+      str("_") >> subscript_value
+    end
+
+    rule(:superscript_marker) do
+      str("^") >> superscript_value
+    end
+
+    rule(:element_symbol) do
+      match("[A-Z]") >> match("[a-z]").maybe
+    end
+
+    rule(:subscript_value) do
+      (str("{") >> (str("}").absent? >> any).repeat >> str("}")) |
+        digits
+    end
+
+    rule(:superscript_value) do
+      oxidation_state | charge | braced_or_bare
+    end
+
+    rule(:charge) do
+      (digits >> match("[+-]")) |
+        (match("[+-]") >> digits.maybe) |
+        digits
+    end
+
+    rule(:oxidation_state) do
+      str("(") >> roman_numeral >> str(")")
+    end
+
+    rule(:roman_numeral) { match("[IVXLCDM]").repeat(1) }
+
+    rule(:braced_or_bare) do
+      (str("{") >> (str("}").absent? >> any).repeat >> str("}")) |
+        match("[0-9a-zA-Z]").repeat(1)
+    end
+
+    # -- groups ------------------------------------------------------------
+
+    rule(:group) do
+      group_open.as(:open_bracket) >>
+        group_nodes >>
+        group_close.as(:close_bracket) >>
+        multiplicity.maybe.as(:multiplicity)
+    end
+
+    # `group_nodes` is a separate rule so we can carve out the closing
+    # bracket from `node`'s text fallback. Without this, `text_run`
+    # would consume the closing bracket and the group never terminates.
+    rule(:group_nodes) do
+      group_node.repeat(1).as(:group_nodes)
+    end
+
+    rule(:group_node) do
+      reaction | electron_config | molecule | embedded_math | group_text_run
+    end
+
+    rule(:group_text_run) do
+      str('"') >> (str('"').absent? >> any).repeat >> str('"')
+    end
+
+    rule(:group_open)  { str("(") | str("[") | str("{") }
+    rule(:group_close) { str(")") | str("]") | str("}") }
+
+    rule(:multiplicity) { str("_") >> digits }
+
+    # -- electron configuration -------------------------------------------
+
+    rule(:electron_config) do
+      (orbital.as(:orbital) >> str("^") >> digits.as(:occupancy) >> spaces?.maybe).repeat(2).as(:electron_config)
+    end
+
+    rule(:orbital) { digits >> match("[spdfgh]") }
+
+    # -- embedded math ----------------------------------------------------
+
+    rule(:embedded_math) do
+      str("`") >>
+        (str("`").absent? >> any).repeat.as(:math_source) >>
+        str("`")
+    end
+
+    # -- text (top level) -------------------------------------------------
+
+    # Free-form text uses `"..."` delimiters, matching AsciiMath's
+    # convention. The quoted content becomes a Text node with the
+    # surrounding quotes stripped (handled by the transform).
+    rule(:text_run) do
+      str('"') >> (str('"').absent? >> any).repeat >> str('"')
+    end
+
+    # -- primitives -------------------------------------------------------
+
+    rule(:digits)   { match("[0-9]").repeat(1) }
+    rule(:spaces)   { match(/\s/).repeat(1) }
+    rule(:spaces?)  { spaces.maybe }
+  end
+end