leaderboard 3.6.0 → 3.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 457a795959a19eb87e92f2e15df972997cf862c0
-  data.tar.gz: 46efa5becb8ddcada520c3ca5b37235c9d751507
+  metadata.gz: 73f4fb333c04f1aef154ecf0469cdea2f3602c24
+  data.tar.gz: 6ada4c6ec175b491b2dec536b4961e3bd472eb54
 SHA512:
-  metadata.gz: d1a7accf722c5fb0e1d1e24a897e173a88296694fdf94dabfc9289569a3543482c355c411365fab3ded182d91ba4ceb614708d21073205c54f31a0afbfb4d8f9
-  data.tar.gz: 0582a7737d0b07933f3665644c7436e90e2ed59684698bd0f4971dc061cd9b2aaa614024ca70636712364029fe29ee124fb64c2de3beb40e9424146e18e780c3
+  metadata.gz: 104e46c727ed24d53883a4f45260af84fc3518d863ef662ccafab806152aea83aea40a5a740c80452535c2dcf25853cd54ce52aa7b398f9b019638654f44e99c
+  data.tar.gz: 96f0f5756c4a17bd0dd9e573a3e8b682f961168f7a47e2fb0f0100cd6ec427457afdacb194367bf01a6f38eb5032bdcd3458f344a8683450dc8697a5a31d62c6

data/.rspec

@@ -1,3 +1,3 @@
 --color
---format nested
+--format documentation
 --order random

data/.ruby-version

@@ -1,3 +1 @@
-ruby-1.8.7
-ruby-1.9.3
-ruby-2.0.0
+ruby-2.1.2

data/.travis.yml

@@ -1,7 +1,6 @@
 language: ruby
 rvm:
-  - 2.0.0
+  - 2.1.2
   - 1.9.3
-  - 1.8.7
 services:
   - redis-server

data/CHANGELOG.markdown

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## 3.7.0 (2014-07-28)
+
+* Add support for tie handling in leaderboards [#46](https://github.com/agoragames/leaderboard/pull/46)
+
 ## 3.6.0 (2014-02-15)
 
 * Allow for customization of member_data namespace [#45](https://github.com/agoragames/leaderboard/pull/45)

data/README.markdown

@@ -21,7 +21,7 @@ check out the [Redis documentation](http://redis.io/documentation).
 
 ## Compatibility
 
-The gem has been built and tested under Ruby 1.8.7, Ruby 1.9.2 and Ruby 1.9.3.
+The gem has been built and tested under Ruby 1.9.3 and Ruby 2.1.2.
 
 ## Usage
 
@@ -302,6 +302,38 @@ Use this method to do bulk insert of data, but be mindful of the amount of data
 highscore_lb.rank_member_across(['highscores', 'more_highscores'], 'david', 50000, { :member_name => "david" })
 ```
 
+### Alternate leaderboard types
+
+The leaderboard library offers 3 styles of ranking. This is only an issue for members with the same score in a leaderboard.
+
+Default: The `Leaderboard` class uses the default Redis sorted set ordering, whereby different members having the same score are ordered lexicographically. As per the Redis documentation on Redis sorted sets, "The lexicographic ordering used is binary, it compares strings as array of bytes."
+
+Tie ranking: The `TieRankingLeaderboard` subclass of `Leaderboard` allows you to define a leaderboard where members with the same score are given the same rank. For example, members in a leaderboard with the associated scores would have the ranks of:
+
+```
+| member     | score | rank |
+-----------------------------
+| member_1   | 50    | 1    |
+| member_2   | 50    | 1    |
+| member_3   | 30    | 2    |
+| member_4   | 30    | 2    |
+| member_5   | 10    | 3    |
+```
+
+The `TieRankingLeaderboard` accepts one additional option, `:ties_namespace` (default: ties), when initializing a new instance of this class. Please note that in its current implementation, the `TieRankingLeaderboard` class uses an additional sorted set to rank the scores, so please keep this in mind when you are doing any capacity planning for Redis with respect to memory usage.
+
+Competition ranking: The `CompetitionRankingLeaderboard` subclass of `Leaderboard` allows you to define a leaderboard where members with the same score will have the same rank, and then a gap is left in the ranking numbers. For example, members in a leaderboard with the associated scores would have the ranks of:
+
+```
+| member     | score | rank |
+-----------------------------
+| member_1   | 50    | 1    |
+| member_2   | 50    | 1    |
+| member_3   | 30    | 3    |
+| member_4   | 30    | 3    |
+| member_5   | 10    | 5    |
+```
+
 ### Other useful methods
 
 ```

data/Rakefile

@@ -9,8 +9,3 @@ RSpec::Core::RakeTask.new(:spec) do |spec|
 end
 
 task :default => :spec
-
-desc "Run the specs against Ruby 1.8.7, 1.9.3, 2.0.0"
-task :test_rubies do
-  system "rvm 1.8.7@leaderboard_gem,1.9.3@leaderboard_gem,2.0.0@leaderboard_gem do rake spec"
-end

data/leaderboard.gemspec

@@ -22,8 +22,5 @@ Gem::Specification.new do |s|
 
   s.add_dependency('redis')
   s.add_development_dependency('rake')
-  if '1.8.7'.eql?(RUBY_VERSION)
-    s.add_development_dependency('SystemTimer')
-  end
   s.add_development_dependency('rspec')
 end

data/lib/competition_ranking_leaderboard.rb

@@ -0,0 +1,98 @@
+require 'leaderboard'
+
+class CompetitionRankingLeaderboard < Leaderboard
+  # Retrieve the rank for a member in the named leaderboard.
+  #
+  # @param leaderboard_name [String] Name of the leaderboard.
+  # @param member [String] Member name.
+  #
+  # @return the rank for a member in the leaderboard.
+  def rank_for_in(leaderboard_name, member)
+    member_score = score_for_in(leaderboard_name, member)
+    if @reverse
+      return @redis_connection.zcount(leaderboard_name, '-inf', "(#{member_score}") + 1 rescue nil
+    else
+      return @redis_connection.zcount(leaderboard_name, "(#{member_score}", '+inf') + 1 rescue nil
+    end
+  end
+
+  # Retrieve the score and rank for a member in the named leaderboard.
+  #
+  # @param leaderboard_name [String]Name of the leaderboard.
+  # @param member [String] Member name.
+  #
+  # @return the score and rank for a member in the named leaderboard as a Hash.
+  def score_and_rank_for_in(leaderboard_name, member)
+    responses = @redis_connection.multi do |transaction|
+      transaction.zscore(leaderboard_name, member)
+      if @reverse
+        transaction.zrank(leaderboard_name, member)
+      else
+        transaction.zrevrank(leaderboard_name, member)
+      end
+    end
+
+    responses[0] = responses[0].to_f if responses[0]
+    responses[1] =
+      if @reverse
+        @redis_connection.zcount(leaderboard_name, '-inf', "(#{responses[0]}") + 1 rescue nil
+      else
+        @redis_connection.zcount(leaderboard_name, "(#{responses[0]}", '+inf') + 1 rescue nil
+      end
+
+    {@member_key => member, @score_key => responses[0], @rank_key => responses[1]}
+  end
+
+  # Retrieve a page of leaders from the named leaderboard for a given list of members.
+  #
+  # @param leaderboard_name [String] Name of the leaderboard.
+  # @param members [Array] Member names.
+  # @param options [Hash] Options to be used when retrieving the page from the named leaderboard.
+  #
+  # @return a page of leaders from the named leaderboard for a given list of members.
+  def ranked_in_list_in(leaderboard_name, members, options = {})
+    leaderboard_options = DEFAULT_LEADERBOARD_REQUEST_OPTIONS.dup
+    leaderboard_options.merge!(options)
+
+    ranks_for_members = []
+
+    responses = @redis_connection.multi do |transaction|
+      members.each do |member|
+        if @reverse
+          transaction.zrank(leaderboard_name, member)
+        else
+          transaction.zrevrank(leaderboard_name, member)
+        end
+        transaction.zscore(leaderboard_name, member)
+      end
+    end unless leaderboard_options[:members_only]
+
+    members.each_with_index do |member, index|
+      data = {}
+      data[@member_key] = member
+      unless leaderboard_options[:members_only]
+        data[@score_key] = responses[index * 2 + 1].to_f if responses[index * 2 + 1]
+        if @reverse
+          data[@rank_key] = @redis_connection.zcount(leaderboard_name, '-inf', "(#{data[@score_key]}") + 1 rescue nil
+        else
+          data[@rank_key] = @redis_connection.zcount(leaderboard_name, "(#{data[@score_key]}", '+inf') + 1 rescue nil
+        end
+      end
+
+      if leaderboard_options[:with_member_data]
+        data[@member_data_key] = member_data_for_in(leaderboard_name, member)
+      end
+
+      ranks_for_members << data
+    end
+
+    case leaderboard_options[:sort_by]
+    when :rank
+      ranks_for_members = ranks_for_members.sort_by { |member| member[@rank_key] }
+    when :score
+      ranks_for_members = ranks_for_members.sort_by { |member| member[@score_key] }
+    end
+
+    ranks_for_members
+  end
+end

data/lib/leaderboard.rb

@@ -966,7 +966,7 @@ class Leaderboard
     @redis_connection.zinterstore(destination, keys.insert(0, @leaderboard_name), options)
   end
 
-  private
+  protected
 
   # Key for retrieving optional member data.
   #

data/lib/leaderboard/version.rb

@@ -1,3 +1,3 @@
 class Leaderboard
-  VERSION = '3.6.0'.freeze
+  VERSION = '3.7.0'.freeze
 end

data/lib/tie_ranking_leaderboard.rb

@@ -0,0 +1,253 @@
+require 'leaderboard'
+
+class TieRankingLeaderboard < Leaderboard
+  # Default options when creating a leaderboard. Page size is 25 and reverse
+  # is set to false, meaning various methods will return results in
+  # highest-to-lowest order.
+  DEFAULT_OPTIONS = {
+    :page_size => DEFAULT_PAGE_SIZE,
+    :reverse => false,
+    :member_key => :member,
+    :rank_key => :rank,
+    :score_key => :score,
+    :member_data_key => :member_data,
+    :member_data_namespace => 'member_data',
+    :ties_namespace => 'ties'
+  }
+
+  # Create a new instance of a leaderboard.
+  #
+  # @param leaderboard [String] Name of the leaderboard.
+  # @param options [Hash] Options for the leaderboard such as +:page_size+.
+  # @param redis_options [Hash] Options for configuring Redis.
+  #
+  # Examples
+  #
+  #   leaderboard = Leaderboard.new('highscores')
+  #   leaderboard = Leaderboard.new('highscores', {:page_size => 10})
+  def initialize(leaderboard_name, options = DEFAULT_OPTIONS, redis_options = DEFAULT_REDIS_OPTIONS)
+    super
+
+    leaderboard_options = DEFAULT_OPTIONS.dup
+    leaderboard_options.merge!(options)
+
+    @ties_namespace = leaderboard_options[:ties_namespace]
+  end
+
+  # Delete the named leaderboard.
+  #
+  # @param leaderboard_name [String] Name of the leaderboard.
+  def delete_leaderboard_named(leaderboard_name)
+    @redis_connection.multi do |transaction|
+      transaction.del(leaderboard_name)
+      transaction.del(member_data_key(leaderboard_name))
+      transaction.del(ties_leaderboard_key(leaderboard_name))
+    end
+  end
+
+  # Rank a member in the named leaderboard.
+  #
+  # @param leaderboard_name [String] Name of the leaderboard.
+  # @param member [String] Member name.
+  # @param score [float] Member score.
+  # @param member_data [String] Optional member data.
+  def rank_member_in(leaderboard_name, member, score, member_data = nil)
+    @redis_connection.multi do |transaction|
+      transaction.zadd(leaderboard_name, score, member)
+      transaction.zadd(ties_leaderboard_key(leaderboard_name), score, score.to_f.to_s)
+      transaction.hset(member_data_key(leaderboard_name), member, member_data) if member_data
+    end
+  end
+
+  # Rank a member across multiple leaderboards.
+  #
+  # @param leaderboards [Array] Leaderboard names.
+  # @param member [String] Member name.
+  # @param score [float] Member score.
+  # @param member_data [String] Optional member data.
+  def rank_member_across(leaderboards, member, score, member_data = nil)
+    @redis_connection.multi do |transaction|
+      leaderboards.each do |leaderboard_name|
+        transaction.zadd(leaderboard_name, score, member)
+        transaction.zadd(ties_leaderboard_key(leaderboard_name), score, score.to_f.to_s)
+        transaction.hset(member_data_key(leaderboard_name), member, member_data) if member_data
+      end
+    end
+  end
+
+  # Rank an array of members in the named leaderboard.
+  #
+  # @param leaderboard_name [String] Name of the leaderboard.
+  # @param members_and_scores [Splat or Array] Variable list of members and scores
+  def rank_members_in(leaderboard_name, *members_and_scores)
+    if members_and_scores.is_a?(Array)
+      members_and_scores.flatten!
+    end
+
+    @redis_connection.multi do |transaction|
+      members_and_scores.each_slice(2) do |member_and_score|
+        transaction.zadd(leaderboard_name, member_and_score[1], member_and_score[0])
+        transaction.zadd(ties_leaderboard_key(leaderboard_name), member_and_score[0], member_and_score[0].to_f.to_s)
+      end
+    end
+  end
+
+  # Remove a member from the named leaderboard.
+  #
+  # @param leaderboard_name [String] Name of the leaderboard.
+  # @param member [String] Member name.
+  def remove_member_from(leaderboard_name, member)
+    member_score = @redis_connection.zscore(leaderboard_name, member) || nil
+    can_delete_score = member_score && members_from_score_range_in(leaderboard_name, member_score, member_score).length == 1
+
+    @redis_connection.multi do |transaction|
+      transaction.zrem(leaderboard_name, member)
+      transaction.zrem(ties_leaderboard_key(leaderboard_name), member_score.to_f.to_s) if can_delete_score
+      transaction.hdel(member_data_key(leaderboard_name), member)
+    end
+  end
+
+  # Retrieve the rank for a member in the named leaderboard.
+  #
+  # @param leaderboard_name [String] Name of the leaderboard.
+  # @param member [String] Member name.
+  #
+  # @return the rank for a member in the leaderboard.
+  def rank_for_in(leaderboard_name, member)
+    member_score = score_for_in(leaderboard_name, member)
+    if @reverse
+      return @redis_connection.zrank(ties_leaderboard_key(leaderboard_name), member_score.to_f.to_s) + 1 rescue nil
+    else
+      return @redis_connection.zrevrank(ties_leaderboard_key(leaderboard_name), member_score.to_f.to_s) + 1 rescue nil
+    end
+  end
+
+  # Retrieve the score and rank for a member in the named leaderboard.
+  #
+  # @param leaderboard_name [String]Name of the leaderboard.
+  # @param member [String] Member name.
+  #
+  # @return the score and rank for a member in the named leaderboard as a Hash.
+  def score_and_rank_for_in(leaderboard_name, member)
+    member_score = @redis_connection.zscore(leaderboard_name, member)
+
+    responses = @redis_connection.multi do |transaction|
+      transaction.zscore(leaderboard_name, member)
+      if @reverse
+        transaction.zrank(ties_leaderboard_key(leaderboard_name), member_score.to_f.to_s)
+      else
+        transaction.zrevrank(ties_leaderboard_key(leaderboard_name), member_score.to_f.to_s)
+      end
+    end
+
+    responses[0] = responses[0].to_f if responses[0]
+    responses[1] = responses[1] + 1 rescue nil
+
+    {@member_key => member, @score_key => responses[0], @rank_key => responses[1]}
+  end
+
+  # Remove members from the named leaderboard in a given score range.
+  #
+  # @param leaderboard_name [String] Name of the leaderboard.
+  # @param min_score [float] Minimum score.
+  # @param max_score [float] Maximum score.
+  def remove_members_in_score_range_in(leaderboard_name, min_score, max_score)
+    @redis_connection.multi do |transaction|
+      transaction.zremrangebyscore(leaderboard_name, min_score, max_score)
+      transaction.zremrangebyscore(ties_leaderboard_key(leaderboard_name), min_score, max_score)
+    end
+  end
+
+  # Expire the given leaderboard in a set number of seconds. Do not use this with
+  # leaderboards that utilize member data as there is no facility to cascade the
+  # expiration out to the keys for the member data.
+  #
+  # @param leaderboard_name [String] Name of the leaderboard.
+  # @param seconds [int] Number of seconds after which the leaderboard will be expired.
+  def expire_leaderboard_for(leaderboard_name, seconds)
+    @redis_connection.multi do |transaction|
+      transaction.expire(leaderboard_name, seconds)
+      transaction.expire(ties_leaderboard_key(leaderboard_name), seconds)
+      transaction.expire(member_data_key(leaderboard_name), seconds)
+    end
+  end
+
+  # Expire the given leaderboard at a specific UNIX timestamp. Do not use this with
+  # leaderboards that utilize member data as there is no facility to cascade the
+  # expiration out to the keys for the member data.
+  #
+  # @param leaderboard_name [String] Name of the leaderboard.
+  # @param timestamp [int] UNIX timestamp at which the leaderboard will be expired.
+  def expire_leaderboard_at_for(leaderboard_name, timestamp)
+    @redis_connection.multi do |transaction|
+      transaction.expireat(leaderboard_name, timestamp)
+      transaction.expireat(ties_leaderboard_key(leaderboard_name), timestamp)
+      transaction.expireat(member_data_key(leaderboard_name), timestamp)
+    end
+  end
+
+  # Retrieve a page of leaders from the named leaderboard for a given list of members.
+  #
+  # @param leaderboard_name [String] Name of the leaderboard.
+  # @param members [Array] Member names.
+  # @param options [Hash] Options to be used when retrieving the page from the named leaderboard.
+  #
+  # @return a page of leaders from the named leaderboard for a given list of members.
+  def ranked_in_list_in(leaderboard_name, members, options = {})
+    leaderboard_options = DEFAULT_LEADERBOARD_REQUEST_OPTIONS.dup
+    leaderboard_options.merge!(options)
+
+    ranks_for_members = []
+
+    responses = @redis_connection.multi do |transaction|
+      members.each do |member|
+        if @reverse
+          transaction.zrank(leaderboard_name, member)
+        else
+          transaction.zrevrank(leaderboard_name, member)
+        end
+        transaction.zscore(leaderboard_name, member)
+      end
+    end unless leaderboard_options[:members_only]
+
+    members.each_with_index do |member, index|
+      data = {}
+      data[@member_key] = member
+      unless leaderboard_options[:members_only]
+        data[@score_key] = responses[index * 2 + 1].to_f if responses[index * 2 + 1]
+
+        if @reverse
+          data[@rank_key] = @redis_connection.zrank(ties_leaderboard_key(leaderboard_name), data[@score_key].to_s) + 1 rescue nil
+        else
+          data[@rank_key] = @redis_connection.zrevrank(ties_leaderboard_key(leaderboard_name), data[@score_key].to_s) + 1 rescue nil
+        end
+      end
+
+      if leaderboard_options[:with_member_data]
+        data[@member_data_key] = member_data_for_in(leaderboard_name, member)
+      end
+
+      ranks_for_members << data
+    end
+
+    case leaderboard_options[:sort_by]
+    when :rank
+      ranks_for_members = ranks_for_members.sort_by { |member| member[@rank_key] }
+    when :score
+      ranks_for_members = ranks_for_members.sort_by { |member| member[@score_key] }
+    end
+
+    ranks_for_members
+  end
+
+  protected
+
+  # Key for ties leaderboard.
+  #
+  # @param leaderboard_name [String] Name of the leaderboard.
+  #
+  # @return a key in the form of +leaderboard_name:ties_namespace+
+  def ties_leaderboard_key(leaderboard_name)
+    "#{leaderboard_name}:#{@ties_namespace}"
+  end
+end