asciichem 0.29.0 → 0.29.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 106d03bf9d192f66b4f9ade534ed84f8dcc5cbf0ceeb07d45b633c353fc92aaa
-  data.tar.gz: 36c047aa3f26f73f94cc698eb905a939025feb9fc34fb86b67163cf3a93f7fbe
+  metadata.gz: f372a8539906c658a399b015255e574de5feb73d1b5e7183958901681bfbce34
+  data.tar.gz: 7269dc4ad6e39e7c5ea6726b54a8ffe1508c039bdf9ced5c0a74e23efdc9b00f
 SHA512:
-  metadata.gz: b9215fa19d5dc3a65d82cfbe5cdfd4f837bd136cbb18cb0241654e7307a314c42088a870a76c3393858bd285e8e5834a95de136849c6f4d1ee4d2469fe616731
-  data.tar.gz: f7654b2d8257c634e7be6b514011b5875c8060886204c43dd9293b982c8cd241773fb92958d8772d0e28ec07ce50ad82753aba085469e0c3edbc03446201c3bc
+  metadata.gz: 6f936bc0e95907d589c0095d34e4e65c554dcbdccd276aab7186db8f1218cbb179652b082f088f1b70a76391e830db53de2259ea8d333b64dd85ba367b16c610
+  data.tar.gz: 63d979830e4a8ab9aca450006a9740e83428e26073323af0ed4f8ddeed4be6f7aecb8bcfe1e5173f7a6049f92ff8b0a8e0a2b374fbd13630ae00b0e9e7a0db60

data/.github/workflows/release.yml

@@ -34,6 +34,15 @@ jobs:
         with:
           ruby-version: "3.4"
           bundler-cache: true
+      # CI never pushes to git (read-only contents). `rake release`
+      # attempts `git push origin main` after publishing unless the
+      # version tag already exists locally — bundler then prints
+      # "Tag vX has already been created" and skips its git stage
+      # entirely (this is how 0.29.0/0.29.1 released). Pre-create the
+      # tag so the gem push is the only remote operation; tags on the
+      # remote remain the maintainer's.
+      - name: Pre-create the release tag (skips rake's git stage)
+        run: git tag "v${{ inputs.version }}"
       # Builds and pushes using the GitHub OIDC identity — no API keys.
       - uses: rubygems/release-gem@v1
       - name: Summary

data/CHANGELOG.md

@@ -3,6 +3,26 @@
 All notable changes to AsciiChem are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.29.2] - 2026-09-17
+
+### Changed
+- `relaton-bib` constraint widened to `>= 0.1, < 3`: asciichem now
+  co-resolves with current metanorma gems (metanorma-standoc and
+  friends require relaton-bib 2). The citation track speaks both
+  major lines through a single `Citation::RelatonApi` seam —
+  relaton-bib 1 (`RelatonBib`) and relaton-bib 2
+  (`Relaton::Bib` typed models) both build and serialize the
+  dataset-type bibitems; profile data is version-independent.
+- nil resolver links no longer emit an empty `<uri>` element.
+
+## [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

data/asciichem.gemspec

@@ -39,7 +39,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "mml", "~> 2.3"
   spec.add_dependency "nokogiri", "~> 1.16"
   spec.add_dependency "parslet", "~> 2.0"
-  spec.add_dependency "relaton-bib", ">= 0.1", "< 2"
+  spec.add_dependency "relaton-bib", ">= 0.1", "< 3"
   spec.add_dependency "plurimath", "~> 0.8"
   spec.add_dependency "thor", "~> 1.3"
 

data/benchmarks/README.md

@@ -104,9 +104,67 @@ fork-per-case gate so Rust aborts are reported, not fatal):
   but rejected under parslet (optimizer Str/Re run-merging semantics;
   no corpus case covers these spellings today).
 
-**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.
-
+### 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: superseded — the engine IS switchable and shipped**
+(asciichem 0.29.0, TODO.impl 64).
+
+### Re-check 6 (2026-09-16, parsanol 1.3.18)
+
+Gate still **221/221** through the shipped engine, but the "one
+decode path" rework **regressed compat-layer throughput ~60%** for
+this grammar: 7.2 ms/batch (138 i/s) vs 4.3-4.6 ms on 1.3.15/16,
+with the parslet control stable across sessions (11-14 ms
+throughout). The `H2`/`_2O` acceptance divergence also persists.
+Reported upstream (parsanol-ruby#25, fourth comment). We stay on
+the shipped engine; users pinning parsanol for speed should prefer
+1.3.16/1.3.17 until the regression is addressed.
+
+### Re-check 7 (2026-09-16, parsanol 1.3.20)
+
+Three upstream issues closed since 1.3.18:
+
+- **#38** (`Dynamic.register` `@next_id` collision panicking the
+  Rust core) — fixed; no panic during full-corpus run.
+- **#37** ("one decode path" throughput regression) — fixed as a
+  side effect of the optimizer acceptance fix in #39; throughput on
+  this grammar is back to and ahead of 1.3.15/16 levels.
+- **#39** (optimizer Str/Re run-merging changed sequence-boundary
+  acceptance) — root-caused to Re-run regex-source concatenation
+  (proven unsafe: `"a|"+"b"` → `"a|b"` accepts `"a"`); Re runs now
+  stay unmerged, Str-run merging stays. Spec-level decision
+  recorded: the optimizer may never alter acceptance.
+
+Validation against 1.3.20:
+
+- Gate **221/221** through the shipped `ParsanolEngine` (fork-per-case,
+  no Rust aborts).
+- Head-to-head vs parslet, same Ruby process (3 runs, ±3-15%):
+  parsanol **2.6x faster** (4.65–5.19 ms/batch vs 12.18–13.65 ms for
+  parslet). Up from the 1.7x under 1.3.18 — the #37 regression is
+  gone.
+- Direct `H2` / `_2O` / `Ca2+` / `H22` / `O2` probe across both
+  parslet and parsanol (native and ruby backends) shows **identical
+  parse outcomes**. The earlier "divergence" framing in re-checks
+  3-6 was a misreading: AsciiChem's `hydrogen_atom` grammar rule
+  intentionally permits bare-digit subscripts after `H` ("lets users
+  write `H2O` instead of `H_2O`" — grammar_rules.rb:228-231) and
+  `isotope_marker` accepts both `^digits` and `_digits`, so `_2O`
+  parses as the isotope of `O` and round-trips as `^2O`. The
+  parsanol optimizer bug in #39 was real and is fixed, but the
+  AsciiChem repro was a misleading example — both engines agree on
+  these inputs because they share the same grammar rules.
+
+**Verdict: shipped engine fully validated.** 2.6x speedup, 100%
+corpus gate, all four reported upstream issues now resolved or
+non-blocking (#36 bare repeated sibling captures remains open but
+is worked around in `ParsanolEngine` via single `.as(...)` capture
+wrapping).
 

data/benchmarks/parsanol_recheck.rb

@@ -1,25 +1,30 @@
 # frozen_string_literal: true
 
-# Parsanol re-check (parsanol-ruby 1.3.15, issue-25 thread): 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).
 #
-# Mode: native by default (PARSOLAN_MODE=native — default routing);
-# PARSANOL_MODE=ruby forces the pure-Ruby engine. As of 1.3.15 the
-# native backend parses 169/170 corpus accepts + all 51 rejects at
-# ~2.3x parslet speed; the single fatal case is embedded-math input,
-# which panics the Rust core on the known @next_id collision
-# (parsanol-ruby#25) — run that one in :ruby until upstream fixes it.
+# Requires the parsanol gem (add to the Gemfile, or point -I at a
+# local checkout):
 #
-# Run from asciichem-ruby/ with the shim dir prepended:
-#   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"
 
-puts "parsanol #{Parsanol::VERSION} | parslet-compat Parser=#{Parsanol::Parslet::Parser}"
-puts "AsciiChem::Grammar superclass: #{AsciiChem::Grammar.superclass}"
+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")}"
 
 if ENV.fetch("PARSANOL_MODE", "native") == "ruby"

data/lib/asciichem/citation.rb

@@ -1,6 +1,14 @@
 # frozen_string_literal: true
 
-require "relaton_bib"
+# relaton-bib 2 renamed the entry file (relaton_bib -> relaton/bib)
+# and reworked the namespace (RelatonBib -> Relaton::Bib). The
+# gemspec admits both major lines, so load whichever is resolved and
+# speak to it through RelatonApi below.
+begin
+  require 'relaton/bib'
+rescue LoadError
+  require 'relaton_bib'
+end
 
 module AsciiChem
   # Citation track (TODO.v2 08; TODO.impl 44): a bibitem is a function
@@ -16,25 +24,25 @@ module AsciiChem
     Profile = Struct.new(:publisher, :link_for, :identifier_for, keyword_init: true)
 
     PROFILES = {
-      "pubchem" => Profile.new(
-        publisher: "PubChem, U.S. National Library of Medicine",
-        link_for: ->(substance) do
-          cid = substance.identifier_value("pubchem-cid")
+      'pubchem' => Profile.new(
+        publisher: 'PubChem, U.S. National Library of Medicine',
+        link_for: lambda do |substance|
+          cid = substance.identifier_value('pubchem-cid')
           "https://pubchem.ncbi.nlm.nih.gov/compound/#{cid}" if cid
         end,
-        identifier_for: ->(substance) do
-          cid = substance.identifier_value("pubchem-cid")
+        identifier_for: lambda do |substance|
+          cid = substance.identifier_value('pubchem-cid')
           "PubChem CID #{cid}" if cid
         end
       ),
-      "common_chemistry" => Profile.new(
-        publisher: "CAS Common Chemistry",
-        link_for: ->(substance) do
-          cas = substance.identifier_value("cas")
+      'common_chemistry' => Profile.new(
+        publisher: 'CAS Common Chemistry',
+        link_for: lambda do |substance|
+          cas = substance.identifier_value('cas')
           "https://commonchemistry.cas.org/detail?cas_rn=#{cas}" if cas
         end,
-        identifier_for: ->(substance) do
-          cas = substance.identifier_value("cas")
+        identifier_for: lambda do |substance|
+          cas = substance.identifier_value('cas')
           "CAS RN #{cas}" if cas
         end
       )
@@ -42,8 +50,8 @@ module AsciiChem
 
     DEFAULT_PROFILE = Profile.new(
       publisher: nil,
-      link_for: ->(_substance) { nil },
-      identifier_for: ->(substance) do
+      link_for: ->(_substance) {},
+      identifier_for: lambda do |substance|
         key = substance.identifiers.first
         "#{key.convention}: #{key.value}" if key
       end
@@ -56,34 +64,20 @@ module AsciiChem
       # carries no provenance (hand-built, not resolved).
       def bibitem(substance)
         provenance = substance.provenance
-        unless provenance&.source
-          raise Error, "substance has no provenance - resolve it first (AsciiChem::Resolver)"
-        end
+        raise Error, 'substance has no provenance - resolve it first (AsciiChem::Resolver)' unless provenance&.source
 
         profile = PROFILES.fetch(provenance.source, DEFAULT_PROFILE)
-        RelatonBib::BibliographicItem.new(
-          type: "dataset",
-          title: [{ type: "main",
-                    content: "#{title_base(substance)} - #{profile.publisher || provenance.source} substance record" }],
-          docid: [RelatonBib::DocumentIdentifier.new(
-                    id: profile.identifier_for.call(substance) || "#{provenance.source} substance",
-                    type: provenance.source)],
-          contributor: [{ entity: RelatonBib::Organization.new(name: profile.publisher || provenance.source),
-                          role: [{ type: "publisher" }] }],
-          date: [{ type: "accessed", on: accessed_on(provenance) }],
-          link: [{ type: "src", content: profile.link_for.call(substance) }].compact,
-          keyword: substance.identifiers.map { |i| "#{i.convention}=#{i.value}" }
-        )
+        RelatonApi.dataset_bibitem(fields(substance, profile, provenance))
       end
 
       # Convenience: bibitem XML (what a document pipeline embeds).
       def to_xml(substance)
-        bibitem(substance).to_xml
+        RelatonApi.to_xml(bibitem(substance))
       end
 
       # The cite syntax (TODO.impl 45): a molecule annotated
       # `@cite("pubchem")` (a property annotation — the grammar needs
-      # no extension) declares *which source to cite it from*. This
+      # no extension) declares *which source to cite it from. This
       # resolves the molecule's identifiers and emits one bibitem per
       # cited source. Returns [[source, bibitem]] pairs; empty when the
       # molecule has no @cite annotations.
@@ -97,13 +91,14 @@ module AsciiChem
         convention, value = lookup_key(molecule)
         unless value
           raise Error,
-                "molecule carries no resolvable identifier for citation " \
-                "(annotate @cas/@inchikey/@smiles or @name)"
+                'molecule carries no resolvable identifier for citation ' \
+                '(annotate @cas/@inchikey/@smiles or @name)'
         end
 
         sources.filter_map do |source|
           substance = AsciiChem::Resolver[source].new.resolve(
-            value: value, convention: convention, cache: cache, fetch: fetch)
+            value: value, convention: convention, cache: cache, fetch: fetch
+          )
           next unless substance
 
           [source, bibitem(substance)]
@@ -112,11 +107,27 @@ module AsciiChem
 
       private
 
+      # The version-independent field payload: one hash describing the
+      # citation, translated to Relaton objects by RelatonApi.
+      def fields(substance, profile, provenance)
+        publisher = profile.publisher || provenance.source
+        {
+          type: 'dataset',
+          title: "#{title_base(substance)} - #{publisher} substance record",
+          docid: { id: profile.identifier_for.call(substance) || "#{provenance.source} substance",
+                   type: provenance.source },
+          publisher: publisher,
+          accessed_on: accessed_on(provenance),
+          link: profile.link_for.call(substance),
+          keywords: substance.identifiers.map { |i| "#{i.convention}=#{i.value}" }
+        }
+      end
+
       # The property annotation whose title is "cite": values are the
       # source names to cite from.
       def citation_sources(molecule)
         molecule.properties
-                .select { |p| p.title == "cite" && p.value }
+                .select { |p| p.title == 'cite' && p.value }
                 .map(&:value)
       end
 
@@ -127,23 +138,96 @@ module AsciiChem
         return [identifier.convention, identifier.value] if identifier
 
         name = molecule.names.first
-        return ["name", name.content] if name
+        return ['name', name.content] if name
 
         nil
       end
 
-      private
-
       def title_base(substance)
-        substance.preferred_name || substance.identifier_value("cas") ||
-          substance.identifier_value("inchikey") || "Substance"
+        substance.preferred_name || substance.identifier_value('cas') ||
+          substance.identifier_value('inchikey') || 'Substance'
       end
 
       def accessed_on(provenance)
         return provenance.retrieved_at[0, 10] if provenance.retrieved_at
 
-        Time.now.utc.strftime("%Y-%m-%d")
+        Time.now.utc.strftime('%Y-%m-%d')
+      end
+    end
+
+    # The relaton-bib version seam. Both major lines accept the same
+    # field hash (see Citation#fields) and serialize through their own
+    # API; the rest of the citation track stays version-agnostic.
+    # Adding a future major = one more module here (OCP).
+    module RelatonApi
+      module_function
+
+      def dataset_bibitem(fields)
+        (defined?(::Relaton::Bib) ? V2 : V1).build(fields)
+      end
+
+      def to_xml(item)
+        item.to_xml
+      end
+
+      # relaton-bib 1: RelatonBib::* with hash-argument constructors.
+      module V1
+        module_function
+
+        def build(fields)
+          RelatonBib::BibliographicItem.new(
+            type: fields[:type],
+            title: [{ type: 'main', content: fields[:title] }],
+            docid: [RelatonBib::DocumentIdentifier.new(id: fields[:docid][:id],
+                                                       type: fields[:docid][:type])],
+            contributor: [{ entity: RelatonBib::Organization.new(name: fields[:publisher]),
+                            role: [{ type: 'publisher' }] }],
+            date: [{ type: 'accessed', on: fields[:accessed_on] }],
+            link: fields[:link] ? [{ type: 'src', content: fields[:link] }] : [],
+            keyword: fields[:keywords]
+          )
+        end
+      end
+
+      # relaton-bib 2: Relaton::Bib::* typed models (lutaml-model).
+      # Date's XML <on> element maps to the Ruby `at` attribute;
+      # keywords carry their text in a nested vocab LocalizedString;
+      # links are source Uri entries serializing to <uri type="src">.
+      module V2
+        module_function
+
+        def build(fields)
+          Relaton::Bib::ItemData.new(
+            type: fields[:type],
+            title: [Relaton::Bib::Title.new(type: 'main', content: fields[:title])],
+            docidentifier: [docidentifier(fields[:docid])],
+            contributor: [contributor(fields[:publisher])],
+            date: [Relaton::Bib::Date.new(type: 'accessed', at: fields[:accessed_on])],
+            source: fields[:link] ? [Relaton::Bib::Uri.new(type: 'src', content: fields[:link])] : [],
+            keyword: fields[:keywords].map { |text| keyword(text) }
+          )
+        end
+
+        def docidentifier(docid)
+          Relaton::Bib::Docidentifier.new(type: docid[:type], content: docid[:id])
+        end
+
+        def contributor(publisher)
+          Relaton::Bib::Contributor.new(
+            organization: Relaton::Bib::Organization.new(
+              name: [Relaton::Bib::TypedLocalizedString.new(content: publisher)]
+            ),
+            role: [Relaton::Bib::Contributor::Role.new(type: 'publisher')]
+          )
+        end
+
+        def keyword(text)
+          Relaton::Bib::Keyword.new(
+            vocab: Relaton::Bib::LocalizedString.new(content: text)
+          )
+        end
       end
     end
+    private_constant :RelatonApi
   end
 end

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,

data/lib/asciichem/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AsciiChem
-  VERSION = "0.29.0"
+  VERSION = "0.29.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asciichem
 version: !ruby/object:Gem::Version
-  version: 0.29.0
+  version: 0.29.2
 platform: ruby
 authors:
 - Ribose Inc.
@@ -108,7 +108,7 @@ dependencies:
         version: '0.1'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '2'
+        version: '3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -118,7 +118,7 @@ dependencies:
         version: '0.1'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '2'
+        version: '3'
 - !ruby/object:Gem::Dependency
   name: plurimath
   requirement: !ruby/object:Gem::Requirement