sec_id 6.0.0 → 6.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c629207aa12be217cf0de6bcb9f7429731da6f33e28b4829c21e789c01246d70
-  data.tar.gz: 18c299442df23cba47816bf3f6ebc7d274299f4e87cb82430018fd3e1ce11f8b
+  metadata.gz: 2c705053b66b513f6cbac21702cd4548f5f446669f9251db569d62693698ff64
+  data.tar.gz: b792e03a67c57ead4064c392925771033c35b68fd984ad93aa5d932e37d1ea21
 SHA512:
-  metadata.gz: 7210e01bab67effdb53376fcd6d4de7ecdf17c61ef505db439a8a08c5ab5e29960b48e0ef57000bbc68c9bd0feb8f123ad1fb397df25104414205a5720f21ef9
-  data.tar.gz: 8325b5b97cd4e1edc9d4e2eae1537e1aa7f02d48d73ad8cda502df4075efe33ffa86ba1ed625c4e45b7cdd748606ac5ed32e509c54be128f310fc8d7b4ca978f
+  metadata.gz: 51880f7c27744b9700e01bca80a6f3a9a436d76a843921fdc97a401e12ef0acb2011c4f67a19034c30ea90e59638de0b66cb8a949b32d2d896e28a4f7957c4ba
+  data.tar.gz: 780d1cd07415046d2c5dfda3b6f548785ae0e244bdb294876440521f90475562000beaf493c88109d609e9c65fa83b94ad67c8509084174a84e52e6be9268543

data/CHANGELOG.md

@@ -8,6 +8,13 @@ and [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
 
 ## [Unreleased]
 
+## [6.1.0] - 2026-07-10
+
+### Added
+
+- `SecID::Base#deconstruct_keys` — every identifier now destructures in `case/in` patterns, exposing the same parsed fields `#to_h` reports under `:components`. The `keys` argument is ignored, no new keys are introduced, and validity is not part of the protocol: `SecID.parse` returning `nil` remains the validity guard, and an instance built from unparseable input binds `nil` for each component. No `deconstruct` (array-pattern) method is defined
+- `SecID::Base.type_key` — the memoized class-level registry symbol for an identifier type, joining the existing `short_name` / `full_name` / `id_length` metadata surface. It round-trips through the registry: `SecID[SecID::ISIN.type_key] == SecID::ISIN`. It is now the single authority for that symbol; the registry, `#to_h`, `SecID.explain`, the ActiveModel validator, the detector, and the scanner all read it instead of each deriving it from the class name
+
 ## [6.0.0] - 2026-07-08
 
 ### Added

data/README.md

@@ -11,6 +11,7 @@
   - [Text Scanning](#text-scanning) - find identifiers in freeform text
   - [Debugging Detection](#debugging-detection) - understand why strings match or don't
   - [Structured Validation](#structured-validation) - detailed error codes and messages
+  - [Pattern Matching](#pattern-matching) - destructure identifiers with `case/in`
   - [Generating Test Fixtures](#generating-test-fixtures) - produce valid identifiers for tests
   - [ISIN](#isin) - International Securities Identification Number
   - [CUSIP](#cusip) - Committee on Uniform Securities Identification Procedures
@@ -75,6 +76,7 @@ All identifier classes provide `valid?`, `errors`, `validate`, `validate!` metho
 **All identifiers** support hash serialization:
 - `#to_h` - returns a hash with `:type`, `:full_id`, `:normalized`, `:valid`, and `:components` keys
 - `#as_json` - same as `#to_h`, for JSON serialization compatibility (Rails, `JSON.generate`, etc.)
+- `#deconstruct_keys` - exposes `:components` for [pattern matching](#pattern-matching) with `case/in`
 
 ```ruby
 SecID::ISIN.new('US5949181045').to_h
@@ -119,6 +121,7 @@ SecID.identifiers                         # => [SecID::ISIN, SecID::CUSIP, ...]
 SecID.identifiers.map(&:short_name)       # => ["ISIN", "CUSIP", "SEDOL", ...]
 
 # Query metadata
+SecID::ISIN.type_key                      # => :isin  (SecID[SecID::ISIN.type_key] == SecID::ISIN)
 SecID::ISIN.short_name                    # => "ISIN"
 SecID::ISIN.full_name                     # => "International Securities Identification Number"
 SecID::ISIN.id_length                     # => 12
@@ -261,6 +264,48 @@ SecID::FIGI.new('BSG000BLNNH6').validate!
 isin = SecID::ISIN.validate!('US5949181045')  # => #<SecID::ISIN>
 ```
 
+### Pattern Matching
+
+Every identifier destructures in `case/in` via its parsed components. Since `SecID.parse` returns `nil` for
+anything invalid, an `in nil` branch is a complete validity guard:
+
+```ruby
+case SecID.parse(input)
+in SecID::ISIN[country_code: 'US', nsin:]  then "US security #{nsin}"
+in SecID::ISIN[country_code:]              then "foreign security from #{country_code}"
+in SecID::OCC[underlying:, type:, strike_mills:] then "#{type} option on #{underlying}"
+in nil                                     then 'not a valid identifier'
+end
+```
+
+`SecID::Match` is a `Data`, so scan results destructure one layer up and nest into the identifier they wrap:
+
+```ruby
+SecID.extract('AAPL ISIN US0378331005').each do |match|
+  case match
+  in { type: :isin, identifier: SecID::ISIN[country_code: 'US'] } then puts 'US ISIN found'
+  else next
+  end
+end
+```
+
+The keys are exactly the `:components` of `#to_h`, and destructuring never consults
+`valid?`. An instance built directly from unparseable input therefore binds `nil` for every component, the same shape
+`to_h` reports:
+
+```ruby
+SecID::ISIN.new('GARBAGE') => { country_code:, nsin: }
+country_code # => nil
+nsin         # => nil
+```
+
+CIK, WKN, and Valoren have no sub-fields: they match a bare `in SecID::CIK` but no keyed pattern. Array patterns
+(`deconstruct`) are not supported.
+
+Watch the `:type` key: on a `SecID::Match` it is the registry symbol (`:occ`), while on an `OCC` instance it is the
+OSI option type (`'C'` or `'P'`), so `in SecID::OCC[type: :occ]` never matches. Other types have no `:type` component
+at all — `#to_h`'s envelope keys (`:type`, `:full_id`, `:normalized`, `:valid`) are not part of the pattern surface.
+
 ### Generating Test Fixtures
 
 Generate syntactically valid identifiers — with correct check digits where applicable — for use as test fixtures. Available per class and via the central dispatcher:

data/lib/sec_id/active_model.rb

@@ -93,7 +93,7 @@ class SecIdValidator < ActiveModel::EachValidator
   #
   # @return [Array<Symbol>]
   def candidate_types
-    configured_types || SecID.identifiers.map { |klass| klass.short_name.downcase.to_sym }
+    configured_types || SecID.identifiers.map(&:type_key)
   end
 
   # sec_id's specific failure reason, only when `details: true` and a single `type:` is set;

data/lib/sec_id/base.rb

@@ -50,6 +50,22 @@ module SecID
     attr_reader :identifier
 
     class << self
+      # The type's registry symbol: `SecID[SecID::ISIN.type_key] == SecID::ISIN`.
+      #
+      # @return [Symbol] the registry key (e.g. :isin, :cusip)
+      def type_key = @type_key ||= short_name.downcase.to_sym
+
+      # Composite sort key ranking detection specificity: check-digit types first,
+      # then narrower length range, then registration order. A class the registry
+      # never saw sorts last.
+      #
+      # @api private
+      # @return [Array] frozen [check-digit rank, length specificity, registration order]
+      def detection_priority
+        @detection_priority ||=
+          [has_check_digit? ? 0 : 1, length_specificity, SecID.identifiers.index(self) || Float::INFINITY].freeze
+      end
+
       # @return [String] the unqualified class name (e.g. "ISIN", "CUSIP")
       def short_name = @short_name ||= name.split('::').last
 
@@ -114,7 +130,7 @@ module SecID
     # @return [Hash] hash with :type, :full_id, :normalized, :valid, and :components keys
     def to_h
       {
-        type: self.class.short_name.downcase.to_sym,
+        type: self.class.type_key,
         full_id: full_id,
         normalized: valid? ? normalized : nil,
         valid: valid?,
@@ -129,6 +145,20 @@ module SecID
       to_h
     end
 
+    # Exposes the parsed components for `case/in` destructuring. Validity is not part of
+    # the protocol: components of unparseable input are `nil`, and `SecID.parse` returning
+    # `nil` is the validity guard.
+    #
+    # @param _keys [Array<Symbol>, nil] the keys the pattern requests; ignored
+    # @return [Hash] the parsed components
+    #
+    # @example
+    #   case SecID.parse('US5949181045')
+    #   in SecID::ISIN[country_code:, nsin:] then [country_code, nsin]
+    #   in nil then :invalid
+    #   end #=> ['US', '594918104']
+    def deconstruct_keys(_keys) = components
+
     protected
 
     # @return [String]

data/lib/sec_id/detector.rb

@@ -58,7 +58,7 @@ module SecID
 
       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] }
+      matches.min_by { |instance| instance.class.detection_priority }
     end
 
     private
@@ -81,16 +81,14 @@ module SecID
     # @return [Array<Symbol>]
     def validate_and_sort(input, candidates)
       matches = candidates.select { |klass| klass.valid?(input) }
-      matches.sort_by! { |klass| @priority_for[klass] }
-      matches.map! { |klass| @key_for[klass] }
+      matches.sort_by!(&:detection_priority)
+      matches.map!(&:type_key)
     end
 
     # @return [void]
     def precompute
       build_discriminator_sets
       build_length_table
-      build_priority_table
-      build_key_table
     end
 
     # Classifies types by which special characters their VALID_CHARS_REGEX accepts.
@@ -114,27 +112,6 @@ module SecID
       @candidates_by_length.each_value(&:freeze)
     end
 
-    # Builds composite sort keys: check-digit types first, then smaller range, then load order.
-    #
-    # @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
-
-    # Maps each class to its registry symbol key.
-    #
-    # @return [void]
-    def build_key_table
-      @key_for = {}
-      @classes.each { |klass| @key_for[klass] = klass.short_name.downcase.to_sym }
-      @key_for.freeze
-    end
-
     # Stage 1: route strings with special characters to the only types that accept them.
     # Returns nil if no special chars found (fall through to stage 2).
     #

data/lib/sec_id/scanner.rb

@@ -51,12 +51,24 @@ module SecID
     private
 
     # @return [void]
-    def precompute # rubocop:disable Metrics/AbcSize
-      build_key_table
-      build_priority_table
+    def precompute
+      build_candidate_partitions
+      build_length_table
+    end
+
+    # Splits the registered classes by which CANDIDATE_RE group routes to them.
+    #
+    # @return [void]
+    def build_candidate_partitions
       @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
+    end
+
+    # Builds a Hash mapping each possible length to the classes that accept it.
+    #
+    # @return [void]
+    def build_length_table
       @candidates_by_length = Hash.new { |h, k| h[k] = [] }
       @classes.each do |klass|
         klass.length_values.each { |len| @candidates_by_length[len] << klass }
@@ -64,23 +76,6 @@ module SecID
       @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]
@@ -123,7 +118,7 @@ module SecID
       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))
+      Match.new(type: best.type_key, raw: raw, range: start_pos...end_pos, identifier: best.new(cleaned))
     end
 
     # @return [Class, nil]
@@ -134,7 +129,7 @@ module SecID
       return if candidates.empty?
 
       validated = candidates.select { |k| cleaned.match?(k::VALID_CHARS_REGEX) && k.valid?(cleaned) }
-      validated.min_by { |k| @priority_for[k] }
+      validated.min_by(&:detection_priority)
     end
   end
 end

data/lib/sec_id/version.rb

@@ -2,5 +2,5 @@
 
 module SecID
   # Current gem version.
-  VERSION = '6.0.0'
+  VERSION = '6.1.0'
 end

data/lib/sec_id.rb

@@ -85,7 +85,7 @@ module SecID
     # @return [Hash] hash with :input and :candidates keys
     def explain(str, types: nil)
       input = str.to_s.strip
-      target_keys = types || identifier_list.map { |k| k.short_name.downcase.to_sym }
+      target_keys = types || identifier_list.map(&:type_key)
       candidates = target_keys.map do |key|
         instance = self[key].new(input)
         { type: key, valid: instance.valid?, errors: instance.errors.details }
@@ -143,8 +143,7 @@ module SecID
 
     # @return [void]
     def register_identifier(klass)
-      key = klass.name.split('::').last.downcase.to_sym
-      identifier_map[key] = klass
+      identifier_map[klass.type_key] = klass
       identifier_list << klass
       @detector = nil
       @scanner = nil

data/sig/sec_id/base.rbs

@@ -33,6 +33,9 @@ module SecID
     # RBS forbids narrowing an inherited ivar's type.
     def identifier: () -> String?
 
+    def self.type_key: () -> Symbol
+    # `@api private` in YARD, but public here: Detector and Scanner call it from outside.
+    def self.detection_priority: () -> Array[Integer | Float | nil]
     def self.short_name: () -> String
     def self.full_name: () -> String
     def self.id_length: () -> (Integer | ::Range[Integer] | ::Array[Integer])
@@ -49,6 +52,7 @@ module SecID
     def hash: () -> Integer
     def to_h: () -> Hash[Symbol, untyped]
     def as_json: (*untyped) -> Hash[Symbol, untyped]
+    def deconstruct_keys: (::Array[Symbol]? _keys) -> Hash[Symbol, untyped]
 
     # Check-digit surface. Only the types that `include Checkable` implement these
     # (they raise/NoMethodError otherwise); declared on Base so `Generatable#generate`
@@ -68,5 +72,7 @@ module SecID
     @identifier: untyped
     self.@short_name: String
     self.@has_check_digit: bool
+    self.@type_key: Symbol
+    self.@detection_priority: Array[Integer | Float | nil]
   end
 end

data/sig/sec_id/detector.rbs

@@ -3,8 +3,6 @@ module SecID
   #
   # @api private
   class Detector
-    type priority = Array[Integer | Float | nil]
-
     def initialize: (Array[singleton(Base)] identifier_list) -> void
     def call: (SecID::input str) -> Array[Symbol]
     def matches?: (SecID::input str) -> bool
@@ -17,8 +15,6 @@ module SecID
     def precompute: () -> void
     def build_discriminator_sets: () -> void
     def build_length_table: () -> void
-    def build_priority_table: () -> void
-    def build_key_table: () -> void
     def stage1_special_chars: (String upcased) -> Array[singleton(Base)]?
     def stage2_length: (Integer length) -> Array[singleton(Base)]
     def stage3_charset: (String upcased, Array[singleton(Base)] candidates) -> Array[singleton(Base)]
@@ -29,7 +25,5 @@ module SecID
     @space_only_types: Array[singleton(Base)]
     @special_types: Array[singleton(Base)]
     @candidates_by_length: Hash[Integer, Array[singleton(Base)]]
-    @priority_for: Hash[singleton(Base), priority]
-    @key_for: Hash[singleton(Base), Symbol]
   end
 end

data/sig/sec_id/scanner.rbs

@@ -28,8 +28,8 @@ module SecID
     private
 
     def precompute: () -> void
-    def build_key_table: () -> void
-    def build_priority_table: () -> void
+    def build_candidate_partitions: () -> void
+    def build_length_table: () -> void
     def scan_text: (String input, Array[singleton(Base)] target_classes) { (Match) -> void } -> void
     def identify_candidate: (untyped match_data, Array[singleton(Base)] target_classes) -> Match?
     def try_classes: (String raw, String cleaned, Integer start_pos, Array[singleton(Base)] classes) -> Match?
@@ -40,7 +40,5 @@ module SecID
     @occ_classes: Array[singleton(Base)]
     @simple_classes: Array[singleton(Base)]
     @candidates_by_length: Hash[Integer, Array[singleton(Base)]]
-    @priority_for: Hash[singleton(Base), Array[Integer | Float | nil]]
-    @key_for: Hash[singleton(Base), Symbol]
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sec_id
 version: !ruby/object:Gem::Version
-  version: 6.0.0
+  version: 6.1.0
 platform: ruby
 authors:
 - Leonid Svyatov