fullname-matcher 1.0.0

data/lib/fullname/matcher/core.rb

@@ -0,0 +1,198 @@
+# this class gets people, based on name match, from a table that stores firstname/middlename/lastaname/suffix separately.
+#
+# try a series of searches (exact match first, then different variations) until success
+# a lof of logics/examples (eg. middlename handling, suffix handling, when to use abbreviation, when to use 'regexp') are commented inline
+#
+# public methods:
+# . new(table, mapping={}, options = {})
+#   when constructing a name match using xxx = Fullname::Matcher.new(...), the first arg is the table where the search is executed in;
+#   default column mapping is {:first => 'first', :middle => 'middle', :last => 'last', :suffix => 'suffix'};
+#   - if the actual mapping is different, it should be provided as the second arg of new()
+#   - options:
+#     :skip_match_middle_name     default is false
+# . set_condition(c)
+#   if there's other condition (like "data_import_key = 'yyyy.mm.dd'") in search criteria, set it this way
+#   
+# . get_matches
+#   if the name is one string, use get_matches(orig_name)
+#   if the name is in pieces,  use get_matches(firstname, middlename, lastname, suffix)
+#   return ALL matches of the first successful search or [] if all searches fail
+# . match_fullname
+#   alias of get_matches
+# . names_match?(n1, style1, n2, style2)
+#   return true if two names (n1 and n2) are same; false otherwise
+#
+require 'fullname/parser'
+require 'fullname/equivalence'
+
+module Fullname::Matcher
+  class Core
+
+    DEFAULT_MAPPING = {:first => 'first', :middle => 'middle', :last => 'last', :suffix => 'suffix'}
+    DEFAULT_OPTIONS = {
+      :skip_match_middle_name => false, # skip match middle name if middle name not provided.
+      :skip_match_suffix => false      # skip match suffix if suffix not provided or no column suffix in database.
+    }
+
+    class Error < StandardError ; end
+    
+    attr_accessor :options
+
+    def initialize(table, mapping = {}, options = {})
+      @table        = table
+      @mapping      = DEFAULT_MAPPING.merge(mapping)
+      @condition    = nil
+      @options      = DEFAULT_OPTIONS.merge(options)
+    end
+    
+    def set_condition(c)
+      @condition = c
+    end
+    
+    def get_matches(*args)
+      name = nil
+      match_options = {}
+      case args.size
+      when 1
+        name = ::Fullname::Parser.parse_fullname(args[0])
+      when 4,5
+        name = {:first => args[0], :middle => args[1], :last => args[2], :suffix => args[3]}
+        match_options = args.pop if args.size == 5
+      else
+        raise Error, 'illeagle arguments length of get_matches, must be the length of 1,4,5'
+      end
+      recursive = match_options.include?(:recursive) ? match_options[:recursive] : true
+      return [] if name[:first].nil? || name[:last].nil?
+      match_list = match_first_last_and_suffix(name)
+      
+      # skip validating middlename if @options[:skip_match_middle_name] == true
+      # all matched result which middle name is NULL or NON-NULL will be returned
+      return match_list if @options[:skip_match_middle_name] && match_list.size > 0
+      
+      if match_list.size > 0
+        # 1. exactly match
+        match_list_with_middlename = match_list.select do |r|
+          r_middle_name = r.send(@mapping[:middle])
+          r_middle_name.to_s.downcase.strip == name[:middle].to_s.downcase.strip
+        end
+        return match_list_with_middlename if match_list_with_middlename.size > 0
+        
+        # 2. if name[:middle] is not NULL, regexp match
+        if name[:middle]
+          m_re = build_middlename_regexp(name[:middle])
+          match_list_with_middlename = match_list.select do |r|
+            r_middle_name = r.send(@mapping[:middle])
+            r_middle_name && r_middle_name =~ m_re
+          end
+          return match_list_with_middlename if match_list_with_middlename.size > 0
+          # 2.1 fuzzy match: if middlename in DB is NULL, it matches
+          match_list_with_middlename = match_list.select{ |r| r.send(@mapping[:middle]).nil? }
+          return match_list_with_middlename if match_list_with_middlename.size > 0
+        else
+          # 2.2 fuzzy match: assume all matches since name[:middle] is NULL
+          return match_list if match_list.size > 0
+        end        
+      end
+      
+      # if nothing matches, try to search with equivalence of first name
+      if match_list.size == 0 && recursive
+        firstname_array = ::Fullname::Equivalence.get_name_equivalence(name[:first])
+        firstname_array.each do |n|
+          match_list += get_matches(n, name[:middle], name[:last], name[:suffix], {:recursive => false})
+        end if firstname_array
+      end
+      
+      return match_list
+    end
+  
+    alias_method :match_fullname, :get_matches
+    
+    # return true if two names (n1 and n2) are same; false otherwise
+    # style = :short means the pieces are first/middle/last/suffix; firstname/middlename/lastname/suffix otherwise
+    def names_match?(n1, style1, n2, style2)
+      f1 = style1 == :short ? n1.first : n1.firstname
+      m1 = style1 == :short ? n1.middle : n1.middlename
+      l1 = style1 == :short ? n1.last : n1.lastname
+      
+      f2 = style2 == :short ? n2.first : n2.firstname
+      m2 = style2 == :short ? n2.middle : n2.middlename
+      l2 = style2 == :short ? n2.last : n2.lastname
+      
+      # first/last name have to be provided
+      return false if l1.nil? || l2.nil? || f1.nil? || f2.nil?
+      return false if l1.downcase.strip != l2.downcase.strip
+      
+      unless @options[:skip_match_suffix]
+        s1 = n1.suffix
+        s2 = n2.suffix
+        return false  if s1 && s2 && s1.gsub('.', '').downcase.strip != s2.gsub('.', '').downcase.strip
+      end
+      
+      return false if !abbr_match?(f1, f2)
+      m1.nil? or m2.nil? or abbr_match?(m1, m2)
+    end
+    
+    # 2 strings are 'abbr-match'ed if
+    # . they are same, or
+    # . one string is one char long and the other starts with it
+    # ex: 'abc edf' abbr-matches 'a. e' or 'abc   edf', but not 'abc e'
+    def abbr_match?(str1, str2)
+      build_middlename_regexp(str1) =~ str2
+    end
+    
+    private
+  
+    def match_first_last_and_suffix(name)
+      conditions  = []
+      queries     = []
+      conditions << '(' + @condition + ')' if @condition
+      queries    << '(placeholder)'
+      conditions << "(#{@mapping[:first]} = ? OR #{@mapping[:first]} REGEXP ?)"
+      queries    << name[:first]
+      queries    << '^' + name[:first][0].chr + '([.]?' + (name[:first] =~ /^[a-z]\.?$/i ? '|[a-z]+' : '') + ')$'
+      conditions << "#{@mapping[:last]} = ?"
+      queries    << name[:last]
+      queries[0] = conditions.join(' AND ')
+      matched_list = @table.all(:conditions => queries)
+      unless @options[:skip_match_suffix]
+        
+        suffix = name[:suffix] ? name[:suffix].gsub('.', '').downcase.strip : nil
+        
+        # exactly match suffix
+        matched_list_with_suffix = matched_list.select{|r|
+          r_suffix = r.send(@mapping[:suffix])
+          r_suffix.to_s.downcase.strip == suffix.to_s
+        }
+        return matched_list_with_suffix if matched_list_with_suffix.size > 0
+        
+        # fuzzy match suffix( NULL matches NON-NULL )
+        return matched_list.select{|r|
+          r_suffix = r.send(@mapping[:suffix])
+          r_suffix.nil? || suffix.nil? || suffix == r_suffix.gsub('.', '').downcase.strip
+        }
+        
+      end
+      return matched_list
+    end
+  
+    def build_middlename_regexp(middlename)
+      middle_arr  = middlename.split(/[. ]+/)
+      tmp_reg     = []
+      # Z M                   |Z M
+      # Z. M.                 |ZM
+      # Z.M.                  |Zoellner M
+      # Z Miller              |Z Miller
+      # Zoellner M            |Zoellner Miller
+      # Zoellner Miller       |
+      # K.Taylor
+      if middle_arr.size > 1
+        last_ele = middle_arr.pop
+        tmp_reg << middle_arr.map{|m| Regexp.escape(m[0].chr) + '[. ]+'}.join + Regexp.escape(last_ele) + '[.]?'
+        middle_arr.push(last_ele)
+      end
+      tmp_reg    << middle_arr.map{|m| m.size == 1 ? (Regexp.escape(m) + '\S*') : (Regexp.escape(m[0].chr) + '(' + Regexp.escape(m[1..-1]) + '|[.])?')}.join('[. ]+')
+      Regexp.new("^(#{tmp_reg.join('|')})$", true)
+    end
+  
+  end
+end

data/lib/fullname/matcher/version.rb

@@ -0,0 +1,5 @@
+module Fullname
+  module Matcher
+    VERSION = '1.0.0'
+  end
+end

data/lib/fullname/matcher.rb

@@ -0,0 +1,15 @@
+require 'fullname/matcher/core'
+require 'fullname/matcher/version'
+
+module Fullname
+  module Matcher
+    
+    def self.create(table, mapping = {}, options = {}, &blk)
+      core = Core.new(table, mapping, options)
+      blk.call(core) if block_given?
+      core
+    end
+  
+  end
+end
+

data/lib/fullname.rb

@@ -0,0 +1,4 @@
+module Fullname
+end
+
+require File.expand_path("../fullname/matcher", __FILE__)

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: fullname-matcher
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- xiaohui
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-01-10 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: fullname-parser
+  requirement: &11930540 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: *11930540
+description: Provide fullname, search in database with proper conditions
+email:
+- wesley@zhangxh.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- README.md
+- fullname-matcher.gemspec
+- lib/fullname.rb
+- lib/fullname/equivalence.rb
+- lib/fullname/matcher.rb
+- lib/fullname/matcher/core.rb
+- lib/fullname/matcher/version.rb
+homepage: https://github.com/xiaohui-zhangxh/fullname-matcher
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Match fullname in database
+test_files: []