pubid 1.15.21 → 2.0.0.alpha.10

data/lib/pubid/itu/identifiers/question.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Itu
+    module Identifiers
+      # ITU Question — the study topics assigned to a study group.
+      #
+      # Two printed forms, both modelled by this one class:
+      #
+      #   * numeric (no series):  ITU-R 234-1/7:   ITU-R 237/3:
+      #     number(-part)/study-group, always with a trailing ":".
+      #   * letter-series:        ITU-R P.3/BL/7   ITU-R SM.1/30
+      #     series.number(/BL)?/study-group, optionally bracketed and/or with a
+      #     trailing ":" — e.g. ITU-R S.[4/BL/2]:
+      #
+      # The `/study-group`, the optional "/BL" segment, the surrounding
+      # brackets and the trailing ":" have no home on Components::Code, so they
+      # are carried here and reconstructed exactly by +render_base+.
+      class Question < Identifier
+        include StandardSerialization
+
+        attribute :study_group, :string
+        attribute :has_bl, :boolean, default: -> { false }
+        attribute :bracketed, :boolean, default: -> { false }
+        attribute :has_colon, :boolean, default: -> { false }
+
+        # Extra maps merged on top of the StandardSerialization block. The
+        # booleans emit only when true (false is stripped as the default), and
+        # study_group is a plain scalar.
+        key_value do
+          map "study_group", to: :study_group
+          map "has_bl", to: :has_bl
+          map "bracketed", to: :bracketed
+          map "has_colon", to: :has_colon
+        end
+
+        def render_base(**_opts)
+          result = "#{publisher}-#{sector}"
+          result += series ? " #{series}." : " "
+          result += "[" if bracketed
+          result += code.to_s
+          result += "/BL" if has_bl
+          result += "/#{study_group}"
+          result += "]" if bracketed
+          result += ":" if has_colon
+          result
+        end
+
+        def ==(other)
+          return false unless other.is_a?(Question)
+
+          sector == other.sector &&
+            series == other.series &&
+            code == other.code &&
+            study_group == other.study_group &&
+            has_bl == other.has_bl &&
+            bracketed == other.bracketed &&
+            has_colon == other.has_colon
+        end
+      end
+    end
+  end
+end

data/lib/pubid/itu/identifiers/recommendation.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Itu
+    module Identifiers
+      # ITU Recommendation
+      # Format: ITU-{SECTOR} {SERIES}.{NUMBER}[-PART]
+      # Example: ITU-R V.1234-1
+      class Recommendation < Identifier
+        include StandardSerialization
+        # Type-specific rendering handled by Identifier
+      end
+    end
+  end
+end

data/lib/pubid/itu/identifiers/report.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Itu
+    module Identifiers
+      # ITU Report — a publication series distinct from Recommendations.
+      # Format: Report ITU-{SECTOR} {SERIES}.{NUMBER}[-EDITION]
+      # Example: Report ITU-R BT.2020-1 (2000)
+      #
+      # Reports and Recommendations number INDEPENDENTLY, so the same
+      # series/number/edition is two different documents — "ITU-R BT.2020-1" is
+      # both Report BT.2020-1 (objective quality assessment, 2000) and
+      # Recommendation BT.2020-1 (UHDTV parameter values, 06/2014). ITU
+      # disambiguates them with the leading word, which is therefore part of
+      # the identifier: the marker reaches `to_s`, `to_urn` and `to_mr_string`,
+      # and the class-strict `Identifier#==` keeps the two unequal in both
+      # directions so `#matches?` can never resolve one to the other.
+      #
+      # Everything else is shaped exactly like a Recommendation
+      # (sector/series/code/date/version/language), including the flat
+      # serialization — only `_type` distinguishes the two hashes.
+      class Report < Identifier
+        include StandardSerialization
+
+        def render_base(**_opts)
+          "Report #{super}"
+        end
+
+        # The MR string doubles as an output filename, so the marker has to
+        # reach it too — otherwise a Report and its same-numbered
+        # Recommendation slug identically and one overwrites the other.
+        # "itu.r.report.bt-2020-1"
+        def mr_type
+          [super, "report"].compact.join(".")
+        end
+      end
+    end
+  end
+end

data/lib/pubid/itu/identifiers/special_publication.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Itu
+    module Identifiers
+      # ITU Special Publication — currently models the Operational Bulletin (OB).
+      # OB is a cross-bureau publication (no sector) rendered as
+      # "ITU OB No. {number}" with optional date.
+      #
+      # Pattern: "ITU OB No. 1283 (01/2024)"
+      class SpecialPublication < Identifier
+        include StandardSerialization
+
+        def render_base(**_opts)
+          number = code&.number
+          result = "#{publisher} #{series} No. #{number}"
+
+          if date
+            result += if date.month
+                        " (#{date.month.to_s.rjust(2, '0')}/#{date.year})"
+                      else
+                        " (#{date.year})"
+                      end
+          end
+
+          result
+        end
+      end
+    end
+  end
+end

data/lib/pubid/itu/identifiers/standard_serialization.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Itu
+    module Identifiers
+      # Installs the compact flat `key_value` block shared by the "single
+      # document" leaf types (Recommendation, Handbook, SpecialPublication, and
+      # — extended with their own extra maps — Question and CombinedIdentifier).
+      #
+      # The block lives on the leaves rather than the shared Identifier because
+      # the delegating subtypes (Supplement/Annex) would otherwise inherit-and-
+      # merge it and re-emit their `base`'s fields (the ETSI lesson). The
+      # converter methods it references are defined once on Pubid::Itu::Identifier.
+      module StandardSerialization
+        def self.included(base)
+          base.key_value do
+            map "_type", to: :_type
+            map "sector",
+                with: { to: :sector_to_kv, from: :sector_from_kv }
+            map "series",
+                with: { to: :series_to_kv, from: :series_from_kv }
+            map "imp_marker",
+                with: { to: :imp_marker_to_kv, from: :imp_marker_from_kv }
+            map "number",
+                with: { to: :number_to_kv, from: :number_from_kv }
+            map "series_suffix",
+                with: { to: :series_suffix_to_kv, from: :series_suffix_from_kv }
+            map "series_suffix_spaced",
+                with: { to: :series_suffix_spaced_to_kv,
+                        from: :series_suffix_spaced_from_kv }
+            map "subseries",
+                with: { to: :subseries_to_kv, from: :subseries_from_kv }
+            map "parts",
+                with: { to: :parts_to_kv, from: :parts_from_kv }
+            map "qualifier",
+                with: { to: :qualifier_to_kv, from: :qualifier_from_kv }
+            map "qualifier_glued",
+                with: { to: :qualifier_glued_to_kv,
+                        from: :qualifier_glued_from_kv }
+            map "series_word", to: :series_word
+            map "series_dash", to: :series_dash
+            map "attachment", to: :attachment
+            map "range_end", to: :range_end
+            map "version", to: :version
+            map "year",
+                with: { to: :year_to_kv, from: :year_from_kv }
+            map "month",
+                with: { to: :month_to_kv, from: :month_from_kv }
+            map "language", to: :language
+            map "common_text_twin",
+                with: { to: :common_text_twin_to_kv,
+                        from: :common_text_twin_from_kv }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pubid/itu/identifiers/supplement.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Itu
+    module Identifiers
+      # Supplement identifier (Suppl.)
+      # Pattern: "ITU-T H Suppl. 1", "ITU-T E.156 Suppl. 2"
+      class Supplement < Identifier
+        attribute :base, Identifier, polymorphic: true
+        attribute :number, :string
+
+        # Rendering-only flags for spellings ITU itself uses. Both name the
+        # RARE form so the `false` default is stripped from `to_hash` and no
+        # existing serialized row gains a key.
+        #
+        # `number_glued` — no space before the ordinal ("ITU-T E Suppl.1",
+        # "ITU-T D.211 Suppl.1"). Deliberately NOT part of `==`: "Suppl.1" and
+        # "Suppl. 1" are the same document.
+        #
+        # `slash_joined` — joined to the preceding supplement by "/" instead of
+        # a space ("ITU-T X.680 (1994) Amd. 1/Technical Cor. 1 (12/1997)").
+        attribute :number_glued, :boolean, default: -> { false }
+        attribute :slash_joined, :boolean, default: -> { false }
+
+        # Compact serialization: a supplement carries only its own ordinal
+        # `number`, its own date, and the nested (itself-flat) `base`. type/code
+        # are delegated to `base` and NOT re-emitted. sector/series are emitted
+        # ONLY for the base-less, series-only form ("ITU-T H Suppl. 1"); when a
+        # base is present they are redundant copies of the base's and are
+        # suppressed. Inherited by Amendment / Corrigendum / Errata / Addendum,
+        # of which only Corrigendum adds a key of its own.
+        key_value do
+          map "_type", to: :_type
+          map "sector",
+              with: { to: :supplement_sector_to_kv, from: :sector_from_kv }
+          map "series",
+              with: { to: :supplement_series_to_kv, from: :series_from_kv }
+          map "series_word",
+              with: { to: :supplement_series_word_to_kv,
+                      from: :series_word_from_kv }
+          map "number", to: :number
+          map "number_glued", to: :number_glued
+          map "slash_joined", to: :slash_joined
+          map "year", with: { to: :year_to_kv, from: :year_from_kv }
+          map "month", with: { to: :month_to_kv, from: :month_from_kv }
+          map "base", with: { to: :base_to_kv, from: :base_from_kv }
+          map "common_text_twin",
+              with: { to: :common_text_twin_to_kv,
+                      from: :common_text_twin_from_kv }
+        end
+
+        def supplement_sector_to_kv(model, doc)
+          return unless model.base.nil?
+
+          emit_kv(doc, "sector", model.sector&.sector)
+        end
+
+        def supplement_series_to_kv(model, doc)
+          return unless model.base.nil?
+
+          emit_kv(doc, "series", model.series&.series)
+        end
+
+        # Like sector/series above: the series group's "series" word is part of
+        # the base-less form's identity only. With a base it belongs to (and is
+        # serialized by) the base.
+        def supplement_series_word_to_kv(model, doc)
+          return unless model.base.nil?
+          return unless model.series_word
+
+          doc["series_word"] = true
+        end
+
+        def series_word_from_kv(model, value)
+          model.series_word = value
+        end
+
+        # A supplement carries no `mr_supplement_suffix`, so the shared MR
+        # renderer slugs it FLAT, from the sector/series/code Builder#build_
+        # supplement copied up from its base — which never consults the base's
+        # class. Without this, the supplement of a Report and the supplement of
+        # the same-numbered Recommendation produce one slug (and `to_slug` is an
+        # output filename, so one overwrites the other) — exactly the collision
+        # this type exists to prevent. `root` walks through an intervening annex
+        # or appendix, so a supplement of an annex of a Report is covered too.
+        def mr_type
+          type = super
+          return type unless root.is_a?(Report)
+
+          [type, "report"].compact.join(".")
+        end
+
+        # Shared by every supplement type — Suppl./Amd./Cor./Err./Add. differ
+        # only in the label, so each subclass supplies its own and nothing else.
+        #
+        # `label` is the canonical spelling with its period; the parser also
+        # accepts the period-less input (see Parser#supplement_type), which
+        # normalizes here.
+        def render_supplement(label)
+          result = base ? base.to_s : "#{publisher}-#{sector}"
+
+          # Add series if no base
+          if !base && series
+            result += " #{series}"
+            result += " series" if series_word
+          end
+
+          result += slash_joined ? "/" : " "
+          result += label
+          result += " " unless number_glued
+          result += number.to_s
+
+          result += render_date_suffix
+
+          result
+        end
+
+        def to_s(**opts)
+          annotate_plain_render(render_supplement("Suppl."), **opts)
+        end
+
+        # Shared by Amendment / Corrigendum / Errata.
+        #
+        # `instance_of?` (not `is_a?`) so a Suppl. never equals an Amd./Cor./
+        # Err. with the same ordinal, and so the comparison stays symmetric —
+        # with `is_a?` a Supplement accepted an Amendment but not the reverse.
+        #
+        # sector/series are compared ONLY for the base-less, series-only form
+        # ("ITU-T A Suppl. 2"), where they are the document's whole identity.
+        # When a base is present they are copies of the base's (set by
+        # Builder#build_supplement) and are deliberately not serialized (see
+        # supplement_sector_to_kv), so comparing them would make a parsed
+        # identifier unequal to the same identifier rebuilt via from_hash.
+        def ==(other)
+          return false unless other.instance_of?(self.class)
+
+          return false unless base == other.base &&
+            number == other.number &&
+            date == other.date
+
+          return true if base
+
+          sector == other.sector && series == other.series &&
+            series_word == other.series_word
+        end
+      end
+    end
+  end
+end

data/lib/pubid/itu/identifiers.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Itu
+    module Identifiers
+      autoload :Addendum, "#{__dir__}/identifiers/addendum"
+      autoload :Amendment, "#{__dir__}/identifiers/amendment"
+      autoload :Annex, "#{__dir__}/identifiers/annex"
+      autoload :AnnexOfRecommendation,
+               "#{__dir__}/identifiers/annex_of_recommendation"
+      autoload :AppendixOfRecommendation,
+               "#{__dir__}/identifiers/appendix_of_recommendation"
+      autoload :CombinedIdentifier, "#{__dir__}/identifiers/combined_identifier"
+      autoload :Corrigendum, "#{__dir__}/identifiers/corrigendum"
+      autoload :Errata, "#{__dir__}/identifiers/errata"
+      autoload :Handbook, "#{__dir__}/identifiers/handbook"
+      autoload :Question, "#{__dir__}/identifiers/question"
+      autoload :Recommendation, "#{__dir__}/identifiers/recommendation"
+      autoload :Report, "#{__dir__}/identifiers/report"
+      autoload :SpecialPublication, "#{__dir__}/identifiers/special_publication"
+      autoload :StandardSerialization, "#{__dir__}/identifiers/standard_serialization"
+      autoload :Supplement, "#{__dir__}/identifiers/supplement"
+    end
+  end
+end

data/lib/pubid/itu/model.rb

@@ -0,0 +1,111 @@
+require "lutaml/model"
+# frozen_string_literal: true
+
+module Pubid
+  module Itu
+    class Model < Lutaml::Model::Serializable
+      attribute :sector, :string
+      attribute :series, :string
+      attribute :number, :string
+      attribute :subseries, :string
+      attribute :part, :string
+      attribute :supplement, :string
+      attribute :amendment, :string
+      attribute :annex, :string
+      attribute :corrigendum, :string
+      attribute :addendum, :string
+      attribute :appendix, :string
+      attribute :month, :string
+      attribute :year, :string
+      attribute :second_number, :string
+      attribute :range, :string
+      attribute :sg_number, :string
+
+      def to_s
+        parts = []
+
+        # Add publisher and sector
+        parts << "ITU-#{sector}" if sector
+
+        # Add series (handle special cases)
+        if series == "OB"
+          # Operational Bulletin
+          parts << "#{series} No. #{number}"
+        elsif series&.start_with?("SG")
+          # Study Group Question
+          parts << "#{series}.#{number}"
+          parts[-1] << "-#{part}" if part
+        elsif series == "R" && !number
+          # Resolution without number
+          parts << "R.#{number}"
+          parts[-1] << "-#{part}" if part
+        elsif series
+          # Regular series
+          series_str = series.to_s
+          if number
+            series_str << ".#{number}"
+            series_str << ".#{subseries}" if subseries
+            series_str << "-#{part}" if part
+          end
+          parts << series_str
+
+          # Add second number for combined standards
+          if second_number.is_a?(Hash)
+            second_str = "/#{second_number[:series]}.#{second_number[:number]}"
+            second_str << ".#{second_number[:subseries]}" if second_number[:subseries]
+            second_str << "-#{second_number[:part]}" if second_number[:part]
+            parts[-1] << second_str
+          end
+
+          # Add range notation
+          if range.is_a?(Hash)
+            parts[-1] << "-#{range[:series]}.#{range[:number]}"
+          end
+        elsif number && !series
+          # Handbook or similar (just number)
+          parts << number
+          parts[-1] << "-#{part}" if part
+        end
+
+        # Add supplement
+        if supplement
+          parts << "Suppl. #{supplement}"
+        end
+
+        # Add annex
+        if annex
+          parts << "Annex #{annex}"
+        end
+
+        # Add date
+        if month && year
+          parts << "(#{month.rjust(2, '0')}/#{year})"
+        elsif year
+          parts << "(#{year})"
+        end
+
+        # Add amendment
+        if amendment
+          parts << "Amd. #{amendment}"
+        end
+
+        # Add corrigendum
+        if corrigendum
+          parts << "Cor. #{corrigendum}"
+        end
+
+        # Add addendum
+        if addendum
+          parts << "Add. #{addendum}"
+        end
+
+        # Add appendix
+        if appendix
+          parts << "App. #{appendix}"
+        end
+
+        parts.join(" ")
+      end
+    end
+  end
+end