asciichem 0.3.0

data/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, Ribose Inc.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.adoc

@@ -0,0 +1,55 @@
+= AsciiChem
+
+AsciiChem is an ASCII syntax for representing chemistry: atoms, molecules,
+bonds, reactions, electron configurations, and embedded mathematics. It
+parses to a semantic model and renders to MathML, HTML, LaTeX, and SVG.
+
+== Why
+
+AsciiMath is insufficient for chemistry:
+
+* Prefix superscripts/subscripts have no atom to bind to — AsciiMath
+  forces a phantom `{}` carrier (e.g. `{}^14C`), which is semantically
+  wrong: the isotope belongs to the atom, not to an empty element.
+* No native syntax for stoichiometric coefficients, reaction arrows,
+  conditions, or spectator ions.
+* No representation for electron configuration, term symbols, or bonds.
+* No structural diagrams.
+
+AsciiChem closes these gaps.
+
+== Installation
+
+Add to your Gemfile:
+
+[source,ruby]
+----
+gem "asciichem"
+----
+
+Or install directly:
+
+[source,sh]
+----
+$ gem install asciichem
+----
+
+== Usage
+
+[source,ruby]
+----
+require "asciichem"
+
+formula = AsciiChem.parse("H_2O")
+formula.to_mathml  # => "<math>...</math>"
+formula.to_text    # => "H_2O"  (round trip)
+----
+
+== Design
+
+See link:ARCHITECTURE.adoc[] and the specification at
+https://www.asciichem.org[].
+
+== License
+
+BSD-2-Clause. See link:LICENSE[LICENSE].

data/RELEASING.md

@@ -0,0 +1,102 @@
+= Releasing AsciiChem
+
+== Versioning
+
+AsciiChem follows https://semver.org/[Semantic Versioning]. While the
+public API is still stabilising (0.x), breaking changes bump the minor
+version; additive changes and fixes bump the patch.
+
+== Pre-flight
+
+1. Ensure `main` is green on CI.
+2. Pull latest `main`.
+3. Create a release branch: `git switch -c release/v0.X.Y`.
+
+== Bump version
+
+Edit `lib/asciichem/version.rb`:
+
+[source,ruby]
+----
+module AsciiChem
+  VERSION = "0.X.Y"
+end
+----
+
+== Update changelog
+
+Add a new section at the top of `CHANGELOG.md`:
+
+[source,markdown]
+----
+## [0.X.Y] — YYYY-MM-DD
+
+### Added
+- ...
+
+### Changed
+- ...
+
+### Fixed
+- ...
+----
+
+Update the `[Unreleased]` link at the bottom of `CHANGELOG.md` to point
+at the new version's comparison on GitHub.
+
+== Verify
+
+[source,sh]
+----
+bundle exec rspec          # all specs pass
+bundle exec rake build     # gem builds cleanly
+gem install pkg/asciichem-0.X.Y.gem   # installs locally
+asciichem version          # prints 0.X.Y
+----
+
+== Commit
+
+[source,sh]
+----
+git add lib/asciichem/version.rb CHANGELOG.md
+git commit -m "Bump version to 0.X.Y"
+----
+
+Open a PR for the release branch. **Never commit directly to `main`**
+(global rule).
+
+== Tag and push (maintainer only)
+
+After the release PR merges:
+
+[source,sh]
+----
+git switch main
+git pull
+git tag v0.X.Y
+git push origin v0.X.Y
+----
+
+The tag triggers no automation; it exists as a marker. Tags are
+permanent and visible — only the maintainer decides when and what to
+tag.
+
+== Publish to RubyGems
+
+[source,sh]
+----
+gem push pkg/asciichem-0.X.Y.gem
+----
+
+Verify at https://rubygems.org/gems/asciichem.
+
+== Site deploy
+
+The asciichem.github.io site redeploys automatically on push to `main`.
+If a release adds new syntax, update the spec pages on the site repo
+in a separate PR.
+
+== Post-release
+
+1. Bump `[Unreleased]` back to the top of `CHANGELOG.md`.
+2. Open a PR titled "Post-release housekeeping" with any doc cleanup.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/asciichem.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "lib/asciichem/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "asciichem"
+  spec.version       = AsciiChem::VERSION
+  spec.authors       = ["Ribose Inc."]
+  spec.email         = ["open.source@ribose.com"]
+
+  spec.summary       = "ASCII syntax for chemistry formulae, reactions, and structures."
+  spec.description   = "AsciiChem is an ASCII syntax for representing chemical formulae, " \
+                       "reactions, electron configurations, and bonds. It parses to a semantic " \
+                       "model and renders to MathML, HTML, LaTeX, and SVG. Math embedding uses Plurimath."
+  spec.homepage      = "https://www.asciichem.org"
+  spec.license       = "BSD-2-Clause"
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.3.0")
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/asciichem/asciichem-ruby"
+  spec.metadata["changelog_uri"] = "https://github.com/asciichem/asciichem-ruby/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{^(test|spec|features)/})
+    end
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "chemicalml", "0.2.0"
+  spec.add_dependency "elkrb", "~> 1.0"
+  spec.add_dependency "nokogiri", "~> 1.16"
+  spec.add_dependency "parslet", "~> 2.0"
+  spec.add_dependency "plurimath", "~> 0.8"
+  spec.add_dependency "thor", "~> 1.3"
+end

data/benchmarks/RESULTS.md

@@ -0,0 +1,49 @@
+# Performance benchmarks
+
+Manual benchmarks for AsciiChem. CI does not run them; they exist to
+surface regressions during development.
+
+## Run
+
+```bash
+bundle exec ruby benchmarks/benchmark.rb
+```
+
+If `benchmark-ips` is installed (add to Gemfile dev group), the output
+is iterations-per-second. Otherwise the script falls back to stdlib
+`Benchmark` and reports wall-clock time per call.
+
+## Suites
+
+- **parse** — `AsciiChem.parse(source)` alone.
+- **round-trip** — `parse + to_text`.
+- **to_mathml** — `Formula#to_mathml` on a pre-parsed formula.
+
+Each suite runs against a fixed set of inputs spanning every construct:
+atoms, molecules, isotopes, charges, groups, reactions, equilibrium
+with conditions, cascades, electron configs, and bonds.
+
+## Baseline numbers
+
+Captured on the maintainer's machine (Apple M1, Ruby 3.4). Update this
+table when significant refactors land; investigate regressions of more
+than 2x.
+
+| Input | parse (ips) | round-trip (ips) | to_mathml (ips) |
+|---|---|---|---|
+| simple atom (H) | _tbd_ | _tbd_ | _tbd_ |
+| simple molecule (H_2O) | _tbd_ | _tbd_ | _tbd_ |
+| isotope (^14C) | _tbd_ | _tbd_ | _tbd_ |
+| charged atom (Ca^2+) | _tbd_ | _tbd_ | _tbd_ |
+| group (Ca(OH)_2) | _tbd_ | _tbd_ | _tbd_ |
+| reaction (2H_2 + O_2 -> 2H_2O) | _tbd_ | _tbd_ | _tbd_ |
+| equilibrium (Haber) | _tbd_ | _tbd_ | _tbd_ |
+| cascade (A -> B -> C -> D) | _tbd_ | _tbd_ | _tbd_ |
+| electron config | _tbd_ | _tbd_ | _tbd_ |
+| bonds (H-O-H=O#H) | _tbd_ | _tbd_ | _tbd_ |
+
+## When to investigate
+
+- Any input that drops below 100 ips on parse.
+- A regression of more than 2x in any cell.
+- New grammar productions that fall off the table's curve.

data/benchmarks/benchmark.rb

@@ -0,0 +1,106 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Performance benchmarks for AsciiChem. Uses benchmark-ips if available;
+# falls back to stdlib Benchmark otherwise.
+#
+# Run manually:
+#   bundle exec ruby benchmarks/benchmark.rb
+#
+# CI does not run benchmarks. They are a manual check for regressions
+# during development.
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "asciichem"
+require "benchmark"
+
+begin
+  require "benchmark/ips"
+  HAVE_IPS = true
+rescue LoadError
+  HAVE_IPS = false
+end
+
+CASES = {
+  "simple atom (H)" => "H",
+  "simple molecule (H_2O)" => "H_2O",
+  "isotope (^14C)" => "^14C",
+  "charged atom (Ca^2+)" => "Ca^2+",
+  "group (Ca(OH)_2)" => "Ca(OH)_2",
+  "reaction (2H_2 + O_2 -> 2H_2O)" => "2H_2 + O_2 -> 2H_2O",
+  "equilibrium (Haber)" => "N_2 + 3H_2 <=>[Fe][400°C] 2NH_3",
+  "cascade (A -> B -> C -> D)" => "A -> B -> C -> D",
+  "electron config" => "1s^2 2s^2 2p^6 3s^2 3p^6 4s^2 3d^10",
+  "bonds (H-O-H=O#H)" => "H-O-H=O#H"
+}.freeze
+
+def parse_bench(label, source)
+  if HAVE_IPS
+    Benchmark.ips do |x|
+      x.config(time: 2, warmup: 1)
+      x.report("#{label} parse") { AsciiChem.parse(source) }
+    end
+  else
+    Benchmark.realtime { 100.times { AsciiChem.parse(source) } }
+      .then { |t| printf "  %-40s parse: %6.2f ms/call\n", label, t * 10 }
+  end
+end
+
+def roundtrip_bench(label, source)
+  if HAVE_IPS
+    Benchmark.ips do |x|
+      x.config(time: 2, warmup: 1)
+      x.report("#{label} round-trip") do
+        AsciiChem.parse(source).to_text
+      end
+    end
+  else
+    Benchmark.realtime { 100.times { AsciiChem.parse(source).to_text } }
+      .then { |t| printf "  %-40s round-trip: %6.2f ms/call\n", label, t * 10 }
+  end
+end
+
+def mathml_bench(label, source)
+  formula = AsciiChem.parse(source)
+  if HAVE_IPS
+    Benchmark.ips do |x|
+      x.config(time: 2, warmup: 1)
+      x.report("#{label} to_mathml") { formula.to_mathml }
+    end
+  else
+    Benchmark.realtime { 100.times { formula.to_mathml } }
+      .then { |t| printf "  %-40s to_mathml: %6.2f ms/call\n", label, t * 10 }
+  end
+end
+
+def cml_bench(label, source)
+  formula = AsciiChem.parse(source)
+  if HAVE_IPS
+    Benchmark.ips do |x|
+      x.config(time: 2, warmup: 1)
+      x.report("#{label} to_cml") { formula.to_cml }
+      x.report("#{label} cml parse") { AsciiChem::Cml.parse(formula.to_cml) }
+    end
+  else
+    Benchmark.realtime { 100.times { formula.to_cml } }
+      .then { |t| printf "  %-40s to_cml: %6.2f ms/call\n", label, t * 10 }
+  end
+end
+
+puts "AsciiChem #{AsciiChem::VERSION}  (benchmark-ips: #{HAVE_IPS})"
+puts
+
+puts "== parse =="
+CASES.each { |label, src| parse_bench(label, src) }
+puts
+
+puts "== round-trip (parse + to_text) =="
+CASES.each { |label, src| roundtrip_bench(label, src) }
+puts
+
+puts "== to_mathml =="
+CASES.each { |label, src| mathml_bench(label, src) }
+puts
+
+puts "== CML (to_cml + parse) =="
+CASES.first(5).each { |label, src| cml_bench(label, src) }

data/exe/asciichem

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "asciichem"
+
+AsciiChem::Cli.start(ARGV)

data/lib/asciichem/cli.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module AsciiChem
+  # Thor-based command line interface. Invoked via the `asciichem`
+  # executable (exe/asciichem).
+  class Cli < Thor
+    # Use lowercase 'asciichem' as the program name in help output
+    # and command banners, matching the executable name.
+    package_name "asciichem"
+
+    desc "convert -i INPUT -t FORMAT", "Convert AsciiChem INPUT to FORMAT (mathml|text|html|latex|svg|cml)"
+    method_option :input, aliases: "-i", type: :string, required: true,
+                           desc: "AsciiChem source text (or '-' for stdin)"
+    method_option :file, aliases: "-f", type: :string,
+                          desc: "Read AsciiChem source from a file"
+    method_option :format, aliases: "-t", type: :string, default: "mathml",
+                            desc: "Output format"
+    def convert
+      source = read_source
+      formula = AsciiChem.parse(source)
+      puts render(formula, options[:format])
+    rescue AsciiChem::ParseError => e
+      warn "Parse error: #{e.message}"
+      exit 1
+    rescue AsciiChem::FormatError => e
+      warn "Format error: #{e.message}"
+      exit 2
+    end
+
+    desc "parse-cml -i INPUT", "Parse CML XML and emit AsciiChem text"
+    method_option :input, aliases: "-i", type: :string, required: true,
+                           desc: "CML XML source"
+    def parse_cml
+      formula = AsciiChem::Cml.parse(options[:input])
+      puts formula.to_text
+    rescue AsciiChem::Error => e
+      warn "CML parse error: #{e.message}"
+      exit 1
+    end
+
+    desc "roundtrip -i INPUT", "Parse and re-emit; exit non-zero if not equal"
+    method_option :input, aliases: "-i", type: :string, required: true
+    def roundtrip
+      original = options[:input]
+      rendered = AsciiChem.parse(original).to_text
+      if rendered == original
+        puts rendered
+        exit 0
+      else
+        warn "round-trip mismatch:\n  input:    #{original.inspect}\n  rendered: #{rendered.inspect}"
+        exit 1
+      end
+    end
+
+    desc "lint -i INPUT", "Run chemistry checks; exit 1 on error, 0 if clean"
+    method_option :input, aliases: "-i", type: :string, required: true,
+                           desc: "AsciiChem source text"
+    def lint
+      formula = AsciiChem.parse(options[:input])
+      diagnostics = AsciiChem::Linter.run(formula)
+      diagnostics.each { |d| puts d }
+      exit diagnostics.any? { |d| d.severity == :error } ? 1 : 0
+    rescue AsciiChem::ParseError => e
+      warn "Parse error: #{e.message}"
+      exit 1
+    end
+
+    map %w[--version -v] => :version
+    desc "version", "Print the asciichem version"
+    def version
+      puts "asciichem #{AsciiChem::VERSION}"
+    end
+
+    # Override banner to use lowercase program name consistently.
+    def self.banner(command, _namespace = nil, _subcommand = false)
+      "asciichem #{command.usage}"
+    end
+
+    private
+
+    def read_source
+      return File.read(options[:file]) if options[:file]
+      return $stdin.read if options[:input] == "-"
+
+      options[:input]
+    end
+
+    def render(formula, format)
+      return formula.to_cml if format.to_sym == :cml
+
+      AsciiChem::Formatter.render(format.to_sym, formula)
+    end
+  end
+end