pubid 1.15.21 → 2.0.0.alpha.10

data/lib/pubid/ieee/renderer.rb

@@ -0,0 +1,408 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Ieee
+    # Human-readable renderer for IEEE identifiers.
+    #
+    # Produces strings like:
+    #   "IEEE Std 802.11-2020"
+    #   "IEEE Std 535-2013/Cor. 1-2017"
+    #   "ANSI C37.61-1973 and IEEE Std 321-1973"
+    #
+    # The renderer is registered as the +:human+ format in the IEEE format
+    # registry and invoked via +render(format: :human)+.
+    #
+    # For wrapper types (DualPublished, AdoptedStandard, etc.) the renderer
+    # composes child identifiers. For simple identifiers it delegates to the
+    # identifier's own publisher/code/relationship helpers.
+    class Renderer < ::Pubid::Renderers::Base
+      def render(context: nil, **opts)
+        # IEEE attaches the trademark mark to the document number, before the
+        # year and every suffix ("IEEE Std 802.3®-2018"), so the mark is
+        # emitted by whichever method renders the number rather than appended
+        # to the finished string. A renderer instance is built per render call
+        # (Pubid::Identifier#render), so the flag is safe as instance state.
+        @trademark = opts[:trademark]
+
+        render_id(@id)
+      end
+
+      private
+
+      # Trademark mark for a document number, or "" when the flag is off.
+      # @param number [String, nil] bare document number
+      # @param prefix [String, nil] letter series of the code
+      # @param publishers [Array<String>] printed publisher tokens — the ®
+      #   series belongs to IEEE, not to another body numbering a document 802
+      def mark(number, prefix = nil, publishers: nil)
+        return "" unless @trademark
+
+        Pubid::Ieee.trademark_symbol_for(number, prefix, publishers: publishers)
+      end
+
+      # The publisher tokens an identifier prints, for the ® decision.
+      def publishers_of(id)
+        return id.publishers if id.respond_to?(:publishers) && id.publishers
+
+        copublishers = id.copublisher if id.respond_to?(:copublisher)
+        [id.publisher, *copublishers].compact
+      end
+
+      # Compose a child identifier, propagating the trademark flag only when it
+      # is safe. A foreign (non-IEEE) leaf may not accept the `trademark:`
+      # keyword at all — Pubid::Nist's `to_s(format = :short)` would silently
+      # swallow it as a positional Hash, and Pubid::Iso's would raise — and an
+      # adopted or parenthetical child is not the IEEE document being marked.
+      def child_to_s(child, **opts)
+        return child.to_s(**opts) unless @trademark &&
+          child.is_a?(Pubid::Ieee::Identifier)
+
+        child.to_s(**opts, trademark: true)
+      end
+
+      # Dispatch to the type-specific renderer, returning the composed string
+      # (each branch inserts the trademark mark at its own number boundary).
+      def render_id(id)
+        case id
+        when Identifiers::DualPublished
+          render_dual_published(id)
+        when Identifiers::DualIdentifier
+          render_dual_identifier(id)
+        when Identifiers::AdoptedStandard
+          render_adopted_standard(id)
+        when Identifiers::RedlinedStandard
+          render_redlined_standard(id)
+        when Identifiers::Amendment
+          render_amendment(id)
+        when Identifiers::Corrigendum
+          render_corrigendum(id)
+        when Identifiers::InterpretationIdentifier
+          render_interpretation(id)
+        when Identifiers::ConformanceIdentifier
+          render_conformance(id)
+        when Identifiers::MultiNumberedIdentifier
+          render_multi_numbered(id)
+        when Identifiers::ParentheticalIdentifier
+          render_parenthetical(id)
+        when Identifiers::CsaDualPublished
+          render_csa_dual_published(id)
+        when Identifiers::IecIeeeCopublished
+          render_iec_ieee_copublished(id)
+        when Identifiers::SiStandard
+          render_si_standard(id)
+        when Identifiers::JointDevelopment
+          child_to_s(id)
+        else
+          render_base(id)
+        end
+      end
+
+      # ------------------------------------------------------------------
+      # Base IEEE identifier rendering
+      # ------------------------------------------------------------------
+
+      def render_base(id)
+        parts = []
+
+        # Publisher(s) - handle copublisher array properly
+        if id.copublisher && !id.copublisher.empty?
+          parts << [id.publisher, *id.copublisher].join("/")
+        else
+          parts << id.publisher
+        end
+
+        # Draft status
+        parts << id.draft_status if id.draft_status
+
+        # Type - only render for IEEE/AIEE publishers, and only for non-projects.
+        # An unapproved draft is not yet a standard, so per IEEE guidance the
+        # "Std" token is dropped from the type when draft_status is "Unapproved"
+        # (e.g. "Draft Std" -> "Draft", "Std" -> "").
+        should_render_type = id.publisher&.match?(/^(IEEE|AIEE)/)
+
+        if should_render_type && !id.typed_stage&.project_status && id.type && !id.type.to_s.strip.empty? && id.type != "P"
+          type_str = id.type.dup
+          type_str = type_str.sub(/^P/, "") if type_str.start_with?("P")
+          if id.draft_status.to_s.match?(/unapproved/i)
+            type_str = type_str.gsub(/\bStd\b/i, "").squeeze(" ").strip
+          end
+          parts << type_str unless type_str.strip.empty?
+        end
+
+        # Code - with P prefix for projects (concatenated, not separated)
+        if id.code_obj
+          result = id.code_obj.to_s
+
+          # Prepend P if this is a project AND code doesn't already have P
+          if id.typed_stage&.project_status && should_render_type && !result.start_with?("P")
+            result = "P#{result}"
+          end
+
+          # Trademark mark — right after the number and its parts, before the
+          # year, the revision, the draft and every other suffix.
+          result += mark(id.code_obj.number, id.code_obj.prefix,
+                         publishers: publishers_of(id))
+
+          # Only attach year to code if there's no edition, no month, and no draft
+          result += "-#{id.year}" if id.year && !id.draft_obj && !id.edition && !id.month
+
+          # Append the numbered/lettered revision inline, in IEEE's native
+          # position — right after the code number and before the draft
+          # ("P802.16Rev2/D3"). Keeps a revision distinct from its base standard.
+          result += "Rev#{id.revision}" if id.revision
+
+          # Append draft to code - with or without space based on original format
+          if id.draft_obj
+            result += id.space_before_draft ? " #{id.draft_obj}" : id.draft_obj.to_s
+          end
+
+          # Append interpretation notation (/INT)
+          result += "/INT" if id.interpretation
+
+          # Conformance is always built as a ConformanceIdentifier wrapper
+          # (render_conformance), never inline on a base standard — the base no
+          # longer carries a conf_number attribute.
+
+          # Append ASHRAE joint publication (/ASHRAE Guideline NN-YYYY)
+          if id.ashrae_number
+            result += "/ASHRAE Guideline #{id.ashrae_number}"
+            result += "-#{id.ashrae_year}" if id.ashrae_year
+          end
+
+          # Append IEEE cross-reference (/C62.22.1-1996)
+          result += id.crossref if id.crossref
+
+          parts << result
+        elsif should_render_type && id.typed_stage&.project_status
+          # No code but is a project - add standalone P
+          parts << "P"
+        end
+
+        # Edition - with year if present (IEC style)
+        if id.edition
+          edition_str = "Edition #{id.edition}"
+          if id.year
+            edition_str += " #{id.year}"
+            edition_str += "-#{id.edition_month}" if id.edition_month
+          end
+          parts << edition_str
+        end
+
+        # Build the main identifier (without month yet)
+        result = parts.join(" ")
+
+        # Month/Day - append directly to avoid extra space before comma
+        if id.month
+          result += ", #{id.month}"
+          result += " #{id.day}" if id.day
+          if id.year && !id.edition
+            result += " #{id.year}"
+          end
+        end
+
+        # Bounded parenthetical markers only. The unbounded relationship/
+        # amendment narrative (relationships, revision_of, amendment_to,
+        # adoption, note) is deliberately NOT rendered here: an
+        # "as amended by …" list can run 300+ chars, and an identifier's to_s
+        # is used by consumers (relaton) as a document number and filename. The
+        # narrative is preserved on the runtime accessors (id.relationships
+        # etc.), just not embedded in the identifier string.
+        parentheticals = []
+
+        # Reaffirmation year — a bounded status marker.
+        reaff = id.reaffirmed
+        parentheticals << "(R#{reaff})" if reaff && !reaff.to_s.strip.empty?
+
+        # The catch-all parenthetical is a bounded, printed identity token, not
+        # relationship prose (e.g. the "S-135 (IPCEA P46-426)" co-designation).
+        # Long amendment narratives match the structural relationship grammar
+        # and land in `relationships`, never in this catch-all, so it stays
+        # bounded.
+        if id.parenthetical_content
+          parentheticals << "(#{id.parenthetical_content})"
+        end
+
+        result += " #{parentheticals.join(' ')}" unless parentheticals.empty?
+
+        # Book nickname - outside parentheses in square brackets
+        result += " [#{id.nickname}]" if id.nickname && !id.nickname.to_s.strip.empty?
+
+        # Redline suffix
+        result += " - Redline" if id.redline
+
+        result
+      end
+
+      # ------------------------------------------------------------------
+      # Wrapper types
+      # ------------------------------------------------------------------
+
+      def render_dual_published(id)
+        "#{child_to_s(id.first_identifier)} and " \
+          "#{child_to_s(id.second_identifier)}"
+      end
+
+      def render_dual_identifier(id)
+        "#{child_to_s(id.first_identifier)} and " \
+          "#{child_to_s(id.second_identifier)}"
+      end
+
+      def render_adopted_standard(id)
+        # Only the IEEE designation is marked; the adopted identifiers are
+        # other bodies' documents (and may be foreign pubid objects).
+        result = child_to_s(id.ieee_identifier)
+        if id.adopted_identifiers && !id.adopted_identifiers.empty?
+          adopted_strs = id.adopted_identifiers.map(&:to_s)
+          result += " (#{adopted_strs.join(' and ')})"
+        end
+        result
+      end
+
+      def render_redlined_standard(id)
+        result = child_to_s(id.base)
+        # NOTE: currently unreachable — a redline is built as a flat
+        # `redline: true` on a plain Standard (see the redline invariant in
+        # CLAUDE.md), so determine_identifier_class never routes here. Kept for
+        # completeness; if this path is ever revived, note `revision_of` is a
+        # bounded single-id reference, unlike the unbounded relationship
+        # narrative that render_base deliberately drops.
+        result += " (Revision of #{id.revision_of})" if id.revision_of
+        result += " - Redline" if id.redline
+        result
+      end
+
+      def render_corrigendum(id)
+        return render_base(id) unless id.base
+
+        result = child_to_s(id.base)
+        result += "/Cor"
+        result += ". " if id.number # Add period and space for formal format
+        result += id.number if id.number
+        result += "-#{id.year}" if id.year
+        result
+      end
+
+      def render_amendment(id)
+        return render_base(id) unless id.base
+
+        result = child_to_s(id.base)
+        result += "/Amd"
+        result += " #{id.number}" if id.number # canonical "/Amd 4-2020"
+        result += "-#{id.year}" if id.year
+        result
+      end
+
+      def render_interpretation(id)
+        return render_base(id) unless id.base
+
+        result = child_to_s(id.base)
+        result += "/INT"
+        result += "-#{id.year}" if id.year
+        result
+      end
+
+      def render_conformance(id)
+        return render_base(id) unless id.base
+
+        result = child_to_s(id.base)
+        result += "/Conformance#{id.number}" if id.number
+        result += "-#{id.year}" if id.year
+        result
+      end
+
+      def render_multi_numbered(id)
+        return child_to_s(id.primary_identifier) unless id.secondary_identifier
+
+        # Co-equal designations: each carries its own mark, before its own
+        # suffixes, as IEEE prints them.
+        primary = child_to_s(id.primary_identifier)
+        secondary = child_to_s(id.secondary_identifier)
+
+        secondary_code = id.secondary_identifier.code.to_s
+        if secondary_code.start_with?("C") && secondary_code.match?(/^C\d+\./)
+          # A cross-reference prints the bare second designation after the
+          # slash — "IEEE Std 1299/C62.22.1-1996" — not a second full
+          # reference, so this branch must not reuse `secondary`, which
+          # carries its own "IEEE Std " prefix.
+          "#{primary}/#{secondary_code}"
+        else
+          "#{primary} and #{secondary}"
+        end
+      end
+
+      def render_parenthetical(id)
+        # The mark belongs on the base; the parenthetical is a separate token.
+        result = child_to_s(id.base)
+        result += " (#{id.parenthetical_identifier})" if id.parenthetical_identifier
+        result
+      end
+
+      def render_csa_dual_published(id)
+        # csa_identifier is a Pubid::Csa object — never marked.
+        csa_str = id.csa_identifier.to_s
+        csa_str = "CSA #{csa_str}" unless csa_str.start_with?("CSA", "CAN/")
+
+        "#{child_to_s(id.ieee_identifier)}/#{csa_str}"
+      end
+
+      def render_iec_ieee_copublished(id)
+        result = "IEC/IEEE"
+        # copublished_number glues the parts and the publication year onto the
+        # number, so the mark is spliced in by that single implementation
+        # rather than rebuilt here; with the flag off it is passed "".
+        if id.copublished_number
+          result += " #{id.copublished_number(mark(id.number,
+                                                   publishers: %w[IEC IEEE]))}"
+        end
+        result += id.draft_info if id.draft_info
+        result += " IEC:#{id.iec_year}" if id.iec_year
+        result += " #{id.date_info}" if id.date_info
+        result
+      end
+
+      def render_si_standard(id)
+        parts = []
+
+        # Publisher (IEEE/ASTM)
+        parts << "IEEE/ASTM"
+
+        # Type (SI or PSI based on typed_stage)
+        parts << if id.typed_stage&.abbr&.include?("PSI")
+                   "PSI"
+                 else
+                   "SI"
+                 end
+
+        # Code (number) with draft version for PSI — the mark goes after the
+        # code, before the draft and the date.
+        code_part = id.code.to_s
+        code_part += mark(id.code_obj&.number, id.code_obj&.prefix,
+                          publishers: publishers_of(id))
+        if id.draft_obj
+          code_part += "/D#{id.draft_obj.version}"
+        end
+        parts << code_part if id.code
+
+        # Date
+        if id.month && id.year
+          parts << ", #{id.month} #{id.year}"
+        elsif id.year
+          parts << "-#{id.year}"
+        end
+
+        # Join parts with spaces, but don't insert a space before parts
+        # that start with "-" or "," (e.g., "-2010", ", July 2014") so the
+        # SI form renders as "SI 10-2010" not "SI 10 -2010". The descriptive
+        # relationships narrative is deliberately kept out of to_s (see
+        # render_base); it stays reachable on id.relationships.
+        parts.each_with_object([]) do |part, acc|
+          if acc.empty? || part.to_s.start_with?("-", ",")
+            acc << part.to_s
+          else
+            acc << " " << part.to_s
+          end
+        end.join
+      end
+    end
+  end
+end

data/lib/pubid/ieee/typed_stages.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Ieee
+    # Registry of all IEEE typed stages
+    # Single source of truth for stage/type combinations
+    #
+    # IEEE has three approval levels:
+    # 1. Unapproved Draft (D1-D6): Working drafts
+    # 2. Approved Draft (D7-D9): Board-approved but unpublished
+    # 3. Published: Final standards (no P prefix, no D number)
+    #
+    # For joint development with ISO/IEC, both IEEE and ISO stages may appear
+    module TypedStages
+      TYPED_STAGES = [
+        # Published Standards (no P prefix, no draft notation)
+        Components::TypedStage.new(
+          abbr: ["Std"],
+          stage_code: "published",
+          type_code: "standard",
+          approval_status: "published",
+          project_status: false,
+        ),
+
+        # IEEE Draft Stages (P prefix, unapproved)
+        # D1 - Initial working draft
+        Components::TypedStage.new(
+          abbr: ["D1"],
+          stage_code: "working_draft",
+          type_code: "draft",
+          ieee_draft_equivalent: "D1",
+          iso_stage_equivalent: "WD",
+          approval_status: "unapproved",
+          project_status: true,
+        ),
+
+        # D2, D3 - Committee draft stages
+        Components::TypedStage.new(
+          abbr: ["D2", "D3"],
+          stage_code: "committee_draft",
+          type_code: "draft",
+          ieee_draft_equivalent: "D2-D3",
+          iso_stage_equivalent: "CD",
+          approval_status: "unapproved",
+          project_status: true,
+        ),
+
+        # D4, D5, D6 - Draft standard stages
+        Components::TypedStage.new(
+          abbr: ["D4", "D5", "D6"],
+          stage_code: "draft_standard",
+          type_code: "draft",
+          ieee_draft_equivalent: "D4-D6",
+          iso_stage_equivalent: "DIS",
+          approval_status: "unapproved",
+          project_status: true,
+        ),
+
+        # IEEE Draft Stages (P prefix, approved but unpublished)
+        # D7, D8, D9 - Final draft (board-approved)
+        Components::TypedStage.new(
+          abbr: ["D7", "D8", "D9"],
+          stage_code: "final_draft",
+          type_code: "draft",
+          ieee_draft_equivalent: "D7-D9",
+          iso_stage_equivalent: "FDIS",
+          approval_status: "approved",
+          project_status: true,
+        ),
+
+        # ISO Stages (for joint development with ISO/IEC/IEEE)
+        # These stages appear in joint development identifiers
+        Components::TypedStage.new(
+          abbr: ["PWI"],
+          stage_code: "preliminary",
+          type_code: "draft",
+          ieee_draft_equivalent: "P",
+          iso_stage_equivalent: "PWI",
+          approval_status: "unapproved",
+          project_status: true,
+        ),
+
+        Components::TypedStage.new(
+          abbr: ["NP"],
+          stage_code: "new_proposal",
+          type_code: "draft",
+          ieee_draft_equivalent: "P",
+          iso_stage_equivalent: "NP",
+          approval_status: "unapproved",
+          project_status: true,
+        ),
+
+        Components::TypedStage.new(
+          abbr: ["WD"],
+          stage_code: "working_draft",
+          type_code: "draft",
+          ieee_draft_equivalent: "D1",
+          iso_stage_equivalent: "WD",
+          approval_status: "unapproved",
+          project_status: true,
+        ),
+
+        Components::TypedStage.new(
+          abbr: ["CD", "CD1", "CD2", "CD3", "CD4"],
+          stage_code: "committee_draft",
+          type_code: "draft",
+          ieee_draft_equivalent: "D2-D3",
+          iso_stage_equivalent: "CD",
+          approval_status: "unapproved",
+          project_status: true,
+        ),
+
+        # Committee Draft for Vote (IEC/ISO-led historical stage)
+        Components::TypedStage.new(
+          abbr: ["CDV"],
+          stage_code: "committee_draft_for_vote",
+          type_code: "draft",
+          ieee_draft_equivalent: "D2-D3",
+          iso_stage_equivalent: "CDV",
+          approval_status: "unapproved",
+          project_status: true,
+        ),
+
+        Components::TypedStage.new(
+          abbr: ["DIS"],
+          stage_code: "draft_international_standard",
+          type_code: "draft",
+          ieee_draft_equivalent: "D5",
+          iso_stage_equivalent: "DIS",
+          approval_status: "unapproved",
+          project_status: true,
+        ),
+
+        Components::TypedStage.new(
+          abbr: ["FDIS"],
+          stage_code: "final_draft",
+          type_code: "draft",
+          ieee_draft_equivalent: "D8",
+          iso_stage_equivalent: "FDIS",
+          approval_status: "approved",
+          project_status: true,
+        ),
+
+        # Historical stages (AIEE, IRE)
+        # "No" or "No." for AIEE standards
+        Components::TypedStage.new(
+          abbr: ["No", "No."],
+          stage_code: "published",
+          type_code: "standard",
+          approval_status: "published",
+          project_status: false,
+        ),
+
+        # Generic "P" prefix for drafts (when specific D number not known)
+        Components::TypedStage.new(
+          abbr: ["P"],
+          stage_code: "draft",
+          type_code: "draft",
+          ieee_draft_equivalent: "P",
+          approval_status: "unapproved",
+          project_status: true,
+        ),
+
+        # Draft without specific version (legacy)
+        Components::TypedStage.new(
+          abbr: ["Draft"],
+          stage_code: "draft",
+          type_code: "draft",
+          approval_status: "unapproved",
+          project_status: true,
+        ),
+      ].freeze
+
+      # Default typed stage for published standards
+      DEFAULT_TYPED_STAGE = TYPED_STAGES.first
+    end
+
+    # Backward compatibility aliases at module level
+    # These allow code expecting Pubid::Ieee::TYPED_STAGES to still work
+    TYPED_STAGES = TypedStages::TYPED_STAGES
+    DEFAULT_TYPED_STAGE = TypedStages::DEFAULT_TYPED_STAGE
+  end
+end