pubid 1.15.21 → 2.0.0.alpha.10

data/lib/pubid/sae/identifiers.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Sae
+    module Identifiers
+    end
+  end
+end

data/lib/pubid/sae/parser.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "parslet"
+
+module Pubid
+  module Sae
+    class Parser < ::Pubid::Parser::Grammar
+      rule(:space) { str(" ") }
+      rule(:digit) { match["0-9"] }
+      rule(:digits) { digit.repeat(1) }
+      rule(:letter) { match["A-Z"] }
+      rule(:colon) { str(":") }
+
+      # Publisher
+      rule(:publisher) { str("SAE").as(:publisher) }
+
+      # Document types with optional number suffix (e.g., J300, J308A)
+      rule(:doc_type) do
+        (
+          str("AMS") |  # Aerospace Material Specification
+          str("AIR") |  # Aerospace Information Report
+          str("ARP") |  # Aerospace Recommended Practice
+          str("AS") |   # Aerospace Standard
+          str("J") |    # SAE Standard (e.g., J300)
+          str("MA")     # Material Advisory
+        ).as(:type)
+      end
+
+      # Number with optional letter prefix or suffix
+      rule(:number) do
+        ((letter.repeat(1,
+                        1) >> digits) | (digits >> letter.repeat(0,
+                                                                 1))).as(:number)
+      end
+
+      # Year
+      rule(:year) { digit.repeat(4, 4).as(:year) }
+
+      # Date
+      rule(:date) { colon >> year }
+
+      # Main identifier
+      rule(:identifier) do
+        publisher >> space >> doc_type >> space.maybe >>
+          number >> date.maybe
+      end
+
+      root(:identifier)
+
+      def self.parse(input)
+        new.parse(input)
+      end
+    end
+  end
+end

data/lib/pubid/sae/renderer.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Sae
+    # Human-readable renderer for SAE identifiers.
+    #
+    # Produces strings like:
+    #   "SAE AS5553"
+    #   "SAE ARP4754A"
+    #   "SAE AMS2475:2023"
+    #
+    # The renderer is registered as the +:human+ format in the SAE format
+    # registry and invoked via +render(format: :human)+.
+    class Renderer < ::Pubid::Renderers::Base
+      def render(context: nil, **_opts)
+        id = @id
+
+        parts = []
+
+        # Publisher and type
+        parts << id.publisher if id.publisher
+        parts << id.type.to_s if id.type
+
+        # Number
+        parts << id.number.to_s if id.number
+
+        result = parts.join(" ")
+
+        # Date
+        result += ":#{id.date.render(context:)}" if id.date
+
+        result
+      end
+    end
+  end
+end

data/lib/pubid/sae/urn_generator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Sae
+    class UrnGenerator < Pubid::UrnGenerator::Base
+      def urn_type
+        return "std" unless identifier.type
+
+        identifier.type.abbr.to_s.downcase
+      end
+
+      def urn_number
+        return nil unless identifier.number
+
+        identifier.number.render(context: URN_CONTEXT)
+      end
+
+      def generate
+        parts = ["urn", "sae"]
+        parts << urn_type
+        parts << urn_number if urn_number
+        parts << urn_year if urn_year
+
+        parts[1] = urn_publisher if urn_publisher
+
+        parts.join(":")
+      end
+    end
+  end
+end

data/lib/pubid/sae/urn_parser.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Sae
+    # Parses SAE URNs back into identifiers.
+    #
+    # UrnGenerator emits:
+    #   urn:sae:{type|std}:{number}:{year}
+    # where slot[1] is overwritten with the publisher string when a publisher
+    # is set. The common single-publisher case keeps slot[1] = "sae".
+    #
+    # Examples:
+    # - urn:sae:j:300:2019     → SAE J300:2019
+    # - urn:sae:air:500        → SAE AIR500
+    # - urn:sae:ams:5000:2020  → SAE AMS5000:2020
+    class UrnParser < Pubid::UrnParser::Base
+      def parse_urn(urn)
+        body = strip_namespace(urn)
+        parts = split_parts(body)
+
+        type_token, number, year = parts
+        text = build_text(type_token, number, year)
+        flavor_parse(text)
+      end
+
+      private
+
+      def build_text(type_token, number, year)
+        head = type_token == "std" ? "" : type_token.upcase
+        text = "SAE #{head}#{number}"
+        text += ":#{year}" if year
+        text
+      end
+    end
+  end
+end

data/lib/pubid/sae.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Sae
+    extend Pubid::PrefixesSupport
+
+    # Sole SAE publisher token (see the parser's `publisher` rule). Document
+    # types (AMS/AIR/ARP/AS/J/MA) follow the SAE prefix and are excluded.
+    PREFIXES = ["SAE"].freeze
+
+    autoload :Builder, "#{__dir__}/sae/builder"
+    autoload :Components, "#{__dir__}/sae/components"
+    autoload :Identifier, "#{__dir__}/sae/identifiers/base"
+    autoload :Identifiers, "#{__dir__}/sae/identifiers"
+    autoload :Parser, "#{__dir__}/sae/parser"
+    autoload :Renderer, "#{__dir__}/sae/renderer"
+    autoload :UrnGenerator, "#{__dir__}/sae/urn_generator"
+    autoload :UrnParser, "#{__dir__}/sae/urn_parser"
+
+    def self.parse(input)
+      Identifier.parse(input)
+    end
+
+    # Auto-discover all identifier types from the Identifiers namespace.
+    # SAE has only one identifier class (Base), which IS the document type.
+    # @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 }
+    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
+
+Pubid::Registry.register(:sae, Pubid::Sae)
+
+# Per-flavor format registry: inherits global formats, overrides :human
+Pubid::Sae::Identifier.format_registry = Pubid::FormatRegistry.new(parent: Pubid::Identifier.format_registry)
+Pubid::Sae::Identifier.format_registry.register(:human, renderer: Pubid::Sae::Renderer)

data/lib/pubid/tgpp/builder.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Tgpp
+    class Builder
+      def self.build(parsed_data)
+        new.build(parsed_data)
+      end
+
+      def build(data)
+        identifier_class(data[:type]).new(
+          number: data[:number].to_s,
+          suffix: data[:suffix]&.to_s,
+          parts: extract_part_strings(data[:parts]),
+          release: data[:release]&.to_s,
+          version: data[:version]&.to_s,
+        )
+      end
+
+      private
+
+      def identifier_class(type)
+        if type.to_s == "TR"
+          Identifiers::TechnicalReport
+        else
+          Identifiers::TechnicalSpecification
+        end
+      end
+
+      # parts_data is an array of `{ part: "1" }` hashes (or a single hash for a
+      # one-level part); return the part numbers as strings.
+      def extract_part_strings(parts_data)
+        case parts_data
+        when Array then parts_data.filter_map { |h| h[:part]&.to_s }
+        when Hash then [parts_data[:part]&.to_s].compact
+        else []
+        end
+      end
+    end
+  end
+end

data/lib/pubid/tgpp/identifier.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Tgpp
+    # Base class for every 3GPP identifier AND the flavor's parse entry point —
+    # mirrors Pubid::Jis::Identifier. Concrete identifiers under
+    # Pubid::Tgpp::Identifiers descend from this class, so a parsed 3GPP id is
+    # an instance of Pubid::Tgpp::Identifier.
+    class Identifier < ::Pubid::Identifier
+      # The dotted core (e.g. "23.207") kept as a string to preserve leading
+      # zeros. `number` overrides the base Components::Code attribute.
+      attribute :number, :string
+      # Optional letter suffix directly after the number: "U", "dcs", "ext"…
+      attribute :suffix, :string
+      # 1–2 hyphen parts (e.g. "26.171-1", "29.198-04-1"); strings preserve any
+      # zero-padding.
+      # `initialize_empty` makes a part-less identifier hold `[]` on BOTH
+      # construction paths: Builder always passes an array, but the serialized
+      # hash carries no `parts` key, so from_hash used to leave it nil and the
+      # two compared unequal — which silently broke `#matches?` (and so every
+      # part-less relaton index lookup). It does not change the serialized
+      # shape: lutaml omits an empty collection either way. See CLAUDE.md.
+      attribute :parts, :string, collection: true, initialize_empty: true
+      # Raw release token, stored verbatim: "REL-4", "Ph1", "UMTS",
+      # "Release 2000".
+      attribute :release, :string
+      # Three-part version string, e.g. "2.0.0".
+      attribute :version, :string
+
+      # Polymorphic type map for lutaml::Model key_value (de)serialization.
+      # Keys are the `pubid:3gpp:…` names produced by polymorphic_name (below).
+      TGPP_TYPE_MAP = {
+        "pubid:3gpp:technical-report" =>
+          "Pubid::Tgpp::Identifiers::TechnicalReport",
+        "pubid:3gpp:technical-specification" =>
+          "Pubid::Tgpp::Identifiers::TechnicalSpecification",
+      }.freeze
+
+      key_value do
+        map "_type", to: :_type, polymorphic_map: TGPP_TYPE_MAP
+        map "number", to: :number
+        map "suffix", to: :suffix
+        map "parts", to: :parts
+        map "release", to: :release
+        map "version", to: :version
+      end
+
+      # Publisher token. A plain constant (not a `publisher` method) so it does
+      # not shadow the inherited lutaml `publisher` attribute.
+      PUBLISHER = "3GPP"
+
+      # The auto-derived polymorphic name would be "pubid:tgpp:…" (from the
+      # module constant). Force the "3gpp" segment so the `_type` tag matches
+      # the relaton flavor name and TGPP_TYPE_MAP.
+      def self.polymorphic_name
+        super&.sub(/\Apubid:tgpp:/, "pubid:3gpp:")
+      end
+
+      # Rendering flag: whether to prefix the string with "3GPP ". Transient
+      # (not serialized). #to_s sets it, renders, then resets it to false in an
+      # ensure block, so a subsequent bare #render defaults to no publisher and
+      # the flag never leaks past the to_s call that set it.
+      attr_reader :with_publisher
+
+      # The rendered document code, e.g. "29.198-04-1" (number+suffix+parts).
+      def code
+        result = "#{number}#{suffix}"
+        result += parts.map { |p| "-#{p}" }.join if parts&.any?
+        result
+      end
+
+      # Basic string representation. Delegates to the :human renderer. Default
+      # omits the "3GPP " publisher token (matches the relaton index id);
+      # `to_s(with_publisher: true)` emits the printed "3GPP TS …" form.
+      def to_s(with_publisher: false, **opts)
+        @with_publisher = with_publisher
+        render(format: :human, **opts)
+      ensure
+        @with_publisher = false
+      end
+
+      # Parse a 3GPP identifier string into an identifier object.
+      #
+      # Let Parslet::ParseFailed propagate on a bad reference (matching ISO and
+      # ETSI), so relaton-cli's `rescue Parslet::ParseFailed` fetch handler
+      # catches it instead of a bare RuntimeError. The length guard keeps its
+      # ArgumentError — that is a different failure (input too long, not
+      # unparseable) and it is the ReDoS barrier.
+      #
+      # @param identifier [String] The 3GPP identifier string to parse
+      # @return [Identifier] The appropriate identifier object
+      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
+
+        parsed = Parser.parse(identifier)
+        Builder.build(parsed)
+      end
+    end
+  end
+end

data/lib/pubid/tgpp/identifiers/technical_report.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Tgpp
+    module Identifiers
+      # Technical Report identifier type.
+      # Format: [3GPP ]TR NN.NNN[suffix][-part…][:<release>][/<version>]
+      # Example: TR 00.01U:UMTS/3.0.0, or the partial "TR 00.01U".
+      class TechnicalReport < Pubid::Tgpp::Identifier
+        TYPED_STAGES = [
+          Pubid::Components::TypedStage.new(
+            code: :tr,
+            stage_code: :published,
+            type_code: :tr,
+            abbr: ["TR"],
+            name: "Technical Report",
+            harmonized_stages: [],
+          ),
+        ].freeze
+
+        def self.type
+          { key: :tr,
+            web: :technical_report, title: "Technical Report", short: "TR" }
+        end
+
+        def type_prefix
+          "TR"
+        end
+      end
+    end
+  end
+end

data/lib/pubid/tgpp/identifiers/technical_specification.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Tgpp
+    module Identifiers
+      # Technical Specification identifier type.
+      # Format: [3GPP ]TS NN.NNN[suffix][-part…][:<release>][/<version>]
+      # Example: TS 23.207:REL-4/2.0.0, or the partial "TS 23.207".
+      class TechnicalSpecification < Pubid::Tgpp::Identifier
+        TYPED_STAGES = [
+          Pubid::Components::TypedStage.new(
+            code: :ts,
+            stage_code: :published,
+            type_code: :ts,
+            abbr: ["TS"],
+            name: "Technical Specification",
+            harmonized_stages: [],
+          ),
+        ].freeze
+
+        def self.type
+          { key: :ts,
+            web: :technical_specification,
+            title: "Technical Specification", short: "TS" }
+        end
+
+        def type_prefix
+          "TS"
+        end
+      end
+    end
+  end
+end

data/lib/pubid/tgpp/identifiers.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Tgpp
+    module Identifiers
+      autoload :TechnicalReport, "#{__dir__}/identifiers/technical_report"
+      autoload :TechnicalSpecification,
+               "#{__dir__}/identifiers/technical_specification"
+    end
+  end
+end

data/lib/pubid/tgpp/parser.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "parslet"
+
+module Pubid
+  module Tgpp
+    # Parslet grammar for 3GPP identifiers.
+    #
+    # Form: `[3GPP ]<TR|TS> <NN.NNN>[suffix][-part…][:<release>][/<version>]`
+    #   TS 23.207:REL-4/2.0.0
+    #   3GPP TR 00.01U:UMTS/3.0.0
+    #   TS 29.198-04-1:REL-5/5.0.0
+    #   TS 02.68:Release 2000/9.0.0
+    #   3GPP TS 23.207                (bare reference)
+    #
+    # The release and the version are both optional: a user reference names the
+    # document alone ("3GPP TS 23.207"), and relaton parses that bare form to
+    # search the index. Only the type and the dotted number core are required,
+    # so "TS" and "TS foo" are still rejected.
+    class Parser < ::Pubid::Parser::Grammar
+      rule(:digit) { match["0-9"] }
+      rule(:digits) { digit.repeat(1) }
+      rule(:space) { str(" ") }
+
+      # Optional leading publisher token.
+      rule(:publisher_prefix) { str("3GPP") >> space }
+
+      # Document type.
+      rule(:type) { (str("TR") | str("TS")).as(:type) }
+
+      # Dotted number core, kept as a string (preserves leading zeros).
+      rule(:number_core) { (digits >> str(".") >> digits).as(:number) }
+
+      # Letter suffix directly after the number ("U"/"dcs"/"ext"…). Generic so
+      # future controlled-vocabulary values keep round-tripping.
+      rule(:suffix) { match["A-Za-z"].repeat(1).as(:suffix) }
+
+      # Hyphen parts.
+      rule(:part) { str("-") >> digits.as(:part) }
+      rule(:parts) { part.repeat(0).as(:parts) }
+
+      # Release token, stored verbatim: everything up to the version separator.
+      # Excludes ":" (as well as "/") so the ":"-delimited URN scheme can always
+      # encode it — every real release ("REL-4", "Ph1", "UMTS", "Release 2000")
+      # is colon-free.
+      #
+      # A trailing segment shaped exactly like a version is a mistyped "/"
+      # separator ("TS 23.207:2.0.0"), not a release: no release in the 88,464
+      # published index rows contains a dot at all. Reject it rather than
+      # silently misfiling the version as the release — which only became
+      # reachable once the version segment was made optional.
+      rule(:release) do
+        (version_core >> any.absent?).absent? >>
+          match["^/:"].repeat(1).as(:release)
+      end
+
+      # Three-part version, kept as a string.
+      rule(:version_core) do
+        digits >> str(".") >> digits >> str(".") >> digits
+      end
+      rule(:version) { version_core.as(:version) }
+
+      rule(:identifier) do
+        publisher_prefix.maybe >>
+          type >> space >>
+          number_core >> suffix.maybe >> parts >>
+          (str(":") >> release).maybe >>
+          (str("/") >> version).maybe
+      end
+
+      rule(:root) { identifier }
+
+      def self.parse(input)
+        new.parse(input)
+      end
+    end
+  end
+end

data/lib/pubid/tgpp/renderer.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Tgpp
+    # Human-readable renderer for 3GPP identifiers.
+    #
+    # Produces strings like:
+    #   "TS 23.207:REL-4/2.0.0"                (default, no publisher)
+    #   "3GPP TS 23.207:REL-4/2.0.0"           (with_publisher: true)
+    #   "TS 29.198-04-1:REL-5/5.0.0"           (parts)
+    #   "TR 00.01U:UMTS/3.0.0"                 (suffix)
+    #   "TS 23.207"                            (partial reference)
+    class Renderer < ::Pubid::Renderers::Base
+      PUBLISHER = "3GPP"
+
+      def render(context: nil, **_opts)
+        id = @id
+        head = []
+        head << PUBLISHER if with_publisher?(id)
+        head << id.type_prefix
+        "#{head.join(' ')} #{id.code}#{qualifiers(id)}"
+      end
+
+      private
+
+      # The trailing ":<release>" and "/<version>" qualifiers. Both are
+      # optional: a handful of legacy records omit the release entirely
+      # (e.g. "TS 29.215/2.0.0"), and a partial user reference omits both
+      # (e.g. "TS 23.207"). Render no separator for an absent one.
+      #
+      # Blank, not just nil: the grammar cannot produce "", but a hand-built
+      # hash can, and a dangling "TS 23.207:" would not re-parse. This mirrors
+      # the same guard in UrnGenerator#tail_segments.
+      def qualifiers(id)
+        result = +""
+        result << ":#{id.release}" unless blank?(id.release)
+        result << "/#{id.version}" unless blank?(id.version)
+        result
+      end
+
+      def blank?(value)
+        value.nil? || value.empty?
+      end
+
+      # Default is no publisher token (the relaton index id form); the caller
+      # opts in via `to_s(with_publisher: true)`.
+      def with_publisher?(id)
+        id.with_publisher == true
+      end
+    end
+  end
+end

data/lib/pubid/tgpp/urn_generator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Tgpp
+    # Emits `urn:3gpp:<type>:<code>:<release>:<version>`, e.g.
+    # `urn:3gpp:ts:23.207:REL-4:2.0.0`. `<code>` is number+suffix+parts.
+    #
+    # A partial identifier has no release, no version, or neither. Only the
+    # TRAILING empty segments are dropped, so a bare reference gets the clean
+    # `urn:3gpp:ts:23.207` rather than a malformed `urn:3gpp:ts:23.207::`. An
+    # INTERIOR empty segment is kept, so the release-less form keeps the URN it
+    # has always emitted: `TS 29.215/2.0.0` -> `urn:3gpp:ts:29.215::2.0.0`.
+    class UrnGenerator < Pubid::UrnGenerator::Base
+      def generate
+        (head_segments + tail_segments).join(":")
+      end
+
+      private
+
+      # The namespace, the document type and the code. Always present.
+      def head_segments
+        ["urn", "3gpp", identifier.type_prefix.downcase, identifier.code]
+      end
+
+      # The two optional qualifiers, with the trailing empty ones removed.
+      def tail_segments
+        segments = [identifier.release, identifier.version]
+        # NOTE: `empty?`, not `any?` — a bare `Array#any?` tests element
+        # truthiness, so `[nil, nil].any?` is false and would strip nothing.
+        segments.pop until segments.empty? || !blank?(segments.last)
+        segments.map(&:to_s)
+      end
+
+      def blank?(value)
+        value.nil? || value.empty?
+      end
+    end
+  end
+end

data/lib/pubid/tgpp/urn_parser.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Tgpp
+    # Parses 3GPP URNs back into identifiers.
+    #
+    # UrnGenerator emits `urn:3gpp:<type>:<code>:<release>:<version>`; the code,
+    # release and version chunks never contain ":", so a plain split recovers
+    # them. Example: urn:3gpp:ts:23.207:REL-4:2.0.0 → TS 23.207:REL-4/2.0.0
+    class UrnParser < Pubid::UrnParser::Base
+      # The module is Tgpp but the URN namespace is "3gpp".
+      def flavor_name
+        "3gpp"
+      end
+
+      def parse_urn(urn)
+        body = strip_namespace(urn)
+        type, code, release, version = split_parts(body)
+        # A partial identifier drops its trailing segments, and the no-release
+        # form (e.g. TS 29.215/2.0.0) serialises with an empty release chunk
+        # ("urn:3gpp:ts:29.215::2.0.0"). Rebuild only the segments present, so
+        # neither the release colon nor the version slash dangles.
+        result = "#{type.upcase} #{code}"
+        result += ":#{release}" unless release.nil? || release.empty?
+        result += "/#{version}" unless version.nil? || version.empty?
+        flavor_parse(result)
+      end
+    end
+  end
+end