dcc 0.2.0

data/lib/dcc/migrate.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# `Dcc::Migrate` upgrades or downgrades a parsed DCC between schema versions,
+# applying the necessary field renames and D-SI version transitions.
+#
+# Currently a thin shim: serializes the source DCC and re-parses under
+# the target version's context. Future work will add per-field transformations.
+module Dcc
+  module Migrate
+    class << self
+      # @param dcc [Lutaml::Model::Serializable]
+      # @param from [String] source version (e.g. "2.3.0").
+      # @param to [String] target version (e.g. "3.3.0").
+      # @return [Dcc::V2::DigitalCalibrationCertificate, Dcc::V3::DigitalCalibrationCertificate]
+      def call(dcc, from:, to:)
+        from_major = ::Dcc::Schema::Version.major(from)
+        to_major = ::Dcc::Schema::Version.major(to)
+        if from_major == to_major
+          # Same major: just rewrite the schemaVersion attribute.
+          return rewrite_schema_version(dcc, to)
+        end
+
+        # Cross-major migration: serialize then re-parse under target.
+        xml = dcc.to_xml
+        target_parser = ::Dcc.parser_for(to_major)
+        target_parser.load_all!
+        migrated = target_parser.parse(xml)
+        rewrite_schema_version(migrated, to)
+      end
+
+      private
+
+      def rewrite_schema_version(dcc, version)
+        return dcc unless Dcc::TypeGuards.has_writer?(dcc, :schema_version)
+
+        dcc.schema_version = version
+        dcc
+      end
+    end
+  end
+end

data/lib/dcc/namespace/dcc.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "lutaml/xml"
+
+module Dcc
+  module Namespace
+    # The DCC XML namespace. PTB publishes the canonical URI as
+    # `https://ptb.de/dcc`; older documents occasionally use the
+    # `https://ptb.de/dcc.xsd` alias which we accept via `uri_aliases`.
+    #
+    # Schema location is versioned (e.g. `https://ptb.de/dcc/v3.3.0/dcc.xsd`).
+    # The default points to the latest published version; per-version overrides
+    # happen in `Dcc::V2::Namespace` and `Dcc::V3::Namespace`.
+    class Dcc < Lutaml::Xml::Namespace
+      uri "https://ptb.de/dcc"
+      uri_aliases "https://ptb.de/dcc.xsd"
+      schema_location "https://ptb.de/dcc/v3.3.0/dcc.xsd"
+      prefix_default "dcc"
+      element_form_default :qualified
+      attribute_form_default :unqualified
+      version "3.3.0"
+
+      # DCC imports D-SI for quantity expressions, MathML for formulae, and
+      # (from v3.4.0) W3C XMLDSig for digital signatures.
+      imports ::Dcc::Namespace::Si,
+              ::Dcc::Namespace::MathMl,
+              ::Dcc::Namespace::Dsig
+    end
+  end
+end

data/lib/dcc/namespace/dsig.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "lutaml/xml"
+
+module Dcc
+  module Namespace
+    # W3C XML Digital Signature namespace. Imported by DCC v3.4.0+ to support
+    # `ds:Signature` elements on the root `digitalCalibrationCertificate`.
+    class Dsig < Lutaml::Xml::Namespace
+      uri "http://www.w3.org/2000/09/xmldsig#"
+      prefix_default "ds"
+      element_form_default :qualified
+    end
+  end
+end

data/lib/dcc/namespace/math_ml.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "lutaml/xml"
+
+module Dcc
+  module Namespace
+    # W3C MathML namespace used inside DCC `dcc:formula` elements.
+    class MathMl < Lutaml::Xml::Namespace
+      uri "http://www.w3.org/1998/Math/MathML"
+      prefix_default "ml"
+      element_form_default :qualified
+    end
+  end
+end

data/lib/dcc/namespace/qudt.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "lutaml/xml"
+
+module Dcc
+  module Namespace
+    # QUDT vocabulary namespace. Referenced by D-SI for quantity-kind
+    # identifiers (e.g. `https://qudt.org/vocab/quantitykind/Length`).
+    class Qudt < Lutaml::Xml::Namespace
+      uri "http://qudt.org/vocab/"
+      prefix_default "qudt"
+      element_form_default :qualified
+    end
+  end
+end

data/lib/dcc/namespace/si.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "lutaml/xml"
+
+module Dcc
+  module Namespace
+    # The D-SI XML namespace (https://ptb.de/si). Used to express measurement
+    # quantities (real, complex, constant, list) and their uncertainties inside
+    # DCC documents.
+    #
+    # Schema location is versioned. The default points to the latest D-SI
+    # release; per-version overrides live in `Dcc::Si::V1::Namespace` and
+    # `Dcc::Si::V2::Namespace`.
+    class Si < Lutaml::Xml::Namespace
+      uri "https://ptb.de/si"
+      uri_aliases "https://ptb.de/si.xsd"
+      schema_location "https://ptb.de/si/v2.2.1/SI_Format.xsd"
+      prefix_default "si"
+      element_form_default :qualified
+      attribute_form_default :unqualified
+      version "2.2.1"
+
+      imports ::Dcc::Namespace::Qudt
+    end
+  end
+end

data/lib/dcc/namespace.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# `Dcc::Namespace` aggregates the five XML namespaces used by DCC documents:
+#
+# * `dcc:`  — the Digital Calibration Certificate itself (https://ptb.de/dcc)
+# * `si:`   — D-SI quantity values (https://ptb.de/si)
+# * `ml:`   — MathML formulae (http://www.w3.org/1998/Math/MathML)
+# * `ds:`   — W3C XML Digital Signature (http://www.w3.org/2000/09/xmldsig#)
+# * `qudt:` — QUDT quantity kinds (http://qudt.org/vocab/)
+module Dcc
+  module Namespace
+    autoload :Dcc, "dcc/namespace/dcc"
+    autoload :Si, "dcc/namespace/si"
+    autoload :MathMl, "dcc/namespace/math_ml"
+    autoload :Dsig, "dcc/namespace/dsig"
+    autoload :Qudt, "dcc/namespace/qudt"
+  end
+end

data/lib/dcc/plugin/registry.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Dcc
+  module Plugin
+    # Category-based registry. Each category (validators, converters,
+    # cli_commands) gets its own array. Thread-safe via a Mutex.
+    class Registry
+      @categories = ::Hash.new { |h, k| h[k] = [] }
+      @mutex = ::Mutex.new
+
+      class << self
+        # @param category [Symbol]
+        # @param entry [Class, Object]
+        # @return [Class, Object]
+        def register(category, entry)
+          @mutex.synchronize do
+            @categories[category.to_sym] << entry
+            entry
+          end
+        end
+
+        # @param category [Symbol]
+        # @return [Array<Object>]
+        def all(category)
+          @mutex.synchronize { @categories[category.to_sym].dup }
+        end
+
+        # @param category [Symbol]
+        # @return [Boolean]
+        def any?(category)
+          @mutex.synchronize { !@categories[category.to_sym].empty? }
+        end
+
+        def reset!
+          @mutex.synchronize { @categories.clear }
+        end
+
+        # @return [Array<Symbol>] the registered category names.
+        def categories
+          @mutex.synchronize { @categories.keys.dup }
+        end
+      end
+    end
+  end
+end

data/lib/dcc/plugin.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# `Dcc::Plugin` is the registry-based extension point for the gem.
+# Plugins can register custom validators, converters, or CLI commands
+# without modifying the core codebase (Open/Closed Principle).
+#
+# @example Register a custom validator
+#   Dcc::Plugin.register(:validators, MyCustomRule)
+#
+# @example List all registered validators
+#   Dcc::Plugin.all(:validators)
+module Dcc
+  module Plugin
+    autoload :Registry, "dcc/plugin/registry"
+
+    class << self
+      # @param category [Symbol] e.g. :validators, :converters, :cli_commands.
+      # @param entry [Class, Object] the plugin to register.
+      # @return [Class, Object] the entry.
+      def register(category, entry)
+        ::Dcc::Plugin::Registry.register(category, entry)
+      end
+
+      # @param category [Symbol]
+      # @return [Array<Object>]
+      def all(category)
+        ::Dcc::Plugin::Registry.all(category)
+      end
+
+      # @param category [Symbol]
+      # @return [Boolean]
+      def any?(category)
+        ::Dcc::Plugin::Registry.any?(category)
+      end
+
+      # Reset the registry (test-only helper).
+      def reset!
+        ::Dcc::Plugin::Registry.reset!
+      end
+    end
+  end
+end

data/lib/dcc/quantity_format/formatter.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Dcc
+  module QuantityFormat
+    # SmartCom-style quantity pretty-printing. Significant digits derived
+    # from uncertainty (PTB convention: 2 sig digits in uncertainty).
+    class Formatter
+      attr_reader :value, :uncertainty, :unit
+
+      # @param value [BigDecimal, Numeric]
+      # @param uncertainty [BigDecimal, Numeric, nil]
+      # @param unit [String, nil] siunitx expression
+      def initialize(value:, uncertainty: nil, unit: nil)
+        @value = BigDecimal(value.to_s)
+        @uncertainty = uncertainty.nil? ? nil : BigDecimal(uncertainty.to_s)
+        @unit = unit
+      end
+
+      # @return [String] compact notation: `42.00(5) K`
+      def to_short
+        return format_value.to_s + unit_suffix if uncertainty.nil?
+
+        v_str, u_str = align_value_and_uncertainty
+        "#{v_str}(#{u_str})#{unit_suffix}"
+      end
+
+      # @return [String] verbose: `42.00 ± 0.05 K`
+      def to_long
+        if uncertainty.nil?
+          "#{format_value}#{unit_suffix}"
+        else
+          "#{format_value} ± #{format_uncertainty}#{unit_suffix}"
+        end
+      end
+
+      # @return [String] LaTeX siunitx: `\qty{42.00 +- 0.05}{\kelvin}`
+      def to_latex
+        if uncertainty.nil?
+          "\\qty{#{format_value}}{#{unit || ''}}"
+        else
+          "\\qty{#{format_value} +- #{format_uncertainty}}{#{unit || ''}}"
+        end
+      end
+
+      private
+
+      def format_value
+        # Two decimals by default; tightened to uncertainty precision when known.
+        return @value.round(2).to_s("F") if uncertainty.nil?
+
+        # Decimal places = 1 - floor(log10(uncertainty))
+        decimal_places = [0, 1 - Integer(Math.log10(uncertainty.to_f).floor)].max
+        @value.round(decimal_places).to_s("F")
+      end
+
+      def format_uncertainty
+        return "" if uncertainty.nil?
+
+        decimal_places = [0, 1 - Integer(Math.log10(uncertainty.to_f).floor)].max
+        uncertainty.round(decimal_places).to_s("F")
+      end
+
+      def align_value_and_uncertainty
+        return [@value.to_s("F"), uncertainty.to_s("F")] if uncertainty.nil?
+
+        decimal_places = [0, 1 - Integer(Math.log10(uncertainty.to_f).floor)].max
+        v_str = @value.round(decimal_places).to_s("F")
+        u_str = uncertainty.round(decimal_places).to_s("F")
+        # Short form: digits of uncertainty after the last common digit
+        last_digits = u_str.gsub(/[^0-9]/, "")[-2..]
+        [v_str, last_digits]
+      end
+
+      def unit_suffix
+        return "" if unit.nil? || unit.empty?
+
+        " #{human_unit}"
+      end
+
+      def human_unit
+        unit
+          .to_s
+          .gsub(/\\([a-z]+)/, '\\1') # \kelvin → kelvin
+          .gsub(/\\per/, '/')
+          .gsub(/\\cubic/, '^3')
+          .gsub(/\\square/, '^2')
+      end
+    end
+  end
+end

data/lib/dcc/quantity_format.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# `Dcc::QuantityFormat` renders quantities in human-readable form. Three
+# formats: `:short` (compact, e.g. `42.00(5) K`), `:long` (verbose), and
+# `:latex` (siunitx).
+module Dcc
+  module QuantityFormat
+    autoload :Formatter, "dcc/quantity_format/formatter"
+  end
+end

data/lib/dcc/quantity_math/quantity.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module Dcc
+  module QuantityMath
+    # A simple `(value, unit, uncertainty)` value object used by
+    # `Dcc::QuantityMath::Real` for arithmetic. Immutable.
+    class Quantity
+      attr_reader :value, :unit, :uncertainty
+
+      # @param value [BigDecimal, Numeric]
+      # @param unit [String, nil] siunitx expression
+      # @param uncertainty [BigDecimal, Numeric, nil] 1σ absolute uncertainty
+      def initialize(value:, unit: nil, uncertainty: nil)
+        @value = cast_decimal(value)
+        @unit = unit
+        @uncertainty = uncertainty.nil? ? nil : cast_decimal(uncertainty)
+      end
+
+      # @return [Boolean] whether the quantity carries uncertainty info.
+      def uncertain?
+        !uncertainty.nil?
+      end
+
+      # @return [Boolean] whether units match (or both are nil).
+      def same_unit?(other)
+        unit == other.unit
+      end
+
+      def to_s
+        u = uncertain? ? " ± #{uncertainty}" : ""
+        n = unit ? " #{unit}" : ""
+        "#{value}#{u}#{n}"
+      end
+
+      private
+
+      def cast_decimal(value)
+        return value if value.is_a?(::BigDecimal)
+
+        BigDecimal(value.to_s)
+      end
+    end
+  end
+end

data/lib/dcc/quantity_math/real.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module Dcc
+  module QuantityMath
+    # BigDecimal arithmetic on real-valued quantities with RSS uncertainty
+    # propagation for add/sub and fractional propagation for mul/div.
+    class Real < Quantity
+      # @return [Real]
+      def +(other)
+        ensure_same_unit!(other)
+        Real.new(
+          value: value + other.value,
+          unit: unit,
+          uncertainty: rss_uncertainty(other),
+        )
+      end
+
+      # @return [Real]
+      def -(other)
+        ensure_same_unit!(other)
+        Real.new(
+          value: value - other.value,
+          unit: unit,
+          uncertainty: rss_uncertainty(other),
+        )
+      end
+
+      # @return [Real]
+      def *(other)
+        new_value = value * other.value
+        new_unit = compose_unit(unit, other.unit)
+        Real.new(
+          value: new_value,
+          unit: new_unit,
+          uncertainty: fractional_uncertainty_mul_div(other, new_value),
+        )
+      end
+
+      # @return [Real]
+      def /(other)
+        new_value = value / other.value
+        new_unit = compose_unit(unit, inverse_unit(other.unit))
+        Real.new(
+          value: new_value,
+          unit: new_unit,
+          uncertainty: fractional_uncertainty_mul_div(other, new_value),
+        )
+      end
+
+      # @param exponent [Integer]
+      # @return [Real]
+      def **(exponent)
+        new_value = value ** exponent
+        Real.new(
+          value: new_value,
+          unit: unit && "^#{exponent}",
+          uncertainty: power_uncertainty(exponent, new_value),
+        )
+      end
+
+      private
+
+      def ensure_same_unit!(other)
+        return if same_unit?(other)
+
+        raise ::ArgumentError,
+              "unit mismatch: #{unit.inspect} vs #{other.unit.inspect}"
+      end
+
+      # Root-sum-square for add/sub: σ_result = sqrt(σ1² + σ2²)
+      def rss_uncertainty(other)
+        return nil unless uncertain? && other.uncertain?
+        return other.uncertainty if uncertainty.nil?
+        return uncertainty if other.uncertainty.nil?
+
+        sum_of_squares = (uncertainty ** 2) + (other.uncertainty ** 2)
+        BigDecimal(Math.sqrt(sum_of_squares.to_f).to_s)
+      end
+
+      # Fractional for mul/div: σ_y / y = sqrt((σ_a/a)² + (σ_b/b)²)
+      def fractional_uncertainty_mul_div(other, new_value)
+        return nil unless uncertain? && other.uncertain?
+        return nil if value.zero? || other.value.zero?
+
+        a_rel = uncertainty / value
+        b_rel = other.uncertainty / other.value
+        sum_of_squares = (a_rel ** 2) + (b_rel ** 2)
+        BigDecimal(Math.sqrt(sum_of_squares.to_f).to_s) * new_value.abs
+      end
+
+      # Power rule: σ_y = |n * x^(n-1)| * σ_x
+      def power_uncertainty(exponent, new_value)
+        return nil unless uncertain?
+
+        derivative = exponent * (value ** (exponent - 1))
+        (derivative.abs * uncertainty)
+      end
+
+      def compose_unit(u1, u2)
+        return nil if u1.nil? && u2.nil?
+        return u1 if u2.nil?
+        return u2 if u1.nil?
+
+        "#{u1}\\cdot#{u2}"
+      end
+
+      def inverse_unit(u)
+        return nil if u.nil?
+
+        "#{u}^-1"
+      end
+    end
+  end
+end

data/lib/dcc/quantity_math.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "bigdecimal/math"
+
+module Dcc
+  # `Dcc::QuantityMath` provides BigDecimal-based arithmetic on D-SI
+  # quantities with proper uncertainty propagation. RSS (root-sum-square)
+  # for addition/subtraction, fractional for multiplication/division.
+  module QuantityMath
+    autoload :Quantity, "dcc/quantity_math/quantity"
+    autoload :Real, "dcc/quantity_math/real"
+  end
+end