identified 0.1.0

data/lib/identified/ssn/sequential_group_number.rb

@@ -0,0 +1,43 @@
+module Identified
+  # An alternate version of the group number indexed by the allocation sequence. 1 indicates the 1st
+  # group number issued. 70 indicates the 70th group number issued, etc.
+  class SequentialGroupNumber < DelegateClass(Fixnum)
+    # Takes a regular group number and becomes a representation sequenced by allocation order.
+    # Input values must be between 1 and 99. Output values will be between 1 and 100
+    def initialize(group_number)
+      sequential_group_number = self.class.convert_to_sequential_number(group_number)
+      super(sequential_group_number)
+    end
+
+    # Converts a group number to the index of the sequence of its allocation. Valid return values
+    # are between 1 and 100.
+    def self.convert_to_sequential_number(group_number)
+      @group_index_table ||= generate_index_conversion
+      @group_index_table.fetch(group_number)
+    end
+
+    # Creates the conversion table that goes from regular group number to the index of allocation
+    def self.generate_index_conversion
+      index_table = {}
+
+      # Build the lookup table (group number => sequence number).
+      allocation_sequence.each.with_index(1) do |group_number, index|
+        index_table[group_number] = index
+      end
+
+      index_table
+    end
+    private_class_method :generate_index_conversion
+
+    def self.allocation_sequence
+      # Group numbers are allocated in the order that follows:
+      #  ODD - 01, 03, 05, 07, 09
+      #  EVEN - 10 to 98
+      #  EVEN - 02, 04, 06, 08
+      #  ODD - 11 to 99
+      # See http://www.ssa.gov/history/ssn/geocard.html for details.
+      [*(1..9).step(2), *(10..98).step(2), *(2..8).step(2), *(11..99).step(2)]
+    end
+    private_class_method :allocation_sequence
+  end
+end

data/lib/identified/ssn/serial_number.rb

@@ -0,0 +1,10 @@
+module Identified
+  # Represents the serial number of an SSN and performs simple validation.
+  class SerialNumber < DelegateClass(Fixnum)
+    # All non-zero serial numbers are valid regardless of when the ssn was issued.
+    # See http://www.ssa.gov/history/ssn/geocard.html
+    def valid?
+      (1..9999).include?(self)
+    end
+  end
+end

data/lib/identified/ssn/ssn.rb

@@ -0,0 +1,74 @@
+module Identified
+  # Represents a Social Security Number and provides validation functionality.
+  class SSN
+    RANDOMIZATION_DATE = Date.parse('2011-06-25').freeze
+    RETIRED_SSNS = %w(078-05-1120 219-09-9999)
+    SSN_REGEX = /\A\d{3}-\d{2}-\d{4}\Z/
+    SSN_REGEX_WITHOUT_DASHES = /\A(?<area>\d{3})(?<group>\d{2})(?<serial>\d{4})\Z/
+
+    attr_reader :date_issued, :area, :group, :serial
+
+    # Date is optional but should be provided to improve validation quality.
+    def initialize(ssn_string, options = {})
+      area_num, group_num, serial_num = extract_ssn_values(ssn_string)
+
+      @area = AreaNumber.new(area_num)
+      @group = GroupNumber.new(group_num)
+      @serial = SerialNumber.new(serial_num)
+
+      # Emulating keyword arguments to provide ruby 1.9.3 support.
+      if options.instance_of?(Hash)
+        @date_issued = options.delete(:date_issued)
+      else
+        fail ArgumentError, 'Unexpected argument. The second argument must be an options hash.'
+      end
+      fail ArgumentError, "Unrecgonized option(s): #{options}" if options.any?
+    end
+
+    # Returns whether the ssn COULD be a valid ssn.
+    def valid?
+      area.valid? && group.valid?(area, date_issued) && serial.valid? && !retired?
+    end
+
+    # Provides an array of potential states or protectorates the ssn was issued in. This information
+    # cannot be known unless an issuance date is known and it before SSN randomizaiton. If no
+    # information is avaliable, issuing_states will return [].
+    def issuing_states
+      IssuingStateData.issuing_states(area, date_issued)
+    end
+
+    def ==(other)
+      area == other.area && group == other.group && serial == other.serial
+    end
+
+    # Uses '123-45-6789' format.
+    def to_s
+      format('%.03d-%.02d-%.04d', area, group, serial)
+    end
+
+    private
+
+    # Determines if the ssn is one of the handful of abused / always invalid ssns.
+    def retired?
+      RETIRED_SSNS.map { |ssn_string| SSN.new(ssn_string) }.any? { |ssn| ssn == self }
+    end
+
+    # Returns the integer components of a normalized ssn string for easy mass-assignment.
+    def extract_ssn_values(ssn_string)
+      formatted_ssn = format_ssn(ssn_string)
+      formatted_ssn.split('-').map(&:to_i)
+    end
+
+    # Validates / converts an inputted ssn string to the normalized 123-45-6789 format.
+    def format_ssn(ssn_string)
+      if ssn_string =~ SSN_REGEX
+        ssn_string
+      elsif ssn_string =~ SSN_REGEX_WITHOUT_DASHES
+        match = Regexp.last_match
+        "#{match[:area]}-#{match[:group]}-#{match[:serial]}"
+      else
+        fail MalformedSSNError
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,150 @@
+--- !ruby/object:Gem::Specification
+name: identified
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Daniel Gollahon
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-07-29 00:00:00.000000000 Z
+dependencies: []
+description: Validate government document identifiers (like SSNs) with ease.
+email: Daniel.Gollahon@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- data/ssn/area_data.txt
+- data/ssn/area_data_raw.txt
+- data/ssn/high_groups/april_2004_raw.txt
+- data/ssn/high_groups/april_2005_raw.txt
+- data/ssn/high_groups/april_2006_raw.txt
+- data/ssn/high_groups/april_2007_raw.txt
+- data/ssn/high_groups/april_2008_raw.txt
+- data/ssn/high_groups/april_2009_raw.txt
+- data/ssn/high_groups/april_2010_raw.txt
+- data/ssn/high_groups/april_2011_raw.txt
+- data/ssn/high_groups/august_2004_raw.txt
+- data/ssn/high_groups/august_2005_raw.txt
+- data/ssn/high_groups/august_2006_raw.txt
+- data/ssn/high_groups/august_2007_raw.txt
+- data/ssn/high_groups/august_2008_raw.txt
+- data/ssn/high_groups/august_2009_raw.txt
+- data/ssn/high_groups/august_2010_raw.txt
+- data/ssn/high_groups/december_2003_raw.txt
+- data/ssn/high_groups/december_2004_raw.txt
+- data/ssn/high_groups/december_2005_raw.txt
+- data/ssn/high_groups/december_2006_raw.txt
+- data/ssn/high_groups/december_2007_raw.txt
+- data/ssn/high_groups/december_2008_raw.txt
+- data/ssn/high_groups/december_2009_raw.txt
+- data/ssn/high_groups/december_2010_raw.txt
+- data/ssn/high_groups/february_2004_raw.txt
+- data/ssn/high_groups/february_2005_raw.txt
+- data/ssn/high_groups/february_2006_raw.txt
+- data/ssn/high_groups/february_2007_raw.txt
+- data/ssn/high_groups/february_2008_raw.txt
+- data/ssn/high_groups/february_2009_raw.txt
+- data/ssn/high_groups/february_2010_raw.txt
+- data/ssn/high_groups/february_2011_raw.txt
+- data/ssn/high_groups/january_2004_raw.txt
+- data/ssn/high_groups/january_2005_raw.txt
+- data/ssn/high_groups/january_2006_raw.txt
+- data/ssn/high_groups/january_2007_raw.txt
+- data/ssn/high_groups/january_2008_raw.txt
+- data/ssn/high_groups/january_2009_raw.txt
+- data/ssn/high_groups/january_2010_raw.txt
+- data/ssn/high_groups/january_2011_raw.txt
+- data/ssn/high_groups/july_2004_raw.txt
+- data/ssn/high_groups/july_2005_raw.txt
+- data/ssn/high_groups/july_2006_raw.txt
+- data/ssn/high_groups/july_2007_raw.txt
+- data/ssn/high_groups/july_2008_raw.txt
+- data/ssn/high_groups/july_2009_raw.txt
+- data/ssn/high_groups/july_2010_raw.txt
+- data/ssn/high_groups/june_2004_raw.txt
+- data/ssn/high_groups/june_2005_raw.txt
+- data/ssn/high_groups/june_2006_raw.txt
+- data/ssn/high_groups/june_2007_raw.txt
+- data/ssn/high_groups/june_2008_raw.txt
+- data/ssn/high_groups/june_2009_raw.txt
+- data/ssn/high_groups/june_2010_raw.txt
+- data/ssn/high_groups/june_2011_raw.txt
+- data/ssn/high_groups/june_24_2011_raw.txt
+- data/ssn/high_groups/march_2004_raw.txt
+- data/ssn/high_groups/march_2005_raw.txt
+- data/ssn/high_groups/march_2006_raw.txt
+- data/ssn/high_groups/march_2007_raw.txt
+- data/ssn/high_groups/march_2008_raw.txt
+- data/ssn/high_groups/march_2009_raw.txt
+- data/ssn/high_groups/march_2010_raw.txt
+- data/ssn/high_groups/march_2011_raw.txt
+- data/ssn/high_groups/may_2004_raw.txt
+- data/ssn/high_groups/may_2005_raw.txt
+- data/ssn/high_groups/may_2006_raw.txt
+- data/ssn/high_groups/may_2007_raw.txt
+- data/ssn/high_groups/may_2008_raw.txt
+- data/ssn/high_groups/may_2009_raw.txt
+- data/ssn/high_groups/may_2010_raw.txt
+- data/ssn/high_groups/may_2011_raw.txt
+- data/ssn/high_groups/november_2003_raw.txt
+- data/ssn/high_groups/november_2004_raw.txt
+- data/ssn/high_groups/november_2005_raw.txt
+- data/ssn/high_groups/november_2006_raw.txt
+- data/ssn/high_groups/november_2007_raw.txt
+- data/ssn/high_groups/november_2008_raw.txt
+- data/ssn/high_groups/november_2009_raw.txt
+- data/ssn/high_groups/november_2010_raw.txt
+- data/ssn/high_groups/october_2004_raw.txt
+- data/ssn/high_groups/october_2005_raw.txt
+- data/ssn/high_groups/october_2006_raw.txt
+- data/ssn/high_groups/october_2007_raw.txt
+- data/ssn/high_groups/october_2008_raw.txt
+- data/ssn/high_groups/october_2009_raw.txt
+- data/ssn/high_groups/october_2010_raw.txt
+- data/ssn/high_groups/september_2004_raw.txt
+- data/ssn/high_groups/september_2005_raw.txt
+- data/ssn/high_groups/september_2006_raw.txt
+- data/ssn/high_groups/september_2007_raw.txt
+- data/ssn/high_groups/september_2008_raw.txt
+- data/ssn/high_groups/september_2009_raw.txt
+- data/ssn/high_groups/september_2010_raw.txt
+- lib/identified.rb
+- lib/identified/errors/error.rb
+- lib/identified/errors/ssn/malformed_ssn_error.rb
+- lib/identified/ssn/area_number.rb
+- lib/identified/ssn/group_number.rb
+- lib/identified/ssn/high_group_data.rb
+- lib/identified/ssn/high_group_list.rb
+- lib/identified/ssn/issuing_state_data.rb
+- lib/identified/ssn/sequential_group_number.rb
+- lib/identified/ssn/serial_number.rb
+- lib/identified/ssn/ssn.rb
+homepage: http://rubygems.org/gems/identified
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.6
+signing_key: 
+specification_version: 4
+summary: A simple ssn validator.
+test_files: []
+has_rdoc: