Getting started

AsciiChem is a language for chemistry. This page walks through using the Ruby reference implementation (asciichem-ruby). Other implementations (TypeScript, Python) may follow; the syntax and model are the same across all of them.

Install

1. Install the gem

   gem install asciichem

   Or add to your Gemfile:

   gem "asciichem"

2. Require and parse

   require "asciichem"
   
   formula = AsciiChem.parse("H_2O")
   formula.to_mathml  # => "<math>...</math>"
   formula.to_text    # => "H_2O"  (round trip)

3. Use the CLI

   $ asciichem convert -i "2H_2 + O_2 -> 2H_2O" -t mathml
   $ asciichem version
   0.2.0

What’s in a parse?

AsciiChem parses text into a model tree. Each node has typed fields — chemistry semantics, not just typography.

Source	Model
H_2O	Molecule[Atom(H, sub:"2"), Atom(O)]
^14C	Molecule[Atom(C, isotope:"14")]
Ca^2+	Molecule[Atom(Ca, charge:"2+")]
Ca(OH)_2	Molecule[Atom(Ca), Group(...,mult:"2")]
2H_2+O_2 -> 2H_2O	Reaction(reactants:[...], products:[...], arrow::forward)

The headline semantic fix

For ^14C, AsciiChem binds the isotope to the atom — the model says “Carbon with isotope 14”. AsciiMath would produce an empty element followed by the atom — the binding is lost.

Where to next?

• Why AsciiChem? — the gaps in AsciiMath it closes.
• Atoms — elements, isotopes, charges, oxidation states.
• Molecules — stoichiometry, groups, brackets.
• Reactions — forward, equilibrium, conditions.