pubid 1.15.21 → 2.0.0.alpha.10

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

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Pubid
+  module Nist
+    module Components
+      # Supplement component for NIST publications
+      # Represents supplement notation with number, year, month, or revision
+      #
+      # Examples:
+      #   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); 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: -> {
+          false
+        } # "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? && month.nil? && !has_revision &&
+            suffix.nil? && month_end.nil? && year_end.nil?
+
+          case format
+          when :short, :mr
+            build_short_format
+          when :long
+            build_long_format
+          else
+            build_short_format
+          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: "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 "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
+          return build_year_format if year
+          return build_number_format if number
+
+          ""
+        end
+
+        # Build long format: "Supplement 2", "Supplement 1925", etc.
+        def build_long_format
+          return "Supplement with Revision" if has_revision
+          return "Supplement #{suffix}" if suffix
+          return build_long_date_range_format if date_range?
+          return build_long_month_year_format if month && year
+          return build_long_number_year_format if number && year
+          return build_long_year_format if year
+          return build_long_number_format if number
+
+          ""
+        end
+
+        # A range is marked by the presence of an END; START reuses month/year.
+        # Months are optional, so a year-only range ("1925-1926") also counts.
+        def date_range?
+          year && year_end
+        end
+
+        def build_date_range_format
+          "sup#{month}#{year}-#{month_end}#{year_end}"
+        end
+
+        def build_month_year_format
+          "sup#{month}#{year}"
+        end
+
+        def build_number_year_format
+          "sup#{number}/#{year}"
+        end
+
+        def build_year_format
+          "sup#{year}"
+        end
+
+        def build_number_format
+          "sup#{number}"
+        end
+
+        def build_long_date_range_format
+          start = [month, year].compact.join(" ")
+          finish = [month_end, year_end].compact.join(" ")
+          "Supplement #{start}-#{finish}"
+        end
+
+        def build_long_month_year_format
+          "Supplement #{month} #{year}"
+        end
+
+        def build_long_number_year_format
+          "Supplement #{number}/#{year}"
+        end
+
+        def build_long_year_format
+          "Supplement #{year}"
+        end
+
+        def build_long_number_format
+          "Supplement #{number}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Pubid
+  module Nist
+    module Components
+      # Translation component for NIST publications
+      # Uses 3-letter ISO 639-2 language codes
+      #
+      # Examples:
+      #   Translation.new(code: "spa").to_s(:short) # => " spa"
+      #   Translation.new(code: "por").to_s(:mr)    # => ".por"
+      #   Translation.new(code: "ind").to_s(:short) # => " ind"
+      class Translation < Lutaml::Model::Serializable
+        attribute :code, :string # 3-letter ISO 639-2 code: spa, por, ind, etc.
+
+        # Backward compatibility: language method returns code
+        # @return [String, nil] language code
+        def language
+          code
+        end
+
+        # Render translation in specified format
+        # @param format [:short, :mr, :long] The output format
+        # @return [String] The formatted translation representation
+        def to_s(format = :short)
+          return "" if code.nil?
+
+          case format
+          when :short, :long
+            " #{code}"
+          when :mr
+            ".#{code}"
+          else
+            " #{code}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require "date"
+
+module Pubid
+  module Nist
+    module Components
+      # Update component for NIST publications
+      # Represents errata updates with number, year, and optional month
+      #
+      # Examples:
+      #   Update.new(number: 1, year: 2021, month: 2).to_s(:short) # => "/Upd1-202102"
+      #   Update.new(number: 3, year: 2015).to_s(:short)           # => "/Upd3-2015"
+      #   Update.new(number: 1, year: 2021, month: 2).to_s(:mr)    # => "-upd1-202102"
+      #   Update.new(number: 1, prefix: "dash").to_s(:short)       # => "-upd1" (preserves original prefix)
+      class Update < Lutaml::Model::Serializable
+        attribute :number, :string   # Update number as string
+        attribute :year, :string     # Year (4 digits as string)
+        attribute :month, :string    # Month (01-12 as string, optional)
+        attribute :prefix, :string   # Original prefix: "dash" for -upd, "slash" for /Upd (default: "slash")
+
+        # Render update in specified format
+        # @param format [:short, :mr, :long] The output format
+        # @return [String] The formatted update representation
+        def to_s(format = :short)
+          # For MR format, render -upd even without number
+          return "-upd" if format == :mr && number.nil? && year.nil?
+          # For other formats, return empty string if no number
+          return "" if number.nil?
+
+          # Use prefix attribute to determine which prefix to use
+          # If prefix is "dash", always use dash prefix regardless of format
+          # This preserves original input format (e.g., -upd vs /Upd)
+          return build_dash_format if prefix == "dash"
+
+          case format
+          when :short
+            build_short_format
+          when :mr
+            build_mr_format
+          when :long
+            build_long_format
+          else
+            build_short_format
+          end
+        end
+
+        private
+
+        # Build dash format: "-upd1-202102" or "-upd3-2015" or "-upd1" (no year)
+        # Used when original input used dash prefix (-upd) to preserve format
+        def build_dash_format
+          if year
+            year_month = build_year_month_string
+            "-upd#{number}-#{year_month}"
+          else
+            "-upd#{number}"
+          end
+        end
+
+        # Build short format: "/Upd1-202102" or "/Upd3-2015" or "/Upd1" (no year)
+        def build_short_format
+          if year
+            year_month = build_year_month_string
+            "/Upd#{number}-#{year_month}"
+          else
+            "/Upd#{number}"
+          end
+        end
+
+        # Build machine-readable format: "-upd1-202102" or "-upd3-2015" or "-upd1" (no year)
+        def build_mr_format
+          if year
+            year_month = build_year_month_string
+            "-upd#{number}-#{year_month}"
+          else
+            "-upd#{number}"
+          end
+        end
+
+        # Build long format: "Update 1-2021 February" or "Update 3-2015"
+        def build_long_format
+          return "Update #{number}" unless year
+
+          month_str = month ? " #{Date::MONTHNAMES[month.to_i]}" : ""
+          "Update #{number}-#{year}#{month_str}"
+        end
+
+        # Build year-month string: "202102" or "2015"
+        def build_year_month_string
+          return "" unless year
+
+          if month
+            "#{year}#{month.to_s.rjust(2, '0')}"
+          else
+            year.to_s
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Pubid
+  module Nist
+    module Components
+      # Version component for NIST publications
+      # Uses dotted notation: "1.0.2", "2.0", etc.
+      #
+      # Examples:
+      #   Version.new(value: "1.0.2").to_s(:short) # => "ver1.0.2"
+      #   Version.new(value: "2.0").to_s(:long)    # => "Version 2.0"
+      class Version < Lutaml::Model::Serializable
+        attribute :value, :string # Dotted notation: "1.0.2"
+
+        # Render version in specified format
+        # @param format [:short, :mr, :long] The output format
+        # @return [String] The formatted version representation
+        def to_s(format = :short)
+          return "" if value.nil?
+
+          case format
+          when :short, :mr
+            "ver#{value}"
+          when :long
+            "Version #{value}"
+          else
+            "ver#{value}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Pubid
+  module Nist
+    module Components
+      # Volume component for NIST publications
+      # Format: v{NUMBER} where NUMBER is the volume number
+      #
+      # Examples:
+      #   Volume.new(value: "6").to_s => "v6"
+      #   Volume.new(value: "12").to_s => "v12"
+      #
+      # Used in:
+      #   - CSM (Commercial Standards Monthly): Volume 6, Issue 1
+      #   - CIRC (Circular): Volume 539
+      class Volume < Lutaml::Model::Serializable
+        attribute :value, :string
+
+        def to_s
+          "v#{value}"
+        end
+
+        # Alias for numeric comparison
+        def to_i
+          value.to_i
+        end
+      end
+    end
+  end
+end

data/lib/pubid/nist/components.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Nist
+    module Components
+      autoload :Code, "#{__dir__}/components/code"
+      autoload :Edition, "#{__dir__}/components/edition"
+      autoload :IssueNumber, "#{__dir__}/components/issue_number"
+      autoload :Part, "#{__dir__}/components/part"
+      autoload :Stage, "#{__dir__}/components/stage"
+      autoload :Supplement, "#{__dir__}/components/supplement"
+      autoload :Translation, "#{__dir__}/components/translation"
+      autoload :Update, "#{__dir__}/components/update"
+      autoload :Version, "#{__dir__}/components/version"
+      autoload :Volume, "#{__dir__}/components/volume"
+    end
+  end
+end

data/lib/pubid/nist/configuration.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Pubid
+  module Nist
+    # Configuration class responsible for loading and managing series definitions
+    # Single Responsibility: Series configuration management
+    class Configuration
+      attr_reader :series
+
+      def initialize(series_file_path = nil)
+        @series_file_path = series_file_path || default_series_path
+        load_series
+      end
+
+      # Get series long name
+      # @param series_code [String] the series code (e.g., "SP", "FIPS")
+      # @return [String, nil] the long name or nil if not found
+      def series_long_name(series_code)
+        @series.dig("long", series_code)
+      end
+
+      # Get series abbreviation
+      # @param series_code [String] the series code
+      # @return [String, nil] the abbreviation or nil if not found
+      def series_abbrev(series_code)
+        @series.dig("abbrev", series_code)
+      end
+
+      # Get series MR (machine-readable) format
+      # @param series_code [String] the series code
+      # @return [String, nil] the MR format or nil if not found
+      def series_mr(series_code)
+        @series.dig("mr", series_code)
+      end
+
+      # Check if series code is valid
+      # @param series_code [String] the series code
+      # @return [Boolean] true if series is valid
+      def valid_series?(series_code)
+        @series["long"].key?(series_code)
+      end
+
+      # Get all series codes
+      # @return [Array<String>] all valid series codes
+      def all_series_codes
+        @series["long"].keys
+      end
+
+      # Get series code from MR format
+      # @param mr_format [String] the MR format
+      # @return [String, nil] the series code or nil if not found
+      def series_from_mr(mr_format)
+        @series["mr"].key(mr_format)
+      end
+
+      private
+
+      def default_series_path
+        # Prefer data/nist/series.yaml (the canonical home in the monorepo);
+        # fall back to archived-gems/pubid-nist/series.yaml for backward
+        # compat with the v1 layout.
+        monorepo = File.join(__dir__, "../../../data/nist/series.yaml")
+        return monorepo if File.exist?(monorepo)
+
+        File.join(__dir__, "../../../archived-gems/pubid-nist/series.yaml")
+      end
+
+      def load_series
+        @series = YAML.load_file(@series_file_path)
+      rescue Errno::ENOENT
+        raise ConfigurationError,
+              "Series configuration file not found: #{@series_file_path}"
+      rescue Psych::SyntaxError => e
+        raise ConfigurationError,
+              "Invalid YAML in series configuration: #{e.message}"
+      end
+    end
+
+    # Raised when the NIST series YAML cannot be loaded. Included in the
+    # marker module so `rescue Pubid::Errors::Error` stays exhaustive.
+    class ConfigurationError < StandardError
+      include ::Pubid::Errors::Error
+    end
+  end
+end

data/lib/pubid/nist/identifier.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# The NIST flavor base class is Pubid::Nist::Identifier — a real
+# Pubid::Identifier subclass that every concrete NIST identifier descends from,
+# so `id.is_a?(Pubid::Nist::Identifier)` and the shared polymorphic `from_hash`
+# work natively (no facade needed). Its full body and `.parse` are defined in identifiers/base.rb to keep
+# that large body in one place; this file just ensures it is loaded when a
+# consumer references Pubid::Nist::Identifier directly.