pubid 1.15.21 → 2.0.0.alpha.10

data/lib/pubid/ogc/builder.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Ogc
+    # Turns the parse tree into an Ogc::Identifiers::Document. OGC has a single
+    # document type, so there is no type dispatch.
+    class Builder
+      def self.build(parsed_data)
+        new.build(parsed_data)
+      end
+
+      def build(data)
+        Identifiers::Document.new(
+          year: data[:year].to_s,
+          number: data[:number].to_s,
+          revision: normalize_revision(data[:revision]),
+        )
+      end
+
+      private
+
+      # Normalize the revision suffix to its canonical lowercased form (the
+      # shape the relaton index stores, e.g. "R1" -> "r1"). nil when there is
+      # no revision.
+      def normalize_revision(revision)
+        return nil if revision.nil?
+
+        normalized = revision.to_s.strip.downcase
+        normalized.empty? ? nil : normalized
+      end
+    end
+  end
+end

data/lib/pubid/ogc/identifier.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Ogc
+    # Base class for every OGC identifier AND the flavor's parse/create entry
+    # point. There is a single concrete type (Identifiers::Document), so this
+    # base mostly exists to hold the shared attributes and the polymorphic
+    # serialization mapping.
+    class Identifier < ::Pubid::Identifier
+      # OGC ids are digit-leading (`<yy>-<nnn>`) with no publisher token in the
+      # printed form. Everything is kept as a string to preserve zero-padding
+      # ("032", not 32) and the exact revision suffix.
+      attribute :year, :string   # the "<yy>" field, e.g. "24"
+      attribute :number, :string # the "<nnn>" field, e.g. "032"
+      # Optional revision suffix, stored as the full lowercased token including
+      # its separator letter: "r1", "c1", "a", "r3a", "r12a". nil when absent.
+      attribute :revision, :string
+
+      # Polymorphic type map for lutaml::Model key_value (de)serialization: maps
+      # the concrete class's polymorphic_name to its class name so a stored hash
+      # rebuilds the correct identifier type via from_hash.
+      OGC_TYPE_MAP = {
+        "pubid:ogc:document" => "Pubid::Ogc::Identifiers::Document",
+      }.freeze
+
+      key_value do
+        map "_type", to: :_type, polymorphic_map: OGC_TYPE_MAP
+        map "year", to: :year
+        map "number", to: :number
+        map "revision", to: :revision
+      end
+
+      # Publisher is always "OGC". 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 = "OGC"
+
+      attr_reader :with_publisher
+
+      # Basic string representation. Delegates to the human renderer. The
+      # printed OGC id carries no publisher token, so with_publisher defaults to
+      # false; pass with_publisher: true to prepend "OGC ".
+      def to_s(**opts)
+        render(format: :human, **opts)
+      end
+
+      # Capture the with_publisher flag on EVERY render call (default false), so
+      # it can never leak across calls: a bare render/to_s always renders
+      # without the publisher token regardless of a prior with_publisher: true.
+      # 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: false, **opts)
+        @with_publisher = with_publisher
+        super(format: format, **opts)
+      end
+
+      # from_hash is the shared polymorphic dispatch on Pubid::Identifier.
+      # OGC_TYPE_MAP remains as the key_value polymorphic_map.
+
+      # Parse an OGC identifier string into an identifier object.
+      # @param identifier [String] The OGC identifier string to parse
+      # @return [Identifier] The document 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/ogc/identifiers/document.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Ogc
+    module Identifiers
+      # The sole OGC identifier type. An OGC document is numbered
+      # `<yy>-<nnn>[<revision>]` with no publisher token in the printed form.
+      class Document < Identifier
+        TYPED_STAGES = [
+          Pubid::Components::TypedStage.new(
+            code: :ogc,
+            stage_code: :published,
+            type_code: :ogc,
+            abbr: ["OGC"],
+            name: "OGC Document",
+            harmonized_stages: [],
+          ),
+        ].freeze
+
+        def self.type
+          { key: :ogc, web: :document, title: "OGC Document", short: "OGC" }
+        end
+      end
+    end
+  end
+end

data/lib/pubid/ogc/identifiers.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Ogc
+    # Namespace for concrete OGC identifier types.
+    module Identifiers
+      autoload :Document, "#{__dir__}/identifiers/document"
+    end
+  end
+end

data/lib/pubid/ogc/parser.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "parslet"
+
+module Pubid
+  module Ogc
+    # Parslet grammar for OGC identifiers.
+    #
+    # Recognizes `<yy>-<nnn>` optionally followed by a revision suffix that
+    # begins with a letter (r/c/a/R…) and may carry a trailing letter
+    # (e.g. "r3a"). An optional leading "OGC" publisher token is accepted for
+    # leniency, though the canonical printed form omits it.
+    #
+    # Examples: "25-023", "24-032r1", "01-009a", "04-095c1", "OGC 24-032r1".
+    class Parser < ::Pubid::Parser::Grammar
+      rule(:space) { match["\\s"].repeat(1) }
+      rule(:digits) { match["0-9"].repeat(1) }
+
+      # Optional leading publisher token, e.g. "OGC " — consumed, not captured.
+      rule(:publisher) { (str("OGC") >> space).maybe }
+
+      # Revision suffix: a run of letters/digits that starts after the numeric
+      # part (which greedily consumes all digits, so the suffix begins with a
+      # separator letter). Kept as a single token for the builder to normalize.
+      rule(:revision) { match["A-Za-z0-9"].repeat(1).as(:revision) }
+
+      rule(:identifier) do
+        publisher >>
+          digits.as(:year) >> str("-") >> digits.as(:number) >>
+          revision.maybe >> space.maybe
+      end
+
+      root(:identifier)
+
+      def self.parse(input)
+        new.parse(input)
+      end
+    end
+  end
+end

data/lib/pubid/ogc/renderer.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Ogc
+    # Human-readable renderer for OGC identifiers.
+    #
+    # Produces the canonical printed form, e.g.:
+    #   "24-032r1"
+    #   "01-009a"
+    #   "OGC 24-032r1"   (only when with_publisher: true)
+    #
+    # Registered as the `:human` format in the OGC format registry and invoked
+    # via `render(format: :human)`.
+    class Renderer < ::Pubid::Renderers::Base
+      PUBLISHER = "OGC"
+
+      def render(**_opts)
+        id = @id
+        result = +""
+        result << "#{PUBLISHER} " if with_publisher?(id)
+        result << "#{id.year}-#{id.number}"
+        result << id.revision.to_s if id.revision
+        result
+      end
+
+      private
+
+      def with_publisher?(id)
+        id.respond_to?(:with_publisher) && id.with_publisher == true
+      end
+    end
+  end
+end

data/lib/pubid/ogc/urn_generator.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Ogc
+    # Emits `urn:ogc:<year>:<number>[:<revision>]`, e.g. `urn:ogc:24:032:r1`.
+    class UrnGenerator < Pubid::UrnGenerator::Base
+      def generate
+        parts = ["urn", "ogc", identifier.year.to_s, identifier.number.to_s]
+        parts << identifier.revision.to_s if identifier.revision
+        parts.join(":")
+      end
+    end
+  end
+end

data/lib/pubid/ogc/urn_parser.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Ogc
+    # Parses OGC URNs back into identifiers.
+    #
+    # UrnGenerator emits: `urn:ogc:<year>:<number>[:<revision>]`.
+    #
+    # Examples:
+    # - urn:ogc:25:023    → 25-023
+    # - urn:ogc:24:032:r1 → 24-032r1
+    class UrnParser < Pubid::UrnParser::Base
+      def parse_urn(urn)
+        body = strip_namespace(urn)
+        year, number, revision = split_parts(body)
+        text = "#{year}-#{number}"
+        text += revision.to_s if revision
+        flavor_parse(text)
+      end
+    end
+  end
+end

data/lib/pubid/ogc.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Ogc
+    extend Pubid::PrefixesSupport
+
+    # OGC identifiers are digit-leading (`25-023`) and carry no publisher token
+    # in the printed form. Per the PREFIXES inclusion policy, bare numeric
+    # patterns are NOT listed (they would make cross-flavor routing ambiguous).
+    # Instead the sole entry is the publisher token "OGC", which relaton uses to
+    # route a reference to this flavor even though it is not literally present
+    # in the id string.
+    PREFIXES = ["OGC"].freeze
+
+    autoload :Builder, "#{__dir__}/ogc/builder"
+    autoload :Identifier, "#{__dir__}/ogc/identifier"
+    autoload :Identifiers, "#{__dir__}/ogc/identifiers"
+    autoload :Parser, "#{__dir__}/ogc/parser"
+    autoload :Renderer, "#{__dir__}/ogc/renderer"
+    autoload :UrnGenerator, "#{__dir__}/ogc/urn_generator"
+    autoload :UrnParser, "#{__dir__}/ogc/urn_parser"
+
+    # Parse an OGC identifier string
+    def self.parse(identifier)
+      Identifier.parse(identifier)
+    end
+
+    # Per-flavor format registry: inherits global formats, overrides :human
+    Identifier.format_registry = FormatRegistry.new(parent: Identifier.format_registry)
+    Identifier.format_registry.register(:human, renderer: Ogc::Renderer)
+
+    # 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
+
+    # 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
+
+# Register OGC flavor with the registry
+Pubid::Registry.register(:ogc, Pubid::Ogc)

data/lib/pubid/oiml/builder.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Oiml
+    class Builder
+      # Type to identifier class mapping (MECE)
+      TYPE_CLASS_MAP = {
+        "B" => "BasicPublication",
+        "Bulletin" => "Bulletin",
+        "D" => "Document",
+        "E" => "ExpertReport",
+        "G" => "Guide",
+        "R" => "Recommendation",
+        "S" => "SeminarReport",
+        "V" => "Vocabulary",
+      }.freeze
+
+      def build(parsed_hash)
+        # Check for short amendment format (has amd_marker)
+        if parsed_hash[:amd_marker]
+          return build_short_amendment(parsed_hash)
+        end
+
+        # Check for supplements first (have base)
+        if parsed_hash[:base]
+          return build_supplement(parsed_hash)
+        end
+
+        # Build base document
+        build_base_document(parsed_hash)
+      end
+
+      private
+
+      def build_short_amendment(parsed_hash)
+        # Build base identifier from the code and type
+        base_hash = {
+          publisher: parsed_hash[:publisher],
+          type: parsed_hash[:type],
+        }
+
+        # Copy number/part/subpart from base_code
+        if parsed_hash[:base_code]
+          base_hash[:number] = parsed_hash[:base_code][:number]
+          if parsed_hash[:base_code][:part]
+            base_hash[:part] =
+              parsed_hash[:base_code][:part]
+          end
+          if parsed_hash[:base_code][:subpart]
+            base_hash[:subpart] =
+              parsed_hash[:base_code][:subpart]
+          end
+        end
+
+        # Build the base document
+        base = build_base_document(base_hash)
+
+        # Create amendment
+        amendment = Identifiers::Amendment.new
+        amendment.base = base
+
+        # Extract year from edition_format if present, otherwise from year directly
+        year_value = if parsed_hash[:edition_format].is_a?(Hash)
+                       parsed_hash[:edition_format][:year]
+                     else
+                       parsed_hash[:year]
+                     end
+
+        amendment.year = year_value.to_s if year_value
+        amendment.language = extract_language(parsed_hash[:language]) if parsed_hash[:language]
+
+        # Track if amendment itself was parsed with Edition format
+        if parsed_hash[:edition_format]
+          amendment.parsed_format = "long"
+        end
+
+        amendment
+      end
+
+      def build_supplement(parsed_hash)
+        marker = parsed_hash[:trailing_marker].to_s if parsed_hash[:trailing_marker]
+        plus_marker = parsed_hash[:plus_marker].to_s if parsed_hash[:plus_marker]
+
+        # Determine supplement type. The trailing word ("Amendment"/"Errata")
+        # selects the class; the concrete class then carries the word via
+        # #supplement_type, so only the `trailing` flag needs storing.
+        supplement_class = if parsed_hash[:annex_letter] || parsed_hash[:annex_marker]
+                             Identifiers::Annex
+                           elsif marker == "Errata" || plus_marker == "Errata"
+                             Identifiers::Errata
+                           else
+                             Identifiers::Amendment
+                           end
+
+        supplement = supplement_class.new
+        supplement.trailing = true if marker
+        supplement.joined = true if plus_marker
+
+        # Recursively parse base identifier
+        if parsed_hash[:base]
+          supplement.base = build(parsed_hash[:base])
+        end
+
+        # Extract year from edition_format if present, otherwise from year directly
+        year_value = if parsed_hash[:edition_format].is_a?(Hash)
+                       parsed_hash[:edition_format][:year]
+                     else
+                       parsed_hash[:year]
+                     end
+
+        # Set supplement-specific attributes
+        supplement.year = year_value.to_s if year_value
+        supplement.language = extract_language(parsed_hash[:language]) if parsed_hash[:language]
+        supplement.letter = parsed_hash[:annex_letter].to_s if parsed_hash[:annex_letter]
+
+        # Annex with no year of its own but a dated base ("R 60:2017 Annexes"):
+        # the year belongs to the base and must render glued to it.
+        if supplement.is_a?(Identifiers::Annex) && !year_value &&
+            supplement.base&.date
+          supplement.year_on_base = true
+        end
+
+        # Track if supplement itself was parsed with Edition format
+        if parsed_hash[:edition_format]
+          supplement.parsed_format = "long"
+        end
+
+        supplement
+      end
+
+      def build_base_document(parsed_hash)
+        # Determine identifier class from type
+        type = parsed_hash[:type].to_s
+        class_name = TYPE_CLASS_MAP[type] || "Recommendation" # Default to R
+        identifier_class = Identifiers.const_get(class_name)
+
+        identifier = identifier_class.new
+
+        # Handle code (number-part-subpart-suffix) specially
+        if parsed_hash[:number] || parsed_hash[:part] || parsed_hash[:subpart] || parsed_hash[:code_suffix]
+          code_attrs = {}
+          if parsed_hash[:number]
+            code_attrs[:number] =
+              parsed_hash[:number].to_s
+          end
+          code_attrs[:part] = parsed_hash[:part].to_s if parsed_hash[:part]
+          if parsed_hash[:subpart]
+            code_attrs[:subpart] =
+              parsed_hash[:subpart].to_s
+          end
+          if parsed_hash[:code_suffix]
+            code_attrs[:suffix] = parsed_hash[:code_suffix].to_s
+            code_attrs[:space_suffix] = true if parsed_hash.key?(:space_suffix)
+          end
+          # The code fields are flat index columns on the leaf (see
+          # Identifiers::CodeNumber) — `number` is what relaton-index keys on —
+          # so they are assigned individually rather than as a Code object.
+          # Bulletin has no code columns and never reaches this branch.
+          code_attrs.each { |name, value| identifier.public_send(:"#{name}=", value) }
+        end
+
+        # Handle other attributes
+        identifier.publisher = parsed_hash[:publisher].to_s if parsed_hash[:publisher]
+
+        # Handle edition attribute
+        identifier.edition = parsed_hash[:edition].to_s if parsed_hash[:edition]
+
+        # Handle year -> date conversion
+        # Year could be in edition_format hash or directly
+        year_value = nil
+        if parsed_hash[:edition_format].is_a?(Hash)
+          year_value = parsed_hash[:edition_format][:year]
+          # Also extract edition if present
+          identifier.edition = parsed_hash[:edition_format][:edition].to_s if parsed_hash[:edition_format][:edition]
+        elsif parsed_hash[:year]
+          year_value = parsed_hash[:year]
+        end
+
+        if year_value
+          identifier.date = Pubid::Components::Date.new(year: year_value.to_s)
+        end
+
+        # Bulletin-specific locator fields. The structured form captures
+        # issue/sequence directly; the citation form captures volume/issue/
+        # article_id, which we decode to the same (year, issue, sequence)
+        # tuple. Year comes from either the date rule (structured) or the
+        # article_id (citation).
+        if identifier.is_a?(Identifiers::Bulletin)
+          apply_bulletin_locator(identifier, parsed_hash)
+        end
+
+        # Determine parsed format for round-trip fidelity
+        # If edition_format was captured, it means "Edition" text was present
+        identifier.parsed_format = if parsed_hash[:edition_format]
+                                     "long"
+                                   elsif parsed_hash[:space_before_lang]
+                                     "short_with_space"
+                                   elsif parsed_hash[:article_id]
+                                     # Bulletin citation form — preserve on
+                                     # the identifier so default to_s gives
+                                     # back the citation string verbatim.
+                                     "citation"
+                                   else
+                                     "short"
+                                   end
+
+        # Handle stage attributes
+        identifier.stage = parsed_hash[:stage].to_s if parsed_hash[:stage]
+        identifier.iteration = parsed_hash[:iteration].to_s if parsed_hash[:iteration]
+
+        # Handle language
+        identifier.language = extract_language(parsed_hash[:language]) if parsed_hash[:language]
+
+        identifier
+      end
+
+      # Populate issue/sequence on a Bulletin from either parse shape.
+      # Structured: :issue and :sequence captured directly as zero-padded
+      # strings. Citation: :volume_roman, :issue_arabic, :article_id —
+      # decode the 8-digit article_id to recover year+issue+sequence.
+      #
+      # For the citation form, the parsed roman volume is cross-checked
+      # against the year decoded from the article_id; a mismatch warns but
+      # does not raise (the article_id is the source of truth — the roman
+      # volume is redundant display).
+      def apply_bulletin_locator(identifier, parsed_hash)
+        if parsed_hash[:article_id]
+          article_id = parsed_hash[:article_id].to_s
+          identifier.date ||= Pubid::Components::Date.new
+          identifier.date.year = article_id[0, 4]
+          identifier.issue = article_id[4, 2]
+          identifier.sequence = article_id[6, 2]
+          warn_on_volume_mismatch(identifier, parsed_hash[:volume_roman])
+          return
+        end
+
+        identifier.issue = parsed_hash[:issue].to_s if parsed_hash[:issue]
+        identifier.sequence = parsed_hash[:sequence].to_s if parsed_hash[:sequence]
+      end
+
+      # Citation form carries the volume in two places: spelled out as a
+      # roman numeral ("LXVII") and encoded in the 8-digit article_id
+      # (year+issue+sequence, where year - 1959 = volume). They should
+      # agree; if they don't, the input was malformed. Warn loudly so the
+      # user sees the discrepancy, but continue using the article_id
+      # (deterministic) rather than the roman (possibly mistyped).
+      def warn_on_volume_mismatch(identifier, parsed_volume_roman)
+        return unless parsed_volume_roman && identifier.date&.year
+
+        declared = parsed_volume_roman.to_s
+        computed = Identifiers::Bulletin.to_roman(identifier.date.year.to_i -
+                                                  Identifiers::Bulletin::BASE_YEAR_OFFSET)
+        return if declared == computed
+
+        warn "OIML Bulletin citation volume mismatch: parsed '#{declared}' " \
+             "but article_id year #{identifier.date.year} implies '#{computed}'"
+      end
+
+      def extract_language(lang_data)
+        # Handle both direct string and nested hash from parser
+        case lang_data
+        when Hash
+          lang_data[:language].to_s
+        else
+          lang_data.to_s
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Oiml
+    module Components
+      # Code component for OIML identifiers.
+      #
+      # Stays independent of Pubid::Components::Code because OIML uses
+      # +number+ as the primary field (shared Code uses +value+). The
+      # shape is otherwise compatible; a future rename of +number+ →
+      # +value+ would let this become a subclass.
+      class Code < Lutaml::Model::Serializable
+        attribute :number, :string
+        attribute :part, :string
+        attribute :subpart, :string
+        # Free-form trailing suffix glued to the code, e.g. "sup", "A",
+        # "erratum", "GUM 1", "ISO3930". Preserved verbatim for round-trip.
+        attribute :suffix, :string
+        # When true the suffix is space-separated ("D 1 Brochure") rather than
+        # the default dash ("R 60-sup").
+        attribute :space_suffix, :boolean, default: false
+
+        def to_s
+          result = number.to_s
+          result += "-#{part}" if part
+          result += "-#{subpart}" if subpart
+          result += "#{space_suffix ? ' ' : '-'}#{suffix}" if suffix
+          result
+        end
+
+        def render(context: nil)
+          to_s
+        end
+      end
+    end
+  end
+end

data/lib/pubid/oiml/components.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Oiml
+    module Components
+      autoload :Code, "#{__dir__}/components/code"
+    end
+  end
+end