pubid 1.15.21 → 2.0.0.alpha.10

data/lib/pubid/errors.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "parslet"
+
+module Pubid
+  # Every failure pubid raises.
+  #
+  # The three classes below have three different superclasses, chosen so that
+  # code written against the old contract keeps working: relaton-cli rescues
+  # `Parslet::ParseFailed`, and the input guards have always raised
+  # `ArgumentError`. What unifies them is the marker module
+  # {Pubid::Errors::Error}, which every one of them includes, so a caller that
+  # wants "pubid could not do this" writes one rescue:
+  #
+  #   begin
+  #     Pubid::Iso.parse(reference)
+  #   rescue Pubid::Errors::Error => e
+  #     warn e.message
+  #   end
+  #
+  # A URN failure deliberately does not inherit `Parslet::ParseFailed`: no
+  # grammar runs, so there is no parse failure to report.
+  module Errors
+    # Marker module included by every pubid error. Rescue this to catch all
+    # of them, whatever their superclass.
+    module Error; end
+
+    # A printed identifier could not be turned into an identifier object.
+    #
+    # Raised for a grammar rejection, and also for the few flavors that reject
+    # an input before the grammar runs (a CSA comment line, a bad ISBN check
+    # digit). Those synthetic failures carry no parslet cause, so
+    # {#parse_failure_cause} is nillable — check it before calling
+    # `ascii_tree` on it.
+    #
+    # v1's `Pubid::Core::Errors::ParseError` flattened the cause into the
+    # message and threw the object away. This one keeps it.
+    class ParseError < ::Parslet::ParseFailed
+      include Error
+
+      # The string that could not be parsed, when it is known.
+      # @return [String, nil]
+      attr_reader :input
+
+      # The flavor whose grammar rejected the input, lowercased ("iso").
+      #
+      # This is the flavor that actually ran, which is not always the one the
+      # caller named: `Pubid::Iso.parse("ITU-T G.711")` routes through the
+      # MR-string parser into ITU, and reports "itu".
+      # @return [String, nil]
+      attr_reader :flavor
+
+      # @param message [String]
+      # @param parse_failure_cause [Parslet::Cause, nil] parslet's structured
+      #   cause, nil for a failure raised without running a grammar
+      # @param input [String, nil]
+      # @param flavor [String, nil]
+      def initialize(message, parse_failure_cause = nil, input: nil,
+                     flavor: nil)
+        super(message, parse_failure_cause)
+        @input = input
+        @flavor = flavor
+      end
+    end
+
+    # A URN could not be turned into an identifier object.
+    class UrnParseError < ::StandardError
+      include Error
+    end
+
+    # The input was not a String, or was longer than {Pubid::MAX_INPUT_LENGTH}.
+    #
+    # Inherits `ArgumentError` because that is what the guards have always
+    # raised, and because the input is wrong in kind rather than unparseable.
+    class InvalidInputError < ::ArgumentError
+      include Error
+    end
+  end
+end

data/lib/pubid/etsi/builder.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Etsi
+    class Builder
+      def self.build(parsed_data)
+        new.build(parsed_data)
+      end
+
+      def build(data)
+        # Check if supplements are present
+        if data[:supplements]
+          build_with_supplements(data)
+        else
+          build_etsi_standard(data)
+        end
+      end
+
+      private
+
+      def build_with_supplements(data)
+        # Build base identifier first (without supplements)
+        base_data = data.dup
+        base_data.delete(:supplements)
+        base = build_etsi_standard(base_data)
+
+        # Process supplements - create supplement objects wrapping the base
+        supplements_array = data[:supplements]
+        supplements_array = [supplements_array] unless supplements_array.is_a?(Array)
+
+        # Build supplements recursively - each wraps the previous
+        supplements_array.reduce(base) do |current_base, supp|
+          if supp[:amendment]
+            Identifiers::Amendment.new(
+              base: current_base,
+              number: supp[:amendment][:number].to_i,
+            )
+          elsif supp[:corrigendum]
+            Identifiers::Corrigendum.new(
+              base: current_base,
+              number: supp[:corrigendum][:number].to_i,
+            )
+          else
+            current_base # Skip unknown supplement types
+          end
+        end
+      end
+
+      def build_etsi_standard(data)
+        # Build components
+        code = build_code(data)
+        version = build_version(data)
+        date = build_date(data)
+
+        # The code fields are stored as flat index columns on the leaf (see
+        # EtsiStandard) — `number` is what relaton-index keys on — so the Code
+        # object built above is unpacked rather than assigned.
+        Identifiers::EtsiStandard.new(
+          type: data[:type].to_s,
+          number: code.number,
+          minor: code.minor,
+          parts: code.parts || [],
+          version: version,
+          date: date,
+        )
+      end
+
+      def build_code(data)
+        number_data = data[:number]
+
+        # Extract number string based on format
+        number = if number_data.is_a?(Hash)
+                   # Captured format
+                   if number_data[:gsm_prefix]
+                     # GSM with space: "GSM 11.14"
+                     "GSM #{number_data[:main]}.#{number_data[:sub]}"
+                   elsif number_data[:main] && number_data[:sub]
+                     # Dotted format: "11.40"
+                     "#{number_data[:main]}.#{number_data[:sub]}"
+                   elsif number_data[:prefix1]
+                     # Complex format: "ABC 123" or "ABC-DEF 123"
+                     prefix = number_data[:prefix1].to_s
+                     prefix += "-#{number_data[:prefix2]}" if number_data[:prefix2]
+                     "#{prefix} #{number_data[:num]}"
+                   else
+                     # Simple with capture
+                     number_data[:num].to_s
+                   end
+                 else
+                   number_data.to_s
+                 end
+
+        parts = extract_parts(data[:parts])
+
+        Components::Code.new(
+          number: number,
+          minor: data[:minor]&.to_s,
+          parts: parts,
+        )
+      end
+
+      def build_version(data)
+        # Handle both version and edition. A partial reference omits both, in
+        # which case version is left nil (not defaulted) so exclude/matches?
+        # treat it as a wildcard.
+        if data[:version]
+          Components::Version.new(version: data[:version].to_s,
+                                  is_edition: false)
+        elsif data[:edition]
+          Components::Version.new(version: data[:edition].to_s,
+                                  is_edition: true)
+        end
+      end
+
+      def build_date(data)
+        # A partial reference omits the date; leave it nil rather than building
+        # an empty Date, so the canonical to_hash drops it entirely.
+        return nil unless data[:year]
+
+        Pubid::Components::Date.new(
+          year: data[:year].to_s,
+          month: data[:month].to_s,
+        )
+      end
+
+      def extract_parts(parts_data)
+        return [] unless parts_data
+
+        parts = []
+        if parts_data.is_a?(Array)
+          parts_data.each do |part_hash|
+            parts << part_hash[:part].to_s if part_hash[:part]
+          end
+        elsif parts_data.is_a?(Hash) && parts_data[:part]
+          parts << parts_data[:part].to_s
+        end
+
+        parts
+      end
+    end
+  end
+end

data/lib/pubid/etsi/components/code.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Pubid
+  module Etsi
+    module Components
+      # Represents an ETSI code with complex number formats
+      # Handles three variants:
+      #   Simple: 012, 123, 456
+      #   GSM: GSM 02.01, 02.01
+      #   Complex: ABC 123, ABC-DEF 123
+      #
+      # Stays independent of Pubid::Components::Code because ETSI uses
+      # +minor+ (a flavor-specific sub-number) plus +parts+.
+      class Code < Lutaml::Model::Serializable
+        attribute :number, :string # Main number
+        attribute :minor, :string # Optional minor part
+        attribute :parts, :string, collection: true, default: [] # Parts array
+
+        # Render code with space for minor and dash-separated parts
+        def to_s
+          result = number.to_s
+          result += " #{minor}" if minor
+          result += parts.map { |p| "-#{p}" }.join if parts&.any?
+          result
+        end
+
+        def render(context: nil)
+          to_s
+        end
+
+        def ==(other)
+          return false unless other.is_a?(Code)
+
+          number == other.number &&
+            minor == other.minor &&
+            parts == other.parts
+        end
+      end
+    end
+  end
+end

data/lib/pubid/etsi/components/version.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Pubid
+  module Etsi
+    module Components
+      # Represents an ETSI version string
+      # Format: V1.2.3, V2.0.0, or ed.1
+      class Version < Lutaml::Model::Serializable
+        attribute :version, :string # e.g., "1.1.1", "2.0.0", "1"
+        attribute :is_edition, :boolean, default: -> {
+          false
+        } # true for ed.N format
+
+        def to_s
+          if is_edition
+            "ed.#{version}"
+          else
+            "V#{version}"
+          end
+        end
+
+        def ==(other)
+          return false unless other.is_a?(Version)
+
+          version == other.version && is_edition == other.is_edition
+        end
+      end
+    end
+  end
+end

data/lib/pubid/etsi/components.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Etsi
+    module Components
+      autoload :Code, "#{__dir__}/components/code"
+      autoload :Version, "#{__dir__}/components/version"
+    end
+  end
+end

data/lib/pubid/etsi/identifier.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Pubid::Etsi::Identifier is the ETSI base class (a real Pubid::Identifier
+# subclass); its body and `.parse` live in identifiers/base.rb. This file just ensures it is loaded.

data/lib/pubid/etsi/identifiers/amendment.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Etsi
+    module Identifiers
+      # ETSI Amendment
+      # Format: {base}/A{number}
+      class Amendment < SupplementIdentifier
+        def supplement_notation
+          "A#{number}"
+        end
+      end
+    end
+  end
+end

data/lib/pubid/etsi/identifiers/base.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Etsi
+    # Base class for all ETSI identifiers. Canonical name Pubid::Etsi::Identifier;
+    # every concrete ETSI identifier descends from it.
+    class Identifier < ::Pubid::Identifier
+      # Let Parslet::ParseFailed propagate on a bad reference (matching ISO), so
+      # relaton-cli's `rescue Parslet::ParseFailed` fetch handler catches it
+      # instead of a bare RuntimeError.
+      def self.parse(identifier)
+        unless identifier.is_a?(String)
+          raise Pubid::Errors::InvalidInputError,
+                Pubid::INPUT_NOT_A_STRING_MESSAGE
+        end
+
+        if identifier.length > Pubid::MAX_INPUT_LENGTH
+          raise Pubid::Errors::InvalidInputError, Pubid::INPUT_TOO_LONG_MESSAGE
+        end
+
+        parsed = Parser.parse(identifier)
+        Builder.build(parsed)
+      end
+
+      attribute :type, :string
+      attribute :version, Pubid::Etsi::Components::Version
+      attribute :date, Pubid::Components::Date
+      # Stored as a plain string (always "ETSI") so it round-trips through
+      # to_hash/from_hash. Was previously a `def publisher` method, which made
+      # lutaml serialize a String against the Components::Publisher attribute and
+      # raise on to_hash.
+      attribute :publisher, :string, default: -> { "ETSI" }
+
+      def ==(other)
+        return false unless other.is_a?(Pubid::Etsi::Identifier)
+
+        type == other.type &&
+          code == other.code &&
+          version == other.version &&
+          date == other.date
+      end
+
+      # The document code is composed from the split index columns declared on
+      # EtsiStandard (`number`/`minor`/`parts`). Returning nil here keeps `==`
+      # and the URN generator total for the abstract base and for a supplement
+      # whose own base is missing; EtsiStandard composes the real value and
+      # SupplementIdentifier delegates to its base.
+      def code
+        nil
+      end
+
+      # `parts` is a plain collection attribute on the leaf, so the base
+      # #exclude reaches it directly and nils it. It must come back as an EMPTY
+      # ARRAY instead: a part-less reference parses with `parts` defaulting to
+      # [], so a nil here would make `==` — and therefore #matches? — fail
+      # against exactly the reference this exclusion exists to match. Same
+      # "reset the whole cluster" rule recorded for CSA's year and IEEE's
+      # year/month/day in CLAUDE.md.
+      #
+      # This also covers supplements: the base #exclude recurses into the
+      # nested `base` identifier through exclude_from_nested, which re-enters
+      # this method on the inner EtsiStandard.
+      def exclude(*args)
+        result = super
+        part_keys = args & %i[part parts]
+        if !part_keys.empty? && result.respond_to?(:parts=)
+          result.parts = []
+        end
+        result
+      end
+    end
+
+  end
+end

data/lib/pubid/etsi/identifiers/corrigendum.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Etsi
+    module Identifiers
+      # ETSI Corrigendum
+      # Format: {base}/C{number}
+      class Corrigendum < SupplementIdentifier
+        def supplement_notation
+          "C#{number}"
+        end
+      end
+    end
+  end
+end

data/lib/pubid/etsi/identifiers/etsi_standard.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Etsi
+    module Identifiers
+      # Single class for all ETSI standard types
+      # Type is passed as parameter: EN, ES, EG, TS, ETR, ETS, I-ETS, TBR,
+      # TCRTR, NET, GR, GS, SR, TR, GTS
+      # Format: ETSI TYPE CODE VERSION (DATE)
+      # Examples:
+      #   ETSI GS ZSM 012 V1.1.1 (2022-12)
+      #   ETSI GR ZSM 009-3 V1.1.1 (2023-08)
+      #   ETSI GTS GSM 02.01 V5.5.0 (1999-01)
+      class EtsiStandard < Identifier
+        # Type is stored in @type attribute from Identifier
+        # All rendering handled by Identifier class
+
+        # --- Index columns -------------------------------------------------
+        #
+        # relaton-index sorts and bsearches every row on `id.root.number.to_s`,
+        # so the document number must be reachable as `number`. ETSI used to
+        # keep it inside an Etsi::Components::Code under a `code` attribute,
+        # leaving the inherited `number` nil and every index row keyed "".
+        #
+        # The three Code fields are now plain sibling attributes, which is the
+        # shape the serialized hash ALREADY had — the converters below merely
+        # read them directly instead of reaching through `code`, so the wire
+        # format is byte-identical and relaton-data-etsi's published index-v2
+        # needs no regeneration.
+        #
+        # `number` holds the BARE number ("300 175"), never the part, so all
+        # parts of a document share one index bucket and a part-less reference
+        # finds them all — the IEEE/ISO semantics documented in CLAUDE.md.
+        #
+        # LANDMINE: these redeclare attributes inherited from ::Pubid::Identifier
+        # (`number` is a Components::Code there, and Etsi::Components::Code is
+        # NOT a subclass of it). That resolves nondeterministically under
+        # multi-flavor load when declared on a class others inherit from, so it
+        # is confined to this LEAF — EtsiStandard has no subclasses, while the
+        # shared Pubid::Etsi::Identifier is also SupplementIdentifier's parent
+        # and must stay untouched. spec/pubid/etsi/root_number_spec.rb carries
+        # the tripwire and is only meaningful under the full `rake` suite.
+        attribute :number, :string
+        attribute :minor, :string
+        attribute :parts, :string, collection: true, default: -> { [] }
+
+        # Compact serialization (mirrors ISO/JCGM/OIML): the code fields are
+        # bare scalars (`number`, a `parts` array and, rarely, a `minor`);
+        # Version flattens to a scalar `version` string with an `is_edition`
+        # boolean flag (omitted when false); Date flattens to top-level
+        # year/month/day. The constant `publisher` ("ETSI") is intentionally
+        # NOT mapped — it is reconstructed on load from its attribute default,
+        # keeping the hash compact.
+        #
+        # This block lives on EtsiStandard (a leaf) rather than the shared Identifier:
+        # SupplementIdentifier is a sibling that DELEGATES type/code/version and
+        # date to its inner `base`, so a block on Identifier would be inherited-and-
+        # merged by the supplement and re-emit every delegated field at the top.
+        key_value do
+          map "_type",      to: :_type
+          map "type",       to: :type
+          map "number",     to: :number
+          map "parts",      to: :parts
+          map "minor",      to: :minor
+          map "version",    with: { to: :version_to_kv, from: :version_from_kv }
+          map "is_edition", with: { to: :edition_to_kv, from: :edition_from_kv }
+          map "year",       with: { to: :year_to_kv,  from: :year_from_kv }
+          map "month",      with: { to: :month_to_kv, from: :month_from_kv }
+          map "day",        with: { to: :day_to_kv,   from: :day_from_kv }
+        end
+
+        # The composed document code, rebuilt on demand from the split columns
+        # so the renderer, the URN generator and #== keep one place to ask for
+        # the printed form ("300 175-1"). Deliberately NOT an attribute and NOT
+        # memoised: `number`/`parts` are writable (the base #exclude rebuilds
+        # through them), so a cached Code would go stale.
+        #
+        # nil when there is no number, preserving the old nil-`code` semantics
+        # the URN generator branches on.
+        def code
+          return nil if number.nil?
+
+          Pubid::Etsi::Components::Code.new(
+            number: number,
+            minor: minor,
+            parts: parts || [],
+          )
+        end
+
+        # MR slug number segment.
+        #
+        # The base hook reads the inherited `number` and `part`; ETSI kept
+        # neither, so before the index columns landed every ETSI slug was just
+        # `etsi.<date>` — 454 distinct slugs for 24,724 documents, and
+        # `to_slug` is what consumers use as an output FILENAME.
+        #
+        # Two things the base hook cannot do for ETSI:
+        #   * the parts live in the `parts` collection, not the inherited
+        #     scalar `part`, so they must be appended here or every part of a
+        #     document collapses onto one slug;
+        #   * an ETSI number legitimately contains a SPACE ("300 175", "GSM
+        #     02.01"), which is outside the [a-z0-9.-] charset Renderers::MrString
+        #     documents and guarantees. Sanitize BY CHARSET rather than by an
+        #     enumerated escape list (the BIPM `mr_slug` precedent in
+        #     CLAUDE.md), so a character added later cannot reach a filename.
+        # `minor` is included because it is identity-bearing everywhere else —
+        # Code#== compares it, Code#to_s renders it and the URN carries it — so
+        # omitting it here would let two distinct documents share one filename.
+        # No fixture populates it today; it is in the grammar, so it is here.
+        def mr_number_with_part
+          return nil if number.nil?
+
+          mr_sanitize([number, minor, *Array(parts)].compact.join("-"))
+        end
+
+        # ETSI's identity is type + code + version + date (see
+        # Pubid::Etsi::Identifier#==), so all four must reach the slug —
+        # CLAUDE.md's rule that an identity-bearing marker has to appear on
+        # every identity surface, not just in `==`. The base hooks find
+        # neither: `mr_type` reads `typed_stage` (ETSI has none) and
+        # `mr_edition` reads `edition.number` (ETSI models the edition as
+        # `version`). Without these, "ETSI EN 300 729 V6.1.1 (2000-04)",
+        # "…V7.1.1 (2000-04)" and "ETSI ETS 300 729 ed.2 (2000-04)" all share
+        # one slug — i.e. one output filename.
+        def mr_type
+          type&.to_s&.downcase
+        end
+
+        def mr_edition
+          mr_sanitize(version&.version)
+        end
+
+        # Segment sanitizer. Renderers::MrString joins SEGMENTS with ".", so a
+        # dot inside one would break that structure — hence "." is replaced
+        # here even though it is inside the renderer's overall charset (the
+        # BIPM `bipm.si-brochure.9e-v3-01.e` precedent in CLAUDE.md). Filtering
+        # by charset rather than by an enumerated escape list keeps a character
+        # introduced later from leaking into a filename.
+        #
+        # Public purely to keep this file's surface flat, next to the
+        # lutaml-invoked converters below — it has no external callers and
+        # would work as well private.
+        #
+        # The emptiness check is on the OUTPUT, not just the input: a value
+        # made entirely of characters outside the charset collapses to "-" and
+        # then to "", and an empty string is truthy in Ruby, so it would reach
+        # Renderers::MrString as a blank segment and produce a double dot in
+        # the joined slug. Unreachable from today's grammar, which only feeds
+        # digit/alnum captures here — but not structurally prevented.
+        def mr_sanitize(value)
+          return nil if value.nil? || value.to_s.empty?
+
+          sanitized = value.to_s.downcase
+            .gsub(/[^a-z0-9-]+/, "-").gsub(/\A-+|-+\z/, "")
+          sanitized.empty? ? nil : sanitized
+        end
+
+        # --- Version flattened to scalar version + is_edition flag ---
+        def version_to_kv(model, doc)
+          emit_kv(doc, "version", model.version&.version)
+        end
+
+        def version_from_kv(model, value)
+          version_for(model).version = value.to_s
+        end
+
+        def edition_to_kv(model, doc)
+          return unless model.version&.is_edition
+
+          doc.add_child(
+            Lutaml::KeyValue::DataModel::Element.new("is_edition", true),
+          )
+        end
+
+        def edition_from_kv(model, value)
+          version_for(model).is_edition = value
+        end
+
+        # --- Date flattened to top-level year/month/day scalars ---
+        def year_to_kv(model, doc)
+          emit_kv(doc, "year", model.date&.year)
+        end
+
+        def month_to_kv(model, doc)
+          emit_kv(doc, "month", model.date&.month)
+        end
+
+        def day_to_kv(model, doc)
+          emit_kv(doc, "day", model.date&.day)
+        end
+
+        def year_from_kv(model, value)
+          date_for(model).year = value.to_s
+        end
+
+        def month_from_kv(model, value)
+          date_for(model).month = value.to_s
+        end
+
+        def day_from_kv(model, value)
+          date_for(model).day = value.to_s
+        end
+
+        def emit_kv(doc, key, value)
+          return if value.nil? || value.to_s.empty?
+
+          doc.add_child(
+            Lutaml::KeyValue::DataModel::Element.new(key, value.to_s),
+          )
+        end
+
+        def version_for(model)
+          model.version ||= Pubid::Etsi::Components::Version.new
+        end
+
+        def date_for(model)
+          model.date ||= Pubid::Components::Date.new
+        end
+      end
+    end
+  end
+end