leaderboard 2.0.6 → 2.1.0

data/.gitignore

@@ -8,3 +8,4 @@ pkg
 Gemfile.lock
 test/db/*
 *.rdb
+spec/db/*.pid

data/CHANGELOG.markdown

@@ -1,8 +1,13 @@
 # CHANGELOG
 
+## leaderboard 2.1.0 (2012-06-11)
+
+* Added ability to store optional member data alongside the leaderboard data.
+* `:with_member_data` is now a valid request option when retrieving leader data.
+
 ## leaderboard 2.0.6 (2012-04-26)
 
-* Added accessor for +reverse+ option so that you can set reverse after creating a leaderboard to see results in either highest-to-lowest or lowest-to-highest order.
+* Added accessor for `reverse` option so that you can set reverse after creating a leaderboard to see results in either highest-to-lowest or lowest-to-highest order.
 
 ## leaderboard 2.0.5 (2012-03-14)
 

data/README.markdown

@@ -19,10 +19,14 @@ 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.8.7, Ruby 1.9.2 and Ruby 1.9.3.
+
+The gem is compatible with Redis 2.4.x and Redis 2.6.x.
 	
 ## Usage
 
+### Creating a leaderboard
+
 Create a new leaderboard or attach to an existing leaderboard named 'highscores':
 
 ```ruby
@@ -39,6 +43,8 @@ If you need to pass in options for Redis, you can do this in the initializer:
    => #<Leaderboard:0x00000103095200 @leaderboard_name="highscores", @page_size=25, @redis_connection=#<Redis client v2.2.2 connected to redis://localhost:6379/1 (Redis v2.2.5)>> 
 ```
 
+### Defining leaderboard options
+
 The `Leaderboard::DEFAULT_OPTIONS` are as follows:
 
 ```ruby
@@ -64,6 +70,18 @@ You can pass in an existing connection to Redis using `:redis_connection` in the
    => #<Leaderboard:0x000001028791e8 @leaderboard_name="highscores", @page_size=25, @redis_connection=#<Redis client v2.2.2 connected to redis://127.0.0.1:6379/0 (Redis v2.2.5)>> 
 ```
  
+To use the same connection for multiple leaderboards, reset the options hash before instantiating more leaderboards:
+
+```ruby
+redis = Redis.new
+ => #<Redis client v2.2.2 connected to redis://127.0.0.1:6379/0 (Redis v2.2.5)> 
+redis_options = {:redis_connection => redis}
+ => {:redis_connection=>#<Redis client v2.2.2 connected to redis://127.0.0.1:6379/0 (Redis v2.2.5)>} 
+highscore_lb = Leaderboard.new('highscores', Leaderboard::DEFAULT_OPTIONS, redis_options)
+redis_options = {:redis_connection => redis}
+other_highscore_lb = Leaderboard.new('other_highscores', Leaderboard::DEFAULT_OPTIONS, redis_options)
+```
+
 You can set the page size to something other than the default page size (25):
 
 ```ruby
@@ -72,7 +90,9 @@ You can set the page size to something other than the default page size (25):
   highscore_lb
    => #<Leaderboard:0x000001028791e8 @leaderboard_name="highscores", @page_size=5, @redis_connection=#<Redis client v2.2.2 connected to redis://127.0.0.1:6379/0 (Redis v2.2.5)>> 
 ```
-  
+
+### Ranking members in the leaderboard
+
 Add members to your leaderboard using `rank_member`:
 
 ```ruby
@@ -92,6 +112,30 @@ Get some information about your leaderboard:
   highscore_lb.total_pages
    => 1 
 ```
+
+The `rank_member` call will also accept an optional hash of member data that could 
+be used to store other information about a given member in the leaderboard. This 
+may be useful in situations where you are storing member IDs in the leaderboard and 
+you want to be able to store a member name for display. Example:
+
+```ruby
+highscore_lb.rank_member('84849292', 1, {'username' => 'member_name'})
+```
+
+You can retrieve, update and remove the optional member data using the 
+`member_data_for`, `update_member_data` and `remove_member_data` calls. Example: 
+
+```ruby
+highscore_lb.member_data_for('84849292')
+ => {"username"=>"member_name"}
+
+highscore_lb.update_member_data('84849292', {'last_updated' => Time.now, 'username' => 'updated_member_name'})
+ => "OK" 
+highscore_lb.member_data_for('84849292')
+ => {"username"=>"updated_member_name", "last_updated"=>"2012-06-09 09:11:06 -0400"}
+
+highscore_lb.remove_member_data('84849292')
+```
   
 Get some information about a specific member(s) in the leaderboard:
 
@@ -103,7 +147,9 @@ Get some information about a specific member(s) in the leaderboard:
   highscore_lb.rank_for('member_10')
    => 1 
 ```
-  
+
+### Retrieving members from the leaderboard 
+
 Get page 1 in the leaderboard:
 
 ```ruby
@@ -111,8 +157,10 @@ Get page 1 in the leaderboard:
    => [{:member=>"member_10", :rank=>1, :score=>10.0}, {:member=>"member_9", :rank=>2, :score=>9.0}, {:member=>"member_8", :rank=>3, :score=>8.0}, {:member=>"member_7", :rank=>4, :score=>7.0}, {:member=>"member_6", :rank=>5, :score=>6.0}, {:member=>"member_5", :rank=>6, :score=>5.0}, {:member=>"member_4", :rank=>7, :score=>4.0}, {:member=>"member_3", :rank=>8, :score=>3.0}, {:member=>"member_2", :rank=>9, :score=>2.0}, {:member=>"member_1", :rank=>10, :score=>1.0}] 
 ```
 	
-You can pass various options to the calls `leaders`, `around_me` and `ranked_in_list`. Valid options are `:with_scores`, `:with_rank`, `:use_zero_index_for_rank` and `:page_size`.
-Below is an example of retrieving the first page in the leaderboard without ranks:
+You can pass various options to the calls `leaders`, `around_me` and `ranked_in_list`. 
+Valid options are `:with_scores`, `:with_rank`, `:with_member_data`, `:use_zero_index_for_rank` 
+and `:page_size`. Below is an example of retrieving the first page in the leaderboard 
+without ranks:
 
 ```ruby
   highscore_lb.leaders(1, :with_rank => false)
@@ -151,6 +199,8 @@ Get rank and score for an arbitrary list of members (e.g. friends) from the lead
    => [{:member=>"member_1", :rank=>56, :score=>1.0}, {:member=>"member_62", :rank=>34, :score=>62.0}, {:member=>"member_67", :rank=>29, :score=>67.0}]
 ```
 
+### Ranking multiple members in a leaderboard at once 
+
 Insert multiple data items for members and their associated scores:
 
 As a splat:
@@ -170,7 +220,10 @@ Use this method to do bulk insert of data, but be mindful of the amount of data
 ### Other useful methods
 
 ```
-  delete_leaderboard: Delete the current leaderboard  
+  delete_leaderboard: Delete the current leaderboard
+  member_data_for(member): Retrieve the optional member data for a given member in the leaderboard
+  update_member_data(member, member_data): Update the optional member data for a given member in the leaderboard
+  remove_member_data(member): Remove the optional member data for a given member in the leaderboard
   remove_member(member): Remove a member from the leaderboard
   total_members: Total # of members in the leaderboard
   total_pages: Total # of pages in the leaderboard given the leaderboard's page_size	
@@ -189,7 +242,7 @@ Use this method to do bulk insert of data, but be mindful of the amount of data
 ```
 
 Check the [online documentation](http://rubydoc.info/github/agoragames/leaderboard/master/frames) for more detail on each method.
-      
+
 ## Performance Metrics
 
 10 million sequential scores insert:
@@ -249,7 +302,7 @@ Average time to request an arbitrary page from the leaderboard:
    => 0.0014615999999999531 
 ```
 
-Bulk insert performance:
+### Bulk insert performance
 
 Ranking individual members:
 
@@ -278,10 +331,6 @@ end
  =>  22.390000   6.380000  28.770000 ( 31.144027)
 ```
 
-## Future Ideas
-
-* Ideas?
-
 ## Ports
 
 The following ports have been made of the leaderboard gem.

data/lib/leaderboard.rb

@@ -29,11 +29,13 @@ class Leaderboard
   # Default options when requesting data from a leaderboard.
   # +:with_scores+ true: Return scores along with the member names.
   # +:with_rank+ true: Return ranks along with the member names.
+  # +:with_member_data+ false: Return member data along with the member names.
   # +:use_zero_index_for_rank+ false: If you want to 0-index ranks.
   # +:page_size+ nil: The default page size will be used.
   DEFAULT_LEADERBOARD_REQUEST_OPTIONS = {
     :with_scores => true, 
     :with_rank => true, 
+    :with_member_data => false,
     :use_zero_index_for_rank => false,
     :page_size => nil
   }
@@ -108,8 +110,9 @@ class Leaderboard
   # 
   # @param member [String] Member name.
   # @param score [float] Member score.
-  def rank_member(member, score)
-    rank_member_in(@leaderboard_name, member, score)
+  # @param member_data [Hash] Optional member data.
+  def rank_member(member, score, member_data = nil)
+    rank_member_in(@leaderboard_name, member, score, member_data)
   end
 
   # Rank a member in the named leaderboard.
@@ -117,8 +120,65 @@ class Leaderboard
   # @param leaderboard_name [String] Name of the leaderboard.
   # @param member [String] Member name.
   # @param score [float] Member score.
-  def rank_member_in(leaderboard_name, member, score)
-    @redis_connection.zadd(leaderboard_name, score, member)
+  # @param member_data [Hash] Optional member data.
+  def rank_member_in(leaderboard_name, member, score, member_data)
+    @redis_connection.multi do |transaction|
+      transaction.zadd(leaderboard_name, score, member)
+      if member_data
+        transaction.hmset(member_data_key(leaderboard_name, member), *member_data.to_a.flatten)
+      end
+    end
+  end
+
+  # Retrieve the optional member data for a given member in the leaderboard.
+  #
+  # @param member [String] Member name.
+  #
+  # @return Hash of optional member data.
+  def member_data_for(member)
+    member_data_for_in(@leaderboard_name, member)
+  end
+
+  # Retrieve the optional member data for a given member in the named leaderboard.
+  #
+  # @param leaderboard_name [String] Name of the leaderboard.
+  # @param member [String] Member name.
+  #
+  # @return Hash of optional member data.
+  def member_data_for_in(leaderboard_name, member)
+    @redis_connection.hgetall(member_data_key(leaderboard_name, member))
+  end
+
+  # Update the optional member data for a given member in the leaderboard.
+  # 
+  # @param member [String] Member name.
+  # @param member_data [Hash] Optional member data.
+  def update_member_data(member, member_data)
+    update_member_data_in(@leaderboard_name, member, member_data)
+  end
+
+  # Update the optional member data for a given member in the named leaderboard.
+  #
+  # @param leaderboard_name [String] Name of the leaderboard.
+  # @param member [String] Member name.
+  # @param member_data [Hash] Optional member data.
+  def update_member_data_in(leaderboard_name, member, member_data)
+    @redis_connection.hmset(member_data_key(leaderboard_name, member), *member_data.to_a.flatten)
+  end
+
+  # Remove the optional member data for a given member in the leaderboard.
+  #
+  # @param member [String] Member name.
+  def remove_member_data(member)
+    remove_member_data_in(@leaderboard_name, member)
+  end
+
+  # Remove the optional member data for a given member in the named leaderboard.
+  #
+  # @param leaderboard_name [String] Name of the leaderboard.
+  # @param member [String] Member name.
+  def remove_member_data_in(leaderboard_name, member)
+    @redis_connection.del(member_data_key(leaderboard_name, member))
   end
 
   # Rank an array of members in the leaderboard.
@@ -156,7 +216,10 @@ class Leaderboard
   # @param leaderboard_name [String] Name of the leaderboard.
   # @param member [String] Member name.
   def remove_member_from(leaderboard_name, member)
-    @redis_connection.zrem(leaderboard_name, member)
+    @redis_connection.multi do |transaction|
+      transaction.zrem(leaderboard_name, member)
+      transaction.del(member_data_key(leaderboard_name, member))
+    end
   end
   
   # Retrieve the total number of members in the leaderboard.
@@ -574,6 +637,10 @@ class Leaderboard
           end
         end
       end
+
+      if leaderboard_options[:with_member_data]
+        data[:member_data] = member_data_for_in(leaderboard_name, member)
+      end
       
       ranks_for_members << data
     end
@@ -601,6 +668,16 @@ class Leaderboard
   
   private 
   
+  # Key for retrieving optional member data.
+  #
+  # @param leaderboard_name [String] Name of the leaderboard.
+  # @param member [String] Member name.
+  # 
+  # @return a key in the form of +leaderboard_name:data:member+
+  def member_data_key(leaderboard_name, member)
+    "#{leaderboard_name}:member_data:#{member}" 
+  end
+
   # Validate and return the page size. Returns the +DEFAULT_PAGE_SIZE+ if the page size is less than 1.
   #
   # @param page_size [int] Page size.

data/lib/leaderboard/version.rb

@@ -1,4 +1,4 @@
 class Leaderboard
   # Leaderboard version
-  VERSION = '2.0.6'.freeze
+  VERSION = '2.1.0'.freeze
 end

data/spec/leaderboard_spec.rb

@@ -139,6 +139,42 @@ describe 'Leaderboard' do
     leaders[24].should == member_1
   end
 
+  it 'should allow you to retrieve leaders with extra data' do
+    rank_members_in_leaderboard(Leaderboard::DEFAULT_PAGE_SIZE)
+    
+    @leaderboard.total_members.should be(Leaderboard::DEFAULT_PAGE_SIZE)
+    leaders = @leaderboard.leaders(1, {:with_scores => false, :with_rank => false, :with_member_data => true})
+
+    member_25 = {:member => 'member_25', :member_data => { "member_name" => "Leaderboard member 25" }}
+    leaders[0].should == member_25
+    
+    member_1 = {:member => 'member_1', :member_data => { "member_name" => "Leaderboard member 1" }}
+    leaders[24].should == member_1
+  end
+
+  it 'should allow you to retrieve optional member data' do
+    @leaderboard.rank_member('member_id', 1, {'username' => 'member_name', 'other_data_key' => 'other_data_value'})
+
+    @leaderboard.member_data_for('unknown_member').should == {}
+    @leaderboard.member_data_for('member_id').should == {'username' => 'member_name', 'other_data_key' => 'other_data_value'}
+  end
+
+  it 'should allow you to update optional member data' do
+    @leaderboard.rank_member('member_id', 1, {'username' => 'member_name'})
+
+    @leaderboard.member_data_for('member_id').should == {'username' => 'member_name'}
+    @leaderboard.update_member_data('member_id', {'other_data_key' => 'other_data_value'})
+    @leaderboard.member_data_for('member_id').should == {'username' => 'member_name', 'other_data_key' => 'other_data_value'}
+  end
+
+  it 'should allow you to remove optional member data' do
+    @leaderboard.rank_member('member_id', 1, {'username' => 'member_name'})
+
+    @leaderboard.member_data_for('member_id').should == {'username' => 'member_name'}
+    @leaderboard.remove_member_data('member_id')
+    @leaderboard.member_data_for('member_id').should == {}
+  end
+
   it 'should allow you to call leaders with various options that respect the defaults for the options not passed in' do
     rank_members_in_leaderboard(Leaderboard::DEFAULT_PAGE_SIZE + 1)
 

data/spec/spec_helper.rb

@@ -9,7 +9,7 @@ RSpec.configure do |config|
   # @param members_to_add [int] Number of members to add to the leaderboard.
   def rank_members_in_leaderboard(members_to_add = 5)
     1.upto(members_to_add) do |index|
-      @leaderboard.rank_member("member_#{index}", index)
+      @leaderboard.rank_member("member_#{index}", index, { :member_name => "Leaderboard member #{index}" })
     end
   end
 end

data/spec/version_spec.rb

@@ -2,6 +2,6 @@ require 'spec_helper'
 
 describe 'Leaderboard::VERSION' do
   it 'should be the correct version' do
-    Leaderboard::VERSION.should == '2.0.6'
+    Leaderboard::VERSION.should == '2.1.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: leaderboard
 version: !ruby/object:Gem::Version
-  version: 2.0.6
+  version: 2.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-27 00:00:00.000000000 Z
+date: 2012-06-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
-  requirement: &70173076945220 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,15 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70173076945220
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70173076944740 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +37,15 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70173076944740
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70173076944140 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,7 +53,12 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70173076944140
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Leaderboards backed by Redis in Ruby
 email:
 - dczarnecki@agoragames.com
@@ -82,7 +97,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -4420304645092000909
+      hash: 248515504144092266
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -91,10 +106,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -4420304645092000909
+      hash: 248515504144092266
 requirements: []
 rubyforge_project: leaderboard
-rubygems_version: 1.8.10
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
 summary: Leaderboards backed by Redis in Ruby