chemicalml 0.1.0

data/lib/chemicalml/convention/molecular/constraints.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Molecular
+      # Namespace container for all molecular-convention constraint
+      # classes. One class per file, registered from the parent
+      # `molecular.rb`.
+      module Constraints
+        autoload :AtomArrayMustContainAtoms,
+                 "chemicalml/convention/molecular/constraints/atom_array_must_contain_atoms"
+        autoload :AtomIdsUniqueWithinMolecule,
+                 "chemicalml/convention/molecular/constraints/atom_ids_unique_within_molecule"
+        autoload :BondMustReferenceAtomsInSameMolecule,
+                 "chemicalml/convention/molecular/constraints/bond_must_reference_atoms_in_same_molecule"
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/molecular.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    # The molecular convention. Constraints are based on the rules at
+    # http://www.xml-cml.org/convention/molecular (archived in
+    # `reference-docs/conventions/molecular.md`).
+    module Molecular
+      extend Base
+
+      autoload :Constraints, "chemicalml/convention/molecular/constraints"
+
+      QNAME = "convention:molecular".freeze
+      NAMESPACE_URI = "#{Chemicalml::Convention::CONVENTION_NAMESPACE}molecular".freeze
+
+      def self.qname
+        QNAME
+      end
+
+      def self.namespace_uri
+        NAMESPACE_URI
+      end
+
+      register Constraints::AtomArrayMustContainAtoms
+      register Constraints::AtomIdsUniqueWithinMolecule
+      register Constraints::BondMustReferenceAtomsInSameMolecule
+    end
+  end
+end

data/lib/chemicalml/convention/registry.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    # Lookup table for conventions. Built-in conventions are
+    # registered lazily on first access to avoid load-order surprises.
+    #
+    # Adding a new convention = creating a subclass of `Base` that
+    # returns its QName and namespace_uri, then registering it here.
+    # No switch statements, no if/elsif chains in framework code.
+    module Registry
+      @mutex = Mutex.new
+      @cache = nil
+
+      def self.lookup(qname)
+        load_cache[qname.to_s]
+      end
+
+      def self.validate(document, qname:)
+        convention = lookup(qname)
+        raise ArgumentError, "unknown convention: #{qname.inspect}" unless convention
+
+        convention.validate(document)
+      end
+
+      def self.builtin_qnames
+        load_cache.keys.sort
+      end
+
+      def self.reset!
+        @mutex.synchronize { @cache = nil }
+      end
+
+      def self.load_cache
+        @mutex.synchronize do
+          @cache ||= begin
+            {
+              Molecular.qname            => Molecular,
+              Compchem.qname             => Compchem,
+              Dictionary.qname           => Dictionary,
+              UnitDictionary.qname       => UnitDictionary,
+              UnitTypeDictionary.qname   => UnitTypeDictionary
+            }
+          end
+        end
+      end
+      private_class_method :load_cache
+    end
+  end
+end

data/lib/chemicalml/convention/unit_dictionary/constraints/unit_must_have_symbol_and_unit_type.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module UnitDictionary
+      module Constraints
+        # Every unit MUST have `id`, `title`, `symbol`, `parentSI`,
+        # at least one of `multiplierToSI`/`constantToSI`, and
+        # `unitType` per the unit-dictionary convention.
+        class UnitMustHaveSymbolAndUnitType < Chemicalml::Convention::Constraint::NodeConstraint
+          REQUIRED = %i[title symbol parent_si unit_type].freeze
+
+          def check_node(node, path)
+            return [] unless unit?(node)
+
+            violations = []
+            REQUIRED.each do |attr|
+              val = node.public_send(attr)
+              next unless val.to_s.empty?
+
+              violations << violation(path: path.join("/"),
+                                      message: "unit must have #{attr} (id=#{node.id.inspect})")
+            end
+
+            unless has_si_conversion?(node)
+              violations << violation(path: path.join("/"),
+                                      message: "unit must have multiplierToSI or constantToSI (id=#{node.id.inspect})")
+            end
+
+            violations
+          end
+
+          private
+
+          def unit?(node)
+            node.is_a?(Chemicalml::Cml::Role::Unit)
+          end
+
+          def has_si_conversion?(node)
+            !node.multiplier_to_si.to_s.empty? || !node.constant_to_si.to_s.empty?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/unit_dictionary/constraints.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module UnitDictionary
+      module Constraints
+        autoload :UnitMustHaveSymbolAndUnitType,
+                 "chemicalml/convention/unit_dictionary/constraints/unit_must_have_symbol_and_unit_type"
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/unit_dictionary.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    # The unit-dictionary convention. Constraints based on
+    # http://www.xml-cml.org/convention/unit-dictionary (archived in
+    # `reference-docs/conventions/unit-dictionary.md`).
+    module UnitDictionary
+      extend Base
+
+      autoload :Constraints, "chemicalml/convention/unit_dictionary/constraints"
+
+      QNAME = "convention:unit-dictionary".freeze
+      NAMESPACE_URI = "#{Chemicalml::Convention::CONVENTION_NAMESPACE}unit-dictionary".freeze
+
+      def self.qname
+        QNAME
+      end
+
+      def self.namespace_uri
+        NAMESPACE_URI
+      end
+
+      register Constraints::UnitMustHaveSymbolAndUnitType
+    end
+  end
+end

data/lib/chemicalml/convention/unit_type_dictionary/constraints/unit_type_must_have_id_and_name.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module UnitTypeDictionary
+      module Constraints
+        # Every unitType MUST have an `id` and a `name` attribute per
+        # the unitType-dictionary convention.
+        class UnitTypeMustHaveIdAndName < Chemicalml::Convention::Constraint::NodeConstraint
+          def check_node(node, path)
+            return [] unless unit_type?(node)
+
+            violations = []
+            if node.id.to_s.empty?
+              violations << violation(path: path.join("/"),
+                                      message: "unitType must have an id")
+            end
+            if node.name.to_s.empty?
+              violations << violation(path: path.join("/"),
+                                      message: "unitType must have a name")
+            end
+            violations
+          end
+
+          private
+
+          def unit_type?(node)
+            node.is_a?(Chemicalml::Cml::Role::UnitType)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/unit_type_dictionary/constraints.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module UnitTypeDictionary
+      module Constraints
+        autoload :UnitTypeMustHaveIdAndName,
+                 "chemicalml/convention/unit_type_dictionary/constraints/unit_type_must_have_id_and_name"
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/unit_type_dictionary.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    # The unitType-dictionary convention. Constraints based on
+    # http://www.xml-cml.org/convention/unitType-dictionary (archived
+    # in `reference-docs/conventions/unitType-dictionary.md`).
+    module UnitTypeDictionary
+      extend Base
+
+      autoload :Constraints, "chemicalml/convention/unit_type_dictionary/constraints"
+
+      QNAME = "convention:unitType-dictionary".freeze
+      NAMESPACE_URI = "#{Chemicalml::Convention::CONVENTION_NAMESPACE}unitType-dictionary".freeze
+
+      def self.qname
+        QNAME
+      end
+
+      def self.namespace_uri
+        NAMESPACE_URI
+      end
+
+      register Constraints::UnitTypeMustHaveIdAndName
+    end
+  end
+end

data/lib/chemicalml/convention/violation.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    # Value object describing one constraint violation. Severity is
+    # either `:error` (document is invalid under the convention) or
+    # `:warning` (document is valid but problematic).
+    class Violation
+      SEVERITIES = %i[error warning].freeze
+
+      attr_reader :path, :message, :severity, :constraint
+
+      def initialize(path:, message:, severity: :error, constraint: nil)
+        raise ArgumentError, "unknown severity: #{severity.inspect}" unless SEVERITIES.include?(severity.to_sym)
+
+        @path       = path
+        @message    = message
+        @severity   = severity.to_sym
+        @constraint = constraint
+        freeze
+      end
+
+      def error?
+        severity == :error
+      end
+
+      def warning?
+        severity == :warning
+      end
+
+      def to_s
+        "#{severity.upcase} #{path}: #{message}"
+      end
+    end
+  end
+end

data/lib/chemicalml/convention.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  # Convention framework. A convention is a named, namespaced set of
+  # constraints that CML documents conform to in a particular domain.
+  #
+  # Conventions are *registered*, not switch-statement'd. Each
+  # convention owns its constraint classes; the framework walks
+  # whatever was registered.
+  #
+  # The five built-in conventions:
+  #
+  #   molecular            http://www.xml-cml.org/convention/molecular
+  #   compchem             http://www.xml-cml.org/convention/compchem
+  #   dictionary           http://www.xml-cml.org/convention/dictionary
+  #   unit-dictionary      http://www.xml-cml.org/convention/unit-dictionary
+  #   unitType-dictionary  http://www.xml-cml.org/convention/unitType-dictionary
+  module Convention
+    autoload :Base,                "chemicalml/convention/base"
+    autoload :Compchem,            "chemicalml/convention/compchem"
+    autoload :Constraint,          "chemicalml/convention/constraint"
+    autoload :Dictionary,          "chemicalml/convention/dictionary"
+    autoload :Molecular,           "chemicalml/convention/molecular"
+    autoload :Registry,            "chemicalml/convention/registry"
+    autoload :UnitDictionary,      "chemicalml/convention/unit_dictionary"
+    autoload :UnitTypeDictionary,  "chemicalml/convention/unit_type_dictionary"
+    autoload :Violation,           "chemicalml/convention/violation"
+
+    CONVENTION_NAMESPACE = "http://www.xml-cml.org/convention/".freeze
+
+    def self.lookup(qname)
+      Registry.lookup(qname)
+    end
+
+    def self.validate(document, qname:)
+      Registry.validate(document, qname: qname)
+    end
+  end
+end

data/lib/chemicalml/dictionary/entry.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Dictionary
+    # One dictionary entry. Plain Ruby value object — format-agnostic.
+    # The YAML shape mirrors the structure documented in
+    # `TODO.cml-full/05-dictionary-layer.md`.
+    class Entry
+      ID_PATTERN = /\A[A-Za-z][A-Za-z0-9._-]*\z/.freeze
+
+      attr_reader :id, :term, :definition, :description,
+                  :data_type, :unit_type, :units,
+                  :enum, :links, :source_code
+
+      def initialize(id:, term:, definition:, description: nil,
+                     data_type: nil, unit_type: nil, units: nil,
+                     enum: nil, links: [], source_code: nil)
+        raise ArgumentError, "invalid entry id: #{id.inspect}" unless id.to_s.match?(ID_PATTERN)
+
+        @id          = id.to_s
+        @term        = term
+        @definition  = definition
+        @description = description
+        @data_type   = data_type
+        @unit_type   = unit_type
+        @units       = units
+        @enum        = enum
+        @links       = links.to_a
+        @source_code = source_code
+        freeze
+      end
+
+      def to_h
+        h = {
+          id: id,
+          term: term,
+          definition: definition
+        }
+        h[:description] = description if description
+        h[:data_type]   = data_type   if data_type
+        h[:unit_type]   = unit_type   if unit_type
+        h[:units]       = units       if units
+        h[:enum]        = enum.to_h   if enum
+        h[:links]       = links.map(&:to_h) unless links.empty?
+        h[:source_code] = source_code if source_code
+        h
+      end
+
+      def eql?(other)
+        other.is_a?(Entry) && id == other.id && to_h == other.to_h
+      end
+      alias == eql?
+
+      def hash
+        [id, to_h].hash
+      end
+    end
+  end
+end

data/lib/chemicalml/dictionary/enum.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Dictionary
+    # An entry's enum constraint. CML dictionary entries can be tagged
+    # as either an *open* set (the listed values are recommended but
+    # others are allowed) or a *closed* set (only the listed values are
+    # valid).
+    class Enum
+      KINDS = %i[open closed].freeze
+
+      attr_reader :kind, :values
+
+      def initialize(kind: :open, values: [])
+        raise ArgumentError, "unknown enum kind: #{kind.inspect}" unless KINDS.include?(kind.to_sym)
+
+        @kind = kind.to_sym
+        @values = values.to_a
+        freeze
+      end
+
+      def open?
+        kind == :open
+      end
+
+      def closed?
+        kind == :closed
+      end
+
+      def allows?(value)
+        return true if open?
+        return true if values.empty?
+
+        values.include?(value)
+      end
+
+      def to_h
+        { kind: kind, values: values }
+      end
+
+      def eql?(other)
+        other.is_a?(Enum) && kind == other.kind && values == other.values
+      end
+      alias == eql?
+
+      def hash
+        [kind, values].hash
+      end
+    end
+  end
+end

data/lib/chemicalml/dictionary/link.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Dictionary
+    # One external link from an entry's description or definition.
+    # Maps to the `xhtml:a` element in the original CML dictionary
+    # entries.
+    class Link
+      attr_reader :rel, :href, :title
+
+      def initialize(rel:, href:, title: nil)
+        @rel = rel
+        @href = href
+        @title = title
+        freeze
+      end
+
+      def to_h
+        { rel: rel, href: href, title: title }.compact
+      end
+
+      def eql?(other)
+        other.is_a?(Link) && to_h == other.to_h
+      end
+      alias == eql?
+
+      def hash
+        to_h.hash
+      end
+    end
+  end
+end

data/lib/chemicalml/dictionary/loader.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Chemicalml
+  module Dictionary
+    # Reads a YAML file conforming to the dictionary schema (see
+    # `TODO.cml-full/05-dictionary-layer.md`) and constructs a
+    # `Chemicalml::Dictionary::Model`.
+    #
+    # This is the *only* place that knows about the YAML wire shape —
+    # everything else works in terms of the canonical Model.
+    module Loader
+      def self.from_file(path)
+        from_hash(YAML.load_file(path))
+      end
+
+      def self.from_hash(hash)
+        Model.new(
+          namespace: hash.fetch("namespace"),
+          prefix: hash.fetch("prefix"),
+          title: hash.fetch("title"),
+          description: hash["description"],
+          entries: (hash["entries"] || []).map { |e| build_entry(e) }
+        )
+      end
+
+      def self.build_entry(h)
+        Entry.new(
+          id: h.fetch("id"),
+          term: h.fetch("term"),
+          definition: h.fetch("definition"),
+          description: h["description"],
+          data_type: h["data_type"],
+          unit_type: h["unit_type"],
+          units: h["units"],
+          enum: build_enum(h["enum"]),
+          links: (h["links"] || []).map { |l| build_link(l) },
+          source_code: h["source_code"]
+        )
+      end
+      private_class_method :build_entry
+
+      def self.build_enum(h)
+        return nil unless h
+
+        Enum.new(
+          kind: h["kind"] || :open,
+          values: h["values"] || []
+        )
+      end
+      private_class_method :build_enum
+
+      def self.build_link(h)
+        Link.new(rel: h.fetch("rel"), href: h.fetch("href"), title: h["title"])
+      end
+      private_class_method :build_link
+    end
+  end
+end

data/lib/chemicalml/dictionary/model.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Dictionary
+    # The canonical dictionary model: namespace, prefix, title,
+    # description, and an ordered collection of `Entry` instances.
+    #
+    # Plain Ruby — no XML, no YAML. Loading from YAML goes through
+    # `Loader`; the wire (XML) shape is `Chemicalml::Cml::Dictionary`.
+    class Model
+      attr_reader :namespace, :prefix, :title, :description, :entries
+
+      def initialize(namespace:, prefix:, title:, description: nil, entries: [])
+        @namespace   = namespace
+        @prefix      = prefix
+        @title       = title
+        @description = description
+        @entries     = entries.to_a
+        freeze
+      end
+
+      def lookup(qualified_name)
+        _, id = split_qname(qualified_name)
+        return nil unless id
+
+        entries.find { |e| e.id == id }
+      end
+
+      def lookup!(qualified_name)
+        lookup(qualified_name) ||
+          raise(KeyError, "no entry #{qualified_name.inspect} in #{namespace}")
+      end
+
+      def entry_ids
+        entries.map(&:id)
+      end
+
+      def to_h
+        {
+          namespace: namespace,
+          prefix: prefix,
+          title: title,
+          description: description,
+          entries: entries.map(&:to_h)
+        }
+      end
+
+      def eql?(other)
+        other.is_a?(Model) && namespace == other.namespace && to_h == other.to_h
+      end
+      alias == eql?
+
+      def hash
+        [namespace, to_h].hash
+      end
+
+      private
+
+      def split_qname(qname)
+        qname.to_s.split(":", 2)
+      end
+    end
+  end
+end

data/lib/chemicalml/dictionary/registry.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Dictionary
+    # Registry of built-in dictionaries. Lazily loads YAML from
+    # `data/dictionaries/` on first access; subsequent lookups hit the
+    # in-memory cache.
+    #
+    # Adding a new built-in dictionary = dropping a new `.yaml` file
+    # under `data/dictionaries/`. No code change required.
+    module Registry
+      @cache = {}
+      @mutex = Mutex.new
+
+      def self.lookup(qname)
+        prefix, id = qname.to_s.split(":", 2)
+        return nil unless id
+
+        dict = load_by_prefix(prefix)
+        return nil unless dict
+
+        dict.lookup(qname)
+      end
+
+      def self.lookup!(qname)
+        lookup(qname) || raise(KeyError, "no dictionary entry #{qname.inspect}")
+      end
+
+      def self.load_builtin(name)
+        @mutex.synchronize do
+          @cache[name.to_s] ||= begin
+            path = File.join(Chemicalml::Dictionary::BUILTIN_DIR, "#{name}.yaml")
+            raise KeyError, "no built-in dictionary #{name.inspect}" unless File.exist?(path)
+
+            Loader.from_file(path)
+          end
+        end
+      end
+
+      def self.load_by_prefix(prefix)
+        manifest.each do |name, info|
+          return load_builtin(name) if info["prefix"] == prefix
+        end
+        nil
+      end
+
+      def self.reset!
+        @mutex.synchronize { @cache.clear }
+      end
+
+      def self.builtin_names
+        Dir.glob(File.join(BUILTIN_DIR, "*.yaml"))
+           .reject { |p| File.basename(p).start_with?("_") }
+           .map { |p| File.basename(p, ".yaml").to_sym }
+           .sort
+      end
+
+      def self.manifest
+        @manifest ||= begin
+          path = File.join(BUILTIN_DIR, "_index.yaml")
+          if File.exist?(path)
+            YAML.load_file(path) || {}
+          else
+            builtin_names.each_with_object({}) do |name, h|
+              h[name.to_s] = { "prefix" => name.to_s }
+            end
+          end
+        end
+      end
+      private_class_method :manifest
+
+      require "yaml"
+    end
+  end
+end