sec_id 4.2.0 → 4.3.0

data/lib/sec_id/lei.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module SecId
+  # Legal Entity Identifier (LEI) - a 20-character alphanumeric code that
+  # uniquely identifies legal entities participating in financial transactions.
+  #
+  # Format: 4-character LOU ID + 2-character reserved + 12-character entity ID + 2-digit check digit
+  #
+  # @see https://en.wikipedia.org/wiki/Legal_Entity_Identifier
+  # @see https://www.gleif.org/en/about-lei/iso-17442-the-lei-code-structure
+  #
+  # @example Validate a LEI
+  #   SecId::LEI.valid?('529900T8BM49AURSDO55')  #=> true
+  #
+  # @example Calculate check digit
+  #   SecId::LEI.check_digit('529900T8BM49AURSDO')  #=> 55
+  class LEI < Base
+    # Regular expression for parsing LEI components.
+    ID_REGEX = /\A
+      (?<identifier>
+        (?<lou_id>[0-9A-Z]{4})
+        (?<reserved>[0-9A-Z]{2})
+        (?<entity_id>[0-9A-Z]{12}))
+      (?<check_digit>\d{2})?
+    \z/x
+
+    # @return [String, nil] the 4-character Local Operating Unit (LOU) identifier
+    attr_reader :lou_id
+
+    # @return [String, nil] the 2-character reserved field (typically '00')
+    attr_reader :reserved
+
+    # @return [String, nil] the 12-character entity-specific identifier
+    attr_reader :entity_id
+
+    # @param lei [String] the LEI string to parse
+    def initialize(lei)
+      lei_parts = parse lei
+      @identifier = lei_parts[:identifier]
+      @lou_id = lei_parts[:lou_id]
+      @reserved = lei_parts[:reserved]
+      @entity_id = lei_parts[:entity_id]
+      @check_digit = lei_parts[:check_digit]&.to_i
+    end
+
+    # @return [Integer] the calculated 2-digit check digit (1-98)
+    # @raise [InvalidFormatError] if the LEI format is invalid
+    def calculate_check_digit
+      validate_format_for_calculation!
+      mod97("#{numeric_identifier}00")
+    end
+
+    # @return [String]
+    def to_s
+      return full_number unless check_digit
+
+      "#{identifier}#{check_digit.to_s.rjust(2, '0')}"
+    end
+
+    private
+
+    # @return [String] the numeric string representation
+    def numeric_identifier
+      identifier.each_char.map { |char| char_to_digit(char) }.join
+    end
+  end
+end

data/lib/sec_id/normalizable.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SecId
+  # Provides normalize! class method delegation for identifiers that support normalization.
+  # Include this module in classes that implement an instance-level normalize! method.
+  #
+  # @example
+  #   class MyIdentifier < Base
+  #     include Normalizable
+  #
+  #     def normalize!
+  #       # implementation
+  #     end
+  #   end
+  #
+  #   MyIdentifier.normalize!('ABC123')  #=> normalized string
+  module Normalizable
+    # @api private
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Class methods added when Normalizable is included.
+    module ClassMethods
+      # Normalizes the identifier to its canonical format.
+      #
+      # @param id [String, #to_s] the identifier to normalize
+      # @return [String] the normalized identifier
+      # @raise [InvalidFormatError] if the identifier format is invalid
+      def normalize!(id)
+        new(id).normalize!
+      end
+    end
+  end
+end

data/lib/sec_id/occ.rb

@@ -3,9 +3,25 @@
 require 'date'
 
 module SecId
-  # https://en.wikipedia.org/wiki/Option_symbol#The_OCC_Option_Symbol
-  # https://web.archive.org/web/20120507220143/http://www.theocc.com/components/docs/initiatives/symbology/symbology_initiative_v1_8.pdf
-  class OCC
+  # 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.
+  #
+  # @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
+  #
+  # @example Build an OCC symbol from components
+  #   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
+
+    # Regular expression for parsing OCC symbol components.
     ID_REGEX = /\A
       (?<initial>
         (?=.{1,6})(?<underlying>\d?[A-Z]{1,5}\d?)(?<padding>[ ]*))
@@ -14,90 +30,121 @@ module SecId
       (?<strike_mills>\d{8})
     \z/x
 
-    attr_reader :full_symbol, :underlying, :date_str, :type
+    # @return [String, nil] the underlying security symbol (1-6 chars)
+    attr_reader :underlying
 
+    # @return [String, nil] the expiration date string in YYMMDD format
+    attr_reader :date_str
+
+    # @return [String, nil] the option type ('C' for call, 'P' for put)
+    attr_reader :type
+
+    # @return [String, nil] the strike price in mills (thousandths of a dollar, represented as an 8-digit string)
+    attr_reader :strike_mills
+
+    class << self
+      # Builds an OCC symbol from components.
+      #
+      # @param underlying [String] the underlying symbol (1-6 chars)
+      # @param date [String, Date] the expiration date
+      # @param type [String] 'C' for call or 'P' for put
+      # @param strike [Numeric, String] the strike price in dollars or 8-char mills string
+      # @return [OCC] a new OCC instance
+      # @raise [ArgumentError] if strike format is invalid
+      def build(underlying:, date:, type:, strike:)
+        date_obj = date.is_a?(Date) ? date : Date.parse(date)
+        strike_mills = normalize_strike_mills(strike)
+
+        new(compose_symbol(underlying, date_obj.strftime('%y%m%d'), type, strike_mills))
+      end
+
+      # Composes an OCC symbol string from its components.
+      #
+      # @param underlying [String] the underlying symbol
+      # @param date_str [String] the date in YYMMDD format
+      # @param type [String] 'C' or 'P'
+      # @param strike_mills [String, Integer] the strike in mills
+      # @return [String] the composed OCC symbol
+      def compose_symbol(underlying, date_str, type, strike_mills)
+        padded_underlying = underlying.to_s.ljust(6, "\s")
+        padded_strike = format('%08d', strike_mills.to_i)
+
+        "#{padded_underlying}#{date_str}#{type}#{padded_strike}"
+      end
+
+      private
+
+      # @param strike [Numeric, String] strike price or 8-char mills string
+      # @return [String] 8-character strike mills string
+      # @raise [ArgumentError] if strike format is invalid
+      def normalize_strike_mills(strike)
+        case strike
+        when Numeric
+          format('%08d', (strike * 1000).to_i)
+        when String && /\A\d{8}\z/
+          strike
+        else
+          raise ArgumentError, 'Strike must be numeric or an 8-char string!'
+        end
+      end
+    end
+
+    # @param symbol [String] the OCC symbol string to parse
     def initialize(symbol)
-      symbol_parts = parse symbol
-      @initial = symbol_parts[:initial]
+      symbol_parts = parse(symbol, upcase: false)
+      @identifier = symbol_parts[:initial]
       @underlying = symbol_parts[:underlying]
       @date_str = symbol_parts[:date]
       @type = symbol_parts[:type]
       @strike_mills = symbol_parts[:strike_mills]
+      @check_digit = nil
     end
 
-    def date
-      return @date if @date
-
-      @date = Date.strptime(date_str, '%y%m%d') if date_str
-    rescue Date::Error
-      nil
+    # @return [Boolean] always false
+    def has_check_digit?
+      false
     end
-    alias date_obj date
 
-    def strike
-      @strike ||= @strike_mills.to_i / 1000.0
-    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?
 
-    def valid?
-      valid_format? && !date.nil?
+      @full_number = self.class.compose_symbol(underlying, date_str, type, strike_mills)
     end
 
-    def valid_format?
-      !@initial.nil?
+    # @return [Boolean]
+    def valid?
+      valid_format? && !date.nil? # date must be parseable
     end
 
-    def normalize!
-      raise InvalidFormatError, "OCC '#{full_symbol}' is invalid and cannot be normalized!" unless valid?
+    # @return [Date, nil] the parsed date or nil if invalid
+    def date
+      return nil unless date_str
 
-      @strike_mills.length > 8 && @strike_mills = format('%08d', @strike_mills.to_i)
-      @initial.length < 6 && @initial = underlying.ljust(6, "\s")
+      @date ||= Date.strptime(date_str, '%y%m%d')
+    rescue ArgumentError
+      nil
+    end
+    alias date_obj date
 
-      @full_symbol = "#{@initial}#{date_str}#{type}#{@strike_mills}"
+    # @return [Float] strike price in dollars
+    def strike
+      @strike ||= strike_mills.to_i / 1000.0
     end
 
+    # @return [String]
     def to_s
-      full_symbol
+      full_number
     end
     alias to_str to_s
 
-    class << self
-      def valid?(id)
-        new(id).valid?
-      end
-
-      def valid_format?(id)
-        new(id).valid_format?
-      end
-
-      def normalize!(id)
-        new(id).normalize!
-      end
-
-      # rubocop:disable Metrics/MethodLength
-      def build(underlying:, date:, type:, strike:)
-        initial = underlying.to_s.ljust(6, "\s")
-        date = Date.parse(date.to_s) unless date.is_a?(Date)
-
-        case strike
-        when Numeric
-          strike_mills = format('%08d', (strike * 1000).to_i)
-        when /\A\d{8}\z/
-          strike_mills = strike
-        else
-          raise ArgumentError, 'Strike must be numeric or an 8-char string!'
-        end
-
-        symbol = "#{initial}#{date.strftime('%y%m%d')}#{type}#{strike_mills}"
-        new(symbol)
-      end
-      # rubocop:enable Metrics/MethodLength
-    end
-
-    private
-
-    def parse(symbol)
-      @full_symbol = symbol.to_s.strip
-      @full_symbol.match(ID_REGEX) || {}
+    # @deprecated Use {#full_number} instead
+    # @return [String]
+    def full_symbol
+      full_number
     end
   end
 end

data/lib/sec_id/sedol.rb

@@ -1,32 +1,49 @@
 # frozen_string_literal: true
 
 module SecId
-  # https://en.wikipedia.org/wiki/SEDOL
+  # Stock Exchange Daily Official List (SEDOL) - a 7-character alphanumeric code
+  # that identifies securities traded on the London Stock Exchange and other UK exchanges.
+  #
+  # Format: 6-character identifier + 1-digit check digit
+  # Note: SEDOL excludes vowels (A, E, I, O, U) to avoid forming words.
+  #
+  # @see https://en.wikipedia.org/wiki/SEDOL
+  #
+  # @example Validate a SEDOL
+  #   SecId::SEDOL.valid?('B19GKT4')  #=> true
+  #
+  # @example Calculate check digit
+  #   SecId::SEDOL.check_digit('B19GKT')  #=> 4
   class SEDOL < Base
+    # Regular expression for parsing SEDOL components.
+    # Excludes vowels (A, E, I, O, U) from valid characters.
     ID_REGEX = /\A
       (?<identifier>[0-9BCDFGHJKLMNPQRSTVWXYZ]{6})
       (?<check_digit>\d)?
     \z/x
 
+    # Weights applied to each character position in the check digit calculation.
     CHARACTER_WEIGHTS = [1, 3, 1, 7, 3, 9].freeze
 
+    # @param sedol [String] the SEDOL string to parse
     def initialize(sedol)
       sedol_parts = parse sedol
       @identifier = sedol_parts[:identifier]
       @check_digit = sedol_parts[:check_digit]&.to_i
     end
 
+    # @return [Integer] the calculated check digit (0-9)
+    # @raise [InvalidFormatError] if the SEDOL format is invalid
     def calculate_check_digit
-      unless valid_format?
-        raise InvalidFormatError, "SEDOL '#{full_number}' is invalid and check-digit cannot be calculated!"
-      end
-
+      validate_format_for_calculation!
       mod10(weighted_sum)
     end
 
     private
 
-    # NOTE: I know this isn't the most idiomatic Ruby code, but it's the fastest one
+    # NOTE: Not idiomatic Ruby, but optimized for performance.
+    #
+    # @return [Integer] the weighted sum
     def weighted_sum
       index = 0
       sum = 0
@@ -39,6 +56,7 @@ module SecId
       sum
     end
 
+    # @return [Array<Integer>] array of digit values
     def id_digits
       @id_digits ||= identifier.each_char.map(&method(:char_to_digit))
     end

data/lib/sec_id/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SecId
-  VERSION = '4.2.0'
+  VERSION = '4.3.0'
 end

data/lib/sec_id.rb

@@ -2,11 +2,14 @@
 
 require 'set'
 require 'sec_id/version'
+require 'sec_id/normalizable'
 require 'sec_id/base'
 require 'sec_id/isin'
 require 'sec_id/cusip'
 require 'sec_id/sedol'
 require 'sec_id/figi'
+require 'sec_id/lei'
+require 'sec_id/iban'
 require 'sec_id/cik'
 require 'sec_id/occ'
 

data/sec_id.gemspec

@@ -11,7 +11,8 @@ Gem::Specification.new do |spec|
   spec.email         = ['leonid@svyatov.ru']
 
   spec.summary       = 'Validate securities identification numbers with ease!'
-  spec.description   = %(#{spec.summary} Currently supported standards: ISIN, CUSIP, SEDOL, FIGI, CIK, OCC.)
+  spec.description   = 'Validate, calculate check digits, and parse components of securities identifiers. ' \
+                       'Supports ISIN, CUSIP, SEDOL, FIGI, LEI, IBAN, CIK, and OCC standards.'
   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: 4.2.0
+  version: 4.3.0
 platform: ruby
 authors:
 - Leonid Svyatov
@@ -9,8 +9,8 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: 'Validate securities identification numbers with ease! Currently supported
-  standards: ISIN, CUSIP, SEDOL, FIGI, CIK, OCC.'
+description: Validate, calculate check digits, and parse components of securities
+  identifiers. Supports ISIN, CUSIP, SEDOL, FIGI, LEI, IBAN, CIK, and OCC standards.
 email:
 - leonid@svyatov.ru
 executables: []
@@ -25,7 +25,11 @@ files:
 - lib/sec_id/cik.rb
 - lib/sec_id/cusip.rb
 - lib/sec_id/figi.rb
+- lib/sec_id/iban.rb
+- lib/sec_id/iban/country_rules.rb
 - lib/sec_id/isin.rb
+- lib/sec_id/lei.rb
+- lib/sec_id/normalizable.rb
 - lib/sec_id/occ.rb
 - lib/sec_id/sedol.rb
 - lib/sec_id/version.rb