pubid 1.15.21 → 2.0.0.alpha.10

data/lib/pubid/plateau.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "parslet"
+
+module Pubid
+  module Plateau
+    extend Pubid::PrefixesSupport
+
+    # Sole PLATEAU publisher token (see the parser's `publisher` rule).
+    PREFIXES = ["PLATEAU"].freeze
+
+    autoload :Builder, "#{__dir__}/plateau/builder"
+    autoload :Identifier, "#{__dir__}/plateau/identifiers/base"
+    autoload :Identifiers, "#{__dir__}/plateau/identifiers"
+    autoload :Parser, "#{__dir__}/plateau/parser"
+    autoload :Renderer, "#{__dir__}/plateau/renderer"
+    autoload :SupplementIdentifier, "#{__dir__}/plateau/supplement_identifier"
+    autoload :UrnGenerator, "#{__dir__}/plateau/urn_generator"
+    autoload :UrnParser, "#{__dir__}/plateau/urn_parser"
+
+    def self.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
+
+      # Apply legacy update_codes normalization first
+      normalized = Core::UpdateCodes.apply(input, :plateau)
+      parser = Parser.new
+      parsed = parser.parse(normalized)
+      Builder.build(parsed)
+    end
+
+    # Per-flavor format registry: inherits global formats, overrides :human
+    Identifier.format_registry = FormatRegistry.new(parent: ::Pubid::Identifier.format_registry)
+    Identifier.format_registry.register(:human, renderer: Plateau::Renderer)
+    SupplementIdentifier.format_registry = Identifier.format_registry
+
+    # 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 Uplateau flavor with the registry
+Pubid::Registry.register(:plateau, Pubid::Plateau)

data/lib/pubid/prefixes_support.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Pubid
+  # Mixin providing the uniform, static +prefixes+ class method that every
+  # registered flavor exposes. relaton uses this to build a global prefix
+  # register that routes a printed reference string (e.g. +"DD 1234"+,
+  # +"ISO/IEC 8802"+) to the flavor(s) that own it.
+  #
+  # A flavor +extend+s this module and defines a frozen +PREFIXES+ array holding
+  # only *its own* leading tokens. Joint / co-publication tokens are injected
+  # centrally from {Pubid::JOINT_PREFIXES} so that a co-published prefix
+  # (e.g. +"ISO/IEC"+) is listed symmetrically by every co-publisher without
+  # being duplicated by hand in two files.
+  #
+  # == Inclusion policy
+  # +prefixes+ returns the set of *leading identifier prefix tokens* — the
+  # tokens a printed identifier can start with such that the string belongs to
+  # this SDO. Concretely it INCLUDES:
+  # * publisher prefixes (e.g. +ISO+, +IEC+, +NIST+, +NBS+, +BS+, +BSI+);
+  # * leading series/type tokens that can *begin* a printed reference on their
+  #   own (e.g. BSI +DD+/+PD+, NIST +FIPS+/+SP+);
+  # * joint / co-publication forms (e.g. +ISO/IEC+, +ISO/IEC/IEEE+).
+  # It EXCLUDES:
+  # * pure sub-series that never appear without a publisher prefix;
+  # * dangerously-ambiguous single letters (e.g. BSI aerospace +A+/+B+/+C+),
+  #   which would cause false routing.
+  module PrefixesSupport
+    # The static set of leading prefix tokens this flavor recognizes.
+    #
+    # Static: callable without parsing any identifier string. Strings are
+    # returned in canonical case exactly as printed (e.g. +"BS EN ISO"+,
+    # +"ISO/IEC"+); consumers fold case themselves.
+    #
+    # @return [Array<String>] frozen, de-duplicated list of prefix tokens
+    def prefixes
+      own = const_defined?(:PREFIXES) ? const_get(:PREFIXES) : []
+      joint = Pubid::JOINT_PREFIXES.fetch(prefix_flavor_key, [])
+      (own + joint).uniq.freeze
+    end
+
+    # The registry key for this flavor, derived from the module name
+    # (e.g. +Pubid::CenCenelec+ => +:cen_cenelec+). Used to look this flavor up
+    # in {Pubid::JOINT_PREFIXES} and to label it in {Pubid.prefix_flavors}.
+    #
+    # @return [Symbol]
+    def prefix_flavor_key
+      name.split("::").last
+        .gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase.to_sym
+    end
+  end
+end

data/lib/pubid/renderers/annotator.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Renderers
+    # Adds semantic <span class="..."> markers to an already-rendered
+    # identifier string.
+    #
+    # In pubid 1.x annotation was applied in ONE place — `prerender_params`
+    # wrapped every value in the param hash — so all 40-odd flavors got it for
+    # free. pubid 2 replaced that hash with typed components and per-flavor
+    # renderers, and the annotation went with it: `Renderers::Base#annotate`
+    # exists, but only the HumanReadable family calls it. All 39 flavor
+    # renderers receive `context.annotated` and ignore it, so
+    # `to_s(annotated: true)` returned plain text for every flavor but ISO.
+    #
+    # Re-annotating inside 39 renderers would mean 39 chances to drift. This
+    # class recovers the markup from the OUTSIDE instead: it asks the
+    # identifier for its own component values and wraps each one where it
+    # appears in the rendered string. That is one implementation, and a flavor
+    # added tomorrow is covered without touching its renderer.
+    #
+    # It is a fallback, not a replacement. `Identifier#render` uses it only
+    # when the renderer produced no span of its own, so ISO's exact,
+    # render-time placement still wins.
+    #
+    # Deliberate limits:
+    #
+    # * A token that does not appear verbatim in the output is skipped. A
+    #   renderer may transform a value (abbreviate it, change its case), and a
+    #   missing span is a far better outcome than a wrong one or a crash.
+    # * Matching walks left to right behind a cursor, so a later token can
+    #   never match text an earlier one already claimed — that is what stops
+    #   the part "1" of `ISO 1234-1` from matching inside "1234".
+    class Annotator
+      # Semantic class for each token, in the order tokens appear in a printed
+      # identifier. Order matters: it is the sequence the cursor walks.
+      TOKENS = [
+        [:publisher, "publisher"],
+        [:copublishers, "publisher"],
+        %i[typed_stage typed_stage_css],
+        [:type, "doctype"],
+        [:stage, "stage"],
+        [:number, "docnumber"],
+        [:part, "part"],
+        [:subpart, "part"],
+        [:stage_iteration, "iteration"],
+        [:year, "year"],
+        [:edition, "edition"],
+        [:languages, "language"],
+      ].freeze
+
+      # Characters that may not sit directly against a match, so a token never
+      # binds to the middle of a longer run of the same character class.
+      WORD_CHAR = /[A-Za-z0-9]/
+
+      # How deep to follow nested identifiers. A wrapper around a wrapper is
+      # real (BSI adopts a CEN prestandard that adopts an ISO standard); four
+      # levels is past anything the corpus holds, and the cap is here so a
+      # cyclic `base` cannot hang a rendering call.
+      MAX_NESTING = 4
+
+      def initialize(identifier, context = nil)
+        @id = identifier
+        @context = context
+      end
+
+      # @param rendered [String] the plain rendering of {@id}
+      # @return [String] the same string with semantic spans inserted
+      def annotate(rendered)
+        return rendered unless rendered.is_a?(String) && !rendered.empty?
+
+        cursor = 0
+        result = +""
+
+        ordered_tokens(rendered).each do |text, css_class|
+          index = find_token(rendered, text, cursor)
+          next if index.nil?
+
+          result << rendered[cursor...index]
+          result << %(<span class="#{css_class}">#{text}</span>)
+          cursor = index + text.length
+        end
+
+        result << rendered[cursor..]
+        result
+      end
+
+      private
+
+      # Tokens sorted by where they actually appear, not by the order
+      # {TOKENS} lists them.
+      #
+      # Flavors disagree about layout: ISO prints the number before the type
+      # ("ISO/IEC TR 2131"), CCSDS prints it after ("CCSDS 121.0-B-2"). Walking
+      # in declaration order pushed the cursor past the number for CCSDS, so
+      # "121" was never annotated. Sorting by first occurrence makes the walk
+      # follow the printed identifier instead of a fixed idea of one.
+      def ordered_tokens(rendered)
+        tokens = []
+        each_token { |text, css_class| tokens << [text, css_class] }
+
+        decorated = tokens.each_with_index.map do |token, i|
+          position = find_token(rendered, token.first, 0) || rendered.length
+          [position, i, token]
+        end
+
+        decorated.sort_by { |position, i, _| [position, i] }.map(&:last)
+      end
+
+      # Yields [text, css_class] for every annotatable token this identifier
+      # actually carries, then every one its nested identifiers carry.
+      def each_token(&)
+        emit_tokens(@id, 0, &)
+      end
+
+      # A wrapper — an adoption, a supplement, a bundle — carries no number of
+      # its own and prints the document it wraps, so the annotatable tokens in
+      # its string belong to `base`. Reading only the wrapper's own attributes
+      # is why every CSA container and CIE's supplement rendered plain while
+      # accepting the flag.
+      #
+      # Order does not matter here: `ordered_tokens` sorts by first occurrence,
+      # so a nested token lands where it actually appears in the string.
+      def emit_tokens(id, depth, &)
+        return if depth > MAX_NESTING
+
+        tokens_for(id).each do |attr_name, css_class|
+          Array(token_values(id, attr_name)).each do |value|
+            text = token_text(value)
+            next if text.nil? || text.empty?
+
+            yield text, resolve_class(css_class, value)
+          end
+        end
+
+        nested_identifiers(id).each { |nested| emit_tokens(nested, depth + 1, &) }
+      end
+
+      # {TOKENS} unless the identifier names more of its own — see
+      # `Pubid::Identifier#annotation_tokens`.
+      def tokens_for(id)
+        id.respond_to?(:annotation_tokens) ? id.annotation_tokens : TOKENS
+      end
+
+      # The identifiers this one wraps, under any of the four names the gem
+      # uses: `base` (the uniform parent accessor), the `ids` / `identifiers`
+      # collections that bundles and consolidated identifiers hold instead, and
+      # CSA `Bundled`'s `bundled_with` — which holds the amendments a
+      # consolidation prints, and whose values it composes into the string from
+      # their components rather than from their own `to_s`.
+      def nested_identifiers(id)
+        %i[base ids identifiers bundled_with].flat_map do |name|
+          next [] unless id.respond_to?(name)
+
+          begin
+            Array(id.public_send(name))
+          rescue StandardError
+            []
+          end
+        end.grep(::Pubid::Identifier)
+      end
+
+      def token_values(id, attr_name)
+        return nil unless id.respond_to?(attr_name)
+
+        id.public_send(attr_name)
+      rescue StandardError
+        # A derived reader may assume state a partial identifier lacks. A
+        # missing span is not worth an exception on a rendering path.
+        nil
+      end
+
+      # The printed form of one component. Components render themselves through
+      # the context; a bare scalar is already its own text.
+      def token_text(value)
+        return nil if value.nil?
+
+        text = if value.respond_to?(:render)
+                 value.render(context: @context)
+               else
+                 value
+               end
+        text.to_s.strip
+      rescue StandardError
+        nil
+      end
+
+      def resolve_class(css_class, value)
+        return css_class unless css_class == :typed_stage_css
+
+        TypedStageClass.for(value)
+      end
+
+      # First occurrence of +text+ at or after +cursor+ that is not embedded in
+      # a longer word — so "1" matches the part in "ISO 1234-1", never the "1"
+      # inside "1234".
+      def find_token(rendered, text, cursor)
+        at = cursor
+        while (index = rendered.index(text, at))
+          return index if standalone?(rendered, index, text.length)
+
+          at = index + 1
+        end
+        nil
+      end
+
+      def standalone?(rendered, index, length)
+        before = index.zero? ? nil : rendered[index - 1]
+        after = rendered[index + length]
+
+        !WORD_CHAR.match?(before.to_s) && !WORD_CHAR.match?(after.to_s)
+      end
+
+      # The typed-stage class depends on the stage's type code, the same
+      # mapping `Renderers::Base#typed_stage_css` applies. Kept here rather
+      # than reached for through a private method on another object.
+      module TypedStageClass
+        MAP = {
+          "amd" => "amendment",
+          "cor" => "corrigendum",
+          "add" => "addendum",
+        }.freeze
+
+        def self.for(typed_stage)
+          code = typed_stage.respond_to?(:type_code) ? typed_stage.type_code.to_s : ""
+          return "stage" if code.empty? || code == "is"
+
+          MAP[code] || "doctype"
+        end
+      end
+    end
+  end
+end

data/lib/pubid/renderers/base.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Renderers
+    class Base
+      def initialize(identifier)
+        @id = identifier
+      end
+
+      def render
+        raise NotImplementedError, "#{self.class}#render not implemented"
+      end
+
+      def self.render(identifier)
+        new(identifier).render
+      end
+
+      # Partitions a value into (leading separators, core, trailing separators)
+      # so "- : / space , ." stay OUTSIDE the annotation span (v1 parity).
+      SEMANTIC_SPLIT = %r{\A([-:/ ,.]*)(.*?)([-:/ ,.]*)\z}m
+
+      # type_code (a string) → semantic CSS class for the typed-stage token.
+      # Anything not listed (and not the default "is") renders as "doctype".
+      TYPED_STAGE_CSS = {
+        "amd" => "amendment",
+        "cor" => "corrigendum",
+        "add" => "addendum",
+      }.freeze
+
+      private
+
+      # Wrap a rendered value in a <span class="css_class"> when annotation is
+      # enabled, keeping leading/trailing separator chars outside the span.
+      def annotate(value, css_class, annotated:)
+        str = value.to_s
+        return value unless annotated && css_class && !str.empty?
+
+        lead, core, trail = str.match(SEMANTIC_SPLIT).captures
+        return value if core.empty?
+
+        %(#{lead}<span class="#{css_class}">#{core}</span>#{trail})
+      end
+
+      # Render a value that may be a component or a bare scalar.
+      #
+      # `number`, `part` and `subpart` are `Components::Code` on
+      # ::Pubid::Identifier but a plain `:string` in a growing number of
+      # flavors, so a shared renderer cannot assume the format-aware
+      # `#render(context:)` seam is there. This keeps both shapes working while
+      # the flavors convert one tranche at a time.
+      def render_component(value, context)
+        return nil if value.nil?
+
+        value.respond_to?(:render) ? value.render(context: context) : value.to_s
+      end
+
+      # Choose between "stage" and a type/supplement class for a typed stage.
+      def typed_stage_css(typed_stage)
+        code = typed_stage&.type_code.to_s
+        return "stage" if code.empty? || code == "is"
+
+        TYPED_STAGE_CSS[code] || "doctype"
+      end
+    end
+  end
+end

data/lib/pubid/renderers/directives_renderer.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Renderers
+    class DirectivesRenderer < HumanReadable
+      def render(context:, with_edition: false)
+        parts = []
+        parts << render_publisher_portion(context)
+        num_port = render_number_portion(context)
+
+        if num_port && !num_port.empty?
+          if num_port.start_with?(":")
+            result = parts.compact.join(" ") + num_port
+          else
+            parts << num_port
+            result = parts.compact.join(" ")
+          end
+        else
+          result = parts.compact.join(" ")
+        end
+
+        result << " #{render_edition_portion(context)}" if with_edition && @id.edition&.number
+        result << render_language_portion(context, with_edition: with_edition)
+        result
+      end
+
+      private
+
+      def render_publisher_portion(context)
+        ann = context.annotated
+        if @id.publisher
+          pub_str = annotate(@id.publisher.render(context:), "publisher",
+                             annotated: ann)
+        end
+        abbr = @id.typed_stage ? @id.typed_stage.abbreviation(format_long: false) : ""
+        unless abbr.empty?
+          abbr = annotate(abbr, typed_stage_css(@id.typed_stage), 
+                          annotated: ann)
+        end
+        subgroup_str = @id.subgroup.render(context:) if @id.subgroup
+
+        [
+          pub_str,
+          (subgroup_str ? " #{subgroup_str}" : ""),
+          (abbr.empty? ? "" : " #{abbr}"),
+        ].join
+      end
+
+      def render_number_portion(context)
+        ann = context.annotated
+        parts = []
+        if @id.number
+          parts << annotate(render_component(@id.number, context), "docnumber",
+                            annotated: ann)
+        end
+        if @id.part
+          parts << " #{annotate(render_component(@id.part, context), 'part', 
+                                annotated: ann)}"
+        end
+        if @id.subpart
+          parts << "-#{annotate(render_component(@id.subpart, context), 'part', 
+                                annotated: ann)}"
+        end
+        if @id.stage_iteration
+          parts << ".#{annotate(@id.stage_iteration.render(context:), 
+                                'iteration', annotated: ann)}"
+        end
+        date_str = @id.date.render(context:) if @id.date && context.with_date
+        parts << ":#{annotate(date_str, 'year', annotated: ann)}" if date_str
+        result = parts.join.strip
+        result.empty? ? nil : result
+      end
+    end
+  end
+end

data/lib/pubid/renderers/guide_renderer.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Renderers
+    class GuideRenderer < HumanReadable
+      private
+
+      def render_publisher_and_stage(context)
+        ann = context.annotated
+        if @id.publisher
+          pub_str = annotate(@id.publisher.render(context:), "publisher",
+                             annotated: ann)
+        end
+        stage_str = @id.typed_stage.render(context:) if @id.typed_stage
+
+        if stage_str && !stage_str.empty?
+          stage_str = annotate(stage_str, typed_stage_css(@id.typed_stage),
+                               annotated: ann)
+          "#{pub_str} #{stage_str}"
+        else
+          pub_str
+        end
+      end
+    end
+  end
+end

data/lib/pubid/renderers/human_readable.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Renderers
+    class HumanReadable < Base
+      # `**_opts` absorbs render flags that only some flavors honour (e.g. the
+      # IEEE-specific `:trademark`), so the shared renderer tolerates them.
+      def render(context:, with_edition: false, **_opts)
+        parts = []
+        parts << render_publisher_and_stage(context)
+        parts << render_number_portion(context)
+        parts << render_edition_portion(context) if with_edition
+        result = parts.compact.join(" ")
+        result << render_language_portion(context, with_edition: with_edition)
+        result << " (all parts)" if @id.all_parts
+        result
+      end
+
+      private
+
+      def render_publisher_and_stage(context)
+        ann = context.annotated
+        if @id.publisher
+          pub_str = annotate(@id.publisher.render(context:), "publisher",
+                             annotated: ann)
+        end
+        stage_str = @id.typed_stage.render(context:) if @id.typed_stage
+
+        if stage_str && !stage_str.empty?
+          has_copub = @id.publisher&.copublished?
+          sep = has_copub ? " " : "/"
+          stage_str = annotate(stage_str, typed_stage_css(@id.typed_stage),
+                               annotated: ann)
+          "#{pub_str}#{sep}#{stage_str}"
+        else
+          pub_str
+        end
+      end
+
+      def render_number_portion(context)
+        ann = context.annotated
+        parts = []
+        if @id.number
+          parts << annotate(render_component(@id.number, context), "docnumber",
+                            annotated: ann)
+        end
+        if @id.part
+          parts << "-#{annotate(render_component(@id.part, context), 'part', 
+                                annotated: ann)}"
+        end
+        if @id.subpart
+          parts << "-#{annotate(render_component(@id.subpart, context), 'part', 
+                                annotated: ann)}"
+        end
+        if @id.stage_iteration
+          parts << ".#{annotate(@id.stage_iteration.render(context:), 
+                                'iteration', annotated: ann)}"
+        end
+        date_str = @id.date.render(context:) if @id.date && context.with_date
+        parts << ":#{annotate(date_str, 'year', annotated: ann)}" if date_str
+        parts.join
+      end
+
+      def render_edition_portion(context)
+        return unless @id.edition&.number
+
+        annotate(@id.edition.render(context:), "edition",
+                 annotated: context.annotated)
+      end
+
+      def render_language_portion(context, with_edition: false)
+        return "" unless @id.languages&.any? && context.with_language_code != :none
+
+        use_single = with_edition ? false : context.with_language_code == :single
+        rendered = @id.languages.map do |l|
+          annotate(l.render(context:, lang_single: use_single), "language",
+                   annotated: context.annotated)
+        end
+        "(#{rendered.join(use_single ? '/' : ',')})"
+      end
+    end
+  end
+end

data/lib/pubid/renderers/iwa_renderer.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Renderers
+    class IwaRenderer < HumanReadable
+      def render(context:, with_edition: false)
+        parts = []
+        if @id.typed_stage
+          parts << annotate(@id.typed_stage.render(context:),
+                            typed_stage_css(@id.typed_stage),
+                            annotated: context.annotated)
+        end
+        parts << render_number_portion(context)
+        result = parts.compact.join(" ")
+        result << render_language_portion(context, with_edition: with_edition)
+        result
+      end
+    end
+  end
+end