pubid 1.15.17 → 2.0.0.pre.alpha.1

data/lib/pubid/itu/builder.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require_relative "../components/date"
+require_relative "components/sector"
+require_relative "components/series"
+require_relative "components/code"
+require_relative "identifiers/recommendation"
+require_relative "identifiers/combined_identifier"
+require_relative "identifiers/supplement"
+require_relative "identifiers/amendment"
+require_relative "identifiers/corrigendum"
+require_relative "identifiers/special_publication"
+require_relative "identifiers/annex"
+
+module Pubid
+  module Itu
+    class Builder
+      def self.build(parsed_data)
+        new.build(parsed_data)
+      end
+
+      def build(data)
+        # "Annex to ..." identifier — wraps a Special Publication base
+        if data[:annex_to]
+          return build_annex(data[:annex_to])
+        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)
+        end
+
+        # Check if this is a supplement identifier
+        if data[:supplement_type]
+          return build_supplement(data)
+        end
+
+        # Build basic recommendation or combined identifier
+        sector = Components::Sector.new(sector: data[:sector].to_s)
+        series = Components::Series.new(series: data[:series].to_s) if data[:series]
+        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
+
+          return Identifiers::CombinedIdentifier.new(
+            sector: sector,
+            series: series,
+            code: code,
+            combined_series: combined_series,
+            combined_code: combined_code,
+            date: date,
+            language: data[:language]&.to_s,
+          )
+        end
+
+        Identifiers::Recommendation.new(
+          sector: sector,
+          series: series,
+          code: code,
+          date: date,
+          language: data[:language]&.to_s,
+        )
+      end
+
+      # Build Special Publication (OB). Sector is silently dropped — OB is a
+      # cross-bureau publication and `Identifiers::Base` rejects sector+OB
+      # in its constructor.
+      def build_special_publication(data)
+        Identifiers::SpecialPublication.new(
+          series: Components::Series.new(series: "OB"),
+          code: data[:number] ? build_code(data) : nil,
+          date: data[:year] ? build_date(data) : nil,
+          language: data[:language]&.to_s,
+        )
+      end
+
+      # Build "Annex to ..." identifier. The inner data is the Special
+      # Publication; the annex inherits its language.
+      def build_annex(inner_data)
+        base = build_special_publication(inner_data)
+        Identifiers::Annex.new(
+          base: base,
+          language: inner_data[:language]&.to_s,
+        )
+      end
+
+      def build_supplement(data)
+        # Build the base identifier first
+        base = build(data[:base]) if data[:base]
+
+        # Determine supplement type
+        supplement_type = data[:supplement_type].to_s.gsub(".", "")
+        klass = case supplement_type
+                when "Amd"
+                  Identifiers::Amendment
+                when "Cor"
+                  Identifiers::Corrigendum
+                when "Suppl"
+                  Identifiers::Supplement
+                end
+
+        # Build supplement date (separate from base date)
+        supplement_date = if data[:supplement_year]
+                            Pubid::Components::Date.new(
+                              year: data[:supplement_year].to_s,
+                              month: data[:supplement_month]&.to_s,
+                            )
+                          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,
+          base: base,
+          number: data[:supplement_number].to_s,
+          date: supplement_date,
+          language: data[:language]&.to_s,
+        )
+      end
+
+      private
+
+      def build_code(data)
+        Components::Code.new(
+          number: data[:number].to_s,
+          subseries: data[:subseries]&.to_s,
+          parts: extract_parts(data[:parts]),
+        )
+      end
+
+      def build_date(data)
+        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/itu/components/code.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Pubid
+  module Itu
+    module Components
+      # ITU Code component
+      # Format: NUMBER[.SUBSERIES][-PART]
+      # Examples: 1234, 1234.5, 1234-1, 1234.5-2
+      class Code < Lutaml::Model::Serializable
+        attribute :number, :string
+        attribute :subseries, :string
+        attribute :parts, :string, collection: true
+
+        def initialize(number:, subseries: nil, parts: nil)
+          @number = number
+          @subseries = subseries
+          @parts = parts || []
+        end
+
+        def to_s
+          result = number.to_s
+          result += ".#{subseries}" if subseries
+          result += parts.map { |p| "-#{p}" }.join if parts&.any?
+          result
+        end
+
+        def ==(other)
+          return false unless other.is_a?(Code)
+
+          number == other.number &&
+            subseries == other.subseries &&
+            parts == other.parts
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Pubid
+  module Itu
+    module Components
+      # ITU Sector component
+      # Values: R (Radio), T (Telecommunications), D (Development)
+      class Sector < Lutaml::Model::Serializable
+        attribute :sector, :string # R, T, or D
+
+        VALID_SECTORS = %w[R T D].freeze
+
+        def initialize(sector:)
+          unless VALID_SECTORS.include?(sector.to_s.upcase)
+            raise ArgumentError, "Invalid sector: #{sector}. Must be R, T, or D"
+          end
+
+          @sector = sector.to_s.upcase
+        end
+
+        def to_s
+          sector
+        end
+
+        def ==(other)
+          return false unless other.is_a?(Sector)
+
+          sector == other.sector
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Pubid
+  module Itu
+    module Components
+      # ITU Series component
+      # Examples: BO, V, X, A, etc.
+      class Series < Lutaml::Model::Serializable
+        attribute :series, :string # e.g., BO, V, X, R, SG1, OB
+
+        def initialize(series:)
+          @series = series
+        end
+
+        def to_s
+          series
+        end
+
+        def ==(other)
+          return false unless other.is_a?(Series)
+
+          series == other.series
+        end
+      end
+    end
+  end
+end

data/lib/pubid/itu/i18n.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Pubid
+  module Itu
+    I18N = YAML.load_file(File.expand_path("i18n.yaml", __dir__)).freeze
+  end
+end

data/lib/pubid/itu/i18n.yaml

@@ -0,0 +1,30 @@
+# Translations for ITU identifier rendering.
+#
+# Ported from v1 monorepo gems/pubid-itu/i18n.yaml — only the sections
+# required by the "Annex to ITU OB" feature are populated here. The
+# `type`/`publisher` sections used by the v1 recommendation renderer are
+# intentionally omitted on v2: the v2 rendering pipeline does not yet wire
+# them up (a separate effort).
+
+# Translation of the "Annex to" prefix used when an annex has no number
+# (i.e. the document IS the annex of a Special Publication, not a sub-annex).
+# For Arabic the value is positioned as a postfix instead of a prefix.
+# Languages with an annex_long entry below (fr/es/ru/zh) intentionally have
+# no entry here — they use the long-form template for short rendering too,
+# so French short matches French long etc. This avoids mixing the English
+# "OB" abbreviation with localized text; ITU itself uses the localized
+# abbreviation (e.g. "BE" in French/Spanish).
+# German is not an official ITU language so no long template exists.
+annex_to:
+  ar: "ملحق"
+  de: Anhang zum
+
+# Long-form (title-style) templates for "Annex to ..." identifiers.
+# Used both for to_s(format: :long) and for short rendering when no
+# annex_to entry exists for the language.
+annex_long:
+  fr: "Annexe au BE de l'UIT %{number}"
+  es: "Anexo al BE de la UIT N.º %{number}"
+  ar: "ملحق ابلنشرة التشغيلية رقم %{number}"
+  ru: "Приложение к ОБ МСЭ %{number}"
+  zh: "国际电联操作公报附件 第 %{number} 期"

data/lib/pubid/itu/identifier.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "parser"
+require_relative "builder"
+require_relative "identifiers"
+require_relative "components/sector"
+require_relative "components/series"
+require_relative "components/code"
+
+module Pubid
+  module Itu
+    module Identifier
+      def self.parse(identifier)
+        parsed = Parser.parse(identifier)
+        Builder.build(parsed)
+      rescue Parslet::ParseFailed => e
+        raise "Failed to parse ITU identifier '#{identifier}': #{e.message}"
+      end
+
+      # Factory mirroring v1's Pubid::Itu::Identifier.create API. The v1 form
+      # accepts a `type:` discriminator plus attribute kwargs; this v2
+      # implementation supports the subset needed by metanorma-itu PR #497:
+      #   * type: :annex — builds Identifiers::Annex
+      #   * series: "OB" (with no type:) — builds Identifiers::SpecialPublication
+      def self.create(type: nil, **kwargs)
+        case type
+        when :annex
+          Identifiers::Annex.new(**kwargs)
+        when nil
+          if kwargs[:series].to_s == "OB"
+            create_special_publication(**kwargs)
+          else
+            raise ArgumentError,
+                  "Identifier.create without :type requires series: 'OB'"
+          end
+        else
+          raise ArgumentError,
+                "Unsupported type for Identifier.create: #{type.inspect}"
+        end
+      end
+
+      def self.create_special_publication(number:, series: "OB", date: nil,
+language: nil)
+        Identifiers::SpecialPublication.new(
+          series: Components::Series.new(series: series.to_s),
+          code: Components::Code.new(number: number.to_s),
+          date: date,
+          language: language&.to_s,
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "supplement"
+
+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)"
+      class Amendment < Supplement
+        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
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Pubid
+  module Itu
+    module Identifiers
+      # "Annex to ..." identifier — the document IS the annex of a Special
+      # Publication (e.g. an annex to ITU OB), not a sub-annex with a number.
+      #
+      # Three rendering forms (per v1 PR #38):
+      #   * default (no i18n_lang): English structural, "Annex to ITU OB No. 1000"
+      #   * short with i18n_lang: structural translation using `annex_to`
+      #   * 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
+
+        def to_urn
+          # Annex URN: append :annex to the inner identifier's URN.
+          base_urn = base&.to_urn
+          return "urn:itu:annex" unless base_urn
+
+          "#{base_urn}:annex"
+        end
+
+        def render_base(**opts)
+          lang = opts[:i18n_lang]&.to_s
+          long_template = lang && Pubid::Itu::I18N["annex_long"]&.fetch(lang,
+                                                                        nil)
+
+          if opts[:format] == :long && long_template
+            return long_template % { number: base_number }
+          end
+
+          annex_translation = lang && Pubid::Itu::I18N["annex_to"]&.fetch(lang,
+                                                                          nil)
+
+          if annex_translation
+            base_str = base_render(**opts)
+            return "#{base_str} #{annex_translation}" if lang == "ar"
+
+            return "#{annex_translation} #{base_str}"
+          end
+
+          if long_template
+            return long_template % { number: base_number }
+          end
+
+          "Annex to #{base_render(**opts)}"
+        end
+
+        def ==(other)
+          return false unless other.is_a?(Annex)
+
+          base == other.base && language == other.language
+        end
+
+        private
+
+        def base_render(**opts)
+          base&.render_base(**opts) || ""
+        end
+
+        def base_number
+          return code&.number if code
+
+          base&.code&.number
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require_relative "../../components/date"
+require_relative "../components/sector"
+require_relative "../components/series"
+require_relative "../components/code"
+require_relative "../i18n"
+
+module Pubid
+  module Itu
+    module Identifiers
+      # Base class for all ITU identifiers
+      class Base < Pubid::Identifier
+        # Long-form ↔ ITU single-letter language code map. The parser produces
+        # single-letter codes (E/F/S/R/A/C); API callers (e.g. metanorma-itu)
+        # pass long-form (en/fr/es/ru/ar/zh). Storage is normalized to the
+        # single-letter form. Languages with no canonical letter (e.g. "de")
+        # pass through unchanged and produce no trailing suffix.
+        LANGUAGES = {
+          "fr" => "F", "es" => "S", "ru" => "R",
+          "ar" => "A", "zh" => "C", "en" => "E",
+          "F" => "F", "S" => "S", "R" => "R",
+          "A" => "A", "C" => "C", "E" => "E"
+        }.freeze
+
+        attribute :sector, Pubid::Itu::Components::Sector
+        attribute :series, Pubid::Itu::Components::Series
+        attribute :code, Pubid::Itu::Components::Code
+        attribute :date, Pubid::Components::Date
+        attribute :language, :string
+
+        def initialize(**kwargs)
+          if kwargs[:language]
+            kwargs = kwargs.merge(language: normalize_language(kwargs[:language]))
+          end
+
+          super
+
+          validate_ob_no_sector!
+        end
+
+        # Generate URN for this identifier
+        #
+        # @return [String] URN representation
+
+        # Override base_hash to handle ITU-specific attributes
+        def base_hash
+          hash = super
+          # ITU Series has a 'series' attribute, not 'number'
+          if hash[:series].is_a?(Hash) && series
+            hash[:series] = series.series
+          end
+          # Add sector (ITU-specific, has a 'sector' attribute)
+          hash[:sector] = sector.sector if sector
+          hash
+        end
+
+        def publisher
+          "ITU"
+        end
+
+        # Render identifier as a string.
+        #
+        # @param i18n_lang [Symbol, String] language for identifier text
+        #   translation (e.g. :fr renders "Annex to" as "Annexe au"). Distinct
+        #   from the identifier's `language` attribute, which is the document's
+        #   own language and produces the trailing suffix like "-F".
+        # @param language [Symbol, String] deprecated alias for i18n_lang.
+        # @param format [Symbol] :long for title-style rendering of supported
+        #   identifiers, otherwise the default short form.
+        def to_s(**opts)
+          opts = self.class.normalize_to_s_opts(opts)
+          render_base(**opts) + render_language_suffix
+        end
+
+        def render_base(**_opts)
+          result = "#{publisher}-#{sector}"
+
+          # Add series and code
+          result += if series
+                      " #{series}.#{code}"
+                    else
+                      " #{code}"
+                    end
+
+          # Add date if present
+          if date
+            result += if date.month
+                        " (#{date.month}/#{date.year})"
+                      else
+                        " (#{date.year})"
+                      end
+          end
+
+          result
+        end
+
+        def render_language_suffix
+          return "" unless language
+          # Only render canonical single-letter ITU language codes
+          # (e.g. "F", "S"). Languages with no mapping (e.g. "de") get
+          # no suffix — matches v1 PR #38 render_language behavior.
+          return "" unless LANGUAGES.value?(language)
+
+          "-#{language}"
+        end
+
+        # Translate `language:` opt to `i18n_lang:` opt. v1 PR #38 introduced
+        # `i18n_lang:` to disambiguate "rendering language" from the document
+        # language attribute; `language:` remains a deprecated alias.
+        def self.normalize_to_s_opts(opts)
+          opts = opts.dup
+          if opts.key?(:language) && !opts.key?(:i18n_lang)
+            opts[:i18n_lang] = opts.delete(:language)
+          else
+            opts.delete(:language)
+          end
+          opts
+        end
+
+        def ==(other)
+          return false unless other.is_a?(Base)
+
+          sector == other.sector &&
+            series == other.series &&
+            code == other.code &&
+            date == other.date &&
+            language == other.language
+        end
+
+        private
+
+        def normalize_language(value)
+          str = value.to_s
+          LANGUAGES[str] || str
+        end
+
+        # OB (Operational Bulletin) is a cross-bureau ITU publication and
+        # must not have a sector. Direct construction with both raises;
+        # the parser silently drops sector for legacy strings like
+        # "ITU-T OB.X" (handled in Builder).
+        def validate_ob_no_sector!
+          return unless series&.series == "OB"
+          return if sector.nil?
+          return if sector.is_a?(Components::Sector) && (sector.sector.nil? || sector.sector.to_s.empty?)
+
+          raise ArgumentError,
+                "OB (Operational Bulletin) is a cross-bureau ITU publication; " \
+                "sector must not be set"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Pubid
+  module Itu
+    module Identifiers
+      # Combined identifier for dual-series recommendations
+      # Format: ITU-T G.780/Y.1351
+      # Example: ITU-T G.780/Y.1351 (2004)
+      class CombinedIdentifier < Base
+        attribute :combined_series, Pubid::Itu::Components::Series
+        attribute :combined_code, Pubid::Itu::Components::Code
+
+        def to_s
+          result = "#{publisher}-#{sector}"
+
+          # Add primary series and code
+          result += if series
+                      " #{series}.#{code}"
+                    else
+                      " #{code}"
+                    end
+
+          # Add combined series and code
+          if combined_series && combined_code
+            result += "/#{combined_series}.#{combined_code}"
+          end
+
+          # Add date if present
+          if date
+            result += if date.month
+                        " (#{date.month}/#{date.year})"
+                      else
+                        " (#{date.year})"
+                      end
+          end
+
+          # Add language
+          result += "-#{language}" if language
+
+          result
+        end
+      end
+    end
+  end
+end