Class: Pubid::Nist::Caster

Inherits:

Object

Object
Pubid::Nist::Caster

show all

Defined in:: lib/pubid/nist/caster.rb

Overview

Caster class for NIST type coercion Single Responsibility: Convert parsed values to domain component objects

Extracted from Builder to isolate the 1200+ line type coercion switch from orchestration logic. Caster is stateless — each call to #cast receives all the context it needs via parameters.

Constant Summary collapse

TRANSLATION_MAP = Translation normalization map (V1 compatibility)

{
  "es" => "spa",
  "sp" => "spa",
  "pt" => "por",
  "id" => "ind",
  "chi" => "zho",
  "viet" => "vie",
  "port" => "por",
  "esp" => "spa",
}.freeze

Instance Method Summary collapse

#cast(type, value, parsed_hash = {}) ⇒ Object, ...

Cast parsed value to appropriate component type ALL conversions happen in this single method.
#handle_addendum_cast(value) ⇒ Object

Handle addendum casting (number).
#handle_supplement_cast(value) ⇒ Object

Handle supplement casting with all its variants.
#month_name_to_number(month_name) ⇒ Integer

Convert month name to month number.

Instance Method Details

#cast(type, value, parsed_hash = {}) ⇒ `Object`, ...

Cast parsed value to appropriate component type ALL conversions happen in this single method

Parameters:

type (Symbol) —

the parameter type
value (Object) —

the parsed value
parsed_hash (Hash) (defaults to: {}) —

the full parsed hash for context

Returns:

(Object, Hash, nil) —

the cast component(s)

# File 'lib/pubid/nist/caster.rb', line 30

def cast(type, value, parsed_hash = {})
  case type
  when :publisher
    return nil if value.nil? || value.to_s.strip.empty?

    # publisher is a plain string attribute (see Identifiers::Base).
    value.to_s

  when :dated_date
    # Date-style identifier (DatedDocument): carry the YYYY-MM-DD parts
    # as string attributes.
    return nil unless value.is_a?(Hash)

    { date_year: value[:date_year]&.to_s, date_month: value[:date_month]&.to_s,
      date_day: value[:date_day]&.to_s }

  when :dated_seq
    return nil if value.to_s.strip.empty?

    { dated_seq: value.to_s }

  when :series
    return nil if value.nil? || value.to_s.strip.empty?

    str_value = value.to_s
    publisher_extracted = nil

    # Compound series carry the publisher inside the series token (e.g.
    # "NBS CIRC", "NIST DCI") because the bare series code isn't recognized
    # by the grammar on its own. Split the leading publisher out so
    # `series` holds just the code and `publisher` is populated — matching
    # how standalone series (NIST SP, NBS CS) already parse, and avoiding a
    # nil publisher (which renders fine via the series string but would
    # otherwise force a misleading publisher_was_parsed: false). Routing
    # already ran on the raw compound series, so stripping here can't
    # change the identifier class.
    if (m = str_value.match(/\A(NBS|NIST) (.+)\z/))
      publisher_extracted = m[1]
      str_value = m[2]
    end

    # Return composite hash with both publisher and series if extracted
    if publisher_extracted
      {
        publisher: publisher_extracted,
        series: Components::Code.new(value: str_value),
      }
    else
      Components::Code.new(value: str_value)
    end

  when :volume_number
    # Volume from v#n# pattern - return Volume component
    return nil if value.nil? || value.to_s.strip.empty?

    { volume: Components::Volume.new(value: value.to_s) }

  when :issue_number
    # Issue number from v#n# pattern - return Part component
    return nil if value.nil? || value.to_s.strip.empty?

    { part: Components::Part.new(type: "n", value: value.to_s) }

  when :part_number
    # Part number from GCR pattern (e.g., 85-3273-37)
    # Return raw value for inclusion in compound number
    return nil if value.nil? || value.to_s.strip.empty?

    value # Return raw value to be tracked in builder

  when :letter_number
    # Letter suffix from a dashed pattern (e.g., 800-56A → {:letter_base=>"56", :letter_suffix=>"A"}).
    # Series policy decides whether the suffix becomes a Part component
    # (default) or stays in the number (MONO/NCSTAR/IR-with-R-or-Ur).
    return nil if value.nil? || !value.is_a?(Hash)

    Series.for(parsed_hash).cast_letter_number(value, parsed_hash)

  when :fips_part
    # Part number from FIPS date pattern (e.g., 11-1-Sep30/1977)
    # Return Part component with pt type
    return nil if value.nil? || value.to_s.strip.empty?

    { part: Components::Part.new(type: "pt", value: value.to_s) }

  when :owmwp_date_number
    # OWMWP date-based number format (MM-DD-YYYY)
    # Parser returns: {:owmwp_month=>"06", :owmwp_day=>"13", :owmwp_year=>"2018"}
    # Convert to number + edition: "06-13" + edition "e2018"
    return nil if value.nil?

    number_part = "#{value[:owmwp_month]}-#{value[:owmwp_day]}"
    edition_part = Components::Edition.new(type: "e",
                                           id: value[:owmwp_year])
    { first_number: Components::Code.new(value: number_part), edition: edition_part }

  when :first_number, :second_number
    return nil if value.nil? || value.to_s.strip.empty?

    # NEW: Handle OWMWP date-based number (nested hash structure)
    # Parser returns: {:owmwp_date_number=>{:owmwp_month=>"06", :owmwp_day=>"13", :owmwp_year=>"2018"}}
    # Convert to number + edition: "06-13" + edition "e2018"
    if value.is_a?(Hash) && value[:owmwp_date_number]
      owmwp_hash = value[:owmwp_date_number]
      number_part = "#{owmwp_hash[:owmwp_month]}-#{owmwp_hash[:owmwp_day]}"
      edition_part = Components::Edition.new(type: "e",
                                             id: owmwp_hash[:owmwp_year])
      return { type => Components::Code.new(value: number_part), edition: edition_part }
    end

    # NEW: Handle second_number with edition (hash with :number_only and :edition_id)
    # This handles "126r2013" pattern where parser returns {:number_only=>"126", :edition_id=>"2013"}
    # CRITICAL: Wrap in a structure that builder loop can recognize
    # The builder loop expects keys like :second_number to be present in the hash
    if type == :second_number && value.is_a?(Hash) && value[:number_only] && value[:edition_id]
      # Return wrapped hash so builder loop finds :second_number key
      return { second_number: value }
    end

    # NEW: Handle second_number with revision_letter (hash with :revision_letter containing :number_only and :letter)
    # This handles "27ra" pattern where parser returns {revision_letter: {number_only: "27", letter: "a"}}
    # Should be combined to "27rA" format
    if type == :second_number && value.is_a?(Hash) && value[:revision_letter]
      revision_data = value[:revision_letter]
      number_only = revision_data[:number_only].to_s
      letter = revision_data[:letter].to_s.upcase
      # Return as second_number with combined format "27rA"
      return { second_number: Components::Code.new(value: "#{number_only}r#{letter}") }
    end

    # Handle v#n# pattern (CSM series) - comes as hash from parser
    # Return Volume and Part components separately
    if value.is_a?(Hash) && value[:volume_number] && value[:issue_number]
      volume_num = value[:volume_number].to_s
      issue_num = value[:issue_number].to_s
      return {
        volume: Components::Volume.new(value: volume_num),
        part: Components::Part.new(type: "n", value: issue_num),
      }
    end

    str_value = value.to_s

    # Handle special patterns embedded in first_number
    if type == :first_number

      # NEW: Handle first_number hash with number_with_rev_year (e.g., "1013rv1953")
      # Parser returns: {:number_with_rev_year=>{:number=>"1013", :revision_year=>"1953"}}
      if value.is_a?(Hash) && value[:number_with_rev_year]
        number_part = value[:number_with_rev_year][:number].to_s
        revision_year = value[:number_with_rev_year][:revision_year].to_s
        return {
          first_number: Components::Code.new(value: number_part),
          edition: Components::Edition.new(type: "rv", id: revision_year),
        }
      end

      # Handle first_number with letter suffix and revision (e.g., "8278Ar1", "256Ar1930")
      # Parser returns: {:number_with_letter_revision=>{:number=>"8278", :letter_suffix=>"A", :revision_id=>"1"}}
      # Splits into number + Part(letter) + Edition(r, id) to mirror how :letter_number
      # (dash-separated "56Ar2") is decomposed for SpecialPublication and similar series.
      if value.is_a?(Hash) && value[:number_with_letter_revision]
        data = value[:number_with_letter_revision]
        return {
          first_number: Components::Code.new(value: data[:number].to_s),
          part: Components::Part.new(type: "",
                                     value: data[:letter_suffix].to_s.upcase),
          edition: Components::Edition.new(type: "r",
                                           id: data[:revision_id].to_s),
          edition_component: Components::Edition.new(type: "r",
                                                      id: data[:revision_id].to_s),
          revision: "r#{data[:revision_id]}",
        }
      end

      # NEW: Handle first_number hash with language_code (e.g., "1262es")
      # Parser returns: {:number=>"1262", :language_code=>"es"}
      if value.is_a?(Hash) && value[:number] && value[:language_code]
        number_part = value[:number].to_s
        language_code = value[:language_code].to_s.strip.downcase
        # Apply normalization map (es -> spa, pt -> por, etc.)
        normalized_code = TRANSLATION_MAP[language_code] || language_code
        return {
          first_number: Components::Code.new(value: number_part),
          translation_component: Components::Translation.new(code: normalized_code),
        }
      end

      # NEW: Handle first_number hash with number, part_number, and edition_year (MR format)
      # Parser returns: {:number=>"28", :part_number=>"1", :edition_year=>"1969"}
      # For "NBS.HB.28pt1e1969" MR format input
      if value.is_a?(Hash) && value[:number] && value[:part_number] && value[:edition_year]
        number_part = value[:number].to_s
        part_number = value[:part_number].to_s
        edition_year = value[:edition_year].to_s
        return {
          first_number: Components::Code.new(value: number_part),
          part: Components::Part.new(type: "pt", value: part_number),
          edition: Components::Edition.new(type: "e", id: edition_year),
        }
      end

      # NEW: Check for edition_year_separate in parsed_hash context
      # This handles "11e2-1915" where first_number="11e2" and edition_year_separate="1915"
      if parsed_hash[:edition_year_separate] && str_value =~ /^(\d+)e(\d+)$/
        number_part = $1
        edition_id = $2
        year_part = parsed_hash[:edition_year_separate].to_s
        return {
          first_number: Components::Code.new(value: number_part),
          edition: Components::Edition.new(type: "e", id: edition_id,
                                           additional_text: year_part),
        }
      end

      # NEW: Check for number_with_volume in value hash (for first_number)
      # This handles "539v10" where parser captures :number and :volume_suffix separately
      # Parse tree: value = {:number_with_volume => {:number => "539", :volume_suffix => "10"}}
      if value.is_a?(Hash) && value[:number_with_volume] && value[:number_with_volume][:volume_suffix]
        number_part = value[:number_with_volume][:number].to_s
        volume_value = value[:number_with_volume][:volume_suffix].to_s
        return {
          first_number: Components::Code.new(value: number_part),
          volume: Components::Volume.new(value: volume_value),
        }
      end

      # NEW: Check for historical_month and historical_year in parsed_hash context
      # This handles "-April1909" where it's captured as separate month/year
      if parsed_hash[:historical_month] && parsed_hash[:historical_year]
        month_part = parsed_hash[:historical_month].to_s
        year_part = parsed_hash[:historical_year].to_s
        # Check if str_value is just a number (the part before dash)
        if /^\d+$/.match?(str_value)
          return {
            first_number: Components::Code.new(value: str_value),
            edition: Components::Edition.new(type: "-",
                                             additional_text: "#{month_part}#{year_part}"),
          }
        else
          # No number, just historical edition
          return {
            edition: Components::Edition.new(type: "-",
                                             additional_text: "#{month_part}#{year_part}"),
          }
        end
      end

      # Pattern "9350sup"/"5893supp" - number with bare supplement marker
      # (no trailing payload). Accept both single-p "sup" and double-p
      # "supp" so the marker is isolated as supplement="" and rendered as
      # canonical single-p "sup", instead of staying baked into the number
      # as an opaque suffix. E.g. "NBS RPT 5893supp", "NBS MONO 32supp".
      if str_value =~ /^(\d+)supp?$/
        return {
          first_number: Components::Code.new(value: $1),
          supplement: "",
        }
      end

      # NEW: Check for supplement_year in parsed_hash context
      # This handles "25supp-1924" where first_number="25supp" and supplement_year="1924"
      if parsed_hash[:supplement_year] && str_value =~ /^(\d+)supp?$/
        number_part = $1
        year_part = parsed_hash[:supplement_year].to_s
        return {
          first_number: Components::Code.new(value: number_part),
          supplement: year_part,
        }
      end

      # Pattern: "154supprev" - supplement with revision
      if str_value =~ /^(\d+)supprev$/
        return {
          first_number: Components::Code.new(value: $1),
          supplement: "",
          supplement_has_revision: true,
        }
      # NEW: Pattern "11e2-1915" - edition with separate year (inline match)
      # Creates: number="11", Edition(type: "e", id: "2", additional_text: "1915")
      # Renders: "NBS CIRC 11e2.1915"
      elsif str_value =~ /^(\d+)e(\d+)-(\d{4})$/
        number_part = $1
        edition_id = $2
        year_part = $3
        return {
          first_number: Components::Code.new(value: number_part),
          edition: Components::Edition.new(type: "e", id: edition_id,
                                           additional_text: year_part),
        }
      # NEW: Pattern "-April1909" - historical edition with month+year (inline match)
      # Creates: Edition(type: "-", additional_text: "April1909")
      # Renders: "NBS CIRC -April1909"
      elsif str_value =~ /^-([A-Za-z]{3,9})(\d{4})$/
        month_part = $1
        year_part = $2
        return {
          edition: Components::Edition.new(type: "-",
                                           additional_text: "#{month_part}#{year_part}"),
        }
      # NEW: CS Emergency pattern "e104" or "e104-43" -> extract number
      # This must come BEFORE bare edition check to avoid conflict
      # CS emergency always has 3+ digit number (e104, not e2)
      # NOTE: If second_number exists (e104-43 pattern), defer to compound number logic
      elsif /^e(\d{3,})$/.match?(str_value) && !parsed_hash[:second_number]
        # Extract emergency number: e104 -> 104 (only when no second_number)
        emergency_num = str_value.sub(/^e/, "")
        return {
          first_number: Components::Code.new(value: emergency_num),
        }
      # If e104-43 pattern (with second_number), keep e prefix for compound number logic
      elsif /^e(\d{3,})$/.match?(str_value) && parsed_hash[:second_number]
        # Keep e104 as-is, let compound number logic handle it
        return {
          first_number: Components::Code.new(value: str_value),
        }
      # NEW: Bare edition pattern like "100e1" (CS series without year)
      # ONLY when NO second_number present (to avoid conflict with "123e2-50")
      # Creates: number="100", Edition(type: "e", id: "1")
      # Renders: "NBS CS 100e1"
      # CRITICAL: Skip if edition_dash_year is present - let that handler create Edition with additional_text
      elsif str_value =~ /^(\d+)e(\d+)$/ && !parsed_hash[:second_number] && !parsed_hash[:edition_dash_year]
        number_part = $1
        edition_id = $2

        return {
          first_number: Components::Code.new(value: number_part),
          edition: Components::Edition.new(type: "e", id: edition_id),
        }
      # NEW: Bare edition pattern "e2" - just edition without number prefix
      # Creates: Edition(type: "e", id: "2")
      # Renders: "NBS CIRC e2"
      # Only matches single or double digit (e1, e2, not e104 which is emergency)
      elsif str_value =~ /^e(\d{1,2})$/
        edition_id = $1
        return {
          edition: Components::Edition.new(type: "e", id: edition_id),
        }
      # Pattern: "13e2rev1908" - edition with revision year-only (NO month)
      # Creates: Edition(type: "e", id: "2", additional_text: "1908")
      # Renders: "e2.1908" (DOT separator)
      elsif str_value =~ /^(\d+)e(\d+)rev(\d{4})$/
        # CRITICAL: Capture BEFORE any regex method calls!
        number_part = $1
        edition_id_part = $2
        year_part = $3
        return {
          first_number: Components::Code.new(value: number_part),
          edition: Components::Edition.new(type: "e",
                                           id: edition_id_part, additional_text: year_part),
        }
      # Pattern: "13e2revJune1908" - edition with revision month+year
      # Creates: Edition(type: "e", id: "2", additional_text: "June1908")
      # Renders: "e2.June1908" (DOT separator)
      elsif str_value =~ /^(\d+)e(\d+)(rev.+)$/
        # CRITICAL: Capture $1, $2, $3 BEFORE calling .sub() which resets them!
        number_part = $1
        edition_id_part = $2
        rev_part = $3
        # Strip "rev" prefix from additional_text - store only "June1908" or "1908"
        additional_text = rev_part.sub(/^rev/, "")
        return {
          first_number: Components::Code.new(value: number_part),
          edition: Components::Edition.new(type: "e",
                                           id: edition_id_part, additional_text: additional_text),
        }
      # NEW: Pattern "24suppJan1924" - supplement with month and year in first_number
      # Creates: number="24", supplement="Jan1924"
      elsif str_value =~ /^(\d+)supp([A-Za-z]{3,9})(\d{4})$/
        number_part = $1
        month_part = $2
        year_part = $3
        return {
          first_number: Components::Code.new(value: number_part),
          supplement: "#{month_part}#{year_part}",
        }
      # NEW: Pattern "25supp1924" - supplement with year (no dash, no month)
      # Creates: number="25", supplement="1924"
      # Renders: "NBS SP 25supp1924"
      elsif str_value =~ /^(\d+)supp(\d{4})$/
        number_part = $1
        year_part = $2
        return {
          first_number: Components::Code.new(value: number_part),
          supplement: year_part,
        }
      # NEW: Pattern "25supp-1924" - supplement with dash-year (inline match)
      # Creates: number="25", supplement="1924"
      # Renders: "NBS CIRC 25supp-1924"
      elsif str_value =~ /^(\d+)supp-(\d{4})$/
        number_part = $1
        year_part = $2
        return {
          first_number: Components::Code.new(value: number_part),
          supplement: year_part,
        }
      # NEW: Pattern "101e2supp" - edition + supplement
      # Creates: number="101", Edition(type: "e", id: "2"), supplement=""
      # Renders: "NBS CIRC 101e2supp"
      elsif str_value =~ /^(\d+)e(\d+)supp$/
        number_part = $1
        edition_id = $2
        return {
          first_number: Components::Code.new(value: number_part),
          edition: Components::Edition.new(type: "e", id: edition_id),
          supplement: "",
        }
      end
    elsif type == :second_number && value.is_a?(Hash) && value[:first_number]
      # Handle second_number as a hash with first_number context
      # e.g., for pattern 800-57pt1r4
      number_part = value[:first_number].to_s
      part_value = value[:part_value]&.to_s
      revision_value = value[:revision_value]&.to_s
      return {
        first_number: Components::Code.new(value: number_part),
        part: Components::Part.new(value: part_value),
        edition: Components::Edition.new(type: "r", id: revision_value),
      }
    end

    # Extract revision suffix from number (e.g., "53r5" -> "53" + Edition(r, 5))
    # ENHANCED: Also extract revision with slash-year (e.g., "53r5/1917" -> "53" + Edition)
    # ENHANCED: Also extract revision with 4-digit year (e.g., "1019r1963" -> "1019" + Edition)
    # ENHANCED: Also extract revision with month+year (e.g., "4743rJun1992" -> "4743" + Edition)

    # NEW: Extract part suffix from number (e.g., "800-57pt1" -> "800-57" + Part(1))
    # This handles SP series part notation
    # IMPORTANT: Handle combined part+revision first (e.g., "800-57pt1r4")
    if str_value =~ /^(.+?)pt(\d+)r(\d+[a-z]?)$/
      number_part = $1
      part_value = $2
      revision_value = $3
      return {
        type => Components::Code.new(value: number_part),
        part: Components::Part.new(type: "pt", value: part_value),
        edition: Components::Edition.new(type: "r", id: revision_value),
      }
    elsif str_value =~ /^(.+?)pt(\d+)$/
      number_part = $1
      part_value = $2
      return {
        type => Components::Code.new(value: number_part),
        part: Components::Part.new(type: "pt", value: part_value),
      }
    end

    # NEW: Extract volume suffix from number (e.g., "539v10" -> "539" + volume="10")
    # This handles CIRC volume notation
    if str_value =~ /^(\d+)v(\d+)$/
      number_part = $1
      volume_part = $2
      return {
        type => Components::Code.new(value: number_part),
        volume: volume_part,
      }
    end

    # REVISION PATTERNS - These must come BEFORE letter suffix to avoid conflicts
    case str_value
    when /^(.+?)(r\d+\/\d{4})$/i
      # Pattern: r6/1925 (revision with slash-year)
      number_part = $1
      revision_with_year = $2 # e.g., "r6/1925"
      # Extract revision and year
      if revision_with_year =~ /^r(\d+)\/(\d{4})$/
        revision_id = $1
        year_part = $2
        return {
          type => Components::Code.new(value: number_part),
          edition: Components::Edition.new(type: "r", id: revision_id,
                                           additional_text: year_part),
        }
      end
    when /^(.*\d)(r\d{4})$/i
      # Pattern: r1963 (revision as 4-digit year)
      number_part = $1
      year_value = $2.sub(/^r/, "") # Strip 'r' prefix
      return {
        type => Components::Code.new(value: number_part),
        edition: Components::Edition.new(type: "r", id: year_value),
      }
    when /^(.+?)(r[A-Za-z]{3,9}\d{4})$/i
      # Pattern: rJun1992 (revision with month and year)
      number_part = $1
      revision_with_date = $2 # e.g., "rJun1992"
      # Extract month and year
      if revision_with_date =~ /^r([A-Za-z]{3,9})(\d{4})$/
        month_part = $1
        year_part = $2
        return {
          type => Components::Code.new(value: number_part),
          edition: Components::Edition.new(type: "r",
                                           id: "#{month_part}#{year_part}"),
        }
      end
    when /^(.*\d)(r\d+[a-z]?)$/i
      # Pattern: r5, r1a (simple revision)
      number_part = $1
      revision_value = $2.sub(/^r/, "") # Strip 'r' prefix
      return {
        type => Components::Code.new(value: number_part),
        edition: Components::Edition.new(type: "r", id: revision_value),
      }
    when /^(.+?)(?<![a-zA-Z])(r)$/i
      # Pattern: bare r with no digits (e.g., "800-90r")
      # Negative lookbehind ensures r is NOT preceded by a letter (avoids matching Ur, Ua, etc.)
      number_part = $1
      return {
        type => Components::Code.new(value: number_part),
        edition: Components::Edition.new(type: "r", id: "1"),
      }
    end

    # NEW: Extract UPPERCASE letter suffix as Part component (e.g., "800-56A" -> "800-56" + Part)
    # IMPORTANT: These patterns come AFTER revision patterns to avoid conflicts
    # Letter suffixes are UPPERCASE letters A-Z only (no lowercase to avoid revision markers)

    # Pattern: UPPERCASE letter + revision (e.g., "800-56Ar2" -> number + Part("", "A") + Edition(r, 2))
    # NO /i flag - only match uppercase letters!
    if str_value =~ /^(.+?)([A-Z])(r\d+[a-z]?)$/
      number_part = $1
      letter_part = $2
      revision_part = $3.sub(/^r/, "")
      return {
        type => Components::Code.new(value: number_part),
        part: Components::Part.new(type: "", value: letter_part),
        edition: Components::Edition.new(type: "r", id: revision_part),
      }
    # Pattern: bare UPPERCASE letter suffix (e.g., "800-56A" -> number + Part("", "A"))
    # Only matches uppercase letters - won't match revision markers.
    # Series policy decides whether the letter stays in the number
    # (MR format, RPT/FIPS/IR/CRPL/LC/MONO/MP) or becomes a Part.
    elsif str_value =~ /^(.+?)([A-Z])$/
      number_part = $1
      letter_part = $2

      if Series.for(parsed_hash).preserve_letter_suffix?(parsed_hash)
        return { type => Components::Code.new(value: str_value) }
      else
        return {
          type => Components::Code.new(value: number_part),
          part: Components::Part.new(type: "", value: letter_part),
        }
      end
    end

    Components::Code.new(value: str_value)

  when :crpl_range
    return nil if value.nil? || value.to_s.strip.empty?

    # For CRPL range patterns like "2_3-1" or "2_3-1A" (with supplement)
    # Format: X_Y-Z where X,Y,Z are digits, optional trailing letter is supplement
    # This should split into:
    # - X -> second_number (to combine with first_number as "1-X")
    # - Y-Z -> Part component (with type "pt" for CRPL)
    # - trailing letter (if present) -> Supplement
    str_value = value.to_s

    # Check for supplement letter suffix (e.g., "2_3-1A" -> supplement="A")
    if str_value =~ /^(\d+)_(\d+-\d+)([A-Z])$/
      second_num_part = $1 # "2"
      part_value = $2 # "3-1"
      supplement_letter = $3 # "A"

      # Return second_number, Part, and Supplement
      {
        second_number: Components::Code.new(value: second_num_part),
        part: Components::Part.new(type: "pt", value: part_value),
        supplement: supplement_letter,
      }
    elsif str_value =~ /^(\d+)_(\d+-\d+)$/
      # No supplement letter
      second_num_part = $1 # "2"
      part_value = $2 # "3-1"

      # Return second_number and Part
      {
        second_number: Components::Code.new(value: second_num_part),
        part: Components::Part.new(type: "pt", value: part_value),
      }
    else
      # Fallback: treat entire value as second_number (shouldn't happen with valid CRPL patterns)
      Components::Code.new(value: str_value)
    end

  # ========== V2 COMPONENT CASTING ==========

  when :stage
    # Stage from nested hash with id and type
    return nil unless value.is_a?(Hash)

    stage_id = value[:stage_id]&.to_s&.downcase
    stage_type = value[:stage_type]&.to_s&.downcase
    return nil if stage_id.nil? || stage_type.nil? || stage_id.empty? || stage_type.empty?

    # Return as hash to set the stage attribute
    { stage: Components::Stage.new(id: stage_id, type: stage_type) }

  when :stage_id, :stage_type
    # These are captured by :stage, so skip individual processing
    nil

  when :parsed_format
    # Format detection result from parser. :short is the render default
    # (a nil parsed_format renders short — see Identifiers::Base#to_s), so
    # store only non-default formats (e.g. "mr"); "short" stays unset and
    # is omitted from to_hash. detect_format only emits :mr or :short.
    v = value&.to_s
    v unless v == "short"

  when :translation
    # V1 TRANSLATION NORMALIZATION
    return nil if value.nil? || value.to_s.strip.empty?

    code = value.to_s.strip.downcase
    # Apply normalization map (es -> spa, pt -> por, etc.)
    normalized_code = TRANSLATION_MAP[code] || code

    # Return as hash to set translation_component attribute
    { translation_component: Components::Translation.new(code: normalized_code) }

  when :version
    # Version component with dotted notation
    return nil if value.nil? || value.to_s.strip.empty?

    # Return as hash to set version_component attribute
    { version_component: Components::Version.new(value: value.to_s) }

  when :update
    # Update component with number, year, and optional month
    if value.is_a?(Hash)
      # Convert Parslet slice to regular Hash for reliable key access
      value_hash = value.to_h

      number = value_hash[:update_number]&.to_s # Don't default to "1"
      year = value_hash[:update_year]&.to_s     # String not integer
      month = value_hash[:update_month]&.to_s   # String not integer

      # Determine prefix from update_prefix key (captured by parser)
      # If not present, default to "slash" (/Upd format)
      prefix_str = value_hash[:update_prefix]&.to_s
      prefix_value = if prefix_str&.include?("-") || prefix_str == "-upd"
                       "dash"
                     else
                       "slash"
                     end

      # Create update with at least number
      update_obj = Components::Update.new(number: number, year: year,
                                          month: month, prefix: prefix_value)
      {
        update: update_obj, # Main attribute for tests
        update_component: update_obj, # V2 component
      }
    elsif value.to_s.strip.empty?
      # Empty update string means "-upd" or "/upd" with no details
      # Create Update with default number="1" (no year/month)
      # Check update_prefix key to determine correct prefix format
      prefix_str = parsed_hash[:update_prefix]&.to_s
      prefix_value = if prefix_str&.include?("-") || prefix_str == "-upd"
                       "dash"
                     else
                       "slash"
                     end
      update_obj = Components::Update.new(number: "1", year: nil,
                                          month: nil, prefix: prefix_value)
      {
        update: update_obj,
        update_component: update_obj,
      }
    else
      # Simple string value - shouldn't reach here
      { update: value.to_s.strip } unless value.to_s.strip.empty?
    end

  when :update_prefix, :update_number, :update_year, :update_month
    # Captured as part of :update processing
    nil

  # ========== END V2 COMPONENTS ==========

  when :volume, :section, :appendix, :translation,
       :errata, :index, :insert, :version
    return nil if value.nil?
    return nil if value.is_a?(Array) && value.empty?

    str_value = value.to_s.strip
    return nil if str_value.empty?

    # For volume, create Volume component from string value
    # This handles patterns like "v1" that come from parser as simple strings
    if type == :volume
      { volume: Components::Volume.new(value: str_value) }
    else
      str_value
    end

  when :revision
    # Revision MUST be Edition component with type "r"
    return nil if value.nil? || value.to_s.strip.empty?

    # Handle new structure with :revision_prefix and :revision_id (format preservation)
    if value.is_a?(Hash) && value[:revision_prefix] && value[:revision_id]
      prefix = value[:revision_prefix].to_s
      id = value[:revision_id].to_s.strip

      # Normalize bare "r" -> "r1"
      revision_id = if id.empty? || id == "r" || id == "R"
                      "1"
                    # Handle "r4", "R5", "4" etc. (but prefix already has the r/rev/etc.)
                    elsif id =~ /^(\d+[a-z]?)$/
                      $1
                    else
                      id
                    end

      # Return Edition component with original_prefix for format preservation
      {
        edition: Components::Edition.new(type: "r", id: revision_id,
                                         original_prefix: prefix),
      }
    else
      # Legacy handling: revision as simple string value
      str_value = value.to_s.strip

      # Handle bare "r" -> normalize to "r1"
      revision_id = if str_value.empty? || str_value == "r" || str_value == "R"
                      "1"
                    # Handle "r4", "R5", "4" etc.
                    elsif str_value =~ /^[rR]?(\d+[a-z]?)$/
                      $1
                    else
                      str_value
                    end

      # Return Edition component (no original_prefix available)
      {
        edition: Components::Edition.new(type: "r", id: revision_id),
      }
    end

  when :revision_year, :revision_month
    # When revision_year comes from parser as separate element (e.g., "1019 r1963")
    # Create Edition component
    if type == :revision_year
      year_value = value.to_s.strip
      # Check if this should be an Edition component or legacy revision_year
      # If revision_month is also present, use legacy attributes for "revJune1908" pattern
      if parsed_hash[:revision_month]
        # Legacy: revision with month - keep as revision_year/revision_month
        year_value
      else
        # V2: revision with year only - create Edition component
        {
          edition: Components::Edition.new(type: "r", id: year_value),
        }
      end
    else
      # revision_month - preserve as string for legacy rendering
      return nil if value.nil? || value.to_s.strip.empty?

      value.to_s.strip
    end

  when :edition_year_separate
    # NEW: Edition year from "e2-1915" pattern (captured separately by parser)
    # This comes with first_number like "11e2" and separate year "1915"
    # Already handled in first_number regex matching above, but if it reaches here
    # as a separate capture, we need to process it
    return nil if value.nil? || value.to_s.strip.empty?

    value.to_s # Return as string for potential use

  when :historical_month
    # NEW: Historical month from "-April1909" pattern
    # Handled in first_number pattern matching, but return as string if separate
    return nil if value.nil? || value.to_s.strip.empty?

    value.to_s

  when :historical_year
    # NEW: Historical year from "-April1909" pattern
    # Handled in first_number pattern matching, but return as string if separate
    return nil if value.nil? || value.to_s.strip.empty?

    value.to_s

  when :supplement_year
    # NEW: Supplement year from "supp-1924" pattern (captured separately by parser)
    # This comes with first_number like "25supp" and separate year "1924"
    # Already handled in first_number regex matching above, but if it reaches here
    # as a separate capture, return as supplement value
    return nil if value.nil? || value.to_s.strip.empty?

    { supplement: value.to_s } # Return as supplement attribute

  when :supplement
    handle_supplement_cast(value)

  when :supplement_date_range
    return nil unless value.is_a?(Hash)

    month_start = value[:supp_month_start]&.to_s
    year_start = value[:supp_year_start]&.to_s
    month_end = value[:supp_month_end]&.to_s
    year_end = value[:supp_year_end]&.to_s

    {
      supplement_date_range_start: (month_start && year_start ? "#{month_start}#{year_start}" : nil),
      supplement_date_range_end: (month_end && year_end ? "#{month_end}#{year_end}" : nil),
    }

  when :supplement_date
    return nil unless value.is_a?(Hash)

    month = value[:supp_month]&.to_s
    year = value[:supp_year]&.to_s

    month && year ? "#{month}#{year}" : nil

  when :supplement_slash_year
    return nil unless value.is_a?(Hash)

    number = value[:supp_number]&.to_s
    year = value[:supp_year]&.to_s

    number && year ? "#{number}/#{year}" : nil

  when :supplement_with_rev
    { supplement: "", supplement_has_revision: true }

  when :supp_year
    # Parser extracts supplement year from patterns like "187supp1924"
    # This should set the supplement attribute with the year value
    { supplement: value.to_s }

  # ========== V2 EDITION COMPONENT ==========

  when :edition_e_date
    # Edition with "e" prefix + 6-digit date (YYYYMM): e199206, e202103
    # Used for IR revision+month patterns after preprocessing: "4743rJun1992" -> "4743e199206"
    return nil unless value.is_a?(Hash) && value[:edition_date]

    edition_date = value[:edition_date].to_s
    # Parse 6-digit date as YYYYMM
    # Store as id directly - renders as "e199206"
    {
      edition: Components::Edition.new(type: "e", id: edition_date),
      edition_component: Components::Edition.new(type: "e",
                                                 id: edition_date),
    }

  when :edition_e
    # Edition with "e" prefix: e2, e2021
    return nil unless value.is_a?(Hash) && value[:edition_id]

    edition_id = value[:edition_id].to_s

    {
      edition: Components::Edition.new(type: "e", id: edition_id),
      edition_component: Components::Edition.new(type: "e",
                                                 id: edition_id),
    }

  when :edition_r
    # Revision with "r" prefix: r5, r2021
    return nil unless value.is_a?(Hash) && value[:edition_id]

    edition_id = value[:edition_id].to_s

    {
      edition: Components::Edition.new(type: "r", id: edition_id),
      edition_component: Components::Edition.new(type: "r",
                                                 id: edition_id),
      revision: "r#{edition_id}", # Also set revision string attribute for compatibility
    }

  when :edition_r_no_space
    # Revision with "r" prefix (no space pattern): r2, r5
    # Used for patterns like "800-56Ar2" where edition is "r2"
    return nil unless value.is_a?(Hash) && value[:edition_id]

    edition_id = value[:edition_id].to_s

    {
      edition: Components::Edition.new(type: "r", id: edition_id),
      edition_component: Components::Edition.new(type: "r",
                                                 id: edition_id),
      revision: "r#{edition_id}", # Also set revision string attribute for compatibility
    }

  when :edition_rev
    # Revision with "rev" prefix (verbose): rev2013, rev 2013
    return nil unless value.is_a?(Hash) && value[:edition_id]

    edition_id = value[:edition_id].to_s

    {
      edition: Components::Edition.new(type: "r", id: edition_id),
      edition_component: Components::Edition.new(type: "r",
                                                 id: edition_id),
      revision: "r#{edition_id}", # Also set revision string attribute for compatibility
    }

  when :edition_r_letter
    # Revision with "r" prefix and letter suffix: r1a, r2b (for SP patterns like 800-22r1a)
    return nil unless value.is_a?(Hash) && value[:edition_id] && value[:edition_letter]

    edition_id = value[:edition_id].to_s
    edition_letter = value[:edition_letter].to_s.downcase

    {
      edition: Components::Edition.new(type: "r", id: edition_id,
                                       additional_text: edition_letter),
      edition_component: Components::Edition.new(type: "r",
                                                 id: edition_id,
                                                 additional_text: edition_letter),
      revision: "r#{edition_id}#{edition_letter}", # Also set revision string attribute for compatibility
    }

  when :edition_r_letter_only
    # Revision with "r" prefix and only letter (no digit): ra, rb (for SP patterns like 800-27ra)
    return nil unless value.is_a?(Hash) && value[:edition_letter]

    edition_letter = value[:edition_letter].to_s.downcase

    {
      edition: Components::Edition.new(type: "r", id: edition_letter),
      edition_component: Components::Edition.new(type: "r",
                                                 id: edition_letter),
      revision: "r#{edition_letter}", # Also set revision string attribute for compatibility
    }

  when :edition_historical
    # Historical with "-" prefix: -3, -4
    return nil unless value.is_a?(Hash) && value[:edition_id]

    edition_id = value[:edition_id].to_s

    {
      edition: Components::Edition.new(type: "-", id: edition_id),
      edition_component: Components::Edition.new(type: "-",
                                                 id: edition_id),
    }

  when :edition_r_with_space_letter
    # Revision with "r" prefix, space, and letter: r 5A (format preservation)
    # Used for patterns like "NIST SP 800-53 r5A"
    # NOTE: If there's an update component, the space was added by preprocessing
    return nil unless value.is_a?(Hash) && value[:edition_id] && value[:edition_letter]

    edition_id = value[:edition_id].to_s
    edition_letter = value[:edition_letter].to_s.upcase

    # Check if this is an embedded edition with update (space added by preprocessing)
    has_update = parsed_hash[:update_prefix] || parsed_hash[:update]

    if has_update
      # No original_prefix - space was added by preprocessing
      {
        edition: Components::Edition.new(type: "r", id: edition_id,
                                         additional_text: edition_letter),
        edition_component: Components::Edition.new(type: "r",
                                                   id: edition_id,
                                                   additional_text: edition_letter),
        revision: "r#{edition_id}#{edition_letter}",
      }
    else
      # Space was in original input - preserve format
      {
        edition: Components::Edition.new(type: "r", id: edition_id,
                                         additional_text: edition_letter,
                                         original_prefix: " r"),
        edition_component: Components::Edition.new(type: "r",
                                                   id: edition_id,
                                                   additional_text: edition_letter,
                                                   original_prefix: " r"),
        revision: "r#{edition_id}#{edition_letter}",
      }
    end

  when :edition_r_with_space
    # Revision with "r" prefix and space: r 5 (format preservation)
    # Used for patterns like "NIST SP 800-53 r5"
    # NOTE: If there's an update component, the space was added by preprocessing
    # for patterns like "8115r1/upd" -> "8115 r1/upd", so don't set original_prefix
    return nil unless value.is_a?(Hash) && value[:edition_id]

    edition_id = value[:edition_id].to_s

    # Check if this is an embedded edition with update (space added by preprocessing)
    # Patterns like "8115r1/upd" become "8115 r1/upd" after preprocessing
    has_update = parsed_hash[:update_prefix] || parsed_hash[:update]

    if has_update
      # No original_prefix - space was added by preprocessing
      {
        edition: Components::Edition.new(type: "r", id: edition_id),
        edition_component: Components::Edition.new(type: "r",
                                                   id: edition_id),
        revision: "r#{edition_id}",
      }
    else
      # Space was in original input - preserve format
      {
        edition: Components::Edition.new(type: "r", id: edition_id,
                                         original_prefix: " r"),
        edition_component: Components::Edition.new(type: "r",
                                                   id: edition_id,
                                                   original_prefix: " r"),
        revision: "r#{edition_id}",
      }
    end

  when :edition_id
    # Captured by edition_e, edition_r, edition_rev, edition_historical
    nil

  when :edition_date
    # Captured by edition_e_date
    nil

  # ========== LEGACY EDITION (for migration) ==========

  when :legacy_edition
    # Legacy edition patterns - will be phased out
    # For now, map to old edition_year/edition_month attributes
    nil # Handled by existing edition_year logic below

  when :edition_month, :edition_year, :edition_day, :edition_has_rev
    # These work together: edition_month + edition_year -> single edition ID
    # Skip processing if this is edition_month alone (will be processed with edition_year)
    return nil if type == :edition_month

    # Process edition_year, combining with edition_month if present
    return nil if value.nil? || value.to_s.strip.empty?

    # Build the edition ID from year and optional month
    edition_id = value.to_s # Start with year (e.g., "1985")

    # Add month if present (e.g., "Mar" -> "03", so "1985" + "03" = "198503")
    # For FIPS with day: "Sep30/1977" -> "19770930" (year + month + day)
    if parsed_hash[:edition_month]
      month_str = parsed_hash[:edition_month].to_s
      month_num = Date::ABBR_MONTHNAMES.index(month_str) ||
        Date::MONTHNAMES.index(month_str) ||
        month_str.to_i
      if month_num&.positive?
        # FIPS uses modern (numeric) date format; historical NBS keeps
        # month names like "April1909" instead of "190904".
        modern = Series.for(parsed_hash).modern_edition_date?
        if !modern && month_str.match?(/^[A-Z][a-z]+/) && edition_id.to_s.match?(/^\d{4}$/)
          # Historical NBS month+year format: preserve month name, use "-" type for special rendering
          edition_obj = Components::Edition.new(
            type: "-",
            id: "",
            additional_text: "#{month_str}#{edition_id}",
          )
          return {
            edition: edition_obj,
            edition_component: edition_obj,
            edition_year: edition_id.to_s,
          }
        else
          # Modern format (and FIPS): combine year and month as single number: 1985 + 03 = 198503
          edition_id = "#{edition_id}#{format('%02d', month_num)}"

          # For FIPS with day, append day as well: "Sep30/1977" -> "19770930"
          if modern && parsed_hash[:edition_day]
            day_num = parsed_hash[:edition_day].to_s.to_i
            if day_num.positive? && day_num <= 31
              edition_id = "#{edition_id}#{format('%02d', day_num)}"
            end
          end
        end
      end
    end

    # Create Edition component with type="e" (edition) and combined ID
    edition_obj = Components::Edition.new(type: "e", id: edition_id)

    # Return as hash to set edition and edition_year
    {
      edition: edition_obj, # Main attribute for tests
      edition_component: edition_obj, # V2 component
      edition_year: value.to_s, # Keep string for render logic
    }

  when :part
    # Part component - handle part number with optional addendum
    return nil if value.nil? || value.to_s.strip.empty?

    str_value = value.to_s.strip

    # Pattern: "1adde1" -> Part(value: "1"), addendum=true
    # Note: eN after add is discarded (not included in output per fixture)
    if str_value =~ /^(\d+)add(e\d+)$/
      {
        part: Components::Part.new(type: "pt", value: $1),
        addendum: "true",
      }
    elsif str_value =~ /^(\d+)add/
      {
        part: Components::Part.new(type: "pt", value: $1),
        addendum: "true",
      }
    else
      # Just a part number - return Part component with pt type
      { part: Components::Part.new(type: "pt", value: str_value) }
    end

  when :part_extracted
    # Legacy - this is now handled by :part
    nil

  when :edition_letter
    return nil if value.nil? || value.to_s.strip.empty?

    value.to_s

  when :public_draft
    return nil if value.nil?

    value.to_s

  when :draft
    # Extract draft number from "-draft N" pattern for pd rendering
    return nil if value.nil?

    str_value = value.to_s.strip
    return nil if str_value.empty?

    # Pattern: " -draft 2" or "-draft 2" -> extract "2" for pd rendering
    if str_value =~ /^\s*-draft\s+(\d+)$/
      { draft_number: $1 }
    # Pattern: " 2pd" -> already in pd format
    elsif str_value =~ /^\s*(\d+)pd$/
      { public_draft: $1 }
    # Other patterns (parenthetical, simple -draft)
    else
      str_value
    end

  when :addendum
    handle_addendum_cast(value)

  when :addendum_number
    return nil if value.nil? || value.to_s.strip.empty?

    value.to_s

  when :supplement_suffix
    # Return as hash to set supplement attribute (not supplement_suffix)
    { supplement: value.to_s }

  when :date
    # Date component per NIST spec
    return nil unless value.is_a?(Hash)

    # NEW: Check if this is historical edition pattern ("-April1909")
    # Parser captures as date with month + year, but semantically it's an edition
    if value[:date_month] && value[:date_year] && !value[:date_day]
      month_str = value[:date_month].to_s
      year_str = value[:date_year].to_s
      # If month is a word like "April", this is historical edition format
      if month_str.match?(/^[A-Za-z]+$/)
        return {
          edition: Components::Edition.new(type: "-",
                                           additional_text: "#{month_str}#{year_str}"),
        }
      end
    end

    # Regular date processing
    value[:date_year]&.to_s
    value[:date_month]&.to_s
    value[:date_day]&.to_s

  else
    # Unknown types: return the original value for default processing
    # This allows hashes with arbitrary structures to be processed
    # e.g., second_number hash with number_only and edition_id
    value.is_a?(Hash) ? value : nil
  end
end

#handle_addendum_cast(value) ⇒ `Object`

Handle addendum casting (number)

# File 'lib/pubid/nist/caster.rb', line 1253

def handle_addendum_cast(value)
  if value.is_a?(Hash)
    addendum_num = value[:addendum_number]&.to_s&.strip
    if addendum_num && !addendum_num.empty?
      { addendum_number: addendum_num }
    else
      { addendum: "true" }
    end
  else
    str_value = value.to_s.strip
    if str_value.empty?
      { addendum: "true" }
    else
      { addendum_number: str_value }
    end
  end
end

#handle_supplement_cast(value) ⇒ `Object`

Handle supplement casting with all its variants

# File 'lib/pubid/nist/caster.rb', line 1240

def handle_supplement_cast(value)
  return nil unless value

  if value.is_a?(Array) && value.empty?
    # Empty array means "supp" was present but no suffix
    ""
  else
    str_value = value.to_s.strip
    str_value.empty? ? nil : str_value
  end
end

#month_name_to_number(month_name) ⇒ `Integer`

Convert month name to month number