sec_id 4.4.1 → 5.1.0

data/lib/sec_id/isin.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module SecId
+module SecID
   # International Securities Identification Number (ISIN) - a 12-character alphanumeric code
   # that uniquely identifies a security globally.
   #
@@ -9,13 +9,18 @@ module SecId
   # @see https://en.wikipedia.org/wiki/International_Securities_Identification_Number
   #
   # @example Validate an ISIN
-  #   SecId::ISIN.valid?('US5949181045')  #=> true
+  #   SecID::ISIN.valid?('US5949181045')  #=> true
   #
   # @example Restore check digit
-  #   SecId::ISIN.restore!('US594918104')  #=> 'US5949181045'
+  #   SecID::ISIN.restore!('US594918104')  #=> #<SecID::ISIN>
   class ISIN < Base
     include Checkable
 
+    FULL_NAME = 'International Securities Identification Number'
+    ID_LENGTH = 12
+    EXAMPLE = 'US5949181045'
+    VALID_CHARS_REGEX = /\A[A-Z0-9]+\z/
+
     # Regular expression for parsing ISIN components.
     ID_REGEX = /\A
       (?<identifier>
@@ -71,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
@@ -130,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
@@ -148,9 +167,9 @@ module SecId
 
       case nsin_type
       when :cusip   then to_cusip
-      when :sedol   then SEDOL.new(nsin[2..])
-      when :wkn     then WKN.new(nsin[3..])
-      when :valoren then Valoren.new(nsin)
+      when :sedol   then to_sedol
+      when :wkn     then to_wkn
+      when :valoren then to_valoren
       else nsin # :generic - return raw string
       end
     end

data/lib/sec_id/lei.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module SecId
+module SecID
   # Legal Entity Identifier (LEI) - a 20-character alphanumeric code that
   # uniquely identifies legal entities participating in financial transactions.
   #
@@ -10,13 +10,18 @@ module SecId
   # @see https://www.gleif.org/en/about-lei/iso-17442-the-lei-code-structure
   #
   # @example Validate a LEI
-  #   SecId::LEI.valid?('529900T8BM49AURSDO55')  #=> true
+  #   SecID::LEI.valid?('529900T8BM49AURSDO55')  #=> true
   #
   # @example Calculate check digit
-  #   SecId::LEI.check_digit('529900T8BM49AURSDO')  #=> 55
+  #   SecID::LEI.check_digit('529900T8BM49AURSDO')  #=> 55
   class LEI < Base
     include Checkable
 
+    FULL_NAME = 'Legal Entity Identifier'
+    ID_LENGTH = 20
+    EXAMPLE = '7LTWFZYICNSX8D621K86'
+    VALID_CHARS_REGEX = /\A[0-9A-Z]+\z/
+
     # Regular expression for parsing LEI components.
     ID_REGEX = /\A
       (?<identifier>
@@ -45,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
@@ -52,14 +64,15 @@ module SecId
       mod97("#{numeric_identifier}00")
     end
 
-    # @return [String]
-    def to_s
-      return full_number unless check_digit
+    private
 
-      "#{identifier}#{check_digit.to_s.rjust(2, '0')}"
-    end
+    # @return [Hash]
+    def components = { lou_id:, reserved:, entity_id:, check_digit: }
 
-    private
+    # @return [Integer]
+    def check_digit_width
+      2
+    end
 
     # @return [String] the numeric string representation
     def numeric_identifier

data/lib/sec_id/occ.rb

@@ -2,24 +2,28 @@
 
 require 'date'
 
-module SecId
+module SecID
   # OCC Option Symbol - standardized option symbol format used by Option Clearing Corporation.
   # Format: 6-char underlying (padded) + 6-char date (YYMMDD) + type (C/P) + 8-digit strike (in mills).
   #
-  # @note OCC identifiers have no check digit. The {#has_check_digit?} method returns false
-  #   and validation includes both format and date parseability checks.
+  # @note OCC identifiers have no check digit and validation includes both format
+  #   and date parseability checks.
   #
   # @see https://en.wikipedia.org/wiki/Option_symbol#The_OCC_Option_Symbol
   # @see https://web.archive.org/web/20120507220143/http://www.theocc.com/components/docs/initiatives/symbology/symbology_initiative_v1_8.pdf
   #
   # @example Validate an OCC symbol
-  #   SecId::OCC.valid?('AAPL  210917C00150000')  #=> true
+  #   SecID::OCC.valid?('AAPL  210917C00150000')  #=> true
   #
   # @example Build an OCC symbol from components
-  #   occ = SecId::OCC.build(underlying: 'AAPL', date: '2021-09-17', type: 'C', strike: 150.0)
+  #   occ = SecID::OCC.build(underlying: 'AAPL', date: '2021-09-17', type: 'C', strike: 150.0)
   #   occ.to_s  #=> 'AAPL  210917C00150000'
   class OCC < Base
-    include Normalizable
+    FULL_NAME = 'OCC Option Symbol'
+    ID_LENGTH = (16..21)
+    EXAMPLE = 'AAPL  210917C00150000'
+    VALID_CHARS_REGEX = /\A[A-Z0-9 ]+\z/
+    SEPARATORS = /-/
 
     # Regular expression for parsing OCC symbol components.
     ID_REGEX = /\A
@@ -81,7 +85,7 @@ module SecId
         case strike
         when Numeric
           format('%08d', (strike * 1000).to_i)
-        when String && /\A\d{8}\z/
+        when /\A\d{8}\z/
           strike
         else
           raise ArgumentError, 'Strike must be numeric or an 8-char string!'
@@ -91,7 +95,7 @@ module SecId
 
     # @param symbol [String] the OCC symbol string to parse
     def initialize(symbol)
-      symbol_parts = parse(symbol, upcase: false)
+      symbol_parts = parse(symbol)
       @identifier = symbol_parts[:initial]
       @underlying = symbol_parts[:underlying]
       @date_str = symbol_parts[:date]
@@ -99,14 +103,11 @@ module SecId
       @strike_mills = symbol_parts[:strike_mills]
     end
 
-    # Normalizes the OCC symbol to standard format with 6-char padded underlying and 8-digit strike.
-    #
     # @return [String] the normalized OCC symbol
-    # @raise [InvalidFormatError] if the OCC symbol is invalid
-    def normalize!
-      raise InvalidFormatError, "OCC '#{full_number}' is invalid and cannot be normalized!" unless valid?
-
-      @full_number = self.class.compose_symbol(underlying, date_str, type, strike_mills)
+    # @raise [InvalidFormatError, InvalidStructureError]
+    def normalized
+      validate!
+      self.class.compose_symbol(underlying, date_str, type, strike_mills)
     end
 
     # @return [Boolean]
@@ -116,29 +117,53 @@ module SecId
 
     # @return [Date, nil] the parsed date or nil if invalid
     def date
-      return nil unless date_str
+      return @date if defined?(@date)
+      return unless date_str
 
-      @date ||= Date.strptime(date_str, '%y%m%d')
+      @date = Date.strptime(date_str, '%y%m%d')
     rescue ArgumentError
-      nil
+      @date = nil
     end
     alias date_obj date
 
-    # @return [Float] strike price in dollars
+    # @return [Float, nil] strike price in dollars
     def strike
-      @strike ||= strike_mills.to_i / 1000.0
+      return @strike if defined?(@strike)
+
+      @strike = strike_mills&.then { |m| m.to_i / 1000.0 }
     end
 
     # @return [String]
     def to_s
-      full_number
+      full_id
+    end
+
+    # @return [String, nil]
+    def to_pretty_s
+      return nil unless valid?
+
+      "#{underlying} #{date_str} #{type} #{strike_mills}"
     end
-    alias to_str to_s
 
-    # @deprecated Use {#full_number} instead
+    private
+
+    # @return [Hash]
+    def components = { underlying:, date_str:, type:, strike_mills: }
+
+    # @return [Array<Symbol>]
+    def error_codes
+      return detect_errors unless valid_format?
+      return [:invalid_date] if date.nil?
+
+      []
+    end
+
+    # @param code [Symbol]
     # @return [String]
-    def full_symbol
-      full_number
+    def validation_message(code)
+      return "Date '#{date_str}' cannot be parsed" if code == :invalid_date
+
+      super
     end
   end
 end

data/lib/sec_id/sedol.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module SecId
+module SecID
   # Stock Exchange Daily Official List (SEDOL) - a 7-character alphanumeric code
   # that identifies securities traded on the London Stock Exchange and other UK exchanges.
   #
@@ -10,13 +10,18 @@ module SecId
   # @see https://en.wikipedia.org/wiki/SEDOL
   #
   # @example Validate a SEDOL
-  #   SecId::SEDOL.valid?('B19GKT4')  #=> true
+  #   SecID::SEDOL.valid?('B19GKT4')  #=> true
   #
   # @example Calculate check digit
-  #   SecId::SEDOL.check_digit('B19GKT')  #=> 4
+  #   SecID::SEDOL.check_digit('B19GKT')  #=> 4
   class SEDOL < Base
     include Checkable
 
+    FULL_NAME = 'Stock Exchange Daily Official List'
+    ID_LENGTH = 7
+    EXAMPLE = 'B0YBKJ7'
+    VALID_CHARS_REGEX = /\A[0-9BCDFGHJKLMNPQRSTVWXYZ]+\z/
+
     # Regular expression for parsing SEDOL components.
     # Excludes vowels (A, E, I, O, U) from valid characters.
     ID_REGEX = /\A
@@ -45,10 +50,7 @@ module SecId
         raise InvalidFormatError, "'#{country_code}' is not a valid SEDOL country code!"
       end
 
-      sedol_with_check_digit = "#{identifier}#{check_digit || calculate_check_digit}"
-      isin = ISIN.new("#{country_code}00#{sedol_with_check_digit}")
-      isin.restore!
-      isin
+      ISIN.new("#{country_code}00#{restore}").restore!
     end
 
     # @return [Integer] the calculated check digit (0-9)
@@ -60,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

@@ -1,24 +1,26 @@
 # frozen_string_literal: true
 
-module SecId
+module SecID
   # Valoren (Swiss Security Number) - a numeric identifier for securities
   # in Switzerland, Liechtenstein, and Belgium.
   #
   # Format: 5-9 numeric digits
   #
-  # @note Valoren identifiers have no check digit. The {#has_check_digit?} method
-  #   returns false and validation is based solely on format.
+  # @note Valoren identifiers have no check digit and validation is based solely on format.
   #
   # @see https://en.wikipedia.org/wiki/Valoren_number
   #
   # @example Validate a Valoren
-  #   SecId::Valoren.valid?('3886335')    #=> true
-  #   SecId::Valoren.valid?('003886335')  #=> true
+  #   SecID::Valoren.valid?('3886335')    #=> true
+  #   SecID::Valoren.valid?('003886335')  #=> true
   #
   # @example Normalize a Valoren to 9 digits
-  #   SecId::Valoren.normalize!('3886335')  #=> '003886335'
+  #   SecID::Valoren.normalize('3886335')  #=> '003886335'
   class Valoren < Base
-    include Normalizable
+    FULL_NAME = 'Valoren Number'
+    ID_LENGTH = (5..9)
+    EXAMPLE = '3886335'
+    VALID_CHARS_REGEX = /\A[0-9]+\z/
 
     # Regular expression for parsing Valoren components.
     ID_REGEX = /\A
@@ -38,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
@@ -46,29 +55,27 @@ module SecId
         raise InvalidFormatError, "'#{country_code}' is not a valid Valoren country code!"
       end
 
-      normalize!
-      isin = ISIN.new(country_code + full_number)
-      isin.restore!
-      isin
+      ISIN.new(country_code + normalized).restore!
     end
 
-    # Normalizes the Valoren to a 9-digit zero-padded format.
-    # Updates both @full_number and @padding to reflect the normalized state.
-    #
     # @return [String] the normalized 9-digit Valoren
-    # @raise [InvalidFormatError] if the Valoren format is invalid
-    def normalize!
-      raise InvalidFormatError, "Valoren '#{full_number}' is invalid and cannot be normalized!" unless valid_format?
+    # @raise [InvalidFormatError]
+    def normalized
+      validate!
+      @identifier.rjust(self.class::ID_LENGTH.max, '0')
+    end
 
-      @full_number = @identifier.rjust(9, '0')
-      @padding = @full_number[0, 9 - @identifier.length]
-      @full_number
+    # @return [self]
+    # @raise [InvalidFormatError]
+    def normalize!
+      super
+      @padding = @full_id[0, self.class::ID_LENGTH.max - @identifier.length]
+      self
     end
 
     # @return [String]
     def to_s
-      full_number
+      full_id
     end
-    alias to_str to_s
   end
 end

data/lib/sec_id/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
-module SecId
-  VERSION = '4.4.1'
+module SecID
+  VERSION = '5.1.0'
 end

data/lib/sec_id/wkn.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module SecId
+module SecID
   # Wertpapierkennnummer (WKN) - a 6-character alphanumeric code
   # used to identify securities in Germany.
   #
@@ -10,9 +10,14 @@ module SecId
   # @see https://en.wikipedia.org/wiki/Wertpapierkennnummer
   #
   # @example Validate a WKN
-  #   SecId::WKN.valid?('514000')  #=> true
-  #   SecId::WKN.valid?('CBK100')  #=> true
+  #   SecID::WKN.valid?('514000')  #=> true
+  #   SecID::WKN.valid?('CBK100')  #=> true
   class WKN < Base
+    FULL_NAME = 'Wertpapierkennnummer'
+    ID_LENGTH = 6
+    EXAMPLE = '514000'
+    VALID_CHARS_REGEX = /\A[0-9A-HJ-NP-Z]+\z/
+
     # Regular expression for parsing WKN components.
     # Excludes letters I and O to avoid confusion with 1 and 0.
     ID_REGEX = /\A
@@ -31,11 +36,9 @@ module SecId
     # @raise [InvalidFormatError] if the WKN format is invalid
     def to_isin(country_code = 'DE')
       raise InvalidFormatError, "'#{country_code}' is not a valid WKN country code!" unless country_code == 'DE'
-      raise InvalidFormatError, "WKN '#{full_number}' is invalid!" unless valid_format?
+      raise InvalidFormatError, "WKN '#{full_id}' is invalid!" unless valid_format?
 
-      isin = ISIN.new("#{country_code}000#{identifier}")
-      isin.restore!
-      isin
+      ISIN.new("#{country_code}000#{identifier}").restore!
     end
   end
 end

data/lib/sec_id.rb

@@ -1,10 +1,136 @@
 # frozen_string_literal: true
 
-require 'set'
 require 'sec_id/version'
+
+module SecID
+  # Base error class for all SecID errors.
+  class Error < StandardError; end
+
+  # Raised for invalid format, length, or characters.
+  class InvalidFormatError < Error; end
+
+  # Raised when the check digit does not match the calculated value.
+  class InvalidCheckDigitError < Error; end
+
+  # Raised for type-specific structural errors (invalid prefix, category, group, BBAN, or date).
+  class InvalidStructureError < Error; end
+
+  class << self
+    # Looks up an identifier class by its symbol key.
+    #
+    # @param key [Symbol] identifier type (e.g. :isin, :cusip)
+    # @return [Class] the identifier class
+    # @raise [ArgumentError] if key is unknown
+    def [](key)
+      identifier_map.fetch(key) do
+        raise ArgumentError, "Unknown identifier type: #{key.inspect}"
+      end
+    end
+
+    # Returns all registered identifier classes in load order.
+    #
+    # @return [Array<Class>]
+    def identifiers
+      identifier_list.dup
+    end
+
+    # Detects all identifier types that match the given string.
+    #
+    # @param str [String, nil] the identifier string to detect
+    # @return [Array<Symbol>] matching type symbols sorted by specificity
+    def detect(str)
+      detector.call(str)
+    end
+
+    # Checks whether the string is a valid identifier.
+    #
+    # @param str [String, nil] the identifier string to validate
+    # @param types [Array<Symbol>, nil] restrict to specific types (e.g. [:isin, :cusip])
+    # @return [Boolean]
+    # @raise [ArgumentError] if any key in types is unknown
+    def valid?(str, types: nil)
+      return detect(str).any? if types.nil?
+
+      types.any? { |key| self[key].valid?(str) }
+    end
+
+    # Parses a string into the most specific matching identifier instance.
+    #
+    # @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)
+    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
+    # @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))
+    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
+    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)
+        return instance if instance.valid?
+      end
+      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
+    end
+
+    # @return [Detector]
+    def detector
+      @detector ||= Detector.new(identifier_list)
+    end
+
+    # @return [Hash{Symbol => Class}]
+    def identifier_map
+      @identifier_map ||= {}
+    end
+
+    # @return [Array<Class>]
+    def identifier_list
+      @identifier_list ||= []
+    end
+  end
+end
+
+require 'sec_id/errors'
+require 'sec_id/concerns/identifier_metadata'
 require 'sec_id/concerns/normalizable'
+require 'sec_id/concerns/validatable'
 require 'sec_id/concerns/checkable'
 require 'sec_id/base'
+require 'sec_id/detector'
 require 'sec_id/isin'
 require 'sec_id/cusip'
 require 'sec_id/sedol'
@@ -18,8 +144,3 @@ require 'sec_id/valoren'
 require 'sec_id/cei'
 require 'sec_id/cfi'
 require 'sec_id/fisn'
-
-module SecId
-  class Error < StandardError; end
-  class InvalidFormatError < Error; end
-end

data/sec_id.gemspec

@@ -6,7 +6,7 @@ require 'sec_id/version'
 
 Gem::Specification.new do |spec|
   spec.name          = 'sec_id'
-  spec.version       = SecId::VERSION
+  spec.version       = SecID::VERSION
   spec.authors       = ['Leonid Svyatov']
   spec.email         = ['leonid@svyatov.ru']
 
@@ -17,10 +17,13 @@ Gem::Specification.new do |spec|
   spec.homepage      = 'https://github.com/svyatov/sec_id'
   spec.license       = 'MIT'
 
-  spec.required_ruby_version = '>= 3.1.0'
+  spec.required_ruby_version = '>= 3.2.0'
 
   spec.require_paths = ['lib']
-  spec.files = Dir['lib/**/*.rb'] + %w[CHANGELOG.md LICENSE.txt README.md sec_id.gemspec]
+  spec.files = Dir['lib/**/*.rb'] + %w[CHANGELOG.md LICENSE.txt MIGRATION.md README.md sec_id.gemspec]
 
   spec.metadata['rubygems_mfa_required'] = 'true'
+  spec.metadata['source_code_uri'] = 'https://github.com/svyatov/sec_id'
+  spec.metadata['changelog_uri'] = 'https://github.com/svyatov/sec_id/blob/main/CHANGELOG.md'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/svyatov/sec_id/issues'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sec_id
 version: !ruby/object:Gem::Version
-  version: 4.4.1
+  version: 5.1.0
 platform: ruby
 authors:
 - Leonid Svyatov
@@ -20,6 +20,7 @@ extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE.txt
+- MIGRATION.md
 - README.md
 - lib/sec_id.rb
 - lib/sec_id/base.rb
@@ -27,8 +28,12 @@ files:
 - lib/sec_id/cfi.rb
 - lib/sec_id/cik.rb
 - lib/sec_id/concerns/checkable.rb
+- lib/sec_id/concerns/identifier_metadata.rb
 - lib/sec_id/concerns/normalizable.rb
+- lib/sec_id/concerns/validatable.rb
 - lib/sec_id/cusip.rb
+- lib/sec_id/detector.rb
+- lib/sec_id/errors.rb
 - lib/sec_id/figi.rb
 - lib/sec_id/fisn.rb
 - lib/sec_id/iban.rb
@@ -46,6 +51,9 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/svyatov/sec_id
+  changelog_uri: https://github.com/svyatov/sec_id/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/svyatov/sec_id/issues
 rdoc_options: []
 require_paths:
 - lib
@@ -53,14 +61,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.4
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Validate securities identification numbers with ease!
 test_files: []