chemicalml 0.2.0 → 0.3.0

data/lib/chemicalml.rb

@@ -1,49 +1,111 @@
 # frozen_string_literal: true
 
-require "lutaml/model"
+require 'lutaml/model'
 
 # Chemicalml provides a Ruby object model for the Chemical Markup Language
 # (CML).
 #
 # Top-level entry points:
 #   Chemicalml::Cml::Document.from_xml(xml)  # parse CML
-#   document.to_xml                       # serialize back to XML
+#   document.to_xml                          # serialize back to XML
 #
 # Each CML element is a Lutaml::Model::Serializable subclass with
 # declared attributes and an XML mapping block. Serialization is
 # framework-backed — no hand-rolled XML in this library.
 module Chemicalml
-  autoload :Cml, "chemicalml/cml"
-  autoload :ContextConfiguration, "chemicalml/context_configuration"
-  autoload :Convention, "chemicalml/convention"
-  autoload :Dictionary, "chemicalml/dictionary"
-  autoload :Error, "chemicalml/errors"
-  autoload :Model, "chemicalml/model"
-  autoload :ParseError, "chemicalml/errors"
-  autoload :Schema, "chemicalml/schema"
-  autoload :VERSION, "chemicalml/version"
-  autoload :VersionedParser, "chemicalml/versioned_parser"
+  autoload :Cml, 'chemicalml/cml'
+  autoload :Cli, 'chemicalml/cli'
+  autoload :ContextConfiguration, 'chemicalml/context_configuration'
+  autoload :Convention, 'chemicalml/convention'
+  autoload :Dictionary, 'chemicalml/dictionary'
+  autoload :Error, 'chemicalml/errors'
+  autoload :Logger, 'chemicalml/logger'
+  autoload :ParseError, 'chemicalml/errors'
+  autoload :Schema, 'chemicalml/schema'
+  autoload :VERSION, 'chemicalml/version'
+  autoload :VersionedParser, 'chemicalml/versioned_parser'
+  autoload :Dictionary, 'chemicalml/dictionary'
+  autoload :Error, 'chemicalml/errors'
+  autoload :ParseError, 'chemicalml/errors'
+  autoload :Schema, 'chemicalml/schema'
+  autoload :VERSION, 'chemicalml/version'
+  autoload :VersionedParser, 'chemicalml/versioned_parser'
 
   module_function
 
+  # Parse a CML XML string into a wire document.
+  #
+  # @param xml [String] the XML content.
+  # @param schema [Symbol] one of `:schema3` (default) or `:schema24`.
+  # @param namespace_exist [Boolean] whether the XML already declares
+  #   the CML namespace. When false, the parser injects it.
+  # @return [Chemicalml::Cml::Schema3::Document,
+  #          Chemicalml::Cml::Schema24::Document,
+  #          Chemicalml::Cml::Schema3::Molecule, ...] the parsed root,
+  #          dispatch by detected root element.
+  # @raise [ArgumentError] if `xml` is nil/empty or `schema` is unknown.
+  # @raise [Chemicalml::ParseError] on malformed XML.
+  #
+  # @example Parse a Schema3 document
+  #   doc = Chemicalml.parse("<cml xmlns='...'>...</cml>")
+  # @example Parse a Schema2.4 document
+  #   doc = Chemicalml.parse(xml, schema: :schema24)
   def parse(xml, schema: :schema3, namespace_exist: true)
-    raise ArgumentError, "xml must not be nil" if xml.nil?
-    raise ArgumentError, "xml must not be empty" if xml.to_s.strip.empty?
+    raise ArgumentError, 'xml must not be nil' if xml.nil?
+    raise ArgumentError, 'xml must not be empty' if xml.to_s.strip.empty?
 
     parser_for(schema).parse(xml, namespace_exist: namespace_exist)
   end
 
-  def serialize(document, **opts)
-    document.to_xml(**opts)
+  # Parse a CML file from disk. Convenience wrapper around `parse`
+  # that handles the `File.read` boilerplate.
+  #
+  # @param path [String] path to the CML file.
+  # @param schema [Symbol] `:schema3` (default) or `:schema24`.
+  # @param namespace_exist [Boolean] forwarded to `parse`.
+  # @return (see .parse)
+  # @raise [ArgumentError] if the file doesn't exist or is empty.
+  def parse_file(path, schema: :schema3, namespace_exist: true)
+    raise ArgumentError, "file not found: #{path}" unless File.exist?(path)
+
+    parse(File.read(path), schema: schema, namespace_exist: namespace_exist)
+  end
+
+  # Serialize a wire document back to XML.
+  #
+  # @param document [Lutaml::Model::Serializable] a CML wire instance.
+  # @param opts [Hash] forwarded to `Lutaml::Model::Serializable#to_xml`.
+  # @return [String] the serialized XML.
+  def serialize(document, **)
+    document.to_xml(**)
   end
 
+  # Resolve the versioned-parser module for a schema id.
+  #
+  # @param schema [Symbol] `:schema3` or `:schema24`.
+  # @return [Module] the matching `Schema3` or `Schema24` module.
+  # @raise [ArgumentError] if `schema` is unknown.
   def parser_for(schema)
     case schema.to_sym
     when :schema3  then Chemicalml::Cml::Schema3
     when :schema24 then Chemicalml::Cml::Schema24
     else
       raise ArgumentError, "unsupported schema: #{schema.inspect} " \
-                           "(supported: :schema3, :schema24)"
+                           '(supported: :schema3, :schema24)'
     end
   end
+
+  # Auto-detect the convention from the document's root and validate.
+  # Top-level convenience for `Convention.detect_and_validate`.
+  #
+  # @param document [Lutaml::Model::Serializable] the CML document.
+  # @param logger [Chemicalml::Logger, nil] optional logger for progress.
+  # @return [Chemicalml::Convention::ValidationReport] the report.
+  # @raise [ArgumentError] if no convention is declared.
+  def validate(document, logger: nil)
+    logger&.info 'Auto-detecting convention…'
+    report = Convention.detect_and_validate(document)
+    logger&.info "Validation complete: #{report.size} violation(s)"
+    report
+  end
 end

data/lib/tasks/reference_fetch.rake

@@ -1,41 +1,41 @@
 # frozen_string_literal: true
 
-require "net/http"
-require "uri"
-require "fileutils"
+require 'net/http'
+require 'uri'
+require 'fileutils'
 
 # Idempotent fetcher for xml-cml.org reference material.
 # Re-running this task only downloads files that are missing locally.
 module ReferenceFetch
-  BASE = "http://www.xml-cml.org".freeze
-  LICENSE = "Source: <url>. Distributed by xml-cml.org under CC-BY-3.0.".freeze
+  BASE = 'http://www.xml-cml.org'
+  LICENSE = 'Source: <url>. Distributed by xml-cml.org under CC-BY-3.0.'
 
   # Map of remote URL => local path under reference-docs/.
   SOURCES = {
     # Conventions
-    "#{BASE}/convention/"                                => "reference-docs/conventions/index.md",
-    "#{BASE}/convention/molecular"                       => "reference-docs/conventions/molecular.md",
-    "#{BASE}/convention/compchem"                        => "reference-docs/conventions/compchem.md",
-    "#{BASE}/convention/dictionary"                      => "reference-docs/conventions/dictionary.md",
-    "#{BASE}/convention/unit-dictionary"                 => "reference-docs/conventions/unit-dictionary.md",
-    "#{BASE}/convention/unitType-dictionary"             => "reference-docs/conventions/unitType-dictionary.md",
+    "#{BASE}/convention/" => 'reference-docs/conventions/index.md',
+    "#{BASE}/convention/molecular" => 'reference-docs/conventions/molecular.md',
+    "#{BASE}/convention/compchem" => 'reference-docs/conventions/compchem.md',
+    "#{BASE}/convention/dictionary" => 'reference-docs/conventions/dictionary.md',
+    "#{BASE}/convention/unit-dictionary" => 'reference-docs/conventions/unit-dictionary.md',
+    "#{BASE}/convention/unitType-dictionary" => 'reference-docs/conventions/unitType-dictionary.md',
     # Dictionaries
-    "#{BASE}/dictionary/"                                => "reference-docs/dictionaries/index.md",
-    "#{BASE}/dictionary/compchem/"                       => "reference-docs/dictionaries/compchem.md",
-    "#{BASE}/dictionary/cml/"                            => "reference-docs/dictionaries/cml.md",
-    "#{BASE}/dictionary/cml/name/"                       => "reference-docs/dictionaries/cml-name.md",
-    "#{BASE}/dictionary/cml/formula/"                    => "reference-docs/dictionaries/cml-formula.md",
-    "#{BASE}/dictionary/cif/"                            => "reference-docs/dictionaries/cif.md",
+    "#{BASE}/dictionary/" => 'reference-docs/dictionaries/index.md',
+    "#{BASE}/dictionary/compchem/" => 'reference-docs/dictionaries/compchem.md',
+    "#{BASE}/dictionary/cml/" => 'reference-docs/dictionaries/cml.md',
+    "#{BASE}/dictionary/cml/name/" => 'reference-docs/dictionaries/cml-name.md',
+    "#{BASE}/dictionary/cml/formula/" => 'reference-docs/dictionaries/cml-formula.md',
+    "#{BASE}/dictionary/cif/" => 'reference-docs/dictionaries/cif.md',
     # Unit dictionaries
-    "#{BASE}/unit/si/"                                   => "reference-docs/dictionaries/unit-si.md",
-    "#{BASE}/unit/nonSi/"                                => "reference-docs/dictionaries/unit-nonSi.md",
-    "#{BASE}/unit/unitType/"                             => "reference-docs/dictionaries/unit-type.md",
+    "#{BASE}/unit/si/" => 'reference-docs/dictionaries/unit-si.md',
+    "#{BASE}/unit/nonSi/" => 'reference-docs/dictionaries/unit-nonSi.md',
+    "#{BASE}/unit/unitType/" => 'reference-docs/dictionaries/unit-type.md',
     # Schema / spec
-    "https://www.xml-cml.org/schema/cmllite.html"        => "reference-docs/cmllite.html",
+    'https://www.xml-cml.org/schema/cmllite.html' => 'reference-docs/cmllite.html',
     # Examples
-    "#{BASE}/examples/schema3/molecular/"                => "reference-docs/examples/schema3-molecular-index.md",
-    "#{BASE}/examples/schema3/compchem/"                 => "reference-docs/examples/schema3-compchem-index.md",
-    "#{BASE}/examples/schema24/"                         => "reference-docs/examples/schema24-index.md"
+    "#{BASE}/examples/schema3/molecular/" => 'reference-docs/examples/schema3-molecular-index.md',
+    "#{BASE}/examples/schema3/compchem/" => 'reference-docs/examples/schema3-compchem-index.md',
+    "#{BASE}/examples/schema24/" => 'reference-docs/examples/schema24-index.md'
   }.freeze
 
   def self.fetch_all
@@ -60,7 +60,7 @@ module ReferenceFetch
       return
     end
 
-    if path.end_with?(".html")
+    if path.end_with?('.html')
       File.write(full, body)
     else
       File.write(full, header(url) + body)
@@ -73,19 +73,18 @@ module ReferenceFetch
   end
 
   def self.http_get(url, limit = 5)
-    raise "too many redirects" if limit.zero?
+    raise 'too many redirects' if limit.zero?
 
     uri = URI(url)
     http = Net::HTTP.new(uri.host, uri.port)
     http.use_ssl = true if uri.is_a?(URI::HTTPS)
     http.read_timeout = 30
-    req = Net::HTTP::Get.new(uri, "User-Agent" => "chemicalml-gem-reference-fetch")
+    req = Net::HTTP::Get.new(uri, 'User-Agent' => 'chemicalml-gem-reference-fetch')
     res = http.request(req)
 
     case res
     when Net::HTTPSuccess then res.body
-    when Net::HTTPRedirection then http_get(res["location"], limit - 1)
-    else nil
+    when Net::HTTPRedirection then http_get(res['location'], limit - 1)
     end
   rescue StandardError => e
     warn "  error fetching #{url}: #{e.message}"
@@ -93,12 +92,12 @@ module ReferenceFetch
   end
 
   def self.project_root
-    File.expand_path("..", __dir__)
+    File.expand_path('..', __dir__)
   end
 end
 
 namespace :reference do
-  desc "Download all xml-cml.org reference material into reference-docs/. Idempotent."
+  desc 'Download all xml-cml.org reference material into reference-docs/. Idempotent.'
   task :fetch do
     ReferenceFetch.fetch_all
   end

data/lib/tasks/scrape_fixtures.rake

@@ -1,21 +1,21 @@
 # frozen_string_literal: true
 
-require "net/http"
-require "uri"
-require "fileutils"
-require "cgi"
+require 'net/http'
+require 'uri'
+require 'fileutils'
+require 'cgi'
 
 # Idempotent scraper for xml-cml.org example CML files. Walks the
 # HTML index pages, extracts the embedded CML, and writes one `.cml`
 # file per example under `spec/fixtures/`.
 module FixturesScrape
-  BASE = "http://www.xml-cml.org".freeze
+  BASE = 'http://www.xml-cml.org'
 
   # Map of remote index URL => local target directory.
   INDEXES = {
-    "#{BASE}/examples/schema3/molecular/" => "spec/fixtures/schema3/molecular",
-    "#{BASE}/examples/schema3/compchem/"  => "spec/fixtures/schema3/compchem",
-    "#{BASE}/examples/schema24/"          => "spec/fixtures/schema24"
+    "#{BASE}/examples/schema3/molecular/" => 'spec/fixtures/schema3/molecular',
+    "#{BASE}/examples/schema3/compchem/" => 'spec/fixtures/schema3/compchem',
+    "#{BASE}/examples/schema24/" => 'spec/fixtures/schema24'
   }.freeze
 
   def self.scrape_all
@@ -41,7 +41,7 @@ module FixturesScrape
   end
 
   def self.extract_example_links(html, base_url)
-    hrefs = html.scan(/<a[^>]+href=["']([^"']+\.html?)["'][^>]*>([^<]+)<\/a>/i)
+    hrefs = html.scan(%r{<a[^>]+href=["']([^"']+\.html?)["'][^>]*>([^<]+)</a>}i)
     hrefs.map do |raw_href, raw_title|
       href = URI.join(base_url, raw_href).to_s
       title = CGI.unescapeHTML(raw_title.strip)
@@ -70,63 +70,62 @@ module FixturesScrape
 
     cml = extract_cml(body)
     unless cml
-      log_failure(url, target_dir, reason: "no <cml> block found")
+      log_failure(url, target_dir, reason: 'no <cml> block found')
       return
     end
 
-    File.write(path, cml.strip + "\n")
+    File.write(path, "#{cml.strip}\n")
     puts "  saved   #{slug}.cml"
   end
 
   def self.extract_cml(html)
-    match = html.match(/<cml[^>]*>.*<\/cml>/m)
+    match = html.match(%r{<cml[^>]*>.*</cml>}m)
     return match[0] if match
 
-    match = html.match(/<(?:cml|module|dictionary|molecule|reaction|unitList|unitTypeList)[^>]*>.*<\/(?:cml|module|dictionary|molecule|reaction|unitList|unitTypeList)>/m)
+    match = html.match(%r{<(?:cml|module|dictionary|molecule|reaction|unitList|unitTypeList)[^>]*>.*</(?:cml|module|dictionary|molecule|reaction|unitList|unitTypeList)>}m)
     match && match[0]
   end
 
   def self.slugify(title)
     title.downcase
-         .gsub(/[^a-z0-9]+/, "_")
-         .gsub(/^_+|_+$/, "")
+         .gsub(/[^a-z0-9]+/, '_')
+         .gsub(/^_+|_+$/, '')
   end
 
   def self.http_get(url, limit = 5)
-    raise "too many redirects" if limit.zero?
+    raise 'too many redirects' if limit.zero?
 
     uri = URI(url)
     http = Net::HTTP.new(uri.host, uri.port)
     http.use_ssl = true if uri.is_a?(URI::HTTPS)
     http.read_timeout = 30
-    req = Net::HTTP::Get.new(uri, "User-Agent" => "chemicalml-gem-fixtures-scrape")
+    req = Net::HTTP::Get.new(uri, 'User-Agent' => 'chemicalml-gem-fixtures-scrape')
     res = http.request(req)
 
     case res
     when Net::HTTPSuccess then res.body
-    when Net::HTTPRedirection then http_get(res["location"], limit - 1)
-    else nil
+    when Net::HTTPRedirection then http_get(res['location'], limit - 1)
     end
   rescue StandardError => e
     warn "  error fetching #{url}: #{e.message}"
     nil
   end
 
-  def self.log_failure(url, target_dir, reason: "fetch failed")
-    File.open(File.join(target_dir, ".scrape-log"), "a") do |f|
+  def self.log_failure(url, target_dir, reason: 'fetch failed')
+    File.open(File.join(target_dir, '.scrape-log'), 'a') do |f|
       f.puts "#{Time.now.utc.iso8601}\t#{url}\t#{reason}"
     end
   end
 
   def self.project_root
-    File.expand_path("../..", __dir__)
+    File.expand_path('../..', __dir__)
   end
 end
 
-require "time"
+require 'time'
 
 namespace :fixtures do
-  desc "Scrape every xml-cml.org example CML into spec/fixtures/. Idempotent."
+  desc 'Scrape every xml-cml.org example CML into spec/fixtures/. Idempotent.'
   task :scrape do
     FixturesScrape.scrape_all
   end