sec_id 5.0.0 → 5.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48989505724d7895a9a0bd0308602f4e8a1f5870c91df5802e32f2a26af2c7c4
-  data.tar.gz: 2e810ceadd4d02b47dc3a7cc6eab754e305a44ce83f883a0afdac7cef2bd4740
+  metadata.gz: 0b0779f0d2735ded84be536bcc9690a4b106c729b03aab007a0458b6512020e8
+  data.tar.gz: 3b4d99c3534856e5e05ff68cec5355f3c7a2665e2854dad5415815e275a734b1
 SHA512:
-  metadata.gz: 8f4897e3de16457e2206fcae937316119a1c824b224bbf84d41f61c1d66f6cd5b48e8662bccfca007e68da6e0e059a130dd04ea82778ae2208a9d2aacfc34a75
-  data.tar.gz: b807ce12ec66636016262686b71666d9c84a9e2649c5816dcd97772a02b648a64a26a6f86691969d97f76583652347bb2c627407b674773630764cffe4e3e216
+  metadata.gz: ec036b3fbf2c3d7a89ec823fed2dea6c8cb92be1ede8792bae623c1474454141a3dcc3da27d14c5e3734b050dd95b25672552fc9f4c6983bc68d807a7493d392
+  data.tar.gz: 397e7c17dd46c8aad067262289307317e04cdba4fac65d890aa3e3ff1a1b9ecf175ab916d9600dab7a7a5d4629b54f7750fd40f11c79ed220d3bca339a210d0c

data/CHANGELOG.md

@@ -8,6 +8,16 @@ and [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
 
 ## [Unreleased]
 
+## [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

@@ -22,6 +22,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 +38,7 @@ Ruby 3.2+ is required.
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'sec_id', '~> 5.0'
+gem 'sec_id', '~> 5.1'
 ```
 
 And then execute:
@@ -58,10 +59,38 @@ 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
+
+```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)
@@ -192,6 +221,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 +266,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 +339,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 +364,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,6 +391,7 @@ 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.
@@ -412,6 +446,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 +489,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)
 ```
@@ -506,6 +542,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 +565,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

@@ -63,8 +63,46 @@ 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
+
+    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

@@ -299,6 +299,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/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

@@ -106,8 +106,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/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.1.0'
 end

metadata

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