pubid 1.15.21 → 2.0.0.alpha.10

data/lib/pubid/builder/base.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Builder
+    # Base class for all flavor-specific builders.
+    #
+    # Provides the shared build loop that converts parsed data into identifier
+    # objects. Flavors subclass and override:
+    # - +select_class(data)+ to dispatch by data shape (default returns
+    #   +default_identifier_class+).
+    # - +cast(key, value)+ to transform raw parsed values into components.
+    # - +handle_key(identifier, key, value)+ for non-attribute side effects.
+    #
+    # The build loop:
+    # 1. Flattens array-of-hashes input (from Parslet transforms)
+    # 2. Asks +select_class(data)+ for the identifier class
+    # 3. Iterates each key-value pair
+    # 4. Calls +cast(key, value)+ to convert raw values to component objects
+    # 5. Assigns the result to the identifier via setter
+    # 6. Silently skips unknown attributes
+    class Base
+      attr_reader :identifier
+
+      def initialize(identifier_class = nil)
+        @identifier_class = identifier_class
+      end
+
+      def build(data)
+        data = flatten_array(data) if data.is_a?(Array)
+        identifier_class = @identifier_class || select_class(data)
+        identifier = identifier_class.new
+        assign_attributes(identifier, data)
+        identifier
+      end
+
+      private
+
+      # Override in subclasses to dispatch to a specific identifier class
+      # based on the shape of the parsed data (type code, supplement marker,
+      # etc.). Defaults to +default_identifier_class+.
+      def select_class(_data)
+        default_identifier_class
+      end
+
+      # Override in subclasses to convert raw parsed values to component objects.
+      # Return a Hash to assign multiple attributes, or a single value.
+      # Return nil to skip the assignment.
+      def cast(_key, value)
+        value
+      end
+
+      def default_identifier_class
+        raise NotImplementedError,
+              "#{self.class} must implement default_identifier_class"
+      end
+
+      def flatten_array(data)
+        data.each_with_object({}) do |h, acc|
+          acc.merge!(h)
+        end
+      end
+
+      def assign_attributes(identifier, data)
+        attrs = identifier.class.attributes
+        data.each_pair do |key, value|
+          realized = cast(key.to_sym, value)
+          next if realized.nil?
+
+          next if handle_key(identifier, key, realized)
+
+          if realized.is_a?(Hash)
+            realized.each_pair do |k, v|
+              setter = "#{k}="
+              identifier.public_send(setter, v) if attrs.key?(k.to_sym)
+            end
+          else
+            setter = "#{key}="
+            identifier.public_send(setter, realized) if attrs.key?(key.to_sym)
+          end
+        end
+      end
+
+      def handle_key(_identifier, _key, _value)
+        false
+      end
+
+      LANG_CHAR_MAP = {
+        "R" => "ru",
+        "F" => "fr",
+        "E" => "en",
+        "A" => "ar",
+        "S" => "es",
+        "D" => "de",
+      }.freeze
+
+      ROMAN_MAP = {
+        "I" => 1, "V" => 5, "X" => 10,
+        "L" => 50, "C" => 100, "D" => 500, "M" => 1000
+      }.freeze
+
+      def locate_typed_stage(typed_stage_string)
+        raise NotImplementedError,
+              "#{self.class} must implement locate_typed_stage " \
+              "(rely on the flavor module's locate_stage method)"
+      end
+
+      def convert_roman_to_integer(roman_numeral)
+        return roman_numeral unless roman_numeral.to_s.match?(/^[IVXLCDM]+$/i)
+
+        result = 0
+        prev_value = 0
+
+        roman_numeral.to_s.upcase.chars.reverse.each do |char|
+          value = ROMAN_MAP[char]
+          if value < prev_value
+            result -= value
+          else
+            result += value
+          end
+          prev_value = value
+        end
+
+        result.to_s
+      end
+
+      def parse_date(value)
+        value = value.to_s
+        if value.match?(/^\d{4}(-\d{2}){0,2}$/)
+          year, month, day = value.split("-")
+          Pubid::Components::Date.new(year: year,
+                                       month: month || nil,
+                                       day: day || nil)
+        elsif value.is_a?(Integer) || (value.is_a?(String) && value.match?(/^\d{4}$/))
+          Pubid::Components::Date.new(year: value)
+        else
+          raise ArgumentError, "Invalid date format: #{value.inspect}"
+        end
+      end
+
+      # Splits a compound document number ("1234", "1234-1", "1234-1-2")
+      # into number/part/subpart Code components. Flavor-specific dash/slash
+      # normalization lives in +normalize_number_with_part+; legacy year
+      # extraction (e.g. ISO "4037-1979") lives in +extract_legacy_year+.
+      def parse_number_with_part(value, code_class:)
+        normalized = normalize_number_with_part(value)
+        parts = normalized.split("-").reject(&:empty?)
+        number = parts.shift
+        part = parts.shift&.strip
+        subpart = parts.any? ? parts.join("-") : nil
+
+        legacy = extract_legacy_year(number, part, code_class)
+        return legacy if legacy
+
+        part = convert_roman_to_integer(part) if part
+
+        code_hash = { number: code_class.new(value: number) }
+        code_hash[:part] = code_class.new(value: part) if part
+        code_hash[:subpart] = code_class.new(value: subpart) if subpart
+        code_hash
+      end
+
+      # Hook: normalize the raw number_with_part string before splitting.
+      # Override in subclasses for flavor-specific dash/slash/space handling.
+      def normalize_number_with_part(value)
+        value.to_s
+      end
+
+      # Hook: detect a year masquerading as a part (e.g. "4037-1979") and
+      # return a number+date hash, or nil to continue normal splitting.
+      def extract_legacy_year(_number, _part, _code_class)
+        nil
+      end
+
+      def parse_languages(value)
+        original_value = value.to_s
+        normalized_value = original_value.gsub("/", ",")
+        normalized_value.split(",").map do |lang|
+          lang = lang.strip
+          original_lang = lang
+          lang = LANG_CHAR_MAP[lang] if lang.length == 1
+          Pubid::Components::Language.new(code: lang,
+                                          original_code: original_lang)
+        end
+      end
+    end
+  end
+end

data/lib/pubid/bundled_identifier.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Pubid
+  # Identifier that represents a combined bundle of documents using the + operator.
+  # Examples:
+  #   EN 10077-1:2006+AC:2009+AC2:2009
+  #   ISO/IEC DIR 1 + IEC SUP:2016-05
+  #   ISO 8601:2019+Amd 1:2024+Cor 1:2025
+  #
+  # Semantic: Base document combined with amendments/corrigenda that are applied together
+  # This is different from:
+  #   / operator (SupplementIdentifier) - supplement of a document
+  #   | operator (CombinedIdentifier) - dual-published by multiple organizations
+  class BundledIdentifier < Identifier
+    attribute :base_document, Identifier, polymorphic: true
+    attribute :supplements, Identifier, polymorphic: true, collection: true
+    attribute :type, :string, default: -> { "bundled_identifier" }
+
+    # Delegate common attributes to base_document for easier access
+    def publisher
+      base_document&.publisher
+    end
+
+    def copublishers
+      base_document&.copublishers
+    end
+
+    def number
+      base_document&.number
+    end
+
+    def date
+      base_document&.date
+    end
+
+    def type
+      base_document&.type
+    end
+
+    def stage
+      base_document&.stage
+    end
+
+    def typed_stage
+      base_document&.typed_stage
+    end
+
+    # `**opts` carries render flags this method does not name — `annotated:`
+    # above all. Without it the closed keyword list raised
+    # `ArgumentError: unknown keyword: :annotated` for every bundled
+    # identifier, which is worse than a missing span: a wrapper is exactly the
+    # shape a consumer renders.
+    def to_s(lang: :en, lang_single: false, with_edition: false, format: nil,
+stage_format_long: nil, with_date: nil, **opts)
+      result = base_document.to_s(lang: lang, lang_single: lang_single,
+                                  with_edition: with_edition, format: format, stage_format_long: stage_format_long, with_date: with_date, **opts)
+
+      supplements.each do |supplement|
+        # ISO DirectivesSupplement always uses " + " (space before)
+        # CEN-style supplements (AC, A) without base use "+" (no space before)
+        # Other ISO supplements with base use " + " (space before)
+        if supplement.class.name&.include?("DirectivesSupplement") ||
+            (supplement.class.attributes.key?(:base) && !supplement.base.nil?)
+          result += " + #{supplement.to_s(lang: lang, lang_single: lang_single,
+                                          with_edition: with_edition, format: format, stage_format_long: stage_format_long, with_date: with_date, **opts)}"
+        else
+          result += "+#{supplement.to_s(lang: lang, lang_single: lang_single,
+                                        with_edition: with_edition, format: format, stage_format_long: stage_format_long, with_date: with_date, **opts)}"
+        end
+      end
+
+      result
+    end
+
+    # Generate URN for bundled identifier
+    # Flattens all components into a single URN
+    #
+    # Example: "ISO/IEC DIR 1:2022 + IEC SUP:2022"
+    #          → "urn:iso:doc:iso-iec:dir:1:2022:iec:sup:2022"
+    def to_urn
+      # Start with base document URN components
+      parts = base_document.to_urn.split(":")
+
+      # Add each supplement's components
+      supplements.each do |supplement|
+        # For DirectivesSupplement: add organization and "sup" (not "dir-sup")
+        if supplement.class.name&.include?("DirectivesSupplement")
+          # Add organization (e.g., "IEC")
+          if supplement.class.attributes.key?(:supplement_publisher) && supplement.supplement_publisher
+            parts << supplement.supplement_publisher.body.downcase
+          end
+
+          # Always add "sup" for DirectivesSupplement (not "dir-sup")
+          parts << "sup"
+
+          # Add year
+          parts << supplement.date.year.to_s if supplement.date
+        else
+          # For other supplements: use typed_stage type_code
+          if supplement.typed_stage
+            type_code = supplement.typed_stage.type_code
+            parts << type_code.to_s unless type_code == :is
+          end
+
+          # Add supplement date
+          if supplement.date
+            parts << supplement.date.year.to_s
+          end
+
+          # Add supplement number if present. `supplement` is polymorphic and
+          # `number` is a Components::Code on ::Pubid::Identifier but a plain
+          # :string in a growing number of flavors, so read through either.
+          if supplement.number
+            number = supplement.number
+            value = number.respond_to?(:value) ? number.value : number
+            parts << "v#{value}"
+          end
+        end
+      end
+
+      parts.join(":")
+    end
+
+    # Support comparison for sorting
+    def <=>(other)
+      return nil unless other.is_a?(BundledIdentifier)
+
+      base_comparison = base_document.to_s <=> other.base_document.to_s
+      return base_comparison unless base_comparison.zero?
+
+      supplements.map(&:to_s).sort <=> other.supplements.map(&:to_s).sort
+    end
+  end
+end

data/lib/pubid/calconnect/builder.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Calconnect
+    # Builds a CalConnect identifier object from a Parslet parse tree. There is
+    # a single concrete type (Identifiers::Standard), so no type dispatch.
+    class Builder
+      def self.build(parsed_data)
+        new.build(parsed_data)
+      end
+
+      def build(data)
+        Identifiers::Standard.new(
+          series: data[:series]&.to_s,
+          number: data[:number].to_s,
+          date: build_date(data),
+        )
+      end
+
+      private
+
+      # Publication date as a Pubid::Components::Date, or nil for a partial
+      # reference that omits the trailing ":YYYY" (relaton matches such refs by
+      # excluding the date). Digits are kept as strings verbatim (already
+      # zero-padded in the source, e.g. "07"/"23"); month/day are nil for the
+      # common year-only form.
+      def build_date(data)
+        return nil if data[:year].nil?
+
+        ::Pubid::Components::Date.new(
+          year: data[:year].to_s,
+          month: data[:month]&.to_s,
+          day: data[:day]&.to_s,
+        )
+      end
+    end
+  end
+end

data/lib/pubid/calconnect/identifier.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Calconnect
+    # Base class for every CalConnect identifier AND the flavor's parse entry
+    # point — mirrors Pubid::Jis::Identifier. Concrete identifiers under
+    # Pubid::Calconnect::Identifiers descend from this class, so a parsed
+    # CalConnect id is an instance of Pubid::Calconnect::Identifier and
+    # relaton-index can pass this class as `pubid_class` for from_hash/to_hash.
+    class Identifier < ::Pubid::Identifier
+      # `number` is a CalConnect-specific plain string (preserves leading zeros
+      # like "0514" and the sub-part separator, "0812-1"/"0707.1"), so it
+      # overrides the inherited Components::Code type. The publication date uses
+      # the shared Pubid::Components::Date (inherited attribute): `year` is
+      # always present, `month`/`day` only for the rare full-date form
+      # ("CC/WD 51017:2024-07-23").
+      attribute :series, :string # Optional series letter/token (A, WD, DIR, …)
+      attribute :number, :string
+      attribute :date, ::Pubid::Components::Date
+
+      # Polymorphic type map for lutaml::Model key_value (de)serialization,
+      # mapping the concrete class's polymorphic_name to its class name so a
+      # stored hash rebuilds the correct identifier type via from_hash.
+      CALCONNECT_TYPE_MAP = {
+        "pubid:calconnect:standard" => "Pubid::Calconnect::Identifiers::Standard",
+      }.freeze
+
+      # The date serializes FLAT as year/month/day string keys (nils omitted),
+      # mirroring lib/pubid/iso/identifier.rb — not as a nested "date" object —
+      # so the index row stays a shallow hash and round-trips exactly.
+      key_value do
+        map "_type", to: :_type, polymorphic_map: CALCONNECT_TYPE_MAP
+        map "series", to: :series
+        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 "day", with: { to: :day_to_kv, from: :day_from_kv }
+      end
+
+      # Publisher is always "CC". A plain constant (not a `publisher` method) so
+      # it doesn't shadow the inherited lutaml `publisher` attribute, which
+      # would otherwise fail serialization type validation.
+      PUBLISHER = "CC"
+
+      attr_reader :with_publisher
+
+      # Render the publication date, e.g. "2018" or "2024-07-23". Shared by the
+      # renderer and the URN generator so they always agree.
+      # Pubid::Components::Date#to_s yields the year alone, or the zero-padded
+      # "YYYY-MM-DD" when month/day are present.
+      def date_string
+        date&.to_s
+      end
+
+      # Basic string representation. Delegates to the human renderer. The
+      # printed CalConnect id carries the "CC" publisher token by default; pass
+      # with_publisher: false to drop it (and the series slash).
+      def to_s(**opts)
+        render(format: :human, **opts)
+      end
+
+      # Capture the with_publisher flag on EVERY render call (default true), so
+      # it can never leak across calls. The base `render` only forwards
+      # `:with_edition` to the renderer, so the flag is threaded via this
+      # per-call instance write (the renderer reads `id.with_publisher`).
+      def render(format: :human, with_publisher: true, **opts)
+        @with_publisher = with_publisher
+        super(format: format, **opts)
+      end
+
+      # --- date serialized flat as year/month/day (mirrors ISO) ---
+      def year_to_kv(model, doc)
+        emit_date_part(doc, "year", model.date&.year)
+      end
+
+      def month_to_kv(model, doc)
+        emit_date_part(doc, "month", model.date&.month)
+      end
+
+      def day_to_kv(model, doc)
+        emit_date_part(doc, "day", model.date&.day)
+      end
+
+      def year_from_kv(model, value) = date_for(model).year = value.to_s
+      def month_from_kv(model, value) = date_for(model).month = value.to_s
+      def day_from_kv(model, value) = date_for(model).day = value.to_s
+
+      def emit_date_part(doc, key, val)
+        return if val.nil? || val.to_s.empty?
+
+        doc.add_child(Lutaml::KeyValue::DataModel::Element.new(key, val.to_s))
+      end
+
+      def date_for(model)
+        model.date ||= ::Pubid::Components::Date.new
+      end
+
+      # from_hash is the shared polymorphic dispatch on Pubid::Identifier.
+      # CALCONNECT_TYPE_MAP remains as the key_value polymorphic_map.
+
+      # Parse a CalConnect identifier string into an identifier object.
+      # @param identifier [String] The CalConnect identifier string to parse
+      # @return [Identifier] The appropriate identifier object
+      # @raise [Pubid::Errors::InvalidInputError]
+      #   If the input exceeds the maximum length
+      # @raise [Pubid::Errors::ParseError] If parsing fails
+      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
+
+        Builder.build(Parser.parse(identifier))
+      end
+    end
+  end
+end

data/lib/pubid/calconnect/identifiers/standard.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Calconnect
+    module Identifiers
+      # The sole CalConnect document type. Its polymorphic_name resolves
+      # automatically to "pubid:calconnect:standard".
+      class Standard < Identifier
+        TYPED_STAGES = [
+          Pubid::Components::TypedStage.new(
+            code: :pubcc,
+            stage_code: :published,
+            type_code: :cc,
+            abbr: ["CC"],
+            name: "CalConnect Standard",
+            harmonized_stages: [],
+          ),
+        ].freeze
+
+        def self.type
+          { key: :cc,
+            web: :standard,
+            title: "CalConnect Standard",
+            short: "CC" }
+        end
+      end
+    end
+  end
+end

data/lib/pubid/calconnect/identifiers.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Calconnect
+    module Identifiers
+      autoload :Standard, "#{__dir__}/identifiers/standard"
+    end
+  end
+end

data/lib/pubid/calconnect/parser.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "parslet"
+
+module Pubid
+  module Calconnect
+    # Parslet grammar for CalConnect identifiers.
+    #
+    # Shape: CC[/<series>] <number>:<date>
+    #   CC 18011:2018
+    #   CC/DIR 10006:2019
+    #   CC/Adv 0707.1:2007        (dot sub-part)
+    #   CC/A 0812-1:2008          (dash sub-part)
+    #   CC/WD 51017:2024-07-23    (full ISO date)
+    class Parser < ::Pubid::Parser::Grammar
+      rule(:digit) { match["0-9"] }
+      rule(:digits) { digit.repeat(1) }
+
+      # Publisher token
+      rule(:publisher) { str("CC") }
+
+      # Series token — an open [A-Za-z]+ set (A, WD, R, S, CD, DIR, Adv, FDS, …)
+      rule(:series) { match["A-Za-z"].repeat(1).as(:series) }
+
+      # Number — digits, preserving leading zeros, with at most one dot- or
+      # dash-delimited sub-part ("0707.1", "0812-1"). Kept as a string.
+      rule(:number) do
+        (digits >> ((str(".") | str("-")) >> digits).maybe).as(:number)
+      end
+
+      # Date after the colon: a year, optionally a full "YYYY-MM-DD". The colon
+      # hard-delimits number from date, and month+day only appear together, so
+      # the split is unambiguous.
+      rule(:date) do
+        digits.as(:year) >>
+          (str("-") >> digits.as(:month) >> str("-") >> digits.as(:day)).maybe
+      end
+
+      rule(:identifier) do
+        publisher >>
+          (str("/") >> series).maybe >>
+          str(" ") >>
+          number >>
+          (str(":") >> date).maybe
+      end
+
+      rule(:root) { identifier }
+
+      def self.parse(input)
+        new.parse(input)
+      end
+    end
+  end
+end

data/lib/pubid/calconnect/renderer.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Calconnect
+    # Human-readable renderer for CalConnect identifiers.
+    #
+    # Produces the canonical printed form, e.g.:
+    #   "CC 18011:2018"
+    #   "CC/DIR 10006:2019"
+    #   "CC/WD 51017:2024-07-23"
+    #   "DIR 10006:2019"          (only when with_publisher: false)
+    #
+    # Registered as the `:human` format in the CalConnect format registry and
+    # invoked via `render(format: :human)`.
+    class Renderer < ::Pubid::Renderers::Base
+      PUBLISHER = "CC"
+
+      def render(**_opts)
+        id = @id
+        prefix = if with_publisher?(id)
+                   id.series ? "#{PUBLISHER}/#{id.series} " : "#{PUBLISHER} "
+                 else
+                   id.series ? "#{id.series} " : ""
+                 end
+        date = id.date_string
+        "#{prefix}#{id.number}#{":#{date}" if date}"
+      end
+
+      private
+
+      def with_publisher?(id)
+        id.respond_to?(:with_publisher) && id.with_publisher != false
+      end
+    end
+  end
+end

data/lib/pubid/calconnect/urn_generator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Calconnect
+    # Emits CalConnect URNs of the form
+    #   urn:calconnect[:<series>]:<number>:<date>
+    # e.g. "urn:calconnect:DIR:10006:2019", "urn:calconnect:18011:2018",
+    # "urn:calconnect:WD:51017:2024-07-23".
+    #
+    # The series keeps its printed case (JIS keeps its code case likewise) so a
+    # URN reconstructs the human form losslessly — mirror in urn_parser.rb.
+    #
+    # NOTE: a *partial* (date-less) reference has NO round-trippable URN form.
+    # Both `series` and `date` are optional, and UrnParser reads the trailing
+    # segments positionally, so a date-less URN like "urn:calconnect:11001"
+    # (or "urn:calconnect:DIR:10006") is ambiguous with a series-less dated URN
+    # and does not parse back. Partial refs are matched by pubid `#exclude`,
+    # not by URN, so this generator simply omits the missing segment rather
+    # than emitting an empty ":" — callers must not rely on URN round-trip for
+    # a partial id.
+    class UrnGenerator < Pubid::UrnGenerator::Base
+      def generate
+        # series and date_string are nil for a series-less or partial
+        # (date-less) id; compact drops them so no empty ":" segment appears.
+        parts = [
+          "urn", "calconnect",
+          identifier.series, identifier.number.to_s, identifier.date_string
+        ]
+        parts.compact.join(":")
+      end
+    end
+  end
+end

data/lib/pubid/calconnect/urn_parser.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Calconnect
+    # Parses CalConnect URNs back into identifiers.
+    #
+    # UrnGenerator emits: urn:calconnect[:<series>]:<number>:<date>
+    #   urn:calconnect:18011:2018            → CC 18011:2018
+    #   urn:calconnect:DIR:10006:2019        → CC/DIR 10006:2019
+    #   urn:calconnect:WD:51017:2024-07-23   → CC/WD 51017:2024-07-23
+    #
+    # The date segment (year or full "YYYY-MM-DD") never contains a colon, so
+    # it is a single trailing part; the number precedes it, and an optional
+    # series precedes the number.
+    #
+    # This positional pop assumes a *dated* URN (the form UrnGenerator emits for
+    # a full id). A partial (date-less) reference has no round-trippable URN —
+    # see UrnGenerator — so this parser is only guaranteed for URNs produced
+    # from a full id; a date-less URN misaligns the pops and will not parse.
+    class UrnParser < Pubid::UrnParser::Base
+      def parse_urn(urn)
+        parts = split_parts(strip_namespace(urn))
+        date = parts.pop
+        number = parts.pop
+        series = parts.pop
+
+        text = +"CC"
+        text << "/#{series}" if series
+        text << " #{number}:#{date}"
+        flavor_parse(text)
+      end
+    end
+  end
+end