sec_id 5.0.0 → 5.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48989505724d7895a9a0bd0308602f4e8a1f5870c91df5802e32f2a26af2c7c4
-  data.tar.gz: 2e810ceadd4d02b47dc3a7cc6eab754e305a44ce83f883a0afdac7cef2bd4740
+  metadata.gz: bc458a32d8a5cb8fc4db2b1ab4c635a6c88e4160d38948e4ce779e90b039bd3c
+  data.tar.gz: 298298a51ca424aef20c814ed620e35d32bbfe9bf285fe1f6ee6f44bac163980
 SHA512:
-  metadata.gz: 8f4897e3de16457e2206fcae937316119a1c824b224bbf84d41f61c1d66f6cd5b48e8662bccfca007e68da6e0e059a130dd04ea82778ae2208a9d2aacfc34a75
-  data.tar.gz: b807ce12ec66636016262686b71666d9c84a9e2649c5816dcd97772a02b648a64a26a6f86691969d97f76583652347bb2c627407b674773630764cffe4e3e216
+  metadata.gz: 78650675337ce8a03970e4b1227713aaa0adafb8c18da35466099add8fc39389c8b02583602c18f9aeb59a340ee6b9db9f42ef7662d96284dd0ed93336a50a6a
+  data.tar.gz: 27d54f707d2ec471218a15e6f9dadc2d78d3f46985084f1e18be921b83691f4fe5cd4d82d793ae9cbb34c3e55df30e2966aa834b5942606dfa81d5e3d38e4799

data/CHANGELOG.md

@@ -8,6 +8,30 @@ and [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
 
 ## [Unreleased]
 
+## [5.2.0] - 2026-02-24
+
+### Added
+
+- `SecID.scan` and `SecID.extract` methods for finding identifiers in freeform text — returns `Scanner::Match` objects (`Data.define(:type, :raw, :range, :identifier)`) with the validated identifier instance; supports `types:` filtering, hyphenated identifiers, and compound patterns (OCC with spaces, FISN with slashes)
+- `SecID.explain` method for debugging identifier detection — returns per-type validation results showing exactly why each type matched or rejected the input
+- `on_ambiguous:` option for `SecID.parse` and `SecID.parse!` — `:first` (default, existing behavior), `:raise` (raises `AmbiguousMatchError`), `:all` (returns array of all matching instances)
+- `SecID::AmbiguousMatchError` exception class for ambiguous identifier detection
+- `#as_json` method on all identifier types (delegates to `#to_h`) and on `Errors` (delegates to `#details`) for JSON serialization compatibility
+- `SecID::IBAN.supported_countries` class method returning sorted array of all supported country codes
+- `SecID::CFI.categories` class method returning the categories hash
+- `SecID::CFI.groups_for(category_code)` class method returning groups hash for a given category
+
+
+## [5.1.0] - 2026-02-19
+
+### Added
+
+- `#==`, `#eql?`, and `#hash` methods on all identifier types — two instances of the same type with the same normalized form are equal and usable as Hash keys / in Sets
+- `#to_h` method on all identifier types for consistent hash serialization — returns `{ type:, full_id:, normalized:, valid:, components: }` with type-specific component hashes (e.g. ISIN: `country_code`, `nsin`, `check_digit`)
+- `#to_pretty_s` and `.to_pretty_s` display formatting methods on all identifier types, returning a human-readable string or `nil` for invalid input — with type-specific formats for IBAN (4-char groups), LEI (4-char groups), ISIN (CC + NSIN + CD), CUSIP (cusip6 + issue + CD), FIGI (prefix+G + random + CD), OCC (space-separated components), and Valoren (thousands grouping)
+- Lookup service integration guides and runnable examples for OpenFIGI, SEC EDGAR, GLEIF, and Eurex APIs (`docs/guides/`, `examples/`)
+- GitHub community standards files: Code of Conduct, Contributing guide, Security policy, issue templates, and PR template
+
 ## [5.0.0] - 2026-02-17
 
 ### Added

data/README.md

@@ -1,6 +1,6 @@
 # SecID [![Gem Version](https://img.shields.io/gem/v/sec_id)](https://rubygems.org/gems/sec_id) [![Codecov](https://img.shields.io/codecov/c/github/svyatov/sec_id)](https://app.codecov.io/gh/svyatov/sec_id) [![CI](https://github.com/svyatov/sec_id/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/svyatov/sec_id/actions?query=workflow%3ACI)
 
-> Validate securities identification numbers with ease!
+> A Ruby toolkit for securities identifiers — validate, parse, normalize, detect, and convert.
 
 ## Table of Contents
 
@@ -8,6 +8,8 @@
 - [Installation](#installation)
 - [Supported Standards and Usage](#supported-standards-and-usage)
   - [Metadata Registry](#metadata-registry) - enumerate, filter, look up, and detect identifier types
+  - [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
   - [ISIN](#isin) - International Securities Identification Number
   - [CUSIP](#cusip) - Committee on Uniform Securities Identification Procedures
@@ -22,6 +24,7 @@
   - [Valoren](#valoren) - Swiss Security Number
   - [CFI](#cfi) - Classification of Financial Instruments
   - [FISN](#fisn) - Financial Instrument Short Name
+- [Lookup Service Integration](#lookup-service-integration)
 - [Development](#development)
 - [Contributing](#contributing)
 - [Changelog](#changelog)
@@ -37,7 +40,7 @@ Ruby 3.2+ is required.
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'sec_id', '~> 5.0'
+gem 'sec_id', '~> 5.2'
 ```
 
 And then execute:
@@ -58,10 +61,39 @@ gem install sec_id
 
 All identifier classes provide `valid?`, `errors`, `validate`, `validate!` methods at both class and instance levels.
 
-**All identifiers** support normalization:
+**All identifiers** support normalization and display formatting:
 - `.normalize(id)` - strips separators, upcases, validates, and returns the canonical string
 - `#normalized` / `#normalize` - returns the canonical string for a valid instance
 - `#normalize!` - mutates `full_id` to canonical form, returns `self`
+- `#to_pretty_s` / `.to_pretty_s(id)` - returns a human-readable formatted string, or `nil` for invalid input
+
+**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.)
+
+```ruby
+SecID::ISIN.new('US5949181045').to_h
+# => { type: :isin, full_id: 'US5949181045', normalized: 'US5949181045',
+#      valid: true, components: { country_code: 'US', nsin: '594918104', check_digit: 5 } }
+
+SecID::ISIN.new('INVALID').to_h
+# => { type: :isin, full_id: 'INVALID', normalized: nil,
+#      valid: false, components: { country_code: nil, nsin: nil, check_digit: nil } }
+```
+
+**All identifiers** support value equality — two instances of the same type with the same normalized form are equal:
+
+```ruby
+a = SecID::ISIN.new('US5949181045')
+b = SecID::ISIN.new('us 5949 1810 45')
+
+a == b  # => true
+a.eql?(b) # => true
+
+# Works as Hash keys and in Sets
+{ a => 'MSFT' }[b]          # => 'MSFT'
+Set.new([a, b]).size         # => 1
+```
 
 **Check-digit based identifiers** (ISIN, CUSIP, CEI, SEDOL, FIGI, LEI, IBAN) also provide:
 - `restore` / `.restore` - returns the full identifier string with correct check-digit (no mutation)
@@ -115,6 +147,56 @@ SecID.parse('594918104', types: [:cusip])         # => #<SecID::CUSIP>
 # Bang version raises on failure
 SecID.parse!('US5949181045')                      # => #<SecID::ISIN>
 SecID.parse!('unknown')                           # raises SecID::InvalidFormatError
+
+# Handle ambiguous matches
+SecID.parse('514000', on_ambiguous: :first)        # => #<SecID::WKN> (default)
+SecID.parse('514000', on_ambiguous: :raise)        # raises SecID::AmbiguousMatchError
+SecID.parse('514000', on_ambiguous: :all)          # => [#<SecID::WKN>, #<SecID::Valoren>, #<SecID::CIK>]
+SecID.parse('US5949181045', on_ambiguous: :raise)  # => #<SecID::ISIN> (unambiguous, no error)
+```
+
+### Text Scanning
+
+Find identifiers embedded in freeform text:
+
+```ruby
+# Extract all identifiers from text
+matches = SecID.extract('Portfolio: US5949181045, 594918104, B0YBKJ7')
+matches.map(&:type)   # => [:isin, :cusip, :sedol]
+matches.first.raw     # => "US5949181045"
+matches.first.range   # => 11...23
+matches.first.identifier.country_code  # => "US"
+
+# Lazy scanning with Enumerator
+SecID.scan('Buy US5949181045 now').each { |m| puts m.type }
+
+# Filter by types
+SecID.extract('514000', types: [:valoren])  # => only Valoren matches
+
+# Handles hyphenated identifiers
+match = SecID.extract('ID: US-5949-1810-45').first
+match.raw                    # => "US-5949-1810-45"
+match.identifier.normalized  # => "US5949181045"
+```
+
+> **Known limitations:** Format-only types (CIK, Valoren, WKN, CFI) can false-positive on
+> common numbers and short words in prose — use the `types:` filter to restrict scanning when
+> this is a concern. Identifiers prefixed with special characters (e.g. `#US5949181045`) may be
+> consumed as a single token by CUSIP's `*@#` character class and fail validation, preventing
+> the embedded identifier from being found.
+
+### Debugging Detection
+
+Understand why a string matches or doesn't match specific identifier types:
+
+```ruby
+result = SecID.explain('US5949181040')
+isin = result[:candidates].find { |c| c[:type] == :isin }
+isin[:valid]                      # => false
+isin[:errors].first[:error]       # => :invalid_check_digit
+
+# Filter to specific types
+SecID.explain('US5949181045', types: %i[isin cusip])
 ```
 
 ### Structured Validation
@@ -192,6 +274,7 @@ isin.valid?                # => true
 isin.restore               # => 'US5949181045'
 isin.restore!              # => #<SecID::ISIN> (mutates instance)
 isin.calculate_check_digit # => 5
+isin.to_pretty_s           # => 'US 594918104 5'
 isin.to_cusip              # => #<SecID::CUSIP>
 isin.nsin_type             # => :cusip
 isin.to_nsin               # => #<SecID::CUSIP>
@@ -236,6 +319,7 @@ cusip.valid?                # => true
 cusip.restore               # => '594918104'
 cusip.restore!              # => #<SecID::CUSIP> (mutates instance)
 cusip.calculate_check_digit # => 4
+cusip.to_pretty_s           # => '594918 10 4'
 cusip.to_isin('US')         # => #<SecID::ISIN>
 cusip.cins?                 # => false
 ```
@@ -308,6 +392,7 @@ figi.valid?                # => true
 figi.restore               # => 'BBG000DMBXR2'
 figi.restore!              # => #<SecID::FIGI> (mutates instance)
 figi.calculate_check_digit # => 2
+figi.to_pretty_s           # => 'BBG 000DMBXR 2'
 ```
 
 ### LEI
@@ -332,6 +417,7 @@ lei.valid?                # => true
 lei.restore               # => '5493006MHB84DD0ZWV18'
 lei.restore!              # => #<SecID::LEI> (mutates instance)
 lei.calculate_check_digit # => 18
+lei.to_pretty_s           # => '5493 006M HB84 DD0Z WV18'
 ```
 
 ### IBAN
@@ -358,10 +444,16 @@ iban.restore               # => 'DE89370400440532013000'
 iban.restore!              # => #<SecID::IBAN> (mutates instance)
 iban.calculate_check_digit # => 89
 iban.known_country?        # => true
+iban.to_pretty_s           # => 'DE89 3704 0044 0532 0130 00'
 ```
 
 Full BBAN structural validation is supported for EU/EEA countries. Other countries have length-only validation.
 
+```ruby
+# List all supported countries
+SecID::IBAN.supported_countries  # => ["AD", "AE", "AT", "BE", "BG", "CH", ...]
+```
+
 ### CIK
 
 > [Central Index Key](https://en.wikipedia.org/wiki/Central_Index_Key) - a 10-digit number used by the SEC to identify corporations and individuals who have filed disclosures.
@@ -412,6 +504,7 @@ occ.full_id       # => 'X 250620C00050000'
 occ.valid?        # => true
 occ.normalize!    # => #<SecID::OCC> (mutates full_id, returns self)
 occ.full_id       # => 'X     250620C00050000'
+occ.to_pretty_s   # => 'X 250620 C 00050000'
 ```
 
 ### WKN
@@ -454,6 +547,7 @@ valoren.identifier    # => '3886335'
 valoren.valid?        # => true
 valoren.normalized    # => '003886335'
 valoren.normalize!    # => #<SecID::Valoren> (mutates full_id, returns self)
+valoren.to_pretty_s   # => '3 886 335'
 valoren.to_isin       # => #<SecID::ISIN> (CH ISIN by default)
 valoren.to_isin('LI') # => #<SecID::ISIN> (LI ISIN)
 ```
@@ -486,6 +580,12 @@ cfi.registered?    # => true
 
 CFI validates the category code (position 1) against 14 valid values and the group code (position 2) against valid values for that category. Attribute positions 3-6 accept any letter A-Z, with X meaning "not applicable".
 
+```ruby
+# Introspect valid codes
+SecID::CFI.categories            # => { "E" => :equity, "C" => :collective_investment_vehicles, ... }
+SecID::CFI.groups_for('E')       # => { "S" => :common_shares, "P" => :preferred_shares, ... }
+```
+
 ### FISN
 
 > [Financial Instrument Short Name](https://en.wikipedia.org/wiki/ISO_18774) - a human-readable short name for financial instruments per ISO 18774.
@@ -506,6 +606,19 @@ fisn.to_s          # => 'APPLE INC/SH'
 
 FISN format: `Issuer Name/Abbreviated Instrument Description` with issuer (1-15 chars) and description (1-19 chars) separated by a forward slash. Character set: uppercase A-Z, digits 0-9, and space.
 
+## Lookup Service Integration
+
+SecID validates identifiers but does not include HTTP clients. The [`docs/guides/`](docs/guides/) directory provides integration patterns for external lookup services using only stdlib (`net/http`, `json`):
+
+| Guide | Service | Identifier |
+|-------|---------|------------|
+| [OpenFIGI](docs/guides/openfigi.md) | [OpenFIGI API](https://www.openfigi.com/api) | FIGI |
+| [SEC EDGAR](docs/guides/sec-edgar.md) | [SEC EDGAR](https://www.sec.gov/edgar/sec-api-documentation) | CIK |
+| [GLEIF](docs/guides/gleif.md) | [GLEIF API](https://www.gleif.org/en/lei-data/gleif-api) | LEI |
+| [Eurex](docs/guides/eurex.md) | [Eurex Reference Data](https://www.eurex.com/ex-en/data/free-reference-data-api) | ISIN |
+
+Each guide includes a complete adapter class and a [runnable example](examples/).
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies.
@@ -516,12 +629,9 @@ To install this gem onto your local machine, run `bundle exec rake install`.
 
 ## Contributing
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Make your changes and run tests (`bundle exec rake`)
-4. Commit using [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format (`git commit -m 'feat: add some feature'`)
-5. Push to the branch (`git push origin my-new-feature`)
-6. Create a new Pull Request
+Bug reports and pull requests are welcome on [GitHub](https://github.com/svyatov/sec_id). See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code style, and PR guidelines.
+
+This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).
 
 ## Changelog
 

data/lib/sec_id/base.rb

@@ -52,6 +52,7 @@ module SecID
     # @api private
     def self.inherited(subclass)
       super
+      # Skip anonymous classes and classes outside the SecID namespace (e.g. in tests)
       SecID.__send__(:register_identifier, subclass) if subclass.name&.start_with?('SecID::')
     end
 
@@ -63,8 +64,53 @@ module SecID
       raise NotImplementedError
     end
 
+    # @param other [Object]
+    # @return [Boolean]
+    def ==(other)
+      other.class == self.class && comparison_id == other.comparison_id
+    end
+
+    alias eql? ==
+
+    # @return [Integer]
+    def hash
+      [self.class, comparison_id].hash
+    end
+
+    # Returns a hash representation of this identifier for serialization.
+    #
+    # @return [Hash] hash with :type, :full_id, :normalized, :valid, and :components keys
+    def to_h
+      {
+        type: self.class.short_name.downcase.to_sym,
+        full_id: full_id,
+        normalized: valid? ? normalized : nil,
+        valid: valid?,
+        components: components
+      }
+    end
+
+    # Returns a JSON-compatible hash representation.
+    #
+    # @return [Hash]
+    def as_json(*)
+      to_h
+    end
+
+    protected
+
+    # @return [String]
+    def comparison_id
+      valid? ? normalized : full_id
+    end
+
     private
 
+    # @return [Hash]
+    def components
+      {}
+    end
+
     # @param sec_id_number [String, #to_s] the identifier to parse
     # @return [MatchData, Hash] the regex match data or empty hash if no match
     def parse(sec_id_number)

data/lib/sec_id/cei.rb

@@ -46,6 +46,13 @@ module SecID
       @check_digit = cei_parts[:check_digit]&.to_i
     end
 
+    private
+
+    # @return [Hash]
+    def components = { prefix:, numeric:, entity_id:, check_digit: }
+
+    public
+
     # @return [Integer] the calculated check digit (0-9)
     # @raise [InvalidFormatError] if the CEI format is invalid
     def calculate_check_digit

data/lib/sec_id/cfi.rb

@@ -164,7 +164,22 @@ module SecID
         'C' => :combined_instruments,
         'M' => :miscellaneous
       }
-    }.freeze
+    }.each_value(&:freeze).freeze
+
+    # Returns the category codes hash.
+    #
+    # @return [Hash{String => Symbol}]
+    def self.categories
+      CATEGORIES
+    end
+
+    # Returns the groups hash for a given category code.
+    #
+    # @param category_code [String] single-letter category code
+    # @return [Hash{String => Symbol}, nil]
+    def self.groups_for(category_code)
+      GROUPS[category_code.to_s.upcase]
+    end
 
     # @return [String, nil] the category code (position 1)
     attr_reader :category_code
@@ -299,6 +314,9 @@ module SecID
 
     private
 
+    # @return [Hash]
+    def components = { category_code:, group_code:, attr1:, attr2:, attr3:, attr4: }
+
     # @return [Boolean]
     def valid_format?
       super && valid_category? && valid_group?

data/lib/sec_id/concerns/normalizable.rb

@@ -23,6 +23,15 @@ module SecID
         cleaned = id.to_s.strip.gsub(self::SEPARATORS, '')
         new(cleaned.upcase).normalized
       end
+
+      # Returns a human-readable formatted string, or nil if invalid.
+      #
+      # @param id [String, #to_s] the identifier to format
+      # @return [String, nil]
+      def to_pretty_s(id)
+        cleaned = id.to_s.strip.gsub(self::SEPARATORS, '')
+        new(cleaned.upcase).to_pretty_s
+      end
     end
 
     # Returns the canonical normalized form of this identifier.
@@ -48,6 +57,15 @@ module SecID
       self
     end
 
+    # Returns a human-readable formatted string, or nil if invalid.
+    #
+    # @return [String, nil]
+    def to_pretty_s
+      return nil unless valid?
+
+      to_s
+    end
+
     # @return [String]
     def to_s
       identifier.to_s

data/lib/sec_id/cusip.rb

@@ -45,6 +45,13 @@ module SecID
       @check_digit = cusip_parts[:check_digit]&.to_i
     end
 
+    # @return [String, nil]
+    def to_pretty_s
+      return nil unless valid?
+
+      "#{cusip6} #{issue} #{check_digit}"
+    end
+
     # @return [Integer] the calculated check digit (0-9)
     # @raise [InvalidFormatError] if the CUSIP format is invalid
     def calculate_check_digit
@@ -63,6 +70,13 @@ module SecID
       ISIN.new(country_code + restore).restore!
     end
 
+    private
+
+    # @return [Hash]
+    def components = { cusip6:, issue:, check_digit: }
+
+    public
+
     # @return [Boolean] true if first character is a letter (CINS identifier)
     def cins?
       cusip6[0] < '0' || cusip6[0] > '9'

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

@@ -50,6 +50,13 @@ module SecID
       @check_digit = figi_parts[:check_digit]&.to_i
     end
 
+    # @return [String, nil]
+    def to_pretty_s
+      return nil unless valid?
+
+      "#{prefix}G #{random_part} #{check_digit}"
+    end
+
     # @return [Integer] the calculated check digit (0-9)
     # @raise [InvalidFormatError] if the FIGI format is invalid
     def calculate_check_digit
@@ -59,6 +66,9 @@ module SecID
 
     private
 
+    # @return [Hash]
+    def components = { prefix:, random_part:, check_digit: }
+
     # @return [Boolean]
     def valid_format?
       !identifier.nil? && !RESTRICTED_PREFIXES.include?(prefix)

data/lib/sec_id/fisn.rb

@@ -54,5 +54,10 @@ module SecID
     def to_s
       identifier.to_s
     end
+
+    private
+
+    # @return [Hash]
+    def components = { issuer:, description: }
   end
 end

data/lib/sec_id/iban.rb

@@ -33,6 +33,13 @@ module SecID
       (?<rest>[A-Z0-9]{13,32})
     \z/x
 
+    # 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
 
@@ -106,8 +113,23 @@ module SecID
       "#{country_code}#{check_digit.to_s.rjust(2, '0')}#{bban}"
     end
 
+    # @return [String, nil]
+    def to_pretty_s
+      to_s.scan(/.{1,4}/).join(' ') if valid?
+    end
+
     private
 
+    # @return [Hash]
+    def components
+      hash = { country_code:, bban:, check_digit: }
+      hash[:bank_code] = bank_code if bank_code
+      hash[:branch_code] = branch_code if branch_code
+      hash[:account_number] = account_number if account_number
+      hash[:national_check] = national_check if national_check
+      hash
+    end
+
     # @return [Integer]
     def check_digit_width
       2

data/lib/sec_id/isin.rb

@@ -76,6 +76,13 @@ module SecID
       @check_digit = isin_parts[:check_digit]&.to_i
     end
 
+    # @return [String, nil]
+    def to_pretty_s
+      return nil unless valid?
+
+      "#{country_code} #{nsin} #{check_digit}"
+    end
+
     # @return [Integer] the calculated check digit (0-9)
     # @raise [InvalidFormatError] if the ISIN format is invalid
     def calculate_check_digit
@@ -135,6 +142,13 @@ 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

data/lib/sec_id/lei.rb

@@ -50,6 +50,13 @@ module SecID
       @check_digit = lei_parts[:check_digit]&.to_i
     end
 
+    # @return [String, nil]
+    def to_pretty_s
+      return nil unless valid?
+
+      to_s.scan(/.{1,4}/).join(' ')
+    end
+
     # @return [Integer] the calculated 2-digit check digit (1-98)
     # @raise [InvalidFormatError] if the LEI format is invalid
     def calculate_check_digit
@@ -59,6 +66,9 @@ module SecID
 
     private
 
+    # @return [Hash]
+    def components = { lou_id:, reserved:, entity_id:, check_digit: }
+
     # @return [Integer]
     def check_digit_width
       2

data/lib/sec_id/occ.rb

@@ -138,8 +138,18 @@ module SecID
       full_id
     end
 
+    # @return [String, nil]
+    def to_pretty_s
+      return nil unless valid?
+
+      "#{underlying} #{date_str} #{type} #{strike_mills}"
+    end
+
     private
 
+    # @return [Hash]
+    def components = { underlying:, date_str:, type:, strike_mills: }
+
     # @return [Array<Symbol>]
     def error_codes
       return detect_errors unless valid_format?

data/lib/sec_id/scanner.rb

@@ -0,0 +1,144 @@
+# 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|
+        id_length = klass::ID_LENGTH
+        lengths = id_length.is_a?(Range) ? id_length : [id_length]
+        lengths.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
+        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
+      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

data/lib/sec_id/sedol.rb

@@ -62,6 +62,9 @@ module SecID
 
     private
 
+    # @return [Hash]
+    def components = { check_digit: }
+
     # NOTE: Not idiomatic Ruby, but optimized for performance.
     #
     # @return [Integer] the weighted sum

data/lib/sec_id/valoren.rb

@@ -40,6 +40,13 @@ module SecID
       @identifier = valoren_parts[:identifier]
     end
 
+    # @return [String, nil]
+    def to_pretty_s
+      return nil unless valid?
+
+      identifier.reverse.scan(/.{1,3}/).join(' ').reverse
+    end
+
     # @param country_code [String] the ISO 3166-1 alpha-2 country code (default: 'CH')
     # @return [ISIN] a new ISIN instance with calculated check digit
     # @raise [InvalidFormatError] if the country code is not CH or LI

data/lib/sec_id/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SecID
-  VERSION = '5.0.0'
+  VERSION = '5.2.0'
 end

data/lib/sec_id.rb

@@ -15,6 +15,9 @@ module SecID
   # Raised for type-specific structural errors (invalid prefix, category, group, BBAN, or date).
   class InvalidStructureError < Error; end
 
+  # Raised when multiple identifier types match and on_ambiguous: :raise is used.
+  class AmbiguousMatchError < Error; end
+
   class << self
     # Looks up an identifier class by its symbol key.
     #
@@ -54,45 +57,85 @@ module SecID
       types.any? { |key| self[key].valid?(str) }
     end
 
-    # Parses a string into the most specific matching identifier instance.
-    #
+    # @param text [String, nil] the text to scan
+    # @param types [Array<Symbol>, nil] restrict to specific types
+    # @return [Array<Match>]
+    # @raise [ArgumentError] if any key in types is unknown
+    def extract(text, types: nil)
+      scan(text, types: types).to_a
+    end
+
+    # @param text [String, nil] the text to scan
+    # @param types [Array<Symbol>, nil] restrict to specific types
+    # @return [Enumerator<Match>] if no block given
+    # @yieldparam match [Match]
+    # @raise [ArgumentError] if any key in types is unknown
+    def scan(text, types: nil, &)
+      classes = types&.map { |key| self[key] }
+      scanner.call(text, classes: classes, &)
+    end
+
+    # @param str [String, nil] the identifier string to explain
+    # @param types [Array<Symbol>, nil] restrict to specific types
+    # @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 }
+      candidates = target_keys.map do |key|
+        instance = self[key].new(input)
+        { type: key, valid: instance.valid?, errors: instance.errors.details }
+      end
+      { input: input, candidates: candidates }
+    end
+
     # @param str [String, nil] the identifier string to parse
     # @param types [Array<Symbol>, nil] restrict to specific types (e.g. [:isin, :cusip])
-    # @return [SecID::Base, nil] a valid identifier instance, or nil if no match
-    # @raise [ArgumentError] if any key in types is unknown
-    def parse(str, types: nil)
-      types.nil? ? parse_any(str) : parse_from(str, types)
+    # @param on_ambiguous [:first, :raise, :all] how to handle multiple matches
+    # @return [SecID::Base, nil, Array<SecID::Base>] depends on on_ambiguous mode
+    # @raise [AmbiguousMatchError] when on_ambiguous: :raise and multiple types match
+    def parse(str, types: nil, on_ambiguous: :first)
+      case on_ambiguous
+      when :first then types.nil? ? parse_any(str) : parse_from(str, types)
+      when :raise then parse_strict(str, types)
+      when :all   then parse_all(str, types)
+      else raise ArgumentError, "Unknown on_ambiguous mode: #{on_ambiguous.inspect}"
+      end
     end
 
-    # Parses a string into the most specific matching identifier instance, raising on failure.
-    #
     # @param str [String, nil] the identifier string to parse
     # @param types [Array<Symbol>, nil] restrict to specific types (e.g. [:isin, :cusip])
-    # @return [SecID::Base] a valid identifier instance
+    # @param on_ambiguous [:first, :raise, :all] how to handle multiple matches
+    # @return [SecID::Base, Array<SecID::Base>] depends on on_ambiguous mode
     # @raise [InvalidFormatError] if no matching identifier type is found
-    # @raise [ArgumentError] if any key in types is unknown
-    def parse!(str, types: nil)
-      parse(str, types: types) || raise(InvalidFormatError, parse_error_message(str, types))
+    # @raise [AmbiguousMatchError] when on_ambiguous: :raise and multiple types match
+    def parse!(str, types: nil, on_ambiguous: :first)
+      result = parse(str, types: types, on_ambiguous: on_ambiguous)
+
+      if on_ambiguous == :all
+        raise(InvalidFormatError, parse_error_message(str, types)) if result.empty?
+
+        return result
+      end
+
+      result || raise(InvalidFormatError, parse_error_message(str, types))
     end
 
     private
 
-    # @param klass [Class] the identifier class to register
     # @return [void]
     def register_identifier(klass)
       key = klass.name.split('::').last.downcase.to_sym
       identifier_map[key] = klass
       identifier_list << klass
       @detector = nil
+      @scanner = nil
     end
 
-    # @return [SecID::Base, nil]
     def parse_any(str)
       key = detect(str).first
       key && self[key].new(str)
     end
 
-    # @return [SecID::Base, nil]
     def parse_from(str, types)
       types.each do |key|
         instance = self[key].new(str)
@@ -101,26 +144,37 @@ module SecID
       nil
     end
 
-    # @return [String]
-    def parse_error_message(str, types)
-      base = "No matching identifier type found for #{str.to_s.strip.inspect}"
-      types ? "#{base} among #{types.inspect}" : base
+    def parse_strict(str, types)
+      candidates = resolve_candidates(str, types)
+      raise AmbiguousMatchError, ambiguous_message(str, candidates) if candidates.size > 1
+
+      candidates.first && self[candidates.first].new(str)
     end
 
-    # @return [Detector]
-    def detector
-      @detector ||= Detector.new(identifier_list)
+    def parse_all(str, types)
+      resolve_candidates(str, types).map { |key| self[key].new(str) }
     end
 
-    # @return [Hash{Symbol => Class}]
-    def identifier_map
-      @identifier_map ||= {}
+    # @return [Array<Symbol>]
+    def resolve_candidates(str, types)
+      types ? types.select { |key| self[key].valid?(str) } : detect(str)
     end
 
-    # @return [Array<Class>]
-    def identifier_list
-      @identifier_list ||= []
+    # @return [String]
+    def ambiguous_message(str, candidates)
+      "Ambiguous identifier #{str.to_s.strip.inspect}: matches #{candidates.inspect}"
+    end
+
+    # @return [String]
+    def parse_error_message(str, types)
+      base = "No matching identifier type found for #{str.to_s.strip.inspect}"
+      types ? "#{base} among #{types.inspect}" : base
     end
+
+    def detector = @detector ||= Detector.new(identifier_list)
+    def scanner = @scanner ||= Scanner.new(identifier_list)
+    def identifier_map = @identifier_map ||= {}
+    def identifier_list = @identifier_list ||= []
   end
 end
 
@@ -131,6 +185,7 @@ require 'sec_id/concerns/validatable'
 require 'sec_id/concerns/checkable'
 require 'sec_id/base'
 require 'sec_id/detector'
+require 'sec_id/scanner'
 require 'sec_id/isin'
 require 'sec_id/cusip'
 require 'sec_id/sedol'

data/sec_id.gemspec

@@ -10,10 +10,10 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Leonid Svyatov']
   spec.email         = ['leonid@svyatov.ru']
 
-  spec.summary       = 'Validate securities identification numbers with ease!'
-  spec.description   = 'Validate, calculate check digits, and parse components of securities identifiers. ' \
-                       'Supports ISIN, CUSIP, CEI, SEDOL, FIGI, LEI, IBAN, CIK, OCC, WKN, Valoren, CFI, ' \
-                       'and FISN standards.'
+  spec.summary       = 'A Ruby toolkit for securities identifiers — validate, parse, normalize, detect, and convert.'
+  spec.description   = 'Validate, normalize, parse, and convert securities identifiers. Auto-detect identifier ' \
+                       'type from any string. Calculate and restore check digits. Supports ISIN, CUSIP, CEI, ' \
+                       'SEDOL, FIGI, LEI, IBAN, CIK, OCC, WKN, Valoren, CFI, and FISN.'
   spec.homepage      = 'https://github.com/svyatov/sec_id'
   spec.license       = 'MIT'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sec_id
 version: !ruby/object:Gem::Version
-  version: 5.0.0
+  version: 5.2.0
 platform: ruby
 authors:
 - Leonid Svyatov
@@ -9,9 +9,9 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: Validate, calculate check digits, and parse components of securities
-  identifiers. Supports ISIN, CUSIP, CEI, SEDOL, FIGI, LEI, IBAN, CIK, OCC, WKN, Valoren,
-  CFI, and FISN standards.
+description: Validate, normalize, parse, and convert securities identifiers. Auto-detect
+  identifier type from any string. Calculate and restore check digits. Supports ISIN,
+  CUSIP, CEI, SEDOL, FIGI, LEI, IBAN, CIK, OCC, WKN, Valoren, CFI, and FISN.
 email:
 - leonid@svyatov.ru
 executables: []
@@ -41,6 +41,7 @@ files:
 - lib/sec_id/isin.rb
 - lib/sec_id/lei.rb
 - lib/sec_id/occ.rb
+- lib/sec_id/scanner.rb
 - lib/sec_id/sedol.rb
 - lib/sec_id/valoren.rb
 - lib/sec_id/version.rb
@@ -70,5 +71,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.6
 specification_version: 4
-summary: Validate securities identification numbers with ease!
+summary: A Ruby toolkit for securities identifiers — validate, parse, normalize, detect,
+  and convert.
 test_files: []