AsciiChem

AsciiChem is an ASCII syntax for representing chemistry — atoms, molecules, bonds, reactions, electron configurations, and the embedded mathematics that chemistry publications rely on.

It is to chemistry what AsciiMath is to mathematics.

See it in action

Type chemistry on any keyboard. AsciiChem parses it into a semantic model and renders it as MathML — no LaTeX, no Unicode, no special software.

Source Rendered

H_2O

${\mathrm{H}}_2\mathrm{O}$

2H_2 + O_2 -> 2H_2O

$2{\mathrm{H}}_2+{\mathrm{O}}_2\to 2{\mathrm{H}}_2\mathrm{O}$

N_2 + 3H_2 <=>[Fe][400C] 2NH_3

${\mathrm{N}}_2+3{\mathrm{H}}_2\underset{\mathrm{Fe}}{\overset{400\mathrm{C}}{\rightleftharpoons }}2\mathrm{N}{\mathrm{H}}_3$

^14C

${}^{14}\mathrm{C}$

Ca^2+

${\mathrm{Ca}}^{2+}$

Why another syntax?

AsciiMath’s data model assumes math typography, not chemistry semantics. Chemistry routinely needs things AsciiMath cannot express cleanly:

• Prefix isotopes like ^14C. AsciiMath forces a phantom {} carrier ({}^14C) — the isotope ends up bound to an empty element, semantically wrong. AsciiChem binds it to the atom directly.
• Reactions with stoichiometric coefficients, equilibrium arrows, and catalyst conditions above and below the arrow.
• Electron configurations, term symbols, and bonds (single, double, triple, wedge, hash, dative).
• Embedded mathematics via Plurimath, so equilibrium constants and rate laws sit naturally inside chemistry.

What you get

Model-driven

Every parse produces a semantic tree. Render to MathML, HTML, LaTeX, or SVG without round-tripping through text.

Round-trippable

parse(s).to_text == s for any canonical input. The formatter is the canonicaliser.

IUPAC-aligned

Constructs map to the IUPAC Green Book conventions; numbers-then-sign charges, Roman numeral oxidation states, and equilibrium arrows.

OCP / MECE

Add new constructs as model classes; add new outputs as formatters. No edits to existing code.

The semantic fix in one line

The headline change

^14C parses as Atom(element: "C", isotope: "14") — Carbon-14 with 14 bound to the atom. AsciiMath would emit <msup><mi></mi><mn>14</mn></msup> — an empty base followed by the atom. The binding is lost.

Get started in three steps

1. Install the gem

   gem install asciichem

2. Parse and render

   require "asciichem"
   
   formula = AsciiChem.parse("2H_2 + O_2 -> 2H_2O")
   formula.to_mathml  # => "<math>...</math>"
   formula.to_text    # => "2H_2 + O_2 -> 2H_2O"

3. Explore the syntax guide — atoms, bonds, reactions, electron configurations, and more.

Continue to the Getting started guide.