pubid 2.0.0.pre.alpha.7 → 2.0.0.pre.alpha.9

data/lib/pubid/itu/builder.rb

@@ -13,15 +13,59 @@ module Pubid
           return build_annex(data[:annex_to])
         end
 
+        # Common-text twin ("| ISO/IEC ..." suffix) — extract before building
+        # the base ITU identifier, then attach to whichever class the base
+        # resolves to.
+        twin = parse_common_text_twin(data.delete(:common_text_twin))
+
+        # Labelled annex of a Recommendation — "ITU-T A.23 Annex A (06/2014)".
+        # The annexed document is the :base subtree; :year/:month at this level
+        # are the annex's own date, not the base's.
+        if data[:annex_number]
+          annex = build_annex_of_recommendation(data)
+          annex.common_text_twin = twin if twin
+          return annex
+        end
+
+        # Labelled appendix of a Recommendation — "ITU-T G.101 App. I
+        # (05/2000)". Same shape as the annex above.
+        if data[:appendix_number]
+          appendix = build_appendix_of_recommendation(data)
+          appendix.common_text_twin = twin if twin
+          return appendix
+        end
+
         # Operational Bulletin (Special Publication) — series == "OB" or
         # legacy long form ("Operational Bulletin No. ...").
-        if data[:series].to_s == "OB" || data[:_op_bull]
-          return build_special_publication(data)
+        # The series_dash guard keeps a series-code "ITU-T OB-1" out of this
+        # branch, which would drop the dash and render it "ITU OB No. 1".
+        # Belt-and-braces: `series_code_body` already refuses "OB" + dash, so
+        # nothing reaches here with both set — the guard documents that coupling
+        # so removing the parser's `absent?` fails loudly rather than silently
+        # rerouting.
+        if (data[:series].to_s == "OB" && data[:series_dash].nil?) ||
+            data[:_op_bull]
+          sp = build_special_publication(data)
+          sp.common_text_twin = twin if twin && sp
+          return sp
         end
 
         # Check if this is a supplement identifier
         if data[:supplement_type]
-          return build_supplement(data)
+          supp = build_supplement(data)
+          supp.common_text_twin = twin if twin && supp
+          return supp
+        end
+
+        # Handbook — "ITU-R 42.HDB"
+        if data[:handbook_marker]
+          return build_handbook(data)
+        end
+
+        # Question — numeric ("ITU-R 234-1/7:") or letter-series
+        # ("ITU-R P.3/BL/7"). Both carry a :study_group marker.
+        if data[:study_group]
+          return build_question(data)
         end
 
         # Build basic recommendation or combined identifier
@@ -30,44 +74,77 @@ module Pubid
         code = build_code(data) if data[:number]
         date = build_date(data) if data[:year]
 
-        # Check if this is a combined identifier (has combined_series and combined_number)
-        if data[:combined_series] || data[:combined_number]
-          if data[:combined_series]
-            combined_series = Components::Series.new(
-              series: data[:combined_series][:series].to_s,
-            )
-          end
-
-          if data[:combined_number]
-            combined_code = Components::Code.new(
-              number: data[:combined_number].to_s,
-              subseries: data[:combined_subseries]&.to_s,
-              parts: extract_parts(data[:combined_parts]),
-            )
-          end
-
+        # Combined (joint) recommendation — one or more additional
+        # "/SERIES.CODE" designations after the primary (e.g. "G.780/Y.1351",
+        # "G.780/Y.1351/Z.1362"). The primary stays on the base series/code.
+        if data[:combined]
           return Identifiers::CombinedIdentifier.new(
             sector: sector,
             series: series,
             code: code,
-            combined_series: combined_series,
-            combined_code: combined_code,
+            combined: build_designations(data[:combined]),
             date: date,
+            version: data[:version]&.to_s,
+            # with_series offers these slots on either side of
+            # combined_suffixes, so a joint id can carry them too; not
+            # forwarding them let "ITU-T H.350/X.1 attachment" compare equal to
+            # the un-attached document.
+            series_word: !data[:series_word].nil?,
+            series_dash: !data[:series_dash].nil?,
+            attachment: !data[:attachment].nil?,
+            range_end: data[:range_end]&.to_s,
             language: data[:language]&.to_s,
+            common_text_twin: twin,
           )
         end
 
-        Identifiers::Recommendation.new(
+        # A Report ("Report ITU-R BT.2020-1") is shaped exactly like a
+        # Recommendation — only the leading word, captured as :report_marker,
+        # tells the two apart, and it has to, because the two series number
+        # independently and the same series/number is two real documents.
+        klass = data[:report_marker] ? Identifiers::Report : Identifiers::Recommendation
+
+        klass.new(
           sector: sector,
           series: series,
           code: code,
           date: date,
+          version: data[:version]&.to_s,
+          series_word: !data[:series_word].nil?,
+          series_dash: !data[:series_dash].nil?,
+          attachment: !data[:attachment].nil?,
+          range_end: data[:range_end]&.to_s,
           language: data[:language]&.to_s,
+          common_text_twin: twin,
         )
       end
 
+      # Parse the common-text twin string ("| ISO/IEC 13818-1:2022") into
+      # the appropriate flavor's identifier object. Returns nil if the twin
+      # is empty or unparseable.
+      def parse_common_text_twin(twin_raw)
+        return nil if twin_raw.nil?
+
+        twin_str = twin_raw.to_s.strip
+        # Strip a leading pipe if the parser captured it
+        twin_str = twin_str.sub(/\A\s*\|\s*/, "")
+        return nil if twin_str.empty?
+
+        case twin_str
+        when /\AISO\/IEC\b/, /\AISO\b/
+          Pubid::Iso.parse(twin_str)
+        when /\AIEC\b/
+          Pubid::Iec.parse(twin_str)
+        end
+      rescue StandardError
+        # If the twin doesn't parse as a known flavor, leave it as nil
+        # rather than blowing up the whole parse — the ITU half is still
+        # usable on its own.
+        nil
+      end
+
       # Build Special Publication (OB). Sector is silently dropped — OB is a
-      # cross-bureau publication and `Identifiers::Base` rejects sector+OB
+      # cross-bureau publication and `Identifier` rejects sector+OB
       # in its constructor.
       def build_special_publication(data)
         Identifiers::SpecialPublication.new(
@@ -88,6 +165,59 @@ module Pubid
         )
       end
 
+      # Build a labelled annex of a Recommendation. sector/series/code are
+      # deliberately NOT copied from the base: they are not serialized on the
+      # wrapper, so copies would make a from_hash-rebuilt annex differ from the
+      # parsed one.
+      def build_annex_of_recommendation(data)
+        Identifiers::AnnexOfRecommendation.new(
+          base: build(data[:base]),
+          number: data[:annex_number].to_s,
+          date: data[:year] ? build_date(data) : nil,
+          language: data[:language]&.to_s,
+        )
+      end
+
+      # Build a labelled appendix of a Recommendation. Like the annex above,
+      # sector/series/code are deliberately NOT copied from the base — they are
+      # not serialized on the wrapper, so copies would make a from_hash-rebuilt
+      # appendix differ from the parsed one.
+      def build_appendix_of_recommendation(data)
+        Identifiers::AppendixOfRecommendation.new(
+          base: build(data[:base]),
+          number: data[:appendix_number].to_s,
+          material: data[:appendix_material]&.to_s,
+          date: data[:year] ? build_date(data) : nil,
+          language: data[:language]&.to_s,
+        )
+      end
+
+      # Build Handbook ("ITU-R 42.HDB").
+      def build_handbook(data)
+        Identifiers::Handbook.new(
+          sector: Components::Sector.new(sector: data[:sector].to_s),
+          code: build_code(data),
+          date: data[:year] ? build_date(data) : nil,
+        )
+      end
+
+      # Build Question (numeric or letter-series).
+      def build_question(data)
+        series = if data[:series]
+                   Components::Series.new(series: data[:series].to_s)
+                 end
+
+        Identifiers::Question.new(
+          sector: Components::Sector.new(sector: data[:sector].to_s),
+          series: series,
+          code: build_code(data),
+          study_group: data[:study_group].to_s,
+          has_bl: !data[:has_bl].nil?,
+          bracketed: !data[:bracketed].nil?,
+          has_colon: !data[:question_colon].nil?,
+        )
+      end
+
       def build_supplement(data)
         # Build the base identifier first
         base = build(data[:base]) if data[:base]
@@ -97,10 +227,22 @@ module Pubid
         klass = case supplement_type
                 when "Amd"
                   Identifiers::Amendment
+                when "Add"
+                  Identifiers::Addendum
                 when "Cor"
                   Identifiers::Corrigendum
+                when "Err"
+                  Identifiers::Errata
                 when "Suppl"
                   Identifiers::Supplement
+                else
+                  # Previously fell through to a nil class and died with
+                  # "undefined method 'new' for nil" one frame later. Any token
+                  # added to Parser#supplement_type without a class here should
+                  # say so.
+                  raise ArgumentError,
+                        "Unknown ITU supplement type: " \
+                        "#{data[:supplement_type].inspect}"
                 end
 
         # Build supplement date (separate from base date)
@@ -111,25 +253,84 @@ module Pubid
                             )
                           end
 
-        # Build supplement with extracted components
-        klass.new(
-          sector: base&.sector || Components::Sector.new(sector: data[:sector].to_s),
-          series: base&.series || (data[:series] ? Components::Series.new(series: data[:series].to_s) : nil),
-          code: base&.code,
+        # Sector/series are copied from the base when it has them; the fallback
+        # to this level's own tokens is guarded because an annex base keeps
+        # sector/series/code on *its* base, leaving all three nil here while the
+        # supplement level carries no sector token of its own.
+        # An annex base keeps sector/series/code on *its* base, so reach through
+        # it via #root; otherwise a supplement of an annex would carry none of
+        # them and its MR string would collapse to a bare "itu.<date>".
+        base_identity = base&.sector ? base : base&.root
+        sector = base_identity&.sector ||
+          (Components::Sector.new(sector: data[:sector].to_s) if data[:sector])
+        series = base_identity&.series ||
+          (Components::Series.new(series: data[:series].to_s) if data[:series])
+
+        attrs = {
+          sector: sector,
+          series: series,
+          code: base_identity&.code,
           base: base,
           number: data[:supplement_number].to_s,
+          # The marker is the captured space, so its ABSENCE is the flag.
+          number_glued: data[:supplement_space].nil?,
+          slash_joined: !data[:supplement_slash].nil?,
           date: supplement_date,
           language: data[:language]&.to_s,
-        )
+        }
+        # The "series" word rides on the supplement for the base-less,
+        # series-only form; with a base it is the base's, and renders from
+        # there. It is copied up anyway (like sector/series/code above) so the
+        # supplement's own MR slug stays distinct — `render_supplement` and the
+        # base-nil-guarded key_value/== only consult it when base is nil, so
+        # the copy is render- and serialization-neutral.
+        attrs[:series_word] = if base
+                                !!base_identity&.series_word
+                              else
+                                !data[:series_word].nil?
+                              end
+        attrs[:technical] = true if data[:technical] &&
+          klass == Identifiers::Corrigendum
+
+        klass.new(**attrs)
       end
 
       private
 
+      # Build the additional designations of a combined recommendation from the
+      # repeated parse subtrees (each `{ designation: { series:, number:, … } }`).
+      def build_designations(combined_data)
+        Array(combined_data).map do |element|
+          d = element[:designation] || element
+          Components::Designation.new(
+            series: Components::Series.new(series: d[:series].to_s),
+            code: Components::Code.new(
+              number: d[:number].to_s,
+              series_suffix: d[:series_suffix]&.to_s,
+              series_suffix_spaced: !d[:series_suffix_spaced].nil?,
+              subseries: d[:subseries]&.to_s,
+              parts: extract_parts(d[:parts]),
+              qualifier: d[:qualifier]&.to_s,
+              qualifier_glued: !d[:qualifier].nil? && d[:qualifier_spaced].nil?,
+            ),
+          )
+        end
+      end
+
       def build_code(data)
         Components::Code.new(
+          imp_marker: data[:imp_marker]&.to_s,
           number: data[:number].to_s,
+          series_suffix: data[:series_suffix]&.to_s,
+          # The marker is the captured separating space, so its presence is
+          # the flag for the edition word and its ABSENCE is the flag for the
+          # qualifier letter (whose majority spelling is spaced).
+          series_suffix_spaced: !data[:series_suffix_spaced].nil?,
           subseries: data[:subseries]&.to_s,
           parts: extract_parts(data[:parts]),
+          qualifier: data[:qualifier]&.to_s,
+          qualifier_glued: !data[:qualifier].nil? &&
+            data[:qualifier_spaced].nil?,
         )
       end
 

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

@@ -6,24 +6,64 @@ module Pubid
   module Itu
     module Components
       # ITU Code component
-      # Format: NUMBER[.SUBSERIES][-PART]
-      # Examples: 1234, 1234.5, 1234-1, 1234.5-2
+      # Format: [Imp]NUMBER[SUFFIX][.SUBSERIES][-PART]
+      # Examples: 1234, 1234.5, 1234-1, 1234.5-2, 50bis, 8bis, Imp712, ImpOSI
+      #
+      # The optional "Imp" marker identifies an Implementers' Guide for the
+      # series (e.g. G.Imp712, X.ImpOSI); the NUMBER that follows may be
+      # digits or a short letter string.
+      #
+      # SUFFIX is the edition marker "bis" / "ter" / "quater" attached
+      # directly to the number (e.g. X.50bis, V.8bis).
       #
       # Stays independent of Pubid::Components::Code because ITU uses
       # +subseries+ (dot-separated, flavor-specific) and +parts+
       # (dash-separated).
       class Code < Lutaml::Model::Serializable
+        attribute :imp_marker, :string
         attribute :number, :string
+        attribute :series_suffix, :string
+        # ITU prints the edition word both glued ("X.50bis") and space-
+        # separated ("E.250 bis"). The word itself is stored without the space,
+        # so `series_suffix` stays a clean, whitespace-free value to compare and
+        # index on; the spacing is this rendering-only flag. Named for the
+        # rarer-in-code form so the `false` default stays out of `to_hash`.
+        attribute :series_suffix_spaced, :boolean, default: -> { false }
         attribute :subseries, :string
         attribute :parts, :string, collection: true, default: []
+        # A single trailing letter distinguishing variants of one
+        # Recommendation: "D.200 R" (old D-series tariff recommendations),
+        # "Q.2931 B", "R.38 A", the glued "D.502R" and the lowercase
+        # "I.256.2a". Spaced is the majority spelling, so the glued one is the
+        # flag.
+        attribute :qualifier, :string
+        attribute :qualifier_glued, :boolean, default: -> { false }
 
+        # Segment order mirrors the grammar exactly — a GLUED suffix is
+        # captured inside `standard_code` (the edition word before the
+        # subseries, the qualifier after the parts), while a SPACED one is
+        # captured afterwards by `code_suffixes`. Rendering the edition word
+        # unconditionally first would print "Q.11a bis" back as "Q.11 bisa".
         def to_s
-          result = number.to_s
+          result = "#{imp_marker}#{number}"
+          result += series_suffix.to_s if series_suffix && !series_suffix_spaced
           result += ".#{subseries}" if subseries
           result += parts.map { |p| "-#{p}" }.join if parts&.any?
+          result += qualifier.to_s if qualifier && qualifier_glued
+          result += " #{series_suffix}" if series_suffix && series_suffix_spaced
+          result += " #{qualifier}" if qualifier && !qualifier_glued
           result
         end
 
+        # Space-free rendering for URN and MR use: the print form may separate
+        # the edition word or the qualifier letter with a space ("E.250 bis",
+        # "D.200 R"), which is not admissible inside a URN segment. Removing
+        # the space keeps "D.200" and "D.200 R" on distinct URNs, which
+        # dropping the suffix would not.
+        def compact_s
+          to_s.delete(" ")
+        end
+
         def render(context: nil)
           to_s
         end
@@ -31,9 +71,12 @@ module Pubid
         def ==(other)
           return false unless other.is_a?(Code)
 
-          number == other.number &&
+          imp_marker == other.imp_marker &&
+            number == other.number &&
+            series_suffix == other.series_suffix &&
             subseries == other.subseries &&
-            parts == other.parts
+            parts == other.parts &&
+            qualifier == other.qualifier
         end
       end
     end

data/lib/pubid/itu/components/designation.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Pubid
+  module Itu
+    module Components
+      # One series+number designation of a combined (joint) recommendation.
+      # A combined recommendation such as "ITU-T G.780/Y.1351" keeps its primary
+      # designation on the base identifier (series "G", code "780") and carries
+      # each *additional* designation ("Y.1351", and any further "/Z.1362" …) as
+      # a Designation in Identifiers::CombinedIdentifier#combined.
+      #
+      # Format: SERIES.CODE  (e.g. "Y.1351", "Y.1362-2")
+      class Designation < Lutaml::Model::Serializable
+        attribute :series, Pubid::Itu::Components::Series
+        attribute :code, Pubid::Itu::Components::Code
+
+        def to_s
+          "#{series}.#{code}"
+        end
+
+        def render(context: nil)
+          to_s
+        end
+
+        def ==(other)
+          return false unless other.is_a?(Designation)
+
+          series == other.series && code == other.code
+        end
+      end
+    end
+  end
+end

data/lib/pubid/itu/components.rb

@@ -6,6 +6,7 @@ module Pubid
       autoload :Sector, "#{__dir__}/components/sector"
       autoload :Series, "#{__dir__}/components/series"
       autoload :Code, "#{__dir__}/components/code"
+      autoload :Designation, "#{__dir__}/components/designation"
     end
   end
 end

data/lib/pubid/itu/identifier.rb

@@ -1,6 +1,4 @@
 # frozen_string_literal: true
 
 # Pubid::Itu::Identifier is the ITU base class (a real Pubid::Identifier
-# subclass); its body, `.parse`, and the Identifiers::Base back-compat alias
-# live in identifiers/base.rb. This file just ensures it is loaded.
-require_relative "identifiers/base"
+# subclass); its body and `.parse` live in identifiers/base.rb. This file just ensures it is loaded.

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Itu
+    module Identifiers
+      # Addendum identifier (Add.)
+      # Pattern: "ITU-T I.363 (1993) Add. 1 (11/1993)"
+      class Addendum < Supplement
+        def to_s
+          render_supplement("Add.")
+        end
+      end
+    end
+  end
+end

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

@@ -4,36 +4,14 @@ module Pubid
   module Itu
     module Identifiers
       # Amendment identifier (Amd)
-      # Pattern: "ITU-T G.989 Amd 1", "ITU-T G.780/Y.1351 Amd 1 (2004)"
+      # Pattern: "ITU-T G.989 Amd. 1", "ITU-T G.780/Y.1351 Amd. 1 (2004)"
       class Amendment < Supplement
+        # "Amd." with the period, matching ITU's own rendering and the sibling
+        # supplement types (Cor./Err./Suppl./Add.). The parser accepts both
+        # spellings (see Parser#supplement_type), so the period-less input form
+        # still round-trips through parse — it just normalizes here.
         def to_s
-          result = base ? base.to_s : "#{publisher}-#{sector}"
-
-          # Add series if no base
-          if !base && series
-            result += " #{series}"
-          end
-
-          result += " Amd #{number}"
-
-          # Add date if present
-          if date
-            result += if date.month
-                        " (#{date.month}/#{date.year})"
-                      else
-                        " (#{date.year})"
-                      end
-          end
-
-          result
-        end
-
-        def ==(other)
-          return false unless other.is_a?(Amendment)
-
-          base == other.base &&
-            number == other.number &&
-            date == other.date
+          render_supplement("Amd.")
         end
       end
     end

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

@@ -12,8 +12,19 @@ module Pubid
       #   * long with i18n_lang + format: :long: per-language `annex_long` template
       # Languages without an `annex_to` entry (fr/es/ru/zh) use the long
       # template for the short form too.
-      class Annex < Base
-        attribute :base, Base, polymorphic: true
+      class Annex < Identifier
+        attribute :base, Identifier, polymorphic: true
+
+        # Compact serialization: an Annex is just the nested (itself-flat) base
+        # plus its own language; everything else is delegated to `base`.
+        key_value do
+          map "_type", to: :_type
+          map "base", with: { to: :base_to_kv, from: :base_from_kv }
+          map "language", to: :language
+          map "common_text_twin",
+              with: { to: :common_text_twin_to_kv,
+                      from: :common_text_twin_from_kv }
+        end
 
         def to_urn
           # Annex URN: append :annex to the inner identifier's URN.

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Itu
+    module Identifiers
+      # A labelled annex of a Recommendation — "ITU-T A.23 Annex A (06/2014)",
+      # "ITU-T Z.100 Annex F3 (10/2019)", "ITU-T G.729 Annex C+ (02/2000)".
+      #
+      # The annex is a document in its own right: it is published (and dated)
+      # separately from the Recommendation it annexes, and may itself carry a
+      # corrigendum/errata/amendment ("ITU-T G.729 Annex B (1996) Cor. 3
+      # (03/2001)").
+      #
+      # Distinct from Identifiers::Annex, which models the label-less
+      # "Annex to ITU OB No. 1000" form (a prefix rendering with its own i18n
+      # templates). Keeping them apart keeps each `_type` — already persisted in
+      # relaton index rows — unambiguous.
+      class AnnexOfRecommendation < Identifier
+        attribute :base, Identifier, polymorphic: true
+        # The annex label ("A", "F3", "C+"). Named `number` for symmetry with
+        # Supplement's ordinal; it shadows Identifier#number (code&.number),
+        # which is nil here anyway — the document number is reached via #root.
+        attribute :number, :string
+
+        # Compact serialization: the annex is the nested (itself-flat) base plus
+        # its own label, date and language. sector/series/code are the base's
+        # and are deliberately not re-emitted (the wrapper lesson).
+        key_value do
+          map "_type", to: :_type
+          map "number", to: :number
+          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 "language", to: :language
+          map "common_text_twin",
+              with: { to: :common_text_twin_to_kv,
+                      from: :common_text_twin_from_kv }
+        end
+
+        # "<base urn>:annex:<label>[:<date>]" — the annex's own date must be
+        # there, or two editions of one annex share a URN (the base's date
+        # rides inside base_urn, so omitting the annex's would be asymmetric).
+        def to_urn
+          segments = [base&.to_urn || "urn:itu", "annex", number&.downcase]
+          segments << urn_date_segment
+          segments.compact.join(":")
+        end
+
+        def render_base(**opts)
+          result = base ? base.render_base(**opts) : "#{publisher}-#{sector}"
+
+          "#{result} Annex #{number}#{render_date_suffix}"
+        end
+
+        # MR: recurse into the annexed document and append "annex.<label>[.year]"
+        # (the documented supplement-suffix hook), so the slug stays distinct
+        # per annex. Without it the wrapper's own nil sector/series/code would
+        # collapse every annex onto a bare "itu.<year>".
+        def mr_supplement_suffix
+          # "C+" -> "cplus", not "c" — the MR charset excludes "+", and
+          # dropping it would collide with the sibling "Annex C".
+          label = number.to_s.downcase.gsub("+", "plus").gsub(/[^a-z0-9]/, "")
+
+          ["annex", label.empty? ? nil : label, date&.year].compact.join(".")
+        end
+
+        def ==(other)
+          return false unless other.instance_of?(self.class)
+
+          base == other.base &&
+            number == other.number &&
+            date == other.date &&
+            language == other.language &&
+            common_text_twin == other.common_text_twin
+        end
+
+        private
+
+        def urn_date_segment
+          return nil unless date
+
+          date.month ? "#{date.month}/#{date.year}" : date.year.to_s
+        end
+      end
+    end
+  end
+end