asciichem 0.24.0 → 0.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d733aab290b1e54dfd0139d75a92888dfb8fc2af088544a07cc4395e523e583f
-  data.tar.gz: 5dfe21e949307366a6afbcc94bf2c52f9e9cfedb4a1f328996fbde3a20b5ec99
+  metadata.gz: 54b5e13e60ca4236628c8b8a145add5991c347747b7d7e2aa24f6acda6d89ad1
+  data.tar.gz: 7b8b2380ea9e5030065958cf35148da3addf2c6dcfb3dd1428066fee088dc410
 SHA512:
-  metadata.gz: cdeb663f26df5189cd73df0d7c5f6a9ad3918d981d924ec08f1a781728415af474840de566a8d8f1075cb0cdc0d7086f41f92b80250efee6f71ebd11cdc62680
-  data.tar.gz: 371e88363eb2e143b2b8a1b3f1a3cbc339d3eb81d5bcd521fdc00d02fd90e6068c769864185198c8e35e5ae6e2fc95b0088885d760844f527118a50469eaa9fb
+  metadata.gz: 0f3f2ae54757260f1ad644d77415a557b16ccdcb15d80829775362fbd2194de3351327babf11ed662676fcfefcd6898a3e9d942928e4a831ac770bb8339846fe
+  data.tar.gz: 360208b6be6fc9666505610618e7a029711595c9ff353e3ef391e09f80619e47cafbe1304c15e2dffac7c15d436f016094e039ce6a02480393f967bbc9ab1edc

data/CHANGELOG.md

@@ -3,6 +3,30 @@
 All notable changes to AsciiChem are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.26.0] - 2026-09-14
+
+### Added
+- The cite syntax (TODO.impl 45): `@cite("pubchem")` on a molecule
+  declares which source to cite it from; `Citation.for_molecule`
+  resolves the molecule's identifiers (registry keys preferred over
+  names) and emits one bibitem per cited source. Zero grammar
+  changes — `@cite` rides the property-annotation form by design.
+
+### Fixed
+- Molecule annotations now canonicalise with spaces between them
+  (`@name("Water") @cas("...")`), matching the TypeScript and Python
+  canonicalisers; Ruby was the outlier joining them without a
+  separator.
+
+## [0.25.0] - 2026-09-14
+
+### Added
+- CLI `cite` — resolve a substance and emit the dataset-type Relaton
+  bibitem XML (the citation track's user-facing entry point).
+- Cross-engine parsing benchmarks (`benchmarks/engines.rb`,
+  README with Ruby/TS/Python numbers) and the parsanol investigation
+  verdict (compat shim ~6x slower than parslet; not adopted).
+
 ## [0.24.0] - 2026-09-13
 
 ### Added
@@ -426,7 +450,9 @@ This project follows [Semantic Versioning](https://semver.org/).
   `version`.
 - Comprehensive RSpec suite with round-trip conformance.
 
-[Unreleased]: https://github.com/asciichem/asciichem-ruby/compare/v0.24.0...HEAD
+[Unreleased]: https://github.com/asciichem/asciichem-ruby/compare/v0.26.0...HEAD
+[0.26.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.25.0...v0.26.0
+[0.25.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.24.0...v0.25.0
 [0.24.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.23.0...v0.24.0
 [0.23.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.22.0...v0.23.0
 [0.22.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.21.0...v0.22.0

data/benchmarks/README.md

@@ -0,0 +1,56 @@
+# Parsing benchmarks
+
+Shared workload (identical inputs in every implementation) so numbers
+are comparable across engines:
+
+```ruby
+WORKLOAD = ["H_2O", "Ca^2+", "SO_4^2-", "(R)-CH_3CH(OH)COOH",
+            "2H_2 + O_2 -> 2H_2O", "N_2 + 3H_2 <=>[Fe][400C] 2NH_3",
+            "C1-C-C-C-C-C1", "CH_3-CH_2-OH",
+            "^14C @name(\"carbon-14\") @cas(\"14104-86-4\")",
+            "A ->[heat] B ->[cool] C"]
+```
+
+| Engine | Batch (10 inputs) | Per input | Notes |
+|---|---|---|---|
+| Ruby (parslet), 3.4.8 arm64 | 29.1 ms | ~2.9 ms | `bundle exec ruby benchmarks/engines.rb` |
+| Ruby + parse+text | 35.3 ms | ~3.5 ms | round-trip adds the formatter |
+| TypeScript (peggy), Node 24 | 0.19 ms | ~19 µs | `npm run bench` (asciichem-ts) |
+| Python (RD), 3.10 | 3.94 ms | ~394 µs | `python benchmarks/engines.py` (asciichem-py) |
+
+The peggy engine is ~15x faster than parslet and ~20x faster than the
+Python recursive-descent parser on this workload — the grammar-port
+TS implementation did not trade away speed. Same machine (arm64),
+single-run medians; treat as order-of-magnitude comparison.
+
+## Parsanol investigation (2026-09-14)
+
+[Parsanol](https://github.com/parsanol/parsanol-ruby) (Ribose's
+parslet-alternative PEG library with a Rust native core) was evaluated
+as a drop-in speedup for the reference grammar:
+
+1. **Parslet-compat shim** (zero code change — re-parent the grammar
+   onto `Parsanol::Parslet::Parser`): the identical grammar runs
+   unchanged (10/10 workload inputs), but measures **~6x slower**
+   than parslet (12.2 s vs 2.05 s per 300x10 parses, Ruby 3.4.8,
+   arm64). The shim is a compatibility layer, not the fast path.
+2. **Native Parsanol DSL** (subset micro-benchmark): constructs run,
+   but boundary semantics differ from parslet on greedy-regex +
+   `maybe`/`repeat` interaction (`SO_4^2-` parses under parslet,
+   fails under Parsanol native). A full port would need per-rule
+   revalidation against the whole corpus with no measured win to
+   justify it yet.
+
+**Verdict: not adopted yet.** Two corrections to the spike (tracked
+upstream in parsanol-ruby#25):
+
+1. The native-DSL micro-benchmark ran in Parsanol's default `:ruby`
+   mode — the Rust core (`:native`) was never engaged, so the native
+   path is unmeasured, not disproven.
+2. The `SO_4^2-` failure is a candidate upstream bug (`repeat` of a
+   `maybe`-prefixed sequence fails at end-of-input; minimal repro in
+   the issue).
+
+Revisit trigger unchanged: engage the native backend for full
+grammars, fix the repetition-termination bug, and beat parslet on
+this workload — then re-run the corpus against the port.

data/benchmarks/engines.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Cross-engine parsing benchmark (shared inputs across Ruby/TS/Python
+# so numbers are comparable). Measures full parse (+ Text round-trip
+# where cheap) over the canonical workload, reporting ops/sec and
+# µs/op. Run: bundle exec ruby benchmarks/engines.rb
+require "benchmark/ips"
+require "asciichem"
+
+WORKLOAD = [
+  "H_2O",
+  "Ca^2+",
+  "SO_4^2-",
+  "(R)-CH_3CH(OH)COOH",
+  "2H_2 + O_2 -> 2H_2O",
+  "N_2 + 3H_2 <=>[Fe][400C] 2NH_3",
+  "C1-C-C-C-C-C1",
+  "CH_3-CH_2-OH",
+  "^14C @name(\"carbon-14\") @cas(\"14104-86-4\")",
+  "A ->[heat] B ->[cool] C",
+].freeze
+
+Benchmark.ips do |x|
+  x.report("parse x10 (parslet)") do
+    WORKLOAD.each { |s| AsciiChem.parse(s) }
+  end
+  x.report("parse+text x10") do
+    WORKLOAD.each { |s| AsciiChem.parse(s).to_text }
+  end
+  x.compare!
+end

data/lib/asciichem/citation.rb

@@ -81,6 +81,57 @@ module AsciiChem
         bibitem(substance).to_xml
       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
+      # resolves the molecule's identifiers and emits one bibitem per
+      # cited source. Returns [[source, bibitem]] pairs; empty when the
+      # molecule has no @cite annotations.
+      #
+      #   AsciiChem.parse('H_2O @name("water") @cite("pubchem")')
+      #   AsciiChem::Citation.for_molecule(formula.nodes.first).map(&:last)
+      def for_molecule(molecule, cache: nil, fetch: nil)
+        sources = citation_sources(molecule)
+        return [] if sources.empty?
+
+        convention, value = lookup_key(molecule)
+        unless value
+          raise Error,
+                "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)
+          next unless substance
+
+          [source, bibitem(substance)]
+        end
+      end
+
+      private
+
+      # 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 }
+                .map(&:value)
+      end
+
+      # First identifier the resolver can look up by, in preference
+      # order: unambiguous registry keys before names.
+      def lookup_key(molecule)
+        identifier = molecule.identifiers.find { |i| %w[cas inchikey pubchem-cid].include?(i.convention) }
+        return [identifier.convention, identifier.value] if identifier
+
+        name = molecule.names.first
+        return ["name", name.content] if name
+
+        nil
+      end
+
       private
 
       def title_base(substance)

data/lib/asciichem/cli.rb

@@ -119,6 +119,33 @@ 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"
+    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
+
+      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 AsciiChem::Citation.to_xml(substance)
+    rescue AsciiChem::Error => e
+      warn "Cite error: #{e.message}"
+      exit 4
+    end
+
     desc "validate -i INPUT", "Offline identifier validation"
     method_option :input, aliases: "-i", type: :string, required: true
     def validate

data/lib/asciichem/formatter/text.rb

@@ -38,7 +38,7 @@ module AsciiChem
         molecule.labels.each { |l| parts << %(@label("#{l.value}")) if l.value }
         molecule.properties.each { |p| parts << %(@#{p.title}("#{p.value}")) if p.title && p.value }
         molecule.metadata.each { |m| parts << %(@meta("#{m.name}","#{m.content}")) }
-        parts.empty? ? "" : " #{parts.join}"
+        parts.empty? ? "" : " #{parts.join(" ")}"
       end
 
       def visit_atom(atom)

data/lib/asciichem/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asciichem
 version: !ruby/object:Gem::Version
-  version: 0.24.0
+  version: 0.26.0
 platform: ruby
 authors:
 - Ribose Inc.
@@ -172,8 +172,10 @@ files:
 - RELEASING.md
 - Rakefile
 - asciichem.gemspec
+- benchmarks/README.md
 - benchmarks/RESULTS.md
 - benchmarks/benchmark.rb
+- benchmarks/engines.rb
 - exe/asciichem
 - lib/asciichem.rb
 - lib/asciichem/citation.rb