sec_id 4.1.0 → 4.3.0

data/lib/sec_id/isin.rb

@@ -1,8 +1,20 @@
 # frozen_string_literal: true
 
 module SecId
-  # https://en.wikipedia.org/wiki/International_Securities_Identification_Number
+  # International Securities Identification Number (ISIN) - a 12-character alphanumeric code
+  # that uniquely identifies a security globally.
+  #
+  # Format: 2-letter country code + 9-character NSIN + 1-digit check digit
+  #
+  # @see https://en.wikipedia.org/wiki/International_Securities_Identification_Number
+  #
+  # @example Validate an ISIN
+  #   SecId::ISIN.valid?('US5949181045')  #=> true
+  #
+  # @example Restore check digit
+  #   SecId::ISIN.restore!('US594918104')  #=> 'US5949181045'
   class ISIN < Base
+    # Regular expression for parsing ISIN components.
     ID_REGEX = /\A
       (?<identifier>
         (?<country_code>[A-Z]{2})
@@ -10,6 +22,7 @@ module SecId
       (?<check_digit>\d)?
     \z/x
 
+    # Country codes that use CUSIP Global Services (CGS) for NSIN assignment.
     CGS_COUNTRY_CODES = Set.new(
       %w[
         US CA AG AI AN AR AS AW BB BL BM BO BQ BR BS BZ CL CO CR CW DM DO EC FM
@@ -18,8 +31,13 @@ module SecId
       ]
     ).freeze
 
-    attr_reader :country_code, :nsin
+    # @return [String, nil] the ISO 3166-1 alpha-2 country code
+    attr_reader :country_code
 
+    # @return [String, nil] the National Securities Identifying Number (9 characters)
+    attr_reader :nsin
+
+    # @param isin [String] the ISIN string to parse
     def initialize(isin)
       isin_parts = parse isin
       @identifier = isin_parts[:identifier]
@@ -28,28 +46,30 @@ module SecId
       @check_digit = isin_parts[:check_digit]&.to_i
     end
 
+    # @return [Integer] the calculated check digit (0-9)
+    # @raise [InvalidFormatError] if the ISIN format is invalid
     def calculate_check_digit
-      unless valid_format?
-        raise InvalidFormatError, "ISIN '#{full_number}' is invalid and check-digit cannot be calculated!"
-      end
-
+      validate_format_for_calculation!
       mod10(luhn_sum)
     end
 
-    # CUSIP Global Services
-    def cgs?
-      CGS_COUNTRY_CODES.include?(country_code)
-    end
-
+    # @return [CUSIP] a new CUSIP instance
+    # @raise [InvalidFormatError] if the country code is not a CGS country
     def to_cusip
       raise InvalidFormatError, "'#{country_code}' is not a CGS country code!" unless cgs?
 
       CUSIP.new(nsin)
     end
 
+    # @return [Boolean] true if the country code is a CGS country
+    def cgs?
+      CGS_COUNTRY_CODES.include?(country_code)
+    end
+
     private
 
-    # https://en.wikipedia.org/wiki/Luhn_algorithm
+    # @return [Integer] the Luhn sum
+    # @see https://en.wikipedia.org/wiki/Luhn_algorithm
     def luhn_sum
       reversed_id_digits.each_slice(2).reduce(0) do |sum, (even, odd)|
         double_even = (even || 0) * 2
@@ -58,6 +78,7 @@ module SecId
       end
     end
 
+    # @return [Array<Integer>] the reversed digit array
     def reversed_id_digits
       identifier.each_char.flat_map(&method(:char_to_digits)).reverse!
     end

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

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require 'date'
+
+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.
+  #
+  # @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>[ ]*))
+      (?<date>\d{6})
+      (?<type>[CP])
+      (?<strike_mills>\d{8})
+    \z/x
+
+    # @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, 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
+
+    # @return [Boolean] always false
+    def has_check_digit?
+      false
+    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)
+    end
+
+    # @return [Boolean]
+    def valid?
+      valid_format? && !date.nil? # date must be parseable
+    end
+
+    # @return [Date, nil] the parsed date or nil if invalid
+    def date
+      return nil unless date_str
+
+      @date ||= Date.strptime(date_str, '%y%m%d')
+    rescue ArgumentError
+      nil
+    end
+    alias date_obj date
+
+    # @return [Float] strike price in dollars
+    def strike
+      @strike ||= strike_mills.to_i / 1000.0
+    end
+
+    # @return [String]
+    def to_s
+      full_number
+    end
+    alias to_str to_s
+
+    # @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.1.0'
+  VERSION = '4.3.0'
 end

data/lib/sec_id.rb

@@ -2,12 +2,16 @@
 
 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'
 
 module SecId
   Error = Class.new(StandardError)

data/sec_id.gemspec

@@ -11,16 +11,15 @@ 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.)
+  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'
 
   spec.required_ruby_version = '>= 3.1.0'
 
   spec.require_paths = ['lib']
-  spec.files = `git ls-files -z`.split("\x0").reject do |f|
-    f.match(%r{^(test|spec|features)/})
-  end
+  spec.files = Dir['lib/**/*.rb'] + %w[CHANGELOG.md LICENSE.txt README.md sec_id.gemspec]
 
   spec.metadata['rubygems_mfa_required'] = 'true'
 end

metadata

@@ -1,41 +1,36 @@
 --- !ruby/object:Gem::Specification
 name: sec_id
 version: !ruby/object:Gem::Version
-  version: 4.1.0
+  version: 4.3.0
 platform: ruby
 authors:
 - Leonid Svyatov
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-09-23 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: 'Validate securities identification numbers with ease! Currently supported
-  standards: ISIN, CUSIP, SEDOL.'
+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: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".github/dependabot.yml"
-- ".github/workflows/main.yml"
-- ".gitignore"
-- ".rspec"
-- ".rubocop.yml"
 - CHANGELOG.md
-- Gemfile
 - LICENSE.txt
 - README.md
-- Rakefile
-- bin/console
-- bin/setup
 - lib/sec_id.rb
 - lib/sec_id/base.rb
 - 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
 - sec_id.gemspec
@@ -44,7 +39,6 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -59,8 +53,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.15
-signing_key:
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Validate securities identification numbers with ease!
 test_files: []

data/.github/dependabot.yml

@@ -1,11 +0,0 @@
-# To get started with Dependabot version updates, you'll need to specify which
-# package ecosystems to update and where the package manifests are located.
-# Please see the documentation for all configuration options:
-# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
-
-version: 2
-updates:
-  - package-ecosystem: "bundler" # See documentation for possible values
-    directory: "/" # Location of package manifests
-    schedule:
-      interval: "weekly"

data/.github/workflows/main.yml

@@ -1,39 +0,0 @@
-name: CI
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-on:
-  push:
-    branches: ["main"]
-  pull_request:
-    branches: ["main"]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    name: Ruby ${{ matrix.ruby_version }}
-    strategy:
-      matrix:
-        ruby_version: [ruby-head, '3.3', '3.2', '3.1']
-
-    env:
-      COVERAGE: true
-      CC_TEST_REPORTER_ID: ${{ vars.CC_TEST_REPORTER_ID }}
-
-    steps:
-    - uses: actions/checkout@v4
-
-    - uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: ${{ matrix.ruby_version }}
-        bundler-cache: true
-      continue-on-error: ${{ matrix.ruby_version == 'ruby-head' }}
-
-    - run: bundle exec rake
-      continue-on-error:  ${{ matrix.ruby_version == 'ruby-head' }}
-
-    - uses: paambaati/codeclimate-action@v8.0.0
-      # Only upload coverage for the latest Ruby and don't run for PRs from forks
-      if: ${{ matrix.ruby_version == '3.3' && github.event.pull_request.head.repo.fork == false }}

data/.gitignore

@@ -1,12 +0,0 @@
-/.bundle/
-/.yardoc
-/Gemfile.lock
-/_yardoc/
-/coverage/
-/doc/
-/pkg/
-/spec/reports/
-/tmp/
-
-# rspec failure tracking
-.rspec_status

data/.rspec

@@ -1,3 +0,0 @@
---format documentation
---color
---require spec_helper

data/.rubocop.yml

@@ -1,39 +0,0 @@
-require:
-  - rubocop-rspec
-
-AllCops:
-  TargetRubyVersion: 3.1
-  DisplayCopNames: true
-  DisplayStyleGuide: true
-  ExtraDetails: true
-  SuggestExtensions: false
-  NewCops: enable
-
-Layout/LineLength:
-  Max: 120
-
-Style/Documentation:
-  Enabled: false
-
-Style/HashEachMethods:
-  Enabled: true
-
-Style/HashTransformKeys:
-  Enabled: true
-
-Style/HashTransformValues:
-  Enabled: true
-
-Metrics/BlockLength:
-  Exclude:
-    - 'spec/**/*'
-
-Lint/MissingSuper:
-  AllowedParentClasses:
-    - Base
-
-RSpec/MultipleExpectations:
-  Max: 5
-
-RSpec/ExampleLength:
-  Max: 10

data/Gemfile

@@ -1,20 +0,0 @@
-# frozen_string_literal: true
-
-source 'https://rubygems.org'
-
-git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
-
-# Specify your gem's dependencies in sec_id.gemspec
-gemspec
-
-# Specify your gem's development dependencies below
-gem 'rake', '>= 13'
-
-gem 'rspec', '~> 3.9'
-gem 'rspec_junit_formatter'
-
-gem 'rubocop', '~> 1.64'
-gem 'rubocop-rspec', '~> 3.0'
-
-gem 'simplecov', '~> 0.22', require: false
-gem 'simplecov_json_formatter', require: false

data/Rakefile

@@ -1,13 +0,0 @@
-# frozen_string_literal: true
-
-require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
-require 'rubocop/rake_task'
-
-RSpec::Core::RakeTask.new(:spec)
-
-RuboCop::RakeTask.new do |task|
-  task.requires << 'rubocop-rspec'
-end
-
-task default: %i[rubocop spec]

data/bin/console

@@ -1,15 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-require 'bundler/setup'
-require 'sec_id'
-
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
-
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require 'irb'
-IRB.start(__FILE__)