pubid 2.0.0.pre.alpha.2 → 2.0.0.pre.alpha.3

data/lib/pubid/iso.rb

@@ -11,9 +11,9 @@ module Pubid
     autoload :FormatResolver, "#{__dir__}/iso/format_resolver"
     autoload :Identifier, "#{__dir__}/iso/identifier"
     autoload :Identifiers, "#{__dir__}/iso/identifiers"
+    autoload :Normalizer, "#{__dir__}/iso/normalizer"
     autoload :Parser, "#{__dir__}/iso/parser"
     autoload :RenderingStyle, "#{__dir__}/iso/rendering_style"
-    autoload :Scheme, "#{__dir__}/iso/scheme"
     autoload :SingleIdentifier, "#{__dir__}/iso/single_identifier"
     autoload :SupplementIdentifier, "#{__dir__}/iso/supplement_identifier"
     autoload :UrnGenerator, "#{__dir__}/iso/urn_generator"
@@ -33,10 +33,78 @@ module Pubid
       when :mr_string
         Pubid::Parsers::MrString.parse(identifier)
       else
-        Scheme.parse(identifier)
+        Normalizer.apply(identifier)
       end
     end
 
+    # Build an ISO identifier from attributes.
+    #
+    # This is the public seam: callers in other flavors should never reach
+    # into `Pubid::Iso::Identifiers::*` or `Pubid::Iso::Components::*`
+    # directly — go through this method so the internal class registry can
+    # change without breaking callers.
+    #
+    # Accepts either raw values (Strings/Integers) or pre-built components.
+    # Raw values are wrapped in the appropriate ISO component internally.
+    #
+    # @param type [Symbol] the type key (e.g. :is, :tr, :ts, :guide)
+    # @param publisher [String, Pubid::Iso::Components::Publisher] primary publisher
+    # @param copublishers [Array<String>, Array<Pubid::Components::Publisher>]
+    # @param number [String, Integer, Pubid::Iso::Components::Code]
+    # @param year [String, Integer, Pubid::Components::Date, nil]
+    # @param attrs [Hash] additional identifier attributes
+    # @return [Pubid::Iso::Identifier]
+    def self.build(type:, publisher: nil, copublishers: nil, number: nil,
+                   year: nil, **attrs)
+      klass = locate_type(type) || raise(ArgumentError, "unknown ISO type: #{type.inspect}")
+
+      copub_list = Array(copublishers)
+      attrs[:publisher] = build_publisher(publisher, copub_list) if publisher || copub_list.any?
+      attrs[:copublishers] = build_copublishers(copub_list) if copub_list.any?
+      attrs[:number] = build_code(number) if number
+      attrs[:date] = build_date(year) if year
+
+      klass.new(attrs)
+    end
+
+    # @!visibility private
+    def self.build_publisher(value, copublishers = [])
+      return value if value.is_a?(Components::Publisher) && copublishers.empty?
+
+      copub_strings = copublishers.map { |cp| cp.is_a?(Components::Publisher) ? cp.publisher : cp.to_s }
+      Components::Publisher.new(
+        publisher: value.is_a?(Components::Publisher) ? value.publisher : value.to_s,
+        copublisher: copub_strings,
+      )
+    end
+    private_class_method :build_publisher
+
+    # @!visibility private
+    def self.build_copublishers(list)
+      Array(list).map do |cp|
+        next cp if cp.is_a?(Components::Publisher)
+
+        Components::Publisher.new(publisher: cp.to_s)
+      end
+    end
+    private_class_method :build_copublishers
+
+    # @!visibility private
+    def self.build_code(value)
+      return value if value.is_a?(Components::Code)
+
+      Components::Code.new(value: value.to_s)
+    end
+    private_class_method :build_code
+
+    # @!visibility private
+    def self.build_date(value)
+      return value if value.is_a?(::Pubid::Components::Date)
+
+      ::Pubid::Components::Date.new(year: value.to_s)
+    end
+    private_class_method :build_date
+
     # Parse an ISO URN string
     # @param urn [String] the URN string to parse
     # @return [Identifier] the parsed identifier
@@ -44,6 +112,109 @@ module Pubid
     def self.parse_urn(urn)
       UrnParser.parse(urn)
     end
+
+    # Build an ISO identifier from a Parslet parse-tree hash (used by other
+    # flavors when parsing joint identifiers, e.g. IEC's `IEC … | ISO …` form).
+    #
+    # This is the public seam: callers should never reach into
+    # `Pubid::Iso::Builder` directly.
+    #
+    # @param hash [Hash] parse tree for an ISO identifier
+    # @return [Pubid::Iso::Identifier]
+    def self.build_from_parse(hash)
+      builder.build(hash)
+    end
+
+    # Return the named Parslet rule atom from the ISO parser, for embedding in
+    # another flavor's grammar (e.g. IEC joint identifiers).
+    #
+    # This is the public seam: callers should never instantiate
+    # `Pubid::Iso::Parser` directly.
+    #
+    # @param rule_name [Symbol] the parser rule to expose
+    # @return [Parslet::Atoms::Base]
+    def self.joint_grammar_atom(rule_name)
+      parser.public_send(rule_name)
+    end
+
+    # Auto-discover all identifier types from the Identifiers namespace
+    # @return [Array<Class>] identifier classes that define a self.type Hash
+    def self.identifier_types
+      @identifier_types ||= Identifiers.constants
+        .filter_map { |c| begin; Identifiers.const_get(c); rescue NameError; nil; end }
+        .select { |c| c.is_a?(Class) && c.singleton_methods(false).include?(:type) }
+        .select { |c| c.type.is_a?(Hash) }
+    end
+
+    # Build typed stage index from identifier types
+    # @return [Array<Pubid::Components::TypedStage>] all typed stages
+    def self.all_typed_stages
+      @all_typed_stages ||= identifier_types.flat_map do |klass|
+        if klass.const_defined?(:TYPED_STAGES)
+          klass.const_get(:TYPED_STAGES)
+        else
+          []
+        end
+      end
+    end
+
+    # Memoized builder instance used by Normalizer / URN parser
+    # @return [Pubid::Iso::Builder]
+    def self.builder
+      @builder ||= Builder.new
+    end
+
+    # Memoized parser instance used by Normalizer
+    # @return [Pubid::Iso::Parser]
+    def self.parser
+      @parser ||= Parser.new
+    end
+
+    # Lookup: type code -> identifier class
+    # @param code [String, Symbol] the type key to find
+    # @return [Class, nil] the matching identifier class
+    def self.locate_type(code)
+      identifier_types.find { |t| t.type[:key].to_s == code.to_s }
+    end
+
+    # Lookup: abbreviation -> typed stage
+    # @param abbr [String, Symbol] the abbreviation to find
+    # @return [Pubid::Components::TypedStage, nil] the matching typed stage
+    def self.locate_stage(abbr)
+      abbr_str = abbr.to_s.upcase
+      all_typed_stages.find { |s| s.abbr.any? { |a| a.to_s.upcase == abbr_str } }
+    end
+
+    # Lookup: stage code -> typed stage
+    # @param stage_code [String, Symbol]
+    # @return [Pubid::Components::TypedStage, nil]
+    def self.locate_stage_by_stage_code(stage_code)
+      stage_code_sym = stage_code.to_sym
+      all_typed_stages.find { |s| s.stage_code.to_sym == stage_code_sym }
+    end
+
+    # Lookup: per-typed-stage code -> typed stage
+    # @param code [String, Symbol]
+    # @return [Pubid::Components::TypedStage, nil]
+    def self.locate_stage_by_code(code)
+      code_sym = code.to_sym
+      all_typed_stages.find { |s| s.code&.to_sym == code_sym }
+    end
+
+    # Lookup: harmonized stage code -> typed stage
+    # @param harmonized_code [String]
+    # @return [Pubid::Components::TypedStage, nil]
+    def self.locate_stage_by_harmonized_code(harmonized_code)
+      harmonized_str = harmonized_code.to_s
+      all_typed_stages.find { |s| s.harmonized_stages&.include?(harmonized_str) }
+    end
+
+    # Default typed stage used when no type_with_stage is present
+    # (e.g., the bare International Standard published stage)
+    # @return [Pubid::Components::TypedStage]
+    def self.default_typed_stage
+      locate_stage("") || all_typed_stages.first
+    end
   end
 end
 

data/lib/pubid/itu/builder.rb

@@ -1,17 +1,5 @@
 # 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

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

@@ -8,6 +8,10 @@ module Pubid
       # ITU Code component
       # Format: NUMBER[.SUBSERIES][-PART]
       # Examples: 1234, 1234.5, 1234-1, 1234.5-2
+      #
+      # Stays independent of Pubid::Components::Code because ITU uses
+      # +subseries+ (dot-separated, flavor-specific) and +parts+
+      # (dash-separated).
       class Code < Lutaml::Model::Serializable
         attribute :number, :string
         attribute :subseries, :string
@@ -26,6 +30,10 @@ module Pubid
           result
         end
 
+        def render(context: nil)
+          to_s
+        end
+
         def ==(other)
           return false unless other.is_a?(Code)
 

data/lib/pubid/itu/components.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Itu
+    module Components
+      autoload :Sector, "#{__dir__}/components/sector"
+      autoload :Series, "#{__dir__}/components/series"
+      autoload :Code, "#{__dir__}/components/code"
+    end
+  end
+end

data/lib/pubid/itu/identifier.rb

@@ -1,14 +1,13 @@
 # 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
+    # NOTE: intentionally does NOT `extend Pubid::IdentifierFacade`. ITU's
+    # `to_hash` currently raises (publisher stored as a String, not a Publisher
+    # component), so enabling the facade's identity check would route ITU ids
+    # through a consumer's `to_hash` (e.g. relaton-index#save) and crash.
+    # Re-enable once ITU serialization round-trips cleanly. See
+    # identifier_facade.rb.
     module Identifier
       def self.parse(identifier)
         parsed = Parser.parse(identifier)
@@ -16,103 +15,6 @@ module Pubid
       rescue Parslet::ParseFailed => e
         raise "Failed to parse ITU identifier '#{identifier}': #{e.message}"
       end
-
-      # Factory mirroring pubid 1.x's `Pubid::Itu::Identifier.create` API.
-      # Dispatch on `:type`:
-      #   * nil → Recommendation (or SpecialPublication for series "OB")
-      #   * :recommendation     → Identifiers::Recommendation
-      #   * :annex              → Identifiers::Annex
-      #   * :special_publication → Identifiers::SpecialPublication
-      #
-      # Component-typed kwargs are accepted as primitives and coerced:
-      #   * sector: "T"   → Components::Sector.new(sector: "T")
-      #   * series: "X"   → Components::Series.new(series: "X")
-      #   * number: "509" → Components::Code.new(number: "509")
-      #   * year: "2020"  → Pubid::Components::Date.new(year: "2020")
-      TYPE_KEY_TO_KLASS = {
-        recommendation:      "Recommendation",
-        annex:               "Annex",
-        special_publication: "SpecialPublication",
-      }.freeze
-
-      def self.create(type: nil, **kwargs)
-        # Backward-compat: nil type + series "OB" → SpecialPublication.
-        if type.nil? && kwargs[:series].to_s == "OB"
-          return create_special_publication(**kwargs)
-        end
-
-        klass = resolve_create_class(type)
-        klass.new(**coerce_create_attrs(kwargs, klass: klass))
-      end
-
-      def self.resolve_create_class(type)
-        return Identifiers::Recommendation if type.nil?
-
-        klass_name = TYPE_KEY_TO_KLASS[type.to_sym]
-        raise ArgumentError, "Unknown ITU type: #{type.inspect}" unless klass_name
-
-        Identifiers.const_get(klass_name)
-      end
-
-      # Backward-compat helper retained for the OB-series shortcut.
-      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
-
-      def self.coerce_create_attrs(opts, klass: nil)
-        attrs = {}
-        if (v = opts[:sector])
-          attrs[:sector] = if v.is_a?(Components::Sector)
-                             v
-                           else
-                             Components::Sector.new(sector: v.to_s.upcase)
-                           end
-        end
-        if (v = opts[:series])
-          attrs[:series] = if v.is_a?(Components::Series)
-                             v
-                           else
-                             Components::Series.new(series: v.to_s)
-                           end
-        end
-        if opts[:number] || opts[:code]
-          code_value = opts[:code]
-          if code_value.is_a?(Components::Code)
-            attrs[:code] = code_value
-          else
-            attrs[:code] = Components::Code.new(
-              number:    (opts[:number] || code_value).to_s,
-              subseries: opts[:subseries]&.to_s,
-              parts:     opts[:parts] ? Array(opts[:parts]).map(&:to_s) : nil,
-            )
-          end
-        end
-        if (v = opts[:year])
-          attrs[:date] = Pubid::Components::Date.new(year: v.to_s)
-        end
-        attrs[:date] = opts[:date] if opts[:date].is_a?(Pubid::Components::Date)
-        attrs[:language] = opts[:language].to_s if opts[:language]
-
-        # Pass through any subclass-specific kwarg the chosen class
-        # declares (e.g. Annex#base) — preserves callers that already pass
-        # an explicit attribute that our coercion table doesn't cover.
-        if klass
-          consumed = %i[sector series number code subseries parts year date
-                        language]
-          opts.each do |k, v|
-            next if consumed.include?(k) || attrs.key?(k)
-            attrs[k] = v if klass.attributes.key?(k)
-          end
-        end
-        attrs
-      end
-      private_class_method :resolve_create_class, :coerce_create_attrs
     end
   end
 end

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "supplement"
-
 module Pubid
   module Itu
     module Identifiers

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "base"
-
 module Pubid
   module Itu
     module Identifiers

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

@@ -1,11 +1,5 @@
 # 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

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "base"
-
 module Pubid
   module Itu
     module Identifiers

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "supplement"
-
 module Pubid
   module Itu
     module Identifiers

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "base"
-
 module Pubid
   module Itu
     module Identifiers

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "base"
-
 module Pubid
   module Itu
     module Identifiers

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "base"
-
 module Pubid
   module Itu
     module Identifiers

data/lib/pubid/itu/urn_parser.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Itu
+    # Parses ITU URNs back into identifiers.
+    #
+    # UrnGenerator emits: `urn:itu:{sector}:{code}` where sector is the
+    # lowercase ITU sector letter (t for ITU-T, r for ITU-R, d for ITU-D)
+    # and code is the document code (e.g., "BO.1073-1").
+    #
+    # Examples:
+    # - urn:itu:t:BO.1073-1 → ITU-T BO.1073-1
+    # - urn:itu:r:BO.500    → ITU-R BO.500
+    class UrnParser < Pubid::UrnParser::Base
+      def parse_urn(urn)
+        body = strip_namespace(urn)
+        parts = split_parts(body)
+        sector, code = parts
+        flavor_parse("ITU-#{sector.upcase} #{code}")
+      end
+    end
+  end
+end

data/lib/pubid/itu.rb

@@ -5,16 +5,57 @@ require "lutaml/model"
 module Pubid
   module Itu
     autoload :Builder, "#{__dir__}/itu/builder"
+    autoload :Components, "#{__dir__}/itu/components"
     autoload :Identifier, "#{__dir__}/itu/identifier"
     autoload :Identifiers, "#{__dir__}/itu/identifiers"
     autoload :Parser, "#{__dir__}/itu/parser"
-    autoload :Scheme, "#{__dir__}/itu/scheme"
     autoload :UrnGenerator, "#{__dir__}/itu/urn_generator"
+    autoload :UrnParser, "#{__dir__}/itu/urn_parser"
     autoload :Model, "#{__dir__}/itu/model"
 
+    # I18N is a YAML-loaded constant (not a class), so autoload cannot be used.
+    # It is loaded eagerly when the ITU module is first referenced.
+    require "#{__dir__}/itu/i18n"
+
     def self.parse(identifier)
       Identifier.parse(identifier)
     end
+
+    # Auto-discover all identifier types from the Identifiers namespace
+    # @return [Array<Class>] identifier classes (Pubid::Identifier subclasses)
+    def self.identifier_types
+      @identifier_types ||= Identifiers.constants
+        .filter_map { |c| begin; Identifiers.const_get(c); rescue NameError; nil; end }
+        .select { |c| c.is_a?(Class) && c < Pubid::Identifier }
+        .reject { |c| c.name&.split("::")&.last == "Base" }
+    end
+
+    # Build typed stage index from identifier types
+    # @return [Array<Pubid::Components::TypedStage>] all typed stages
+    def self.all_typed_stages
+      @all_typed_stages ||= identifier_types.flat_map do |klass|
+        if klass.const_defined?(:TYPED_STAGES)
+          klass.const_get(:TYPED_STAGES)
+        else
+          []
+        end
+      end
+    end
+
+    # Lookup: type code -> identifier class
+    # @param code [String, Symbol] the type key to find
+    # @return [Class, nil] the matching identifier class
+    def self.locate_type(code)
+      identifier_types.find { |t| t.type[:key].to_s == code.to_s }
+    end
+
+    # Lookup: abbreviation -> typed stage
+    # @param abbr [String, Symbol] the abbreviation to find
+    # @return [Pubid::Components::TypedStage, nil] the matching typed stage
+    def self.locate_stage(abbr)
+      abbr_str = abbr.to_s.upcase
+      all_typed_stages.find { |s| s.abbr.any? { |a| a.to_s.upcase == abbr_str } }
+    end
   end
 end
 

data/lib/pubid/jcgm/builder.rb

@@ -3,21 +3,22 @@
 module Pubid
   module Jcgm
     class Builder < Pubid::Builder::Base
-      def initialize(scheme)
-        @scheme = scheme
-      end
-
       def locate_identifier_klass(parsed_hash)
         if parsed_hash[:base_identifier]
-          return @scheme.locate_identifier_klass_by_type_code(:amendment)
+          return Jcgm.locate_type(:amendment)
         end
 
         if parsed_hash[:gum_number]
-          return @scheme.locate_identifier_klass_by_type_code(:gum_guide)
+          return Jcgm.locate_type(:gum_guide)
         end
 
+        # Standard guide (no type_with_stage, no gum_number).
+        # Don't use locate_stage("") — Guide and GumGuide both have
+        # abbr: [""], so the result depends on constant iteration order.
+        return Jcgm.locate_type(:guide) unless parsed_hash[:type_with_stage]
+
         typed_stage = locate_typed_stage(parsed_hash[:type_with_stage])
-        @scheme.locate_identifier_klass_by_type_code(typed_stage.type_code)
+        Jcgm.locate_type(typed_stage.type_code)
       end
 
       def build(parsed_hash)
@@ -25,7 +26,8 @@ module Pubid
         assign_attributes(identifier, parsed_hash)
 
         if identifier.class.attributes.key?(:typed_stage) && identifier.typed_stage.nil?
-          default_typed_stage = @scheme.locate_typed_stage_by_abbr("")
+          default_typed_stage = Jcgm.locate_stage("") ||
+            raise(ArgumentError, "Unknown type abbreviation: ''")
           identifier.typed_stage = default_typed_stage
           identifier.stage = default_typed_stage.to_stage if identifier.class.attributes.key?(:stage)
           identifier.type = default_typed_stage.to_type if identifier.class.attributes.key?(:type)
@@ -40,6 +42,12 @@ module Pubid
         Identifiers::Guide
       end
 
+      def locate_typed_stage(typed_stage_string)
+        typed_stage_string = "" if typed_stage_string.nil?
+        Jcgm.locate_stage(typed_stage_string) ||
+          raise(ArgumentError, "Unknown type abbreviation: '#{typed_stage_string}'")
+      end
+
       def cast(type, value)
         case type
         when :base_identifier

data/lib/pubid/jcgm/identifier.rb

@@ -6,49 +6,6 @@ module Pubid
       def self.parse(string)
         Pubid::Jcgm.parse(string)
       end
-
-      # Factory mirroring pubid 1.x's `Pubid::Jcgm::Identifier.create` API.
-      # Dispatches `:guide` (default) → Guide, `:gum_guide` → GumGuide.
-      TYPE_KEY_TO_KLASS = {
-        guide:     "Guide",
-        gum_guide: "GumGuide",
-      }.freeze
-
-      def self.create(type: nil, **opts)
-        klass = resolve_create_class(type)
-        attrs = coerce_create_attrs(opts)
-        ts = klass.const_defined?(:TYPED_STAGES) &&
-             klass.const_get(:TYPED_STAGES).find do |t|
-               t.stage_code&.to_sym == :published
-             end
-        attrs[:typed_stage] = ts if ts
-        klass.new(**attrs)
-      end
-
-      def self.resolve_create_class(type)
-        return Identifiers::Guide if type.nil?
-
-        klass_name = TYPE_KEY_TO_KLASS[type.to_sym]
-        raise ArgumentError, "Unknown JCGM type: #{type.inspect}" unless klass_name
-
-        Identifiers.const_get(klass_name)
-      end
-
-      def self.coerce_create_attrs(opts)
-        attrs = {
-          publisher: Pubid::Jcgm::Components::Publisher.new(
-            publisher: (opts[:publisher] || "JCGM").to_s,
-          ),
-        }
-        if (v = opts[:number])
-          attrs[:number] = Pubid::Components::Code.new(value: v.to_s)
-        end
-        if (v = opts[:year])
-          attrs[:date] = Pubid::Components::Date.new(year: v.to_s)
-        end
-        attrs
-      end
-      private_class_method :resolve_create_class, :coerce_create_attrs
     end
   end
 end

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

@@ -21,13 +21,8 @@ module Pubid
           { key: :amendment, title: "Amendment", short: "Amd" }
         end
 
-        def to_s(lang: :en, lang_single: false, with_edition: false,
-format: nil, stage_format_long: nil, with_date: nil)
-          result = base_identifier.to_s if base_identifier
-          result += "/Amd"
-          result += " #{iteration.value}" if iteration
-          result += ":#{date}" if date
-          result
+        def to_s(**opts)
+          render(format: :human, **opts)
         end
       end
     end

data/lib/pubid/jcgm/identifiers/gum_guide.rb

@@ -22,16 +22,8 @@ module Pubid
           { key: :gum_guide, title: "GUM Guide", short: "GUM" }
         end
 
-        def to_s(lang: :en, lang_single: false, with_edition: false,
-format: nil, stage_format_long: nil, with_date: nil)
-          parts = []
-          parts << publisher.publisher if publisher
-          parts << "GUM-#{gum_number.value}" if gum_number
-
-          result = parts.join(" ")
-          result += ":#{date}" if date
-          result += language_portion if languages&.any?
-          result
+        def to_s(**opts)
+          render(format: :human, **opts)
         end
 
         private