icu_tournament 0.8.9

data/lib/icu_tournament/name.rb

@@ -0,0 +1,274 @@
+module ICU
+
+=begin rdoc
+
+== Names
+
+This class exists for two main reasons:
+
+* to normalise to a common format the different ways names are typed in practice
+* to be able to match two names even if they are not exactly the same
+
+To create a name object, supply both the first and second names separately to the constructor.
+
+  robert = ICU::Name.new(' robert  j ', ' FISHER ')
+
+Capitalisation, white space and punctuation will all be automatically corrected:
+
+  robert.name                                    # => 'Robert J. Fischer'
+  robert.rname                                   # => 'Fischer, Robert J.'  (reversed name)
+
+To avoid ambiguity when either the first or second names consist of multiple words, it is better to
+supply the two separately, if known. However, the full name can be supplied alone to the constructor
+and a guess will be made as to the first and last names.
+
+  bobby = ICU::Name.new(' bobby fischer ')
+  
+  bobby.first                                    # => 'Bobby'
+  bobby.last                                     # => 'Fischer'
+
+Names will match even if one is missing middle initials or if a nickname is used for one of the first names.
+
+  bobby.match(robert)                            # =>  true
+
+Note that the class is aware of only common nicknames (e.g. _Bobby_ and _Robert_, _Bill_ and _William_, etc), not all possibilities.
+
+Supplying the _match_ method with strings is equivalent to instantiating a Name instance with the same
+strings and then matching it. So, for example the following are equivalent:
+
+  robert.match('R. J.', 'Fischer')               # => true
+  robert.match(ICU::Name('R. J.', 'Fischer'))    # => true
+
+In those examples, the inital _R_ matches the first letter of _Robert_. However, nickname matches will not
+always work with initials. In the next example, the initial _R_ does not match the first letter _B_ of the
+nickname _Bobby_.
+
+  bobby.match('R. J.', 'Fischer')                # => false
+
+Some of the ways last names are canonicalised are illustrated below:
+
+  ICU::Name.new('John', 'O Reilly').last         # => "O'Reilly"
+  ICU::Name.new('dave', 'mcmanus').last          # => "McManus"
+  ICU::Name.new('pete', 'MACMANUS').last         # => "MacManus"
+  
+=end
+
+  class Name
+    attr_reader :first, :last
+    
+    def initialize(name1='', name2='')
+      @name1 = name1.to_s
+      @name2 = name2.to_s
+      canonicalize
+    end
+    
+    def name
+      name = ''
+      name << @first
+      name << ' ' if @first.length > 0 && @last.length > 0
+      name << @last
+      name
+    end
+    
+    def rname
+      name = ''
+      name << @last
+      name << ', ' if @first.length > 0 && @last.length > 0
+      name << @first
+      name
+    end
+    
+    def to_s
+      rname
+    end
+    
+    def match(name1='', name2='')
+      other = Name.new(name1, name2)
+      match_first(first, other.first) && match_last(last, other.last)
+    end
+    
+    private
+    
+    def canonicalize
+      first, last = partition
+      @first = finish_first(first)
+      @last  = finish_last(last)
+    end
+    
+    def partition
+      if @name2.length == 0
+        # Only one imput so we must split first and last.
+        parts = @name1.split(/,/)
+        if parts.size > 1
+          last  = clean(parts.shift || '')
+          first = clean(parts.join(' '))
+        else
+          parts = clean(@name1).split(/ /)
+          last  = parts.pop || ''
+          first = parts.join(' ')
+        end
+      else
+        # Two inputs, so we are given first and last.
+        first = clean(@name1)
+        last  = clean(@name2)
+      end
+      [first, last]
+    end
+        
+    def clean(name)
+      name.gsub!(/`/, "'")
+      name.gsub!(/[^-a-zA-Z.'\s]/, '')
+      name.gsub!(/\./, ' ')
+      name.gsub!(/\s*-\s*/, '-')
+      name.gsub!(/'+/, "'")
+      name.strip.downcase.split(/\s+/).map do |n|
+        n.sub!(/^-+/, '')
+        n.sub!(/-+$/, '')
+        n.split(/-/).map do |p|
+          p.capitalize!
+        end.join('-')
+      end.join(' ')
+    end
+    
+    def finish_first(names)
+      names.gsub(/([A-Z])\b/, '\1.')
+    end
+    
+    def finish_last(names)
+      names.gsub!(/\b([A-Z])'([a-z])/) { |m| $1 << "'" << $2.upcase}
+      names.gsub!(/\bMc([a-z])/) { |m| 'Mc' << $1.upcase}
+      names.gsub!(/\bMac([a-z])/) do |m|
+        letter = $1
+        'Mac'.concat(@name2.match("[mM][aA][cC]#{letter}") ? letter : letter.upcase)
+      end
+      names.gsub!(/\bO ([A-Z])/) { |m| "O'" << $1 }
+      names
+    end
+    
+    # Match a complete first name.
+    def match_first(first1, first2)
+      # Is this one a walk in the park?
+      return true if first1 == first2
+      
+      # No easy ride. Begin by splitting into individual first names.
+      first1 = split_first(first1)
+      first2 = split_first(first2)
+      
+      # Get the long list and the short list.
+      long, short = first1.size >= first2.size ? [first1, first2] : [first2, first1]
+      
+      # The short one must be a "subset" of the long one.
+      # An extra condition must also be satisfied.
+      extra = false
+      (0..long.size-1).each do |i|
+        lword = long.shift
+        score = match_first_name(lword, short.first)
+        if score >= 0
+          short.shift
+          extra = true if i == 0 || score == 0
+        end
+        break if short.empty? || long.empty?
+      end
+      
+      # There's a match if the following is true.
+      short.empty? && extra
+    end
+    
+    # Match a complete last name.
+    def match_last(last1, last2)
+      return true if last1 == last2
+      [last1, last2].each do |last|
+        last.downcase!             # MacDonaugh and Macdonaugh
+        last.gsub!(/\bmac/, 'mc')  # MacDonaugh and McDonaugh
+        last.tr!('-', ' ')         # Lowry-O'Reilly and Lowry O'Reilly
+      end
+      last1 == last2
+    end
+    
+    # Split a complete first name for matching.
+    def split_first(first)
+      first.tr!('-', ' ')              # J. K. and J.-K.
+      first = first.split(/ /)         # split on spaces
+      first = [''] if first.size == 0  # in case input was empty string
+      first
+    end
+    
+    # Match individual first names or initials.
+    # -1 = no match
+    #  0 = full match
+    #  1 = match involving 1 initial
+    #  2 = match involving 2 initials
+    def match_first_name(first1, first2)
+      initials = 0
+      initials+= 1 if first1.match(/^[A-Z]\.?$/)
+      initials+= 1 if first2.match(/^[A-Z]\.?$/)
+      return initials if first1 == first2
+      return 0 if initials == 0 && match_nick_name(first1, first2)
+      return -1 unless initials > 0
+      return initials if first1[0] == first2[0]
+      -1
+    end
+    
+    # Match two first names that might be equivalent nicknames.
+    def match_nick_name(nick1, nick2)
+      compile_nick_names unless @@nc
+      code1 = @@nc[nick1]
+      return false unless code1
+      code1 == @@nc[nick2]
+    end
+    
+    # Compile the nick names code hash when matching nick names is first attempted.
+    def compile_nick_names
+      @@nc = Hash.new
+      code = 1
+      @@nl.each do |nicks|
+        nicks.each do |n|
+          throw "duplicate name #{n}" if @@nc[n]
+          @@nc[n] = code
+        end
+        code+= 1
+      end
+    end
+    
+    # A array of data for matching nicknames and also a few common misspellings.
+    @@nc = nil
+    @@nl = <<EOF.split(/\n/).reject{|x| x.length == 0 }.map{|x| x.split(' ')}
+Abdul Abul
+Alexander Alex
+Anandagopal Ananda
+Anne Ann
+Anthony Tony
+Benjamin Ben
+Catherine Cathy Cath
+Daniel Danial Danny Dan
+David Dave
+Deborah Debbie
+Des Desmond
+Eamonn Eamon
+Edward Eddie Ed
+Eric Erick Erik
+Frederick Frederic Fred
+Gerald Gerry
+Gerhard Gerard Ger
+James Jim
+Joanna Joan Joanne
+John Johnny
+Jonathan Jon
+Kenneth Ken Kenny
+Michael Mike Mick Micky
+Nicholas Nick Nicolas
+Nicola Nickie Nicky
+Patrick Pat Paddy
+Peter Pete
+Philippe Philip Phillippe Phillip
+Rick Ricky
+Robert Bob Bobby
+Samual Sam Samuel
+Stefanie Stef
+Stephen Steven Steve
+Terence Terry
+Thomas Tom Tommy
+William Will Willy Willie Bill
+EOF
+  end
+end

data/lib/icu_tournament/player.rb

@@ -0,0 +1,204 @@
+module ICU
+
+=begin rdoc
+
+== Player
+
+A player in a tournament must have a first name, a last name and a number
+which is unique in the tournament but otherwise arbitary.
+
+  bobby = ICU::Player.new('robert j', 'fischer', 17)
+
+Names are automatically cannonicalised (tidied up).
+
+  bobby.first_name                 # => 'Robert J.'
+  bobby.last_name                  # => 'Fischer'
+
+In addition, players have a number of optional attributes which can be specified
+via setters or in constructor hash options: _id_ (either FIDE or national),
+_fed_ (federation), _title_, _rating_, _rank_ and _dob_ (date of birth).
+
+  peter = ICU::Player.new('Peter', 'Svidler', 21, :fed => 'rus', :title => 'g', :rating = 2700)
+  peter.dob = '17th June, 1976'
+  peter.rank = 1
+
+Some of these values will also be canonicalised to some extent. For example,
+the date of birth conforms to a _yyyy-mm-dd_ format, the chess title will be two
+to three capital letters always ending in _M_ and the federation, if it's three
+letters long, will be upcased.
+
+  peter.dob                        # => 1976-07-17
+  peter.title                      # => 'GM'
+  peter.fed                        # => 'RUS'
+
+It is preferable to add results (ICU::Result) to a player via the tournament (ICU::Tournament) object's
+_add_result_ method rather than the method of the same name belonging to player instances. Doing so
+allows mirrored results to be added to both players with one method call (e.g. one player won, the
+other lost). A player's results can later be retieved via the _results_ accessor.
+
+Total scores is available via the _points_ method.
+
+  peter.points                     # => 5.5
+
+Players can be compared to see if they're roughly or exactly the same, which may be useful in detecting duplicates.
+If the names match and the federations don't disagree then two players are equal according to the _==_ operator.
+The player number is irrelevant.
+
+  john1 = ICU::Player.new('John', 'Smith', 12)
+  john2 = ICU::Player.new('John', 'Smith', 22, :fed = 'IRL')
+  john2 = ICU::Player.new('John', 'Smith', 32, :fed = 'ENG')
+
+  john1 == john2                   # => true (federations don't disagree because one is unset)
+  john2 == john3                   # => false (federations disagree)
+
+If, in addition, _rating_, _dob_, _gender_ and _id_ do not disagree then two players are equal
+according to the stricter criteria of _eql?_.
+
+  mark1 = ICU::Player.new('Mark', 'Orr', 31, :fed = 'IRL', :rating => 2100)
+  mark2 = ICU::Player.new('Mark', 'Orr', 33, :fed = 'IRL', :rating => 2100, :title => 'IM')
+  mark3 = ICU::Player.new('Mark', 'Orr', 37, :fed = 'IRL', :rating => 2200, :title => 'IM')
+
+  mark1.eql?(mark2)                # => true (ratings agree and titles don't disagree)
+  mark2.eql?(mark3)                # => false (the ratings are not the same)
+
+The presence of two players in the same tournament that are equal according to _==_ but unequal
+according to _eql?__ is likely to indicate a data entry error.
+
+If two instances represent the same player and are equal according to _==_ then the _id_, _rating_,
+_title_ and _fed_ attributes of the two can be merged. For example:
+
+  fox1 = ICU::Player.new('Tony', 'Fox', 12, :id => 456)
+  fox2 = ICU::Player.new('Tony', 'Fox', 21, :rating => 2100, :fed => 'IRL', :gender => 'M')
+  fox1.merge(fox2)
+
+Any attributes present in the second player but not in the first are copied to the first.
+All other attributes are unaffected.
+
+  fox1.rating                      # => 2100
+  fox1.fed                         # => 'IRL'
+  fox1.gender                      # => 'M'
+
+=end
+
+  class Player
+    
+    extend ICU::Accessor
+    attr_integer :num
+    attr_positive_or_nil :id, :rating, :rank
+    attr_date_or_nil :dob
+    
+    attr_reader :results, :first_name, :last_name, :fed, :title, :gender
+    
+    # Constructor. Must supply both names and a unique number for the tournament.
+    def initialize(first_name, last_name, num, opt={})
+      self.first_name = first_name
+      self.last_name  = last_name
+      self.num        = num
+      [:id, :fed, :title, :rating, :rank, :dob, :gender].each do |atr|
+        self.send("#{atr}=", opt[atr]) unless opt[atr].nil?
+      end
+      @results = []
+    end
+    
+    # Canonicalise and set the first name(s).
+    def first_name=(first_name)
+      name = Name.new(first_name, 'Last')
+      raise "invalid first name" unless name.first.length > 0
+      @first_name = name.first
+    end
+    
+    # Canonicalise and set the last name(s).
+    def last_name=(last_name)
+      name = Name.new('First', last_name)
+      raise "invalid last name" unless name.last.length > 0 && name.first.length > 0
+      @last_name = name.last
+    end
+    
+    # Return the full name, last name first.
+    def name
+      "#{last_name}, #{first_name}"
+    end
+    
+    # Federation. Is either unknown (nil) or a string containing at least three letters.
+    def fed=(fed)
+      obj = Federation.find(fed)
+      @fed = obj ? obj.code : nil
+      raise "invalid federation (#{fed})" if @fed.nil? && fed.to_s.strip.length > 0
+    end
+    
+    # Chess title. Is either unknown (nil) or one of: _GM_, _IM_, _FM_, _CM_, _NM_,
+    # or any of these preceeded by the letter _W_.
+    def title=(title)
+      @title = title.to_s.strip.upcase
+      @title << 'M' if @title.match(/[A-LN-Z]$/)
+      @title = 'IM' if @title == 'M'
+      @title = 'WIM' if @title == 'WM'
+      @title = nil if @title == ''
+      raise "invalid chess title (#{title})" unless @title.nil? || @title.match(/^W?[GIFCN]M$/)
+    end
+    
+    # Gender. Is either unknown (nil) or one of _M_ or _F_.
+    def gender=(gender)
+      @gender = gender.to_s.strip[0,1].upcase
+      @gender = nil if @gender == ''
+      @gender = 'F' if @gender == 'W'
+      raise "invalid gender (#{gender})" unless @gender.nil? || @gender.match(/^[MF]$/)
+    end
+    
+    # Add a result. Don't use this method directly - use ICU::Tournament#add_result instead.
+    def add_result(result)
+      raise "invalid result" unless result.class == ICU::Result
+      raise "player number (#{@num}) is not matched to result player number (#{result.player})" unless @num == result.player
+      already = @results.find_all { |r| r.round == result.round }
+      return if already.size == 1 && already[0].eql?(result)
+      raise "round number (#{result.round}) of new result is not unique and new result is not the same as existing one" unless already.size == 0
+      @results << result
+    end
+    
+    # Lookup a result by round number.
+    def find_result(round)
+      @results.find { |r| r.round == round }
+    end
+    
+    # Return the player's total points.
+    def points
+      @results.inject(0.0) { |t, r| t += r.points }
+    end
+    
+    # Renumber the player according to the supplied hash. Return self.
+    def renumber(map)
+      raise "player number #{@num} not found in renumbering hash" unless map[@num]
+      self.num = map[@num]
+      @results.each{ |r| r.renumber(map) }
+      self
+    end
+    
+    # Loose equality test. Passes if the names match and the federations are not different.
+    def ==(other)
+      return true if equal?(other)
+      return false unless other.is_a? Player
+      return false unless @first_name == other.first_name
+      return false unless @last_name  == other.last_name
+      return false if @fed && other.fed && @fed != other.fed
+      true
+    end
+    
+    # Strict equality test. Passes if the playes are loosly equal and also if their ID, rating, gender and title are not different.
+    def eql?(other)
+      return true if equal?(other)
+      return false unless self == other
+      [:id, :rating, :title, :gender].each do |m|
+        return false if self.send(m) && other.send(m) && self.send(m) != other.send(m)
+      end
+      true
+    end
+    
+    # Merge in some of the details of another player.
+    def merge(other)
+      raise "cannot merge two players that are not equal" unless self == other
+      [:id, :rating, :title, :fed, :gender].each do |m|
+        self.send("#{m}=", other.send(m)) unless self.send(m)
+      end
+    end
+  end
+end