asciichem 0.28.2 → 0.29.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e4646420eb8fdde22a218b2f65d6b4dce4661264124f98d1fd4716eb82a7faf
-  data.tar.gz: 1dd763180c8466a8c0245e0147b4f79201f8e40957586a8392827d8bf21fea11
+  metadata.gz: 9579311feee35b70f9d15879379582cb67a8b6b9fe004e7c714e12448835e53c
+  data.tar.gz: 6f732f510f6d8923f2d1c855113ec34db33910a258135ee36a954035c90a252b
 SHA512:
-  metadata.gz: 9783079bd787334d96149f8f7826bb80c0314aec5b9a4d45ba7be96b6b4a52ff43bce3f962c273c6bdbf2f6d78a4721a011f32a5ef2897a4fbcd99af5f074ef9
-  data.tar.gz: 2edf62206b51e7fa1cf97181976a19b8903f00bb4d5cd9cfbffc1c1a5750dfa0bb60d3f356f8b4031ce17cca1f142f147268f2aaa3ddb65ee8459c4c4130f2f8
+  metadata.gz: 509996644be4e271c9432f8c5cc7baee5120f58b75af97f3f0bc6050b776dca6c567b1f69586bd87258237f12a56eeabccd4085e45b41772506ae099230d261c
+  data.tar.gz: e4b197451e71cc877398d6ce00130d1ac8dc0f2d73878b05dae4f849f145d99ac7de3e4e8e098db574eeb0c528f67030005a3538ed219f2178fb3ee7bc94c6cc

data/.github/workflows/ci.yml

@@ -13,13 +13,17 @@ jobs:
       matrix:
         ruby: ["3.3", "3.4"]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - name: Clone conformance corpus (asciichem-tests)
-        run: git clone --depth 1 https://github.com/asciichem/asciichem-tests.git ../asciichem-tests
-      - name: Record corpus version for the conformance report
+        uses: actions/checkout@v7
+        with:
+          repository: asciichem/asciichem-tests
+          path: .asciichem-tests
+      - name: Point the suite at the corpus and record its version
         run: |
-          git -C ../asciichem-tests fetch --depth 1 --tags --quiet
-          echo "ASCIICHEM_CORPUS_VERSION=$(git -C ../asciichem-tests describe --tags --abbrev=0 2>/dev/null || echo main)" >> "$GITHUB_ENV"
+          echo "ASCIICHEM_CORPUS=$(pwd)/.asciichem-tests/corpus/fixtures" >> "$GITHUB_ENV"
+          git -C .asciichem-tests fetch --depth 1 --tags --quiet
+          echo "ASCIICHEM_CORPUS_VERSION=$(git -C .asciichem-tests describe --tags --abbrev=0 2>/dev/null || echo main)" >> "$GITHUB_ENV"
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}

data/.github/workflows/release.yml

@@ -18,7 +18,7 @@ jobs:
       contents: read
       id-token: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           ref: main
           persist-credentials: false

data/CHANGELOG.md

@@ -3,6 +3,35 @@
 All notable changes to AsciiChem are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.29.1] - 2026-09-16
+
+### Added
+- CLI `convert --engine parslet|parsanol` selects the parsing engine
+  per invocation (parslet stays the default); absent parsanol gem
+  exits 6 with install guidance. The ASCIICHEM_ENGINE env var keeps
+  working for programmatic selection.
+
+## [0.29.0] - 2026-09-15
+
+### Added
+- Opt-in Parsanol parsing engine (TODO.impl 63/64; parsanol-ruby#25):
+  `AsciiChem::Engine.use(:parsanol)` runs the SAME grammar and
+  transform (extracted into backend-neutral GrammarRules /
+  TransformRules modules) over Parsanol's Rust-backed
+  parslet-compat layer - the full suite (1981 examples) passes
+  identically under either engine, at ~2.4x parse speed
+  (219 vs 90 i/s on the benchmark workload). Parsanol is a soft
+  dependency (gemspec unchanged); absent gem raises guidance.
+  ASCIICHEM_ENGINE=parsanol selects it for test runs.
+
+### Changed
+- Cascade legs are captured as one :segments repeat (the
+  electron-config pattern) so every engine arrays them; parsanol
+  merges - and overwrites - bare repeated sibling captures,
+  silently dropping legs (reported upstream). Transform
+  canonicaliser consumes the segments shape; spec'd for scalar and
+  array forms.
+
 ## [0.28.2] - 2026-09-14
 
 ### Fixed

data/benchmarks/README.md

@@ -85,3 +85,37 @@ a meaningful re-measure.** Corpus correctness is already there; the
 native path is the whole point and remains unmeasurable until
 serialization survives a multi-rule grammar.
 
+### Re-check 3 (2026-09-15, parsanol 1.3.15)
+
+The mode-routing/VM rework landed; native now engages for the full
+grammar (`PARSANOL_MODE=native` in `benchmarks/parsanol_recheck.rb`,
+fork-per-case gate so Rust aborts are reported, not fatal):
+
+- **219/221 corpus cases green under native** — every accept case
+  except the two embedded-math inputs, and all 51 rejects clean
+- **3.2x faster than parslet** on the workload (4.28 ms vs 13.64 ms
+  per 10-input pass, same session, ±3.0%)
+- The two failures are the embedded-math grammar paths hitting
+  `serialize_dynamic` — the still-unfixed `@next_id` collision from
+  the re-check above (manifests as the Rust panic or a Ruby-side
+  `NoMethodError` on the native error path). Upstream thread:
+  parsanol-ruby#25 (third comment).
+- Separately noted upstream: `H2` / `_2O` are accepted under native
+  but rejected under parslet (optimizer Str/Re run-merging semantics;
+  no corpus case covers these spellings today).
+
+### Re-check 5 (2026-09-15, parsanol 1.3.17)
+
+The ffi-gem cdylib tier (Rust engine on every runtime) changes
+nothing for us: gate still **221/221**, 4.40 ms/i on the recheck
+workload. The opt-in engine shipped in asciichem 0.29.0 is
+unaffected; `@next_id` remains unfixed upstream but no longer fires
+on corpus inputs. The re-check-3 verdict below is superseded — the
+engine IS switchable and shipped (TODO.impl 64).
+
+**Verdict: one upstream one-liner from adoption evaluation.** With
+`@next_id += 1` fixed, the entire corpus passes under native at
+3x parslet speed — at that point the decision is whether to make the
+engine switchable (opt-in, soft dependency) in the gem.
+
+

data/benchmarks/parsanol_recheck.rb

@@ -1,26 +1,35 @@
 # frozen_string_literal: true
 
-# Parsanol re-check (parsanol-ruby 1.3.13, post-issue-25): runs the
-# UNMODIFIED AsciiChem grammar over the Parsanol engine via the
-# Parslet compat shim, then (1) gates on the shared corpus, (2) gates
-# on the issue-25 EOF repro, (3) measures against the parslet path.
+# Parsanol gate + benchmark against the SHIPPED opt-in engine
+# (asciichem 0.29.0+): AsciiChem::Engine.use(:parsanol) runs the same
+# GrammarRules/TransformRules over Parsanol's Rust-backed compat
+# layer. (1) gates on the shared corpus, forked per case so a Rust
+# panic aborts the child — reported, not fatal; (2) gates on the
+# issue-25 EOF repro; (3) measures against the parslet path
+# (benchmarks/engines.rb).
 #
-# Native mode cannot serialize this grammar today (two upstream bugs:
-# native.rb never loads native/dynamic; Dynamic.register never
-# increments @next_id so the second callback panics the Rust core —
-# parsanol-ruby#25). The measurement therefore forces :ruby, the
-# only working mode for full parslet grammars via the shim.
+# Requires the parsanol gem (add to the Gemfile, or point -I at a
+# local checkout):
 #
-# Run from asciichem-ruby/:
-#   ruby -I /tmp/parsanol_spike -I ../parsanol/parsanol-ruby/lib benchmarks/parsanol_recheck.rb
+#   bundle exec ruby -I ../parsanol/parsanol-ruby/lib benchmarks/parsanol_recheck.rb
+#
+# PARSANOL_MODE=ruby forces Parsanol's pure-Ruby backend (no Rust
+# core) for comparison.
 require "benchmark/ips"
 require "asciichem"
+require "asciichem/engine/parsanol_engine"
 require "json"
 
-Parsanol::Native.singleton_class.define_method(:available?) { false } # spike: force :ruby
+AsciiChem::Engine.use(:parsanol)
+
+engine = AsciiChem::Engine.current
+puts "parsanol #{Parsanol::VERSION} | engine: #{engine}"
+puts "grammar superclass: #{engine.grammar.superclass}"
+puts "mode: #{ENV.fetch("PARSANOL_MODE", "native")}"
 
-puts "parsanol #{Parsanol::VERSION} | parslet-compat Parser=#{Parsanol::Parslet::Parser}"
-puts "AsciiChem::Grammar superclass: #{AsciiChem::Grammar.superclass}"
+if ENV.fetch("PARSANOL_MODE", "native") == "ruby"
+  Parsanol::Native.singleton_class.define_method(:available?) { false }
+end
 
 # -- 1. Issue-25 repro: repeat-of-maybe at end of input --------------
 begin
@@ -31,38 +40,66 @@ rescue AsciiChem::ParseError => e
 end
 
 # -- 2. Shared-corpus gate --------------------------------------------
+# Each case runs in a forked child: a Rust panic aborts the child
+# process (unrescuable in Ruby), and the parent reports it by name
+# instead of dying.
 corpus_dir = File.expand_path("../../asciichem-tests/corpus/fixtures", __dir__)
 cases = Dir[File.join(corpus_dir, "*.json")].sort.flat_map { |p| JSON.parse(File.read(p)) }
 parser_cases = cases.select { |c| c.key?("input") && !c.key?("lint") && !c.key?("convention") }
 
-pass = fail_parse = fail_reject = fail_roundtrip = 0
+def run_in_child
+  reader, writer = IO.pipe
+  pid = fork do
+    reader.close
+    Marshal.dump(yield, writer)
+  rescue StandardError => e
+    Marshal.dump({ exception: e.class.name, message: e.message }, writer)
+  ensure
+    writer.close
+  end
+  writer.close
+  payload = Marshal.load(reader)
+  reader.close
+  _, status = Process.waitpid2(pid)
+  [payload, status]
+end
+
+pass = fail_parse = fail_reject = fail_roundtrip = fatal = 0
 parser_cases.each do |fixture|
   input = fixture.fetch("input")
-  if fixture.fetch("parses")
-    begin
-      formula = AsciiChem.parse(input)
-      if fixture["roundTrip"] && formula.to_text != input
-        fail_roundtrip += 1
-        puts "  ROUNDTRIP DIFF: #{input.inspect} -> #{formula.to_text.inspect}" if fail_roundtrip <= 5
-      end
-      pass += 1
-    rescue AsciiChem::ParseError, Parslet::ParseFailed => e
+  payload, status = run_in_child do
+    formula = AsciiChem.parse(input)
+    { text: (formula.to_text if fixture["roundTrip"]) }
+  end
+  if status.signaled? || !status.success?
+    fatal += 1
+    puts "  FATAL (child #{status.exitstatus ? "exit #{status.exitstatus}" : "aborted"}): #{fixture["id"]} #{input.inspect}" if fatal <= 8
+    next
+  end
+  if payload.key?(:exception)
+    if fixture.fetch("parses")
       fail_parse += 1
-      puts "  PARSE FAIL: #{input.inspect} -> #{e.message[0, 90]}" if fail_parse <= 8
-    end
-  else
-    begin
-      AsciiChem.parse(input)
-      fail_reject += 1
-      puts "  SHOULD REJECT: #{input.inspect}" if fail_reject <= 8
-    rescue AsciiChem::ParseError, Parslet::ParseFailed
+      puts "  PARSE FAIL: #{input.inspect} -> #{payload[:message][0, 90]}" if fail_parse <= 8
+    else
       pass += 1
     end
+    next
+  end
+  unless fixture.fetch("parses")
+    fail_reject += 1
+    puts "  SHOULD REJECT: #{input.inspect}" if fail_reject <= 8
+    next
+  end
+  if fixture["roundTrip"] && payload[:text] != input
+    fail_roundtrip += 1
+    puts "  ROUNDTRIP DIFF: #{input.inspect} -> #{payload[:text].inspect}" if fail_roundtrip <= 5
+    next
   end
+  pass += 1
 end
 total = parser_cases.length
-puts format("corpus gate: %d/%d ok (parse-fails %d, should-reject %d, roundtrip-diffs %d)",
-            pass, total, fail_parse, fail_reject, fail_roundtrip)
+puts format("corpus gate: %d/%d ok (parse-fails %d, should-reject %d, roundtrip-diffs %d, fatal %d)",
+            pass, total, fail_parse, fail_reject, fail_roundtrip, fatal)
 
 # -- 3. Performance ----------------------------------------------------
 WORKLOAD = [

data/lib/asciichem/cli.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "thor"
+require 'thor'
 
 module AsciiChem
   # Thor-based command line interface. Invoked via the `asciichem`
@@ -8,25 +8,30 @@ module AsciiChem
   class Cli < Thor
     # Use lowercase 'asciichem' as the program name in help output
     # and command banners, matching the executable name.
-    package_name "asciichem"
+    package_name 'asciichem'
 
-    desc "convert -i INPUT -t FORMAT", "Convert INPUT to FORMAT (mathml|text|html|latex|svg|structural-svg|model-json|cml|smiles|molfile)"
-    method_option :input, aliases: "-i", type: :string,
-                           desc: "Source text (or '-' for stdin)"
-    method_option :file, aliases: "-f", type: :string,
-                          desc: "Read source from a file"
-    method_option :from, type: :string, default: "asciichem",
-                        desc: "Input grammar: asciichem|smiles|molfile"
-    method_option :format, aliases: "-t", type: :string, default: "mathml",
-                            desc: "Output format"
+    desc 'convert -i INPUT -t FORMAT',
+         'Convert INPUT to FORMAT (mathml|text|html|latex|svg|structural-svg|model-json|cml|smiles|molfile)'
+    method_option :input, aliases: '-i', type: :string,
+                          desc: "Source text (or '-' for stdin)"
+    method_option :file, aliases: '-f', type: :string,
+                         desc: 'Read source from a file'
+    method_option :from, type: :string, default: 'asciichem',
+                         desc: 'Input grammar: asciichem|smiles|molfile'
+    method_option :format, aliases: '-t', type: :string, default: 'mathml',
+                           desc: 'Output format'
+    method_option :engine, type: :string, default: 'parslet',
+                           desc: 'Parsing engine: parslet (default) | parsanol (opt-in, needs the parsanol gem)'
     def convert
-      unless options["input"] || options["file"]
-        raise AsciiChem::ParseError, "provide -i INPUT or -f FILE"
-      end
+      raise AsciiChem::ParseError, 'provide -i INPUT or -f FILE' unless options['input'] || options['file']
 
+      select_engine(options[:engine])
       source = read_source
       formula = ingest(source, options[:from])
       puts render(formula, options[:format])
+    rescue AsciiChem::Engine::Error => e
+      warn "Engine error: #{e.message}"
+      exit 6
     rescue AsciiChem::ParseError => e
       warn "Parse error: #{e.message}"
       exit 1
@@ -35,9 +40,9 @@ module AsciiChem
       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"
+    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
@@ -46,8 +51,8 @@ module AsciiChem
       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
+    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
@@ -60,11 +65,11 @@ module AsciiChem
       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"
-    method_option :format, aliases: "-f", type: :string, default: "text",
-                            desc: "Output format: text or json"
+    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'
+    method_option :format, aliases: '-f', type: :string, default: 'text',
+                           desc: 'Output format: text or json'
     def lint
       formula = AsciiChem.parse(options[:input])
       diagnostics = AsciiChem::Linter.run(formula)
@@ -76,7 +81,7 @@ module AsciiChem
     end
 
     map %w[--version -v] => :version
-    desc "version", "Print the asciichem version"
+    desc 'version', 'Print the asciichem version'
     def version
       puts "asciichem #{AsciiChem::VERSION}"
     end
@@ -86,32 +91,32 @@ module AsciiChem
       "asciichem #{command.usage}"
     end
 
-    desc "resolve --cas X | --name X | ...", "Resolve a substance from a source (network; cached)"
-    method_option :cas, type: :string, desc: "CAS registry number"
-    method_option :name, type: :string, desc: "Substance name"
-    method_option :cid, type: :string, desc: "PubChem CID"
-    method_option :inchikey, type: :string, desc: "InChIKey"
-    method_option :smiles, type: :string, desc: "SMILES"
-    method_option :source, type: :string, default: "pubchem", desc: "Resolver source"
-    method_option :refresh, type: :boolean, default: false, desc: "Bypass the cache"
-    method_option :format, aliases: "-t", type: :string, default: "model-json",
-                            desc: "Output: model-json | text | smiles"
+    desc 'resolve --cas X | --name X | ...', 'Resolve a substance from a source (network; cached)'
+    method_option :cas, type: :string, desc: 'CAS registry number'
+    method_option :name, type: :string, desc: 'Substance name'
+    method_option :cid, type: :string, desc: 'PubChem CID'
+    method_option :inchikey, type: :string, desc: 'InChIKey'
+    method_option :smiles, type: :string, desc: 'SMILES'
+    method_option :source, type: :string, default: 'pubchem', desc: 'Resolver source'
+    method_option :refresh, type: :boolean, default: false, desc: 'Bypass the cache'
+    method_option :format, aliases: '-t', type: :string, default: 'model-json',
+                           desc: 'Output: model-json | text | smiles'
     def resolve
       convention, value = %i[cas name cid inchikey smiles]
                           .filter_map { |k| [k, options[k.to_s]] if options[k.to_s] }
                           .first
-      raise AsciiChem::Error, "give one of --cas/--name/--cid/--inchikey/--smiles" unless value
+      raise AsciiChem::Error, 'give one of --cas/--name/--cid/--inchikey/--smiles' unless value
 
-      convention = { cas: "cas", name: "name", cid: "pubchem-cid",
-                     inchikey: "inchikey", smiles: "smiles" }.fetch(convention)
+      convention = { cas: 'cas', name: 'name', cid: 'pubchem-cid',
+                     inchikey: 'inchikey', smiles: 'smiles' }.fetch(convention)
       substance = AsciiChem::Resolver[options[:source]].new.resolve(
         value: value, convention: convention, refresh: options[:refresh]
       )
       raise AsciiChem::Error, "#{options[:source]} does not know #{value.inspect}" unless substance
 
       puts case options[:format].to_s
-           when "text" then substance.preferred_name.to_s
-           when "smiles" then substance.identifier_value("canonical-smiles").to_s
+           when 'text' then substance.preferred_name.to_s
+           when 'smiles' then substance.identifier_value('canonical-smiles').to_s
            else substance.to_model_json
            end
     rescue AsciiChem::Error => e
@@ -119,22 +124,22 @@ module AsciiChem
       exit 3
     end
 
-    desc "cite --cas X | --name X | ...", "Resolve a substance and emit a dataset-type Relaton bibitem (XML)"
-    method_option :cas, type: :string, desc: "CAS registry number"
-    method_option :name, type: :string, desc: "Substance name"
-    method_option :cid, type: :string, desc: "PubChem CID"
-    method_option :inchikey, type: :string, desc: "InChIKey"
-    method_option :smiles, type: :string, desc: "SMILES"
-    method_option :source, type: :string, default: "pubchem", desc: "Resolver source"
-    method_option :refresh, type: :boolean, default: false, desc: "Bypass the cache"
+    desc 'cite --cas X | --name X | ...', 'Resolve a substance and emit a dataset-type Relaton bibitem (XML)'
+    method_option :cas, type: :string, desc: 'CAS registry number'
+    method_option :name, type: :string, desc: 'Substance name'
+    method_option :cid, type: :string, desc: 'PubChem CID'
+    method_option :inchikey, type: :string, desc: 'InChIKey'
+    method_option :smiles, type: :string, desc: 'SMILES'
+    method_option :source, type: :string, default: 'pubchem', desc: 'Resolver source'
+    method_option :refresh, type: :boolean, default: false, desc: 'Bypass the cache'
     def cite
       convention, value = %i[cas name cid inchikey smiles]
                           .filter_map { |k| [k, options[k.to_s]] if options[k.to_s] }
                           .first
-      raise AsciiChem::Error, "give one of --cas/--name/--cid/--inchikey/--smiles" unless value
+      raise AsciiChem::Error, 'give one of --cas/--name/--cid/--inchikey/--smiles' unless value
 
-      convention = { cas: "cas", name: "name", cid: "pubchem-cid",
-                     inchikey: "inchikey", smiles: "smiles" }.fetch(convention)
+      convention = { cas: 'cas', name: 'name', cid: 'pubchem-cid',
+                     inchikey: 'inchikey', smiles: 'smiles' }.fetch(convention)
       substance = AsciiChem::Resolver[options[:source]].new.resolve(
         value: value, convention: convention, refresh: options[:refresh]
       )
@@ -146,37 +151,43 @@ module AsciiChem
       exit 4
     end
 
-    desc "validate -i INPUT", "Offline identifier validation"
-    method_option :input, aliases: "-i", type: :string, required: true
+    desc 'validate -i INPUT', 'Offline identifier validation'
+    method_option :input, aliases: '-i', type: :string, required: true
     def validate
       formula = AsciiChem.parse(options[:input])
       annotations = formula.nodes.grep(AsciiChem::Model::Molecule).flat_map(&:identifiers)
       if annotations.empty?
-        puts "no identifier annotations found"
+        puts 'no identifier annotations found'
         return
       end
       annotations.each do |identifier|
         known = AsciiChem::Identifiers.known?(identifier.convention)
         valid = known && AsciiChem::Identifiers.valid?(identifier.convention, identifier.value)
-        status = known ? (valid ? "ok" : "INVALID") : "unknown convention"
-        puts format("%-12s %-40s %s", identifier.convention, identifier.value, status)
+        status = if known
+                   valid ? 'ok' : 'INVALID'
+                 else
+                   'unknown convention'
+                 end
+        puts format('%-12s %-40s %s', identifier.convention, identifier.value, status)
+      end
+      exit 1 if annotations.any? do |i|
+        AsciiChem::Identifiers.known?(i.convention) &&
+        !AsciiChem::Identifiers.valid?(i.convention, i.value)
       end
-      exit 1 if annotations.any? { |i| AsciiChem::Identifiers.known?(i.convention) &&
-                                      !AsciiChem::Identifiers.valid?(i.convention, i.value) }
     rescue AsciiChem::ParseError => e
       warn "Parse error: #{e.message}"
       exit 1
     end
 
-    desc "identity -i INPUT", "Derive InChI/InChIKey locally from the structure (offline; requires an InChI engine)"
-    method_option :input, aliases: "-i", type: :string,
-                           desc: "Source text (or '-' for stdin)"
-    method_option :file, aliases: "-f", type: :string,
-                          desc: "Read source from a file"
-    method_option :from, type: :string, default: "asciichem",
-                        desc: "Input grammar: asciichem|smiles|molfile"
+    desc 'identity -i INPUT', 'Derive InChI/InChIKey locally from the structure (offline; requires an InChI engine)'
+    method_option :input, aliases: '-i', type: :string,
+                          desc: "Source text (or '-' for stdin)"
+    method_option :file, aliases: '-f', type: :string,
+                         desc: 'Read source from a file'
+    method_option :from, type: :string, default: 'asciichem',
+                         desc: 'Input grammar: asciichem|smiles|molfile'
     method_option :engine_bin, type: :string,
-                               desc: "Path to the inchi-1 binary (overrides the configured engine)"
+                               desc: 'Path to the inchi-1 binary (overrides the configured engine)'
     def identity
       formula = ingest(read_source, options[:from])
       molecules = molecules_in(formula)
@@ -195,9 +206,18 @@ module AsciiChem
 
     private
 
+    # --engine feeds the Engine selector (0.29.0+); :parsanol is an
+    # opt-in soft dependency, :parslet stays the default.
+    def select_engine(name)
+      return if name.to_s == 'parslet' && AsciiChem::Engine.current == AsciiChem::Engine::ParsletEngine
+
+      require 'asciichem/engine'
+      AsciiChem::Engine.use(name.to_s)
+    end
+
     def read_source
       return File.read(options[:file]) if options[:file]
-      return $stdin.read if options[:input] == "-"
+      return $stdin.read if options[:input] == '-'
 
       options[:input]
     end
@@ -207,9 +227,9 @@ module AsciiChem
     # format works regardless of the input language.
     def ingest(source, from)
       case from.to_s
-      when "asciichem" then AsciiChem.parse(source)
-      when "smiles" then AsciiChem.parse_smiles(source)
-      when "molfile" then molfile_formula(source)
+      when 'asciichem' then AsciiChem.parse(source)
+      when 'smiles' then AsciiChem.parse_smiles(source)
+      when 'molfile' then molfile_formula(source)
       else
         raise AsciiChem::ParseError, "unknown --from grammar: #{from}"
       end
@@ -224,7 +244,7 @@ module AsciiChem
 
     def render(formula, format)
       return formula.to_cml if format.to_sym == :cml
-      return formula.to_model_json if format.to_sym == :"model-json"
+      return formula.to_model_json if format.to_sym == :'model-json'
       return formula.to_smiles if format.to_sym == :smiles
       return formula.nodes.first.to_molfile if format.to_sym == :molfile
 
@@ -246,14 +266,14 @@ module AsciiChem
 
     def output_lint(diagnostics, format)
       case format.to_s
-      when "json" then output_lint_json(diagnostics)
+      when 'json' then output_lint_json(diagnostics)
       else
         diagnostics.each { |d| puts d }
       end
     end
 
     def output_lint_json(diagnostics)
-      require "json"
+      require 'json'
       payload = diagnostics.map do |d|
         {
           severity: d.severity.to_s,