pubid 2.0.0.pre.alpha.1 → 2.0.0.pre.alpha.3

data/lib/pubid/nist/circular_supplement_builder.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Nist
+    # Builder dedicated to CIRC/LCIRC supplement identifier construction.
+    #
+    # Extracted from Builder.build_circular_supplement* methods to keep the
+    # main Builder focused on orchestration. The circular supplement
+    # construction pipeline is a self-contained sub-flow that:
+    #
+    # 1. Decides between the wrapper class (CircularSupplement) for V1-compat
+    #    update forms (slash-year "118supp3/1926" -> ".../Upd1-192603";
+    #    implicit revision "145r11/1925") and the normal Circular /
+    #    LetterCircular classes for everything else.
+    # 2. Builds the base identifier recursively via Builder#build.
+    # 3. Attaches the supplement as either an isolated component on the normal
+    #    class, or a structured edition/update on the wrapper.
+    #
+    # Single Responsibility: Construct CIRC/LCIRC supplement identifier
+    # objects from parsed data, calling back to the parent Builder for base
+    # identifier construction.
+    class CircularSupplementBuilder
+      # @param builder [Builder] the parent builder (for recursive base build)
+      def initialize(builder)
+        @builder = builder
+      end
+
+      # Build CircularSupplement with base_identifier wrapping
+      # @param parsed_hash [Hash] the parsed supplement data
+      # Build a CIRC/LCIRC supplement. Most forms collapse onto the base
+      # identifier's normal class (Circular / LetterCircular) with isolated
+      # supplement attributes, so they share one model with every other series
+      # and are queryable by part. The V1-compat update forms (slash-year
+      # "118supp3/1926" -> ".../Upd1-192603"; implicit revision "145r11/1925")
+      # render through an Update component the flat supplement model can't
+      # express, so they stay on the CircularSupplement wrapper for now.
+      def build_circular_supplement(parsed_hash)
+        if parsed_hash[:supplement_slash_year].is_a?(Hash) ||
+            parsed_hash[:implicit_supplement].is_a?(Hash)
+          return build_circular_supplement_wrapper(parsed_hash)
+        end
+
+        series_value = if parsed_hash[:circ_series].is_a?(Hash)
+                         parsed_hash[:circ_series][:series]
+                       else
+                         parsed_hash[:series]
+                       end
+
+        # Date-range supplement (no base document): a plain base identifier with
+        # no number, carrying the range. parsed_format is left at the default so
+        # a dotted MR input still normalizes to the spaced short form.
+        if parsed_hash[:supplement_date_range].is_a?(Hash)
+          range = parsed_hash[:supplement_date_range]
+          identifier = @builder.build({ series: series_value })
+          ms = range[:supp_month_start]&.to_s
+          ys = range[:supp_year_start]&.to_s
+          me = range[:supp_month_end]&.to_s
+          ye = range[:supp_year_end]&.to_s
+          identifier.supplement = @builder.supplement_from(
+            value: nil, has_revision: false,
+            range_start: (ms && ys ? "#{ms}#{ys}" : nil),
+            range_end: (me && ye ? "#{me}#{ye}" : nil)
+          )
+          return identifier
+        end
+
+        # Based supplement: build the base, then attach the supplement as an
+        # isolated component on that normal class.
+        identifier = build_circular_supplement_base(parsed_hash, series_value)
+        raw = if parsed_hash[:supplement_month_year]
+                parsed_hash[:supplement_month_year].to_s
+              elsif parsed_hash[:supplement_year]
+                parsed_hash[:supplement_year].to_s
+              else
+                "" # supplement_empty or bare marker
+              end
+        identifier.supplement = Components::Supplement.from_raw(raw)
+        identifier
+      end
+
+      # Build just the base identifier for a based CIRC/LCIRC supplement, from
+      # base_portion (number, optional edition "101e2" or letter suffix "378G")
+      # or the merged first_number fallback. Returns the normal class.
+      def build_circular_supplement_base(parsed_hash, series_value)
+        base_portion = parsed_hash[:base_portion]
+        unless base_portion
+          return @builder.build({
+                                  publisher: parsed_hash[:publisher],
+                                  series: series_value || parsed_hash[:series],
+                                  first_number: parsed_hash[:first_number],
+                                  parsed_format: parsed_hash[:parsed_format],
+                                })
+        end
+
+        base_number = if base_portion.is_a?(Hash)
+                        base_portion[:simple_number] || base_portion[:base_number]
+                      else
+                        base_portion
+                      end
+
+        letter_suffix = nil
+        if base_portion.is_a?(Hash) && base_portion[:letter_suffix]
+          letter_suffix = base_portion[:letter_suffix].to_s.upcase
+        end
+
+        publisher_value = nil
+        if parsed_hash[:circ_series].is_a?(Hash) && parsed_hash[:circ_series][:series]
+          series_str = parsed_hash[:circ_series][:series].to_s
+          publisher_value = series_str.split.first if series_str.include?(" ")
+        end
+
+        has_edition = base_portion.is_a?(Hash) && base_portion[:edition_number]
+
+        base_number_with_suffix = base_number.to_s
+        base_number_with_suffix += letter_suffix if letter_suffix
+        if has_edition
+          base_number_with_suffix += "e#{base_portion[:edition_number]}"
+        end
+
+        base_hash = {
+          series: series_value,
+          first_number: base_number_with_suffix,
+          parsed_format: parsed_hash[:parsed_format],
+        }
+        base_hash[:publisher] = publisher_value if publisher_value
+        base_hash[:edition_e] =
+          { edition_id: base_portion[:edition_number] } if has_edition
+
+        @builder.build(base_hash)
+      end
+
+      # @return [Identifiers::CircularSupplement] the supplement identifier
+      def build_circular_supplement_wrapper(parsed_hash)
+        supplement = Identifiers::CircularSupplement.new
+
+        # Extract series from circ_series if present (nested structure from parser)
+        series_value = nil
+        if parsed_hash[:circ_series].is_a?(Hash)
+          series_value = parsed_hash[:circ_series][:series]
+        elsif parsed_hash[:series]
+          series_value = parsed_hash[:series]
+        end
+
+        # Handle date range supplement (no base)
+        if parsed_hash[:supplement_date_range].is_a?(Hash)
+          range = parsed_hash[:supplement_date_range]
+          month_start = range[:supp_month_start]&.to_s
+          year_start = range[:supp_year_start]&.to_s
+          month_end = range[:supp_month_end]&.to_s
+          year_end = range[:supp_year_end]&.to_s
+
+          supplement.supplement_date_range_start = "#{month_start}#{year_start}" if month_start && year_start
+          supplement.supplement_date_range_end = "#{month_end}#{year_end}" if month_end && year_end
+
+          return supplement
+        end
+
+        # Build base identifier from base_portion (if present)
+        # If not present (because it was merged during parsing), use first_number
+        if parsed_hash[:base_portion]
+          # Extract the actual number value from base_portion hash
+          # base_portion can be: {:simple_number=>"118"}, {:base_number=>"145", :revision_letter=>"r", :revision_number=>"11"}, etc.
+          base_portion = parsed_hash[:base_portion]
+          base_number = if base_portion.is_a?(Hash)
+                          # Extract the value from whichever key is present
+                          base_portion[:simple_number] || base_portion[:base_number]
+                        else
+                          base_portion
+                        end
+
+          # Check for letter suffix in base_portion (e.g., "378G")
+          letter_suffix = nil
+          if base_portion.is_a?(Hash) && base_portion[:letter_suffix]
+            letter_suffix = base_portion[:letter_suffix].to_s.upcase
+          end
+
+          # Extract publisher from circ_series if present
+          publisher_value = nil
+          if parsed_hash[:circ_series].is_a?(Hash) && parsed_hash[:circ_series][:series]
+            series_str = parsed_hash[:circ_series][:series].to_s
+            # Extract publisher from series (e.g., "NBS LCIRC" -> "NBS")
+            publisher_value = series_str.split.first if series_str.include?(" ")
+          end
+
+          # Check if base_portion has revision (for patterns like "145r11/1925")
+          has_revision = base_portion.is_a?(Hash) && base_portion[:revision_letter] && base_portion[:revision_number]
+
+          # NEW: Check if base_portion has edition_number (for patterns like "101e2")
+          has_edition = base_portion.is_a?(Hash) && base_portion[:edition_number]
+
+          # Include letter suffix in base_number if present
+          # Also include edition_number if present (for "101e2" pattern)
+          base_number_with_suffix = base_number.to_s
+          if letter_suffix
+            base_number_with_suffix += letter_suffix
+          end
+          if has_edition
+            base_number_with_suffix += "e#{base_portion[:edition_number]}"
+          end
+
+          # Reconstruct parse hash for base identifier
+          base_hash = {
+            series: series_value,
+            first_number: base_number_with_suffix,
+            parsed_format: parsed_hash[:parsed_format],
+          }
+          base_hash[:publisher] = publisher_value if publisher_value
+
+          # NEW: Add edition_number to base_hash for patterns like "101e2"
+          # This will be processed by the normal build() logic to create Edition component
+          if has_edition
+            # Create edition_e hash that will be converted to Edition with type="e"
+            base_hash[:edition_e] =
+              { edition_id: base_portion[:edition_number] }
+          end
+
+          # Recursively build base identifier
+          # This will go through normal build() process which extracts edition from "101e2"
+          supplement.base_identifier = @builder.build(base_hash)
+
+          # NEW: Handle revision + implicit supplement pattern (e.g., "145r11/1925")
+          # Create update format: "Upd1-{year}{revision_number}"
+          if has_revision && parsed_hash[:implicit_supplement].is_a?(Hash)
+            revision_number = base_portion[:revision_number].to_s
+            supplement_year = parsed_hash[:implicit_supplement][:implicit_supplement_year].to_s
+
+            # Create Update component for revision+supplement pattern.
+            # Renders "/Upd1-{year}{revision_number}" via Update#to_s(:short).
+            # The year+revision are fused into the year field (month left nil) so
+            # the revision is NOT zero-padded (e.g. "145r6/1925" -> "Upd1-19256",
+            # not "192506"). Must be a Components::Update (not a String) so
+            # :update serializes.
+            supplement.update = Components::Update.new(
+              number: "1", year: "#{supplement_year}#{revision_number}",
+              prefix: "slash"
+            )
+            supplement.implicit_supplement = true # Mark as implicit supplement for rendering
+          end
+        elsif parsed_hash[:first_number]
+          # base_portion was lost during merge, use first_number to build base identifier
+          base_hash = {
+            publisher: parsed_hash[:publisher],
+            series: series_value || parsed_hash[:series],
+            first_number: parsed_hash[:first_number],
+            parsed_format: parsed_hash[:parsed_format],
+          }
+
+          # Recursively build base identifier
+          supplement.base_identifier = @builder.build(base_hash)
+        end
+
+        # Build supplement edition from captured data
+        if parsed_hash[:supplement_month_year]
+          # Parse month+year format like "Jan1924"
+          month_year = parsed_hash[:supplement_month_year].to_s
+          supplement.edition = Components::Edition.new(type: "s",
+                                                       id: month_year)
+        elsif parsed_hash[:supplement_year]
+          # Just year: 1924
+          supplement.edition = Components::Edition.new(type: "s",
+                                                       id: parsed_hash[:supplement_year].to_s)
+        elsif parsed_hash[:supplement_slash_year].is_a?(Hash)
+          # NEW: Handle supplement_slash_year pattern (e.g., "sup12/1926", "sup1/1927")
+          # V1 format: "Upd1-192612" where "1" is fixed and "192612" is year+number concatenated
+          # Single digit numbers are zero-padded: "sup1/1927" -> "Upd1-192701"
+          supp_hash = parsed_hash[:supplement_slash_year]
+          supp_number = supp_hash[:supp_number]&.to_s
+          supp_year = supp_hash[:supp_year]&.to_s
+
+          # Pad supplement number to 2 digits for single-digit numbers
+          supp_number_padded = supp_number.rjust(2, "0")
+
+          # Create Update component for supplement (V1 compatibility uses Update for supplements).
+          # Renders "/Upd1-{year}{padded_number}" via Update#to_s(:short). The
+          # year and already-padded number are fused into the year field (month
+          # left nil) so rendering reproduces the V1 string exactly. Must be a
+          # Components::Update (not a String) so :update serializes.
+          supplement.update = Components::Update.new(
+            number: "1", year: "#{supp_year}#{supp_number_padded}",
+            prefix: "slash"
+          )
+        elsif parsed_hash[:supplement_empty]
+          # Empty supplement - no edition
+          # supplement.edition remains nil
+        end
+
+        supplement
+      end
+    end
+  end
+end

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

@@ -1,35 +1,24 @@
 # frozen_string_literal: true
 
-require "lutaml/model"
-
 module Pubid
   module Nist
     module Components
-      # Code component for NIST identifiers
-      # Handles number codes like series, volume, etc.
-      class Code < Lutaml::Model::Serializable
-        attribute :number, :string
-        attribute :subpart, :string
-
+      # Code component for NIST identifiers.
+      #
+      # Inherits +value+ and +subpart+ from the shared Code; overrides
+      # rendering to compose compound numbers like "1234.5" (subpart
+      # joined with "." per NIST convention).
+      class Code < ::Pubid::Components::Code
         def to_s
-          result = number.to_s
+          result = value.to_s
           result += ".#{subpart}" if subpart
           result
         end
 
-        # Alias for compatibility
-        def value
-          to_s
-        end
-
-        # Backward compatibility: extract part from compound numbers like "140-2"
-        # Returns the part number if the value contains a dash, nil otherwise
         def part
-          return nil unless number&.include?("-")
+          return nil unless value&.include?("-")
 
-          # Split by last dash to handle patterns like "4-4" (just number-part)
-          # and "4-M-5" (which would return "M-5" as part)
-          parts = number.to_s.split("-")
+          parts = value.to_s.split("-")
           parts.last if parts.length > 1
         end
       end

data/lib/pubid/nist/components/edition.rb

@@ -49,6 +49,22 @@ module Pubid
           end
         end
 
+        # Identity ignores original_prefix: it records how the edition was
+        # spelled in the source ("Rev. " vs "r") for round-trip rendering
+        # only. "r1" and "Rev. 1" are the same edition.
+        def ==(other)
+          return false unless other.is_a?(self.class)
+
+          type == other.type && id == other.id &&
+            additional_text == other.additional_text
+        end
+
+        alias eql? ==
+
+        def hash
+          [self.class, type, id, additional_text].hash
+        end
+
         private
 
         # Build short format: "e2", "e2.June1908", "e2.1908", "e2.50", "r1963", "-April1909", "r1a"

data/lib/pubid/nist/components/supplement.rb

@@ -9,17 +9,19 @@ module Pubid
       # Represents supplement notation with number, year, month, or revision
       #
       # Examples:
-      #   Supplement.new(number: "2").to_s(:short)              # => "supp2"
-      #   Supplement.new(year: "1925").to_s(:short)              # => "supp-1925"
-      #   Supplement.new(number: "3", year: "1926").to_s(:short) # => "supp3/1926"
-      #   Supplement.new(month: "Jan", year: "1924").to_s(:short) # => "suppJan1924"
-      #   Supplement.new(has_revision: true).to_s(:short)        # => "supprev"
+      #   Supplement.new(number: "2").to_s(:short)              # => "sup2"
+      #   Supplement.new(year: "1925").to_s(:short)              # => "sup1925"
+      #   Supplement.new(number: "3", year: "1926").to_s(:short) # => "sup3/1926"
+      #   Supplement.new(month: "Jan", year: "1924").to_s(:short) # => "supJan1924"
+      #   Supplement.new(has_revision: true).to_s(:short)        # => "suprev"
       class Supplement < Lutaml::Model::Serializable
         attribute :number, :string           # Supplement number (e.g., "2" in "supp2")
-        attribute :year, :string             # Year (4 digits)
-        attribute :month, :string            # Month abbreviation (Jan, Feb, etc.)
-        attribute :month_start, :string       # Date range start month
-        attribute :year_start, :string        # Date range start year
+        attribute :year, :string             # Year (4 digits); range START year
+        attribute :month, :string            # Month abbreviation; range START month
+        # Date ranges reuse :month/:year as the start and add the end below. A
+        # present :month_end/:year_end is what marks a value as a range, so a
+        # lone month-year supplement is just a range with no end — and :year is
+        # the single field to filter on for both.
         attribute :month_end, :string         # Date range end month
         attribute :year_end, :string          # Date range end year
         attribute :has_revision, :boolean, default: -> {
@@ -27,12 +29,36 @@ module Pubid
         } # "supprev" pattern
         attribute :suffix, :string # General suffix for other patterns
 
+        # Build a Supplement from the flat string the parser/builder produces
+        # ("1924" year, "Jan1924" month+year, "1" number, "A" suffix, "" bare).
+        # has_revision is supplied separately. Returns a present-but-empty
+        # Supplement for an empty/nil value so callers can distinguish a bare
+        # supplement ("sup") from no supplement (nil).
+        def self.from_raw(value, has_revision: false)
+          supp = new
+          if has_revision
+            supp.has_revision = true
+          elsif value.nil? || value.to_s.empty?
+            # bare marker: present but no isolated parts
+          elsif (m = value.to_s.match(/\A([A-Za-z]{3,9})(\d{4})\z/))
+            supp.month = m[1]
+            supp.year = m[2]
+          elsif value.to_s.match?(/\A(?:18|19|20)\d{2}\z/)
+            supp.year = value.to_s
+          elsif value.to_s.match?(/\A\d+\z/)
+            supp.number = value.to_s
+          else
+            supp.suffix = value.to_s
+          end
+          supp
+        end
+
         # Render supplement in specified format
         # @param format [:short, :mr, :long] The output format
         # @return [String] The formatted supplement representation
         def to_s(format = :short)
-          return "" if number.nil? && year.nil? && !has_revision && suffix.nil? &&
-            month_start.nil? && year_start.nil? && month_end.nil? && year_end.nil?
+          return "" if number.nil? && year.nil? && month.nil? && !has_revision &&
+            suffix.nil? && month_end.nil? && year_end.nil?
 
           case format
           when :short, :mr
@@ -44,12 +70,52 @@ module Pubid
           end
         end
 
+        # True when this supplement is a date range (start reuses month/year).
+        def range?
+          date_range?
+        end
+
+        # The text after the "sup" marker for the simple (non-range, non-rev)
+        # forms: "1924" / "Jan1924" / "1" / "A"; "" for a bare supplement. Used
+        # by URN rendering, which handles range/revision separately.
+        def value_string
+          return "" if has_revision || date_range?
+          return suffix.to_s if suffix
+          return "#{month}#{year}" if month && year
+          return "#{number}/#{year}" if number && year
+          return year.to_s if year
+          return number.to_s if number
+
+          ""
+        end
+
+        # Value equality over the isolated parts, so a structured supplement
+        # participates correctly in Identifier#== and #matches? (two supplements
+        # with the same number/year/month/range/revision are the same).
+        IDENTITY_FIELDS = %i[
+          number year month month_end year_end has_revision suffix
+        ].freeze
+
+        def ==(other)
+          return false unless other.is_a?(self.class)
+
+          IDENTITY_FIELDS.all? { |f| public_send(f) == other.public_send(f) }
+        end
+
+        alias eql? ==
+
+        def hash
+          [self.class, *IDENTITY_FIELDS.map { |f| public_send(f) }].hash
+        end
+
         private
 
-        # Build short format: "supp2", "supp-1925", "supp3/1926", "suppJan1924", "supprev"
+        # Build short format: "sup2", "sup1925", "sup3/1926", "supJan1924", "suprev"
+        # NIST/NBS canonical short form is single-p "sup" with the suffix
+        # attached directly (relaton-data-nist uses "sup2", "sup1940", "supA").
         def build_short_format
-          return "supprev" if has_revision
-          return "supp#{suffix}" if suffix
+          return "suprev" if has_revision
+          return "sup#{suffix}" if suffix
           return build_date_range_format if date_range?
           return build_month_year_format if month && year
           return build_number_year_format if number && year
@@ -72,32 +138,33 @@ module Pubid
           ""
         end
 
+        # A range is marked by the presence of an END; START reuses month/year.
         def date_range?
-          month_start && year_start && month_end && year_end
+          month && year && month_end && year_end
         end
 
         def build_date_range_format
-          "supp#{month_start}#{year_start}-#{month_end}#{year_end}"
+          "sup#{month}#{year}-#{month_end}#{year_end}"
         end
 
         def build_month_year_format
-          "supp#{month}#{year}"
+          "sup#{month}#{year}"
         end
 
         def build_number_year_format
-          "supp#{number}/#{year}"
+          "sup#{number}/#{year}"
         end
 
         def build_year_format
-          "supp-#{year}"
+          "sup#{year}"
         end
 
         def build_number_format
-          "supp#{number}"
+          "sup#{number}"
         end
 
         def build_long_date_range_format
-          "Supplement #{month_start} #{year_start}-#{month_end} #{year_end}"
+          "Supplement #{month} #{year}-#{month_end} #{year_end}"
         end
 
         def build_long_month_year_format

data/lib/pubid/nist/components.rb

@@ -7,7 +7,6 @@ module Pubid
       autoload :Edition, "#{__dir__}/components/edition"
       autoload :IssueNumber, "#{__dir__}/components/issue_number"
       autoload :Part, "#{__dir__}/components/part"
-      autoload :Publisher, "#{__dir__}/components/publisher"
       autoload :Stage, "#{__dir__}/components/stage"
       autoload :Supplement, "#{__dir__}/components/supplement"
       autoload :Translation, "#{__dir__}/components/translation"

data/lib/pubid/nist/identifier.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Nist
+    # NIST factory entry point. `.parse` lives on `Pubid::Nist` itself for
+    # historical reasons; this module hosts the rest of the flavor-facade API
+    # (`from_hash`, identity) for consistency with the other pubid flavors.
+    #
+    # `extend Pubid::IdentifierFacade` adds polymorphic `from_hash` dispatch
+    # over the NIST `_type` registry; the matching `include Pubid::Nist::
+    # Identifier` in Identifiers::Base makes every concrete NIST identifier
+    # `is_a?(Pubid::Nist::Identifier)` (and `=== id`), so a consumer handed this
+    # module (e.g. relaton-index's `pubid_class`) can both deserialize and
+    # identity-check NIST ids through it.
+    module Identifier
+      extend Pubid::IdentifierFacade
+
+      # Delegate to the flavor module so callers can use
+      # `Pubid::Nist::Identifier.parse` consistently with other flavors.
+      def self.parse(identifier)
+        Pubid::Nist.parse(identifier)
+      end
+    end
+  end
+end