pubid 1.15.21 → 2.0.0.alpha.10

data/lib/pubid/ieee/urn_generator.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Ieee
+    class UrnGenerator < Pubid::UrnGenerator::Base
+      def generate
+        parts = ["urn", "ieee"]
+
+        parts << publisher_component
+
+        special_type = special_identifier_type_component
+        parts << special_type if special_type
+
+        tc = type_component
+        parts << tc if tc
+
+        cc = code_component
+        parts << cc if cc
+
+        yc = year_component
+        parts << yc if yc
+
+        dc = draft_component
+        parts << dc if dc
+
+        ec = edition_component
+        parts << ec if ec
+
+        md = month_day_component
+        parts << md if md
+
+        ds = draft_status_component
+        parts << ds if ds
+
+        if !special_type && identifier.redline
+          parts << "redline"
+        end
+
+        if !special_type && identifier.interpretation
+          parts << "int"
+        end
+
+        # Conformance is always a ConformanceIdentifier wrapper (special_type
+        # "conformance"), never inline on a base standard — the base no longer
+        # carries a conf_number attribute, so there is no inline conf part.
+
+        if identifier.ashrae_number
+          ashrae = "ashrae.#{identifier.ashrae_number}"
+          ashrae += "-#{identifier.ashrae_year}" if identifier.ashrae_year
+          parts << ashrae
+        end
+
+        if identifier.crossref
+          parts << "xref.#{identifier.crossref}"
+        end
+
+        if identifier.relationships&.any?
+          rel = identifier.relationships.join("/")
+          parts << "rel.#{rel}"
+        end
+
+        if identifier.revision_of
+          parts << "revof.#{identifier.revision_of}"
+        end
+
+        if identifier.amendment_to
+          parts << "amdto.#{identifier.amendment_to}"
+        end
+
+        if identifier.adoption
+          parts << "adopt.#{identifier.adoption}"
+        end
+
+        reaffirmed = maybe(:reaffirmed)
+        if reaffirmed
+          parts << "reaff.#{reaffirmed}"
+        end
+
+        if identifier.note
+          parts << "note.#{identifier.note}"
+        end
+
+        if identifier.nickname
+          parts << "nick.#{identifier.nickname}"
+        end
+
+        parts.join(":")
+      end
+
+      private
+
+      def special_identifier_type_component
+        class_name = identifier.class.name.to_s
+
+        case class_name
+        when /RedlinedStandard/
+          "redlined"
+        when /SiStandard/
+          "si"
+        when /ConformanceIdentifier/
+          "conformance"
+        when /InterpretationIdentifier/
+          "interpretation"
+        when /SupplementIdentifier/
+          if identifier.typed_stage
+            type_code = identifier.typed_stage.type_code
+            case type_code.to_s
+            when "amd"
+              "amendment"
+            when "cor"
+              "corrigendum"
+            when "errata"
+              "errata"
+            else
+              type_code.to_s
+            end
+          end
+        else
+          if identifier.typed_stage
+            type_code = identifier.typed_stage.type_code
+            case type_code.to_s
+            when "SI"
+              "si"
+            end
+          end
+        end
+      end
+
+      def publisher_component
+        pub = normalized_publisher
+
+        if identifier.copublisher&.any?
+          copubs = identifier.copublisher.map(&:to_s).map(&:downcase)
+          pub = [pub, *copubs].join("-")
+        end
+
+        pub
+      end
+
+      # A dual-published document has TWO publishers, and
+      # DualPublished#publisher returns them as an Array — which `to_s`
+      # rendered into the URN as a literal Ruby array literal, brackets and
+      # quotes included: `urn:ieee:["ieee", "asme"]`. Join them the same way a
+      # copublisher list is joined above.
+      def normalized_publisher
+        names = Array(identifier.publisher)
+          .map { |p| p.to_s.downcase }.reject(&:empty?)
+
+        names.empty? ? "ieee" : names.join("-")
+      end
+
+      def type_component
+        return nil unless identifier.type
+
+        type = identifier.type
+        return nil if !type || type.to_s.strip.empty? || type.to_s == "Std"
+
+        type.to_s.downcase.gsub(" ", ".")
+      end
+
+      def code_component
+        return nil unless identifier.code_obj
+
+        identifier.code_obj.to_s
+      end
+
+      # A multi-designation wrapper (AdoptedStandard, DualPublished,
+      # MultiNumberedIdentifier) carries no year of its own — the year sits on
+      # the designation it wraps — so the URN dropped it and two editions of
+      # one document produced the SAME urn: "AIEE No 15-1944" and
+      # "AIEE No 15-1959" both gave urn:ieee:aiee:15.
+      #
+      # Fixed here, in the one place that reads the year, rather than by
+      # defining a `#year` method on each wrapper: `year` is a lutaml attribute
+      # on the base and a method of that name would shadow its generated
+      # accessor. `#root` already walks to the wrapped designation.
+      def year_component
+        return identifier.year if identifier.year
+
+        root = identifier.root
+        root.equal?(identifier) ? nil : root.year
+      end
+
+      def draft_component
+        return nil unless identifier.draft_obj
+
+        "draft.#{identifier.draft_obj}"
+      end
+
+      def edition_component
+        return nil unless identifier.edition
+
+        "ed.#{identifier.edition}"
+      end
+
+      def month_day_component
+        parts = []
+
+        parts << identifier.month if identifier.month
+        parts << identifier.day if identifier.day
+
+        return nil if parts.empty?
+
+        parts.join("-")
+      end
+
+      def draft_status_component
+        return nil unless identifier.draft_status
+
+        status = identifier.draft_status.downcase
+        status.gsub(" ", ".")
+      end
+    end
+  end
+end

data/lib/pubid/ieee/urn_parser.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Ieee
+    # Parses IEEE URNs back into identifiers.
+    #
+    # UrnGenerator emits many fields; this parser handles the common
+    # published-standard shape:
+    #   urn:ieee:{publisher}:{code}:{year}
+    #
+    # publisher is the lowercase publisher (with optional copublishers
+    # joined by `-`). code is the alphanumeric designation (period is the
+    # part separator within the code). The year separator in human-readable
+    # form is `-`.
+    #
+    # Examples:
+    # - urn:ieee:ieee:802.3:2018 → IEEE Std 802.3-2018
+    # - urn:ieee:ieee:1018:2019  → IEEE Std 1018-2019
+    class UrnParser < Pubid::UrnParser::Base
+      PUBLISHER_LABEL = "IEEE"
+
+      def parse_urn(urn)
+        body = strip_namespace(urn)
+        parts = split_parts(body)
+
+        _publisher, code, year = parts
+
+        text = "#{PUBLISHER_LABEL} Std #{code}"
+        text += "-#{year}" if year
+        flavor_parse(text)
+      end
+    end
+  end
+end

data/lib/pubid/ieee.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Ieee
+    extend Pubid::PrefixesSupport
+
+    # Publisher prefix. The private PreParser::PUBLISHERS list also holds adopted
+    # co-org names (ANSI, AIEE, ASA, ...) that are not leading routing tokens for
+    # an IEEE reference, so they are deliberately excluded. The joint ISO/IEC/IEEE
+    # form comes from Pubid::JOINT_PREFIXES.
+    PREFIXES = ["IEEE"].freeze
+
+    autoload :Aiee, "#{__dir__}/ieee/aiee"
+    autoload :Builder, "#{__dir__}/ieee/builder"
+    autoload :Identifier, "#{__dir__}/ieee/identifiers/base"
+    autoload :Identifiers, "#{__dir__}/ieee/identifiers"
+    autoload :Ire, "#{__dir__}/ieee/ire"
+    autoload :Nesc, "#{__dir__}/ieee/nesc"
+    autoload :Parser, "#{__dir__}/ieee/parser"
+    autoload :PreParser, "#{__dir__}/ieee/pre_parser"
+    autoload :Compaction, "#{__dir__}/ieee/compaction"
+    autoload :Renderer, "#{__dir__}/ieee/renderer"
+    autoload :TypedStages, "#{__dir__}/ieee/typed_stages"
+    autoload :UrnGenerator, "#{__dir__}/ieee/urn_generator"
+    autoload :UrnParser, "#{__dir__}/ieee/urn_parser"
+
+    # Components submodule
+    module Components
+      autoload :Code, "#{__dir__}/ieee/components/code"
+      autoload :Draft, "#{__dir__}/ieee/components/draft"
+      autoload :Relationship, "#{__dir__}/ieee/components/relationship"
+      autoload :TypedStage, "#{__dir__}/ieee/components/typed_stage"
+    end
+
+    # Document-number series carrying an IEEE registered trademark ("®").
+    # 8802 is the ISO/IEC co-published form of the 802 series.
+    REGISTERED_SERIES = %w[802 8802 2030].freeze
+
+    # The ISO/IEC adoption of IEEE 802: the number alone identifies the series,
+    # whatever publishers are printed.
+    ISO_ADOPTED_SERIES = "8802"
+
+    class << self
+      def parse(input)
+        unless input.is_a?(String)
+          raise Pubid::Errors::InvalidInputError,
+                Pubid::INPUT_NOT_A_STRING_MESSAGE
+        end
+
+        if input.length > Pubid::MAX_INPUT_LENGTH
+          raise Pubid::Errors::InvalidInputError, Pubid::INPUT_TOO_LONG_MESSAGE
+        end
+
+        Identifier.parse(input)
+      end
+
+      # True when the document number belongs to a registered-trademark series.
+      # A project number keeps its series identity, so a leading "P" is
+      # stripped. `prefix` is the code's letter series, which must be absent
+      # (or the bare project "P") — "C802.1" is a different series that merely
+      # starts with the same digits. `publishers` guards against claiming an
+      # IEEE registered mark for another body that happens to have numbered a
+      # document 802 or 2030 — "AIEE Std No. 802" predates the IEEE 802 series
+      # by two decades. It is optional: with no publishers given the number
+      # decides, which keeps the plain number lookup usable on its own.
+      # @param number [String, nil] bare document number ("802", "P802")
+      # @param prefix [String, nil] letter series of the code ("C" for C37.09)
+      # @param publishers [Array<String>, String, nil] printed publisher tokens
+      def registered_series?(number, prefix = nil, publishers: nil)
+        return false unless prefix.nil? || prefix.to_s.empty? ||
+          prefix.to_s == "P"
+
+        bare = number.to_s.delete_prefix("P")
+        return false unless REGISTERED_SERIES.include?(bare)
+        return true if bare == ISO_ADOPTED_SERIES || publishers.nil?
+
+        Array(publishers).any? { |p| p.to_s.split("/").include?("IEEE") }
+      end
+
+      # IEEE trademark symbol for a document number: ® for the registered
+      # series, ™ for everything else. This is the entry point render sites
+      # use, because they hold the identifier and so know its number — the
+      # symbol must not depend on where in the rendered string the mark lands.
+      def trademark_symbol_for(number, prefix = nil, publishers: nil)
+        if registered_series?(number, prefix, publishers: publishers)
+          "®"
+        else
+          "™"
+        end
+      end
+
+      # IEEE trademark symbol for a rendered identifier string. Kept for
+      # external callers only — every render site inside pubid passes the
+      # document number to #trademark_symbol_for instead, because the first
+      # numeric token of a rendered string is not reliably the document number
+      # (a NESC or IRE string starts with the publication year).
+      def trademark_symbol(rendered)
+        trademark_symbol_for(rendered.to_s[/(?<![0-9A-Za-z])P?(\d+)/, 1])
+      end
+
+      # Auto-discover all identifier types from the Identifiers namespace
+      # @return [Array<Class>] identifier classes that define a self.type Hash
+      def 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 TypedStages module
+      # @return [Array<Pubid::Components::TypedStage>] all typed stages
+      def all_typed_stages
+        @all_typed_stages ||= TypedStages::TYPED_STAGES
+      end
+
+      # Lookup: type code -> identifier class
+      # @param code [String, Symbol] the type key to find
+      # @return [Class, nil] the matching identifier class
+      def 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 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: IEEE draft notation -> typed stage
+      # @param draft [String] IEEE draft notation (e.g., "D1", "D5", "P")
+      # @return [Pubid::Components::TypedStage, nil] the matching typed stage
+      def locate_stage_by_ieee_draft(draft)
+        return nil if draft.nil? || draft.to_s.strip.empty?
+
+        draft_str = draft.to_s.strip
+
+        # Try exact match on abbreviation first
+        ts = all_typed_stages.find { |t| t.abbr.include?(draft_str) }
+        return ts if ts
+
+        # Try match on ieee_draft_equivalent
+        all_typed_stages.find { |t| t.ieee_draft_equivalent == draft_str }
+      end
+
+      # Lookup: ISO stage code -> typed stage
+      # @param stage [String] ISO stage code (e.g., "WD", "CD", "DIS", "FDIS")
+      # @return [Pubid::Components::TypedStage, nil] the matching typed stage
+      def locate_stage_by_iso_stage(stage)
+        return nil if stage.nil? || stage.to_s.strip.empty?
+
+        all_typed_stages.find { |ts| ts.iso_stage_equivalent == stage.to_s.strip }
+      end
+    end
+  end
+end
+
+Pubid::Registry.register(:ieee, Pubid::Ieee)
+
+# Per-flavor format registry: inherits global formats, overrides :human
+Pubid::Ieee::Identifier.format_registry = Pubid::FormatRegistry.new(parent: Pubid::Identifier.format_registry)
+Pubid::Ieee::Identifier.format_registry.register(:human, renderer: Pubid::Ieee::Renderer)

data/lib/pubid/ieee_debug.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Ieee
+    autoload :Aiee, "#{__dir__}/aiee"
+    autoload :Builder, "#{__dir__}/builder"
+    autoload :Identifier,
+             "#{__dir__}/identifier (DEBUG: __dir__ is \#{__dir__})"
+    autoload :Identifiers, "#{__dir__}/identifiers"
+    autoload :Ire, "#{__dir__}/ire"
+    autoload :Nesc, "#{__dir__}/nesc"
+    autoload :Parser, "#{__dir__}/parser"
+    autoload :TypedStages, "#{__dir__}/typed_stages"
+    autoload :UrnGenerator, "#{__dir__}/urn_generator"
+
+    # Components submodule
+    module Components
+      autoload :Code, "#{__dir__}/components/code"
+      autoload :Draft, "#{__dir__}/components/draft"
+      autoload :Relationship, "#{__dir__}/components/relationship"
+      autoload :TypedStage, "#{__dir__}/components/typed_stage"
+    end
+
+    class << self
+      def parse(input)
+        Identifier.parse(input)
+      end
+    end
+  end
+end

data/lib/pubid/ietf/builder.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Ietf
+    # Turns the Parser's parse tree into a concrete identifier object, choosing
+    # the class from which fields are present.
+    class Builder
+      SUBSERIES_CLASSES = {
+        "BCP" => "Bcp",
+        "STD" => "Std",
+        "FYI" => "Fyi",
+      }.freeze
+
+      def self.build(parsed_data)
+        new.build(parsed_data)
+      end
+
+      def build(data)
+        if data.key?(:draft_rest)
+          build_draft(data)
+        elsif data[:series]
+          build_subseries(data)
+        else
+          build_rfc(data)
+        end
+      end
+
+      private
+
+      def build_rfc(data)
+        Identifiers::Rfc.new(number: unpad(data[:number]))
+      end
+
+      # The series token only selects the class: it is derived back from the
+      # class (Identifiers::Std::SERIES) rather than stored, since `_type`
+      # already carries it.
+      def build_subseries(data)
+        klass = Identifiers.const_get(
+          SUBSERIES_CLASSES.fetch(data[:series].to_s),
+        )
+        klass.new(number: unpad(data[:number]))
+      end
+
+      # Strip the zero-padding the RFC editor's rfc-index.xml writes ("STD0066",
+      # "RFC0001") so the canonical printed form is the unpadded one. The
+      # look-ahead keeps the last digit, so an all-zero number stays "0" rather
+      # than becoming empty.
+      def unpad(number)
+        number.to_s.sub(/\A0+(?=\d)/, "")
+      end
+
+      def build_draft(data)
+        full = "draft-#{data[:draft_rest]}"
+        slug, version = split_draft_version(full)
+        Identifiers::InternetDraft.new(number: slug, version: version)
+      end
+
+      # An Internet-Draft version is a trailing "-NN" of *exactly* two digits at
+      # the very end of the slug. A three-digit topic tail (e.g. "...-256") is
+      # NOT a version: there the char before the last two digits is itself a
+      # digit, not "-", so the guard below leaves it in the slug. This also
+      # means a (non-existent in practice) revision >= 100 would be read as part
+      # of the slug — IETF drafts are always two-digit-versioned, so that case
+      # never arises. Either way the printed string round-trips exactly.
+      #
+      # Dotted slugs need no special handling here: only the final three
+      # characters are inspected, so "draft-ietf-pilc-2.5g3g-12" splits into
+      # ("draft-ietf-pilc-2.5g3g", "12").
+      def split_draft_version(full)
+        if full.length > 3 && full[-3] == "-" && full[-2..].match?(/\A\d\d\z/)
+          [full[0...-3], full[-2..]]
+        else
+          [full, nil]
+        end
+      end
+    end
+  end
+end

data/lib/pubid/ietf/identifier.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Pubid::Ietf::Identifier is the IETF base class and the flavor's parse entry
+# point; its body lives in
+# identifiers/base.rb (mirrors the AMCA layout).

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Ietf
+    # Base class for every IETF identifier AND the flavor's parse/create entry
+    # point (mirrors Pubid::Jis::Identifier). Concrete identifiers under
+    # Pubid::Ietf::Identifiers descend from this class, so a parsed IETF id is
+    # an instance of Pubid::Ietf::Identifier.
+    #
+    # All families are flat, supplement-free, and use plain string attributes.
+    # Those attributes are declared on the LEAVES by Identifiers::Serialization
+    # (see the determinism note there — never re-add `attribute :number` here):
+    #   * Rfc            -> number ("2119")
+    #   * Bcp/Std/Fyi    -> number ("3") + a derived `series` reader
+    #   * InternetDraft  -> number ("draft-giuliano-treedn") + optional version
+    class Identifier < ::Pubid::Identifier
+      # Polymorphic type map for lutaml::Model key_value (de)serialization: maps
+      # each subclass's polymorphic_name to its class name so a stored hash
+      # rebuilds the correct identifier type via the shared from_hash dispatch.
+      IETF_TYPE_MAP = {
+        "pubid:ietf:rfc" => "Pubid::Ietf::Identifiers::Rfc",
+        "pubid:ietf:bcp" => "Pubid::Ietf::Identifiers::Bcp",
+        "pubid:ietf:std" => "Pubid::Ietf::Identifiers::Std",
+        "pubid:ietf:fyi" => "Pubid::Ietf::Identifiers::Fyi",
+        "pubid:ietf:internet-draft" =>
+          "Pubid::Ietf::Identifiers::InternetDraft",
+      }.freeze
+
+      # NOTE: no `key_value` block here on purpose. The mapping lives on the
+      # leaves (Identifiers::Serialization); a block on this shared parent would
+      # be inherited-and-merged by every leaf and re-emit keys the leaf did not
+      # declare.
+
+      # Publisher is always "IETF". 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 = "IETF"
+
+      # Basic string representation. Delegates to the flavor renderer.
+      def to_s(**opts)
+        render(format: :human, **opts)
+      end
+
+      # from_hash is the shared polymorphic dispatch on Pubid::Identifier; the
+      # IETF_TYPE_MAP above serves as its key_value polymorphic_map.
+
+      # Parse an IETF identifier string into the appropriate identifier object.
+      # @param identifier [String] the IETF identifier string to parse
+      # @return [Identifier] the concrete identifier object
+      # @raise [Pubid::Errors::InvalidInputError] if the input exceeds
+      #   Pubid::MAX_INPUT_LENGTH
+      # @raise [Pubid::Errors::ParseError] if parsing fails
+      def self.parse(identifier)
+        # Inline length guard (CodeQL rb/polynomial-redos barrier) — must be
+        # the first statement. This class-level funnel is what relaton reaches
+        # directly through `pubid_class: ::Pubid::Ietf::Identifier`, so it
+        # cannot rely on the guard in Pubid::Ietf.parse.
+        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/ietf/identifiers/bcp.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Ietf
+    module Identifiers
+      # A BCP (Best Current Practice) sub-series id, e.g. "BCP 3".
+      class Bcp < Identifier
+        include Serialization
+
+        # The series token is derived from the class, not stored:
+        # `_type` already encodes it, so serializing `series` would
+        # duplicate the type in every index row.
+        SERIES = "BCP"
+
+        def series
+          SERIES
+        end
+
+        TYPED_STAGES = [
+          Pubid::Components::TypedStage.new(
+            code: :bcp,
+            stage_code: :published,
+            type_code: :bcp,
+            abbr: ["BCP"],
+            name: "Best Current Practice",
+            harmonized_stages: [],
+          ),
+        ].freeze
+
+        def self.type
+          { key: :bcp, web: :bcp, title: "Best Current Practice", short: "BCP" }
+        end
+      end
+    end
+  end
+end

data/lib/pubid/ietf/identifiers/fyi.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Ietf
+    module Identifiers
+      # An FYI (For Your Information) sub-series id, e.g. "FYI 1".
+      class Fyi < Identifier
+        include Serialization
+
+        # The series token is derived from the class, not stored:
+        # `_type` already encodes it, so serializing `series` would
+        # duplicate the type in every index row.
+        SERIES = "FYI"
+
+        def series
+          SERIES
+        end
+
+        TYPED_STAGES = [
+          Pubid::Components::TypedStage.new(
+            code: :fyi,
+            stage_code: :published,
+            type_code: :fyi,
+            abbr: ["FYI"],
+            name: "For Your Information",
+            harmonized_stages: [],
+          ),
+        ].freeze
+
+        def self.type
+          { key: :fyi, web: :fyi, title: "For Your Information", short: "FYI" }
+        end
+      end
+    end
+  end
+end