sec_id 5.1.0 → 6.0.0

data/lib/sec_id/detector.rb

@@ -13,7 +13,7 @@ module SecID
   # Stage 3 — Charset pre-filter:
   #   Survivors are filtered by their VALID_CHARS_REGEX before calling `valid?`.
   #
-  # Typical result: 1-2 `valid?` calls instead of 13.
+  # Typical result: 1-2 `valid?` calls instead of 14.
   #
   # @api private
   class Detector
@@ -36,6 +36,31 @@ module SecID
       validate_and_sort(input, candidates)
     end
 
+    # Returns whether any registered type matches, short-circuiting on the first
+    # valid candidate without sorting or mapping to symbols.
+    #
+    # @param str [String, nil] the identifier string to test
+    # @return [Boolean]
+    def matches?(str)
+      input = str.to_s.strip
+      return false if input.empty?
+
+      filter_candidates(input.upcase).any? { |klass| klass.valid?(input) }
+    end
+
+    # Returns the most-specific matching instance, built once and reused, or nil.
+    #
+    # @param str [String, nil] the identifier string to parse
+    # @return [SecID::Base, nil]
+    def first_match(str)
+      input = str.to_s.strip
+      return if input.empty?
+
+      candidates = filter_candidates(input.upcase)
+      matches = candidates.filter_map { |klass| (i = klass.new(input)).valid? ? i : nil }
+      matches.min_by { |instance| @priority_for[instance.class] }
+    end
+
     private
 
     # Runs stages 1-3 to narrow candidate classes.
@@ -84,9 +109,7 @@ module SecID
     def build_length_table
       @candidates_by_length = Hash.new { |h, k| h[k] = [] }
       @classes.each do |klass|
-        id_length = klass::ID_LENGTH
-        lengths = id_length.is_a?(Range) ? id_length : [id_length]
-        lengths.each { |len| @candidates_by_length[len] << klass }
+        klass.length_values.each { |len| @candidates_by_length[len] << klass }
       end
       @candidates_by_length.each_value(&:freeze)
     end
@@ -98,9 +121,7 @@ module SecID
       @priority_for = {}
       @classes.each_with_index do |klass, index|
         check_digit_rank = klass.has_check_digit? ? 0 : 1
-        id_length = klass::ID_LENGTH
-        range_size = id_length.is_a?(Range) ? id_length.size : 1
-        @priority_for[klass] = [check_digit_rank, range_size, index].freeze
+        @priority_for[klass] = [check_digit_rank, klass.length_specificity, index].freeze
       end
       @priority_for.freeze
     end

data/lib/sec_id/dti.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module SecID
+  # Digital Token Identifier (DTI, ISO 24165) - a 9-character alphanumeric code
+  # that identifies digital tokens (e.g. cryptocurrencies) for regulatory reporting.
+  #
+  # Format: 8-character base + 1 check character, drawn from a 30-symbol alphabet
+  # (digits 0-9 plus consonants; vowels and 'Y' never appear). Validated fully offline
+  # via ISO 7064 hybrid MOD 31,30 over the base.
+  #
+  # @see https://www.dtif.org
+  #
+  # @example Validate a DTI
+  #   SecID::DTI.valid?('X9J9K872S')  #=> true
+  #
+  # @example Restore check digit
+  #   SecID::DTI.restore('X9J9K872')  #=> 'X9J9K872S'
+  class DTI < Base
+    include Checkable
+
+    # Human-readable name of the standard.
+    FULL_NAME = 'Digital Token Identifier'
+    # Valid length(s) of a normalized identifier.
+    ID_LENGTH = 9
+    # A representative valid identifier.
+    EXAMPLE = 'X9J9K872S'
+    # Pattern matching the identifier's permitted character set (digits + consonants, no vowels/Y).
+    VALID_CHARS_REGEX = /\A[0-9B-DF-HJ-NP-TV-XZ]+\z/
+
+    # Regular expression for parsing DTI components. First character of the base
+    # is never '0'.
+    ID_REGEX = /\A
+      (?<identifier>
+        [1-9B-DF-HJ-NP-TV-XZ]
+        [0-9B-DF-HJ-NP-TV-XZ]{7})
+      (?<check_digit>[0-9B-DF-HJ-NP-TV-XZ])?
+    \z/x
+
+    # The 30-symbol DTI alphabet, ordered by check-character value (0-29).
+    ALPHABET = '0123456789BCDFGHJKLMNPQRSTVWXZ'.chars.freeze
+
+    # Maps each alphabet character to its check-character value (0-29).
+    ALPHABET_VALUE = ALPHABET.each_with_index.to_h.freeze
+
+    # Characters valid in a DTI base (same alphabet as VALID_CHARS_REGEX).
+    GENERATE_CHARSET = ALPHANUMERIC.grep(VALID_CHARS_REGEX).freeze
+
+    # Registry-assigned codes whose stored check character differs from the
+    # algorithmic ISO 7064 MOD 31,30 computation. Base (8 chars) => registered code (9 chars).
+    #
+    # @see https://www.dtif.org
+    GRANDFATHERED_CODES = { '4H95J0R2' => '4H95J0R2X' }.freeze
+
+    # @param dti [String] the DTI string to parse
+    def initialize(dti)
+      dti_parts = parse dti
+      @identifier = dti_parts[:identifier]
+      @check_digit = dti_parts[:check_digit]
+    end
+
+    # @return [String] the calculated or grandfathered check character
+    # @raise [InvalidFormatError] if the DTI format is invalid
+    def calculate_check_digit
+      validate_format_for_calculation!
+      grandfathered_check_digit(identifier) || iso7064_mod31_30_check_char(identifier)
+    end
+
+    # Generates a random DTI body: first character non-zero, 8 characters total,
+    # all drawn from the DTI alphabet.
+    #
+    # @param random [Random] source of randomness
+    # @return [String] an 8-character DTI body without check character
+    def self.generate_body(random)
+      first = random_string(GENERATE_CHARSET - ['0'], 1, random: random)
+      "#{first}#{random_string(GENERATE_CHARSET, 7, random: random)}"
+    end
+    private_class_method :generate_body
+
+    private
+
+    # @return [Hash]
+    def components = { check_digit: }
+
+    # @param base [String] the 8-character DTI base
+    # @return [String, nil] the registered check character, or nil if not grandfathered
+    def grandfathered_check_digit(base)
+      GRANDFATHERED_CODES[base]&.delete_prefix(base)
+    end
+
+    # ISO 7064 hybrid MOD 31,30 check character over an 8-character base.
+    #
+    # @param base [String] the 8-character DTI base
+    # @return [String] the single computed check character
+    def iso7064_mod31_30_check_char(base)
+      perm = 30
+      base.each_char do |c|
+        s = (perm + ALPHABET_VALUE.fetch(c)) % 30
+        s = 30 if s.zero?
+        perm = (s * 2) % 31
+      end
+      ALPHABET.fetch((31 - perm) % 30)
+    end
+  end
+end

data/lib/sec_id/errors.rb

@@ -63,5 +63,12 @@ module SecID
     def to_a
       messages
     end
+
+    # Returns a JSON-compatible array of error detail hashes.
+    #
+    # @return [Array<Hash>]
+    def as_json(*)
+      details
+    end
   end
 end

data/lib/sec_id/figi.rb

@@ -17,9 +17,13 @@ module SecID
   class FIGI < Base
     include Checkable
 
+    # Human-readable name of the standard.
     FULL_NAME = 'Financial Instrument Global Identifier'
+    # Valid length(s) of a normalized identifier.
     ID_LENGTH = 12
+    # A representative valid identifier.
     EXAMPLE = 'BBG000BLNNH6'
+    # Pattern matching the identifier's permitted character set.
     VALID_CHARS_REGEX = /\A[B-DF-HJ-NP-TV-Z0-9]+\z/
 
     # Regular expression for parsing FIGI components.
@@ -35,6 +39,9 @@ module SecID
     # Country-code prefixes that are restricted from use in FIGI.
     RESTRICTED_PREFIXES = Set.new %w[BS BM GG GB GH KY VG]
 
+    # Characters valid in a FIGI (alphanumeric excluding vowels).
+    GENERATE_CHARSET = ALPHANUMERIC.grep(VALID_CHARS_REGEX).freeze
+
     # @return [String, nil] the 2-character prefix
     attr_reader :prefix
 
@@ -64,6 +71,17 @@ module SecID
       mod10(luhn_sum_indexed(reversed_digits_single(identifier)))
     end
 
+    # Generates a random FIGI body: non-reserved 2-char prefix + 'G' + 8-char random part.
+    #
+    # @param random [Random] source of randomness
+    # @return [String] an 11-character FIGI body without check digit
+    def self.generate_body(random)
+      prefix = random_string(GENERATE_CHARSET, 2, random: random)
+      prefix = random_string(GENERATE_CHARSET, 2, random: random) while RESTRICTED_PREFIXES.include?(prefix)
+      "#{prefix}G#{random_string(GENERATE_CHARSET, 8, random: random)}"
+    end
+    private_class_method :generate_body
+
     private
 
     # @return [Hash]

data/lib/sec_id/fisn.rb

@@ -21,10 +21,15 @@ module SecID
   #   fisn.issuer       #=> 'APPLE INC'
   #   fisn.description  #=> 'SH'
   class FISN < Base
+    # Human-readable name of the standard.
     FULL_NAME = 'Financial Instrument Short Name'
+    # Valid length(s) of a normalized identifier.
     ID_LENGTH = (3..35)
+    # A representative valid identifier.
     EXAMPLE = 'APPLE INC/SH'
+    # Pattern matching the identifier's permitted character set.
     VALID_CHARS_REGEX = %r{\A[A-Z0-9 /]+\z}
+    # Separators stripped during normalization; spaces are structural here, so only hyphens.
     SEPARATORS = /-/
 
     # Regular expression for parsing FISN components.
@@ -36,6 +41,9 @@ module SecID
         (?<description>[A-Z0-9 ]{1,19}))
     \z}x
 
+    # Characters valid in a FISN segment (alphanumeric and space).
+    FISN_CHARSET = (ALPHANUMERIC + [' ']).freeze
+
     # @return [String, nil] the issuer name portion (before the slash)
     attr_reader :issuer
 
@@ -55,6 +63,29 @@ module SecID
       identifier.to_s
     end
 
+    # Generates a random FISN: issuer (1-15 chars) + '/' + description (1-19 chars).
+    #
+    # @param random [Random] source of randomness
+    # @return [String] a generated FISN, at most 35 characters
+    def self.generate_body(random)
+      "#{generate_part(random.rand(1..15), random)}/#{generate_part(random.rand(1..19), random)}"
+    end
+    private_class_method :generate_body
+
+    # Generates a FISN segment whose first and last characters are not spaces,
+    # so Base#parse's strip leaves both segments intact.
+    #
+    # @param length [Integer] the segment length
+    # @param random [Random] source of randomness
+    # @return [String] a segment of the given length
+    def self.generate_part(length, random)
+      chars = Array.new(length) { FISN_CHARSET.sample(random: random) }
+      chars[0] = ALPHANUMERIC.sample(random: random)
+      chars[-1] = ALPHANUMERIC.sample(random: random)
+      chars.join
+    end
+    private_class_method :generate_part
+
     private
 
     # @return [Hash]

data/lib/sec_id/iban/country_rules.rb

@@ -1,11 +1,8 @@
 # frozen_string_literal: true
 
 module SecID
-  # Country-specific BBAN validation rules for IBAN.
-  #
-  # @api private
-  # rubocop:disable Metrics/ModuleLength
-  module IBANCountryRules
+  # rubocop:disable Metrics/ClassLength
+  class IBAN < Base
     # Country-specific BBAN rules for EU/EEA countries
     # Each entry defines:
     #   - :length => total BBAN length
@@ -15,6 +12,8 @@ module SecID
     # Sources:
     # - https://en.wikipedia.org/wiki/International_Bank_Account_Number
     # - https://www.swift.com/standards/data-standards/iban-international-bank-account-number
+    #
+    # @api private
     COUNTRY_RULES = {
       # Austria - 16 chars: 5-digit bank code + 11-digit account
       'AT' => {
@@ -224,6 +223,8 @@ module SecID
 
     # Countries where only length validation is performed (non-EU/EEA countries)
     # Format: country_code => expected BBAN length
+    #
+    # @api private
     LENGTH_ONLY_COUNTRIES = {
       'AD' => 20, # Andorra
       'AE' => 19, # UAE
@@ -264,5 +265,5 @@ module SecID
       'XK' => 16  # Kosovo
     }.freeze
   end
-  # rubocop:enable Metrics/ModuleLength
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/sec_id/iban.rb

@@ -19,11 +19,14 @@ module SecID
   #   SecID::IBAN.restore!('DE00370400440532013000')  #=> #<SecID::IBAN>
   class IBAN < Base
     include Checkable
-    include IBANCountryRules
 
+    # Human-readable name of the standard.
     FULL_NAME = 'International Bank Account Number'
+    # Valid length(s) of a normalized identifier.
     ID_LENGTH = (15..34)
+    # A representative valid identifier.
     EXAMPLE = 'GB29NWBK60161331926819'
+    # Pattern matching the identifier's permitted character set.
     VALID_CHARS_REGEX = /\A[A-Z0-9]+\z/
 
     # Regular expression for parsing IBAN components.
@@ -33,6 +36,17 @@ module SecID
       (?<rest>[A-Z0-9]{13,32})
     \z/x
 
+    # Country rules whose BBAN format accepts an all-digit value, used for generation.
+    # Restricts generation to numeric BBANs so output validates without interpreting the format regex.
+    NUMERIC_COUNTRY_RULES = COUNTRY_RULES.select { |_cc, rule| rule[:format].match?('0' * rule[:length]) }.to_a.freeze
+
+    # Returns sorted array of all supported country codes.
+    #
+    # @return [Array<String>]
+    def self.supported_countries
+      @supported_countries ||= (COUNTRY_RULES.keys + LENGTH_ONLY_COUNTRIES.keys).sort.freeze
+    end
+
     # @return [String, nil] the ISO 3166-1 alpha-2 country code
     attr_reader :country_code
 
@@ -79,6 +93,17 @@ module SecID
       mod97(numeric_string_for_check)
     end
 
+    # Generates a random IBAN body for a numeric-BBAN country with placeholder check digits.
+    # The default {Generatable::ClassMethods#generate} restores the real check digits via `restore!`.
+    #
+    # @param random [Random] source of randomness
+    # @return [String] a country code + "00" + numeric BBAN
+    def self.generate_body(random)
+      country_code, rule = NUMERIC_COUNTRY_RULES.sample(random: random)
+      "#{country_code}00#{random_string(DIGITS, rule[:length], random: random)}"
+    end
+    private_class_method :generate_body
+
     # @return [Boolean]
     def valid_bban_format?
       return false unless bban

data/lib/sec_id/isin.rb

@@ -16,9 +16,13 @@ module SecID
   class ISIN < Base
     include Checkable
 
+    # Human-readable name of the standard.
     FULL_NAME = 'International Securities Identification Number'
+    # Valid length(s) of a normalized identifier.
     ID_LENGTH = 12
+    # A representative valid identifier.
     EXAMPLE = 'US5949181045'
+    # Pattern matching the identifier's permitted character set.
     VALID_CHARS_REGEX = /\A[A-Z0-9]+\z/
 
     # Regular expression for parsing ISIN components.
@@ -55,12 +59,6 @@ module SecID
       'LI' => :valoren
     }.freeze
 
-    # Country codes that use SEDOL as their national identifier.
-    SEDOL_COUNTRY_CODES = Set.new(%w[GB IE IM JE GG FK]).freeze
-
-    # Country codes that use Valoren as their national identifier.
-    VALOREN_COUNTRY_CODES = Set.new(%w[CH LI]).freeze
-
     # @return [String, nil] the ISO 3166-1 alpha-2 country code
     attr_reader :country_code
 
@@ -90,6 +88,15 @@ module SecID
       mod10(luhn_sum_standard(reversed_digits_multi(identifier)))
     end
 
+    # Generates a random ISIN body: 2-letter country code + 9-character NSIN.
+    #
+    # @param random [Random] source of randomness
+    # @return [String] an 11-character ISIN body without check digit
+    def self.generate_body(random)
+      "#{random_string(ALPHA, 2, random: random)}#{random_string(ALPHANUMERIC, 9, random: random)}"
+    end
+    private_class_method :generate_body
+
     # @return [CUSIP] a new CUSIP instance
     # @raise [InvalidFormatError] if the country code is not a CGS country
     def to_cusip
@@ -105,7 +112,7 @@ module SecID
 
     # @return [Boolean] true if the country code uses SEDOL
     def sedol?
-      SEDOL_COUNTRY_CODES.include?(country_code)
+      NSIN_COUNTRY_TYPES[country_code] == :sedol
     end
 
     # @return [Boolean] true if the country code uses WKN
@@ -115,7 +122,7 @@ module SecID
 
     # @return [Boolean] true if the country code uses Valoren
     def valoren?
-      VALOREN_COUNTRY_CODES.include?(country_code)
+      NSIN_COUNTRY_TYPES[country_code] == :valoren
     end
 
     # @return [SEDOL] a new SEDOL instance
@@ -142,13 +149,6 @@ module SecID
       Valoren.new(nsin)
     end
 
-    private
-
-    # @return [Hash]
-    def components = { country_code:, nsin:, check_digit: }
-
-    public
-
     # Returns the type of NSIN embedded in this ISIN.
     #
     # @return [Symbol] :cusip, :sedol, :wkn, :valoren, or :generic
@@ -173,5 +173,10 @@ module SecID
       else nsin # :generic - return raw string
       end
     end
+
+    private
+
+    # @return [Hash]
+    def components = { country_code:, nsin:, check_digit: }
   end
 end

data/lib/sec_id/lei.rb

@@ -17,9 +17,13 @@ module SecID
   class LEI < Base
     include Checkable
 
+    # Human-readable name of the standard.
     FULL_NAME = 'Legal Entity Identifier'
+    # Valid length(s) of a normalized identifier.
     ID_LENGTH = 20
+    # A representative valid identifier.
     EXAMPLE = '7LTWFZYICNSX8D621K86'
+    # Pattern matching the identifier's permitted character set.
     VALID_CHARS_REGEX = /\A[0-9A-Z]+\z/
 
     # Regular expression for parsing LEI components.
@@ -64,6 +68,15 @@ module SecID
       mod97("#{numeric_identifier}00")
     end
 
+    # Generates a random LEI body: 18 alphanumeric characters.
+    #
+    # @param random [Random] source of randomness
+    # @return [String] an 18-character LEI body without check digits
+    def self.generate_body(random)
+      random_string(ALPHANUMERIC, 18, random: random)
+    end
+    private_class_method :generate_body
+
     private
 
     # @return [Hash]

data/lib/sec_id/occ.rb

@@ -19,10 +19,15 @@ module SecID
   #   occ = SecID::OCC.build(underlying: 'AAPL', date: '2021-09-17', type: 'C', strike: 150.0)
   #   occ.to_s  #=> 'AAPL  210917C00150000'
   class OCC < Base
+    # Human-readable name of the standard.
     FULL_NAME = 'OCC Option Symbol'
+    # Valid length(s) of a normalized identifier.
     ID_LENGTH = (16..21)
+    # A representative valid identifier.
     EXAMPLE = 'AAPL  210917C00150000'
+    # Pattern matching the identifier's permitted character set.
     VALID_CHARS_REGEX = /\A[A-Z0-9 ]+\z/
+    # Separators stripped during normalization; spaces are structural here, so only hyphens.
     SEPARATORS = /-/
 
     # Regular expression for parsing OCC symbol components.
@@ -46,6 +51,22 @@ module SecID
     # @return [String, nil] the strike price in mills (thousandths of a dollar, represented as an 8-digit string)
     attr_reader :strike_mills
 
+    # Generates a random OCC option symbol.
+    #
+    # @note Generated symbols are valid in format only — they are not real, listed options.
+    #
+    # @param random [Random] source of randomness
+    # @return [OCC] a generated, valid OCC instance
+    def self.generate(random: Random.new)
+      build(
+        underlying: random_string(ALPHA, random.rand(1..5), random: random),
+        # Year 2000-2068 so the 2-digit-year symbol round-trips: strptime maps %y 69-99 to 19xx.
+        date: Date.new(2000 + random.rand(0..68), random.rand(1..12), random.rand(1..28)),
+        type: %w[C P].sample(random: random),
+        strike: random_string(DIGITS, 8, random: random)
+      )
+    end
+
     class << self
       # Builds an OCC symbol from components.
       #

data/lib/sec_id/railtie.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module SecID
+  # Auto-activates the ActiveModel validator inside a Rails application.
+  #
+  # It is loaded only through the guarded require at the end of `lib/sec_id.rb`
+  # (`require 'sec_id/railtie' if defined?(Rails::Railtie)`), so it is never referenced outside
+  # Rails and the default `require 'sec_id'` path stays free of Rails/ActiveModel. The initializer
+  # requires `sec_id/active_model` after the framework has booted, when ActiveModel is guaranteed
+  # present — so a Rails app needs no `require:` option and no initializer of its own.
+  class Railtie < ::Rails::Railtie
+    initializer('sec_id.active_model') { require 'sec_id/active_model' }
+  end
+end

data/lib/sec_id/scanner.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module SecID
+  # Immutable value object representing a matched identifier found in text.
+  Match = Data.define(:type, :raw, :range, :identifier)
+
+  # Finds securities identifiers in freeform text using regex candidate extraction,
+  # length/charset pre-filtering, and cursor-based overlap prevention.
+  #
+  # @api private
+  class Scanner
+    # Composite regex for candidate extraction.
+    #
+    # Three named groups tried left-to-right via alternation:
+    # - fisn: contains `/` (unique FISN delimiter)
+    # - occ: contains structural spaces + date/type pattern
+    # - simple: common alphanumeric tokens (covers all other types)
+    CANDIDATE_RE = %r{
+      (?<![A-Za-z0-9*@\#/.$])
+      (?:
+        (?<fisn>[A-Za-z0-9](?:[A-Za-z0-9 ]{0,33}[A-Za-z0-9])?/[A-Za-z0-9](?:[A-Za-z0-9 ]{0,33}[A-Za-z0-9])?)
+        |
+        (?<occ>[A-Za-z]{1,6}\ {1,5}\d{6}[CcPp]\d{8})
+        |
+        (?<simple>[A-Za-z0-9*@\#](?:[A-Za-z0-9*@\#-]{0,40}[A-Za-z0-9*@\#])?)
+      )
+      (?![A-Za-z0-9*@\#.])
+    }x
+
+    # @param identifier_list [Array<Class>] registered identifier classes
+    def initialize(identifier_list)
+      @classes = identifier_list.dup.freeze
+      precompute
+    end
+
+    # Scans text for identifiers, yielding or returning matches.
+    #
+    # @param text [String, nil] the text to scan
+    # @param classes [Array<Class>, nil] restrict to specific classes
+    # @return [Enumerator<Match>] if no block given
+    # @yieldparam match [Match]
+    def call(text, classes: nil, &block)
+      return enum_for(:call, text, classes: classes) unless block
+
+      input = text.to_s
+      return if input.empty?
+
+      scan_text(input, classes || @classes, &block)
+    end
+
+    private
+
+    # @return [void]
+    def precompute # rubocop:disable Metrics/AbcSize
+      build_key_table
+      build_priority_table
+      @fisn_classes = @classes.select { |k| k.short_name == 'FISN' }
+      @occ_classes = @classes.select { |k| k.short_name == 'OCC' }
+      @simple_classes = @classes - @fisn_classes - @occ_classes
+      @candidates_by_length = Hash.new { |h, k| h[k] = [] }
+      @classes.each do |klass|
+        klass.length_values.each { |len| @candidates_by_length[len] << klass }
+      end
+      @candidates_by_length.each_value(&:freeze)
+    end
+
+    # @return [void]
+    def build_key_table
+      @key_for = {}
+      @classes.each { |klass| @key_for[klass] = klass.short_name.downcase.to_sym }
+      @key_for.freeze
+    end
+
+    # @return [void]
+    def build_priority_table
+      @priority_for = {}
+      @classes.each_with_index do |klass, index|
+        check_digit_rank = klass.has_check_digit? ? 0 : 1
+        @priority_for[klass] = [check_digit_rank, klass.length_specificity, index].freeze
+      end
+      @priority_for.freeze
+    end
+
+    # @param input [String]
+    # @param target_classes [Array<Class>]
+    # @return [void]
+    def scan_text(input, target_classes)
+      pos = 0
+      while pos < input.length
+        match_data = CANDIDATE_RE.match(input, pos)
+        break unless match_data
+
+        result = identify_candidate(match_data, target_classes)
+        if result
+          yield result
+          pos = match_data.end(0)
+        else
+          pos = match_data.begin(0) + 1
+        end
+      end
+    end
+
+    # @param match_data [MatchData]
+    # @param target_classes [Array<Class>]
+    # @return [Match, nil]
+    def identify_candidate(match_data, target_classes)
+      raw = match_data[0]
+      start_pos = match_data.begin(0)
+
+      if match_data[:fisn]
+        try_classes(raw, raw.upcase, start_pos, target_classes & @fisn_classes)
+      elsif match_data[:occ]
+        try_classes(raw, raw.upcase, start_pos, target_classes & @occ_classes)
+      else
+        cleaned = raw.gsub('-', '').upcase
+        try_classes(raw, cleaned, start_pos, target_classes & @simple_classes)
+      end
+    end
+
+    # @return [Match, nil]
+    def try_classes(raw, cleaned, start_pos, classes)
+      best = best_match(cleaned, classes)
+      return unless best
+
+      end_pos = start_pos + raw.length
+      Match.new(type: @key_for[best], raw: raw, range: start_pos...end_pos, identifier: best.new(cleaned))
+    end
+
+    # @return [Class, nil]
+    def best_match(cleaned, classes)
+      return if classes.empty?
+
+      candidates = (@candidates_by_length[cleaned.length] || []) & classes
+      return if candidates.empty?
+
+      validated = candidates.select { |k| cleaned.match?(k::VALID_CHARS_REGEX) && k.valid?(cleaned) }
+      validated.min_by { |k| @priority_for[k] }
+    end
+  end
+end