leaderboard 3.0.0.rc2 → 3.0.0

data/CHANGELOG.markdown

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## leaderboard 3.0.0 (2012-12-03)
+
+* Added `rank_member_if` and `rank_member_if_in` methods that allow you to rank a member in the leaderboard based on execution of a lambda. 
+
 ## leaderboard 3.0.0.rc2 (2012-11-27)
 
 * No longer cast scores to a floating point automatically. If requesting a score for an unknown member in the leaderboard, return `nil`. Under the old behavior, a `nil` score gets returned as 0.0. This is misleading as 0.0 is a valid score.

data/README.markdown

@@ -119,7 +119,7 @@ Get some information about your leaderboard:
    => 1
 ```
 
-The `rank_member` call will also accept an optional string member data that could 
+The `rank_member` call will also accept an optional parameter, `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. You could use JSON to 
@@ -236,6 +236,36 @@ friends = highscore_lb.ranked_in_list(['member_6', 'member_1', 'member_10'], :so
  => [{:member=>"member_1", :rank=>56, :score=>1.0}, {:member=>"member_6", :rank=>51, :score=>6.0}, {:member=>"member_10", :rank=>47, :score=>10.0}] 
 ```
 
+### Conditionally rank a member in the leaderboard
+
+You can pass a lambda to the `rank_member_if` method to conditionally rank a member in the leaderboard. The lambda is passed the following 5 parameters:
+
+* `member`: Member name.
+* `current_score`: Current score for the member in the leaderboard. May be `nil` if the member is not currently ranked in the leaderboard.
+* `score`: Member score.
+* `member_data`: Optional member data.
+* `leaderboard_options`: Leaderboard options, e.g. :reverse => Value of reverse option
+
+```ruby
+highscore_check = lambda do |member, current_score, score, member_data, leaderboard_options|
+  return true if current_score.nil?
+  return true if score > current_score
+  false
+end
+
+highscore_lb.rank_member_if(highscore_check, 'david', 1337)
+highscore_lb.score_for('david')
+ => 1337.0
+highscore_lb.rank_member_if(highscore_check, 'david', 1336)
+highscore_lb.score_for('david')
+ => 1337.0
+highscore_lb.rank_member_if(highscore_check, 'david', 1338)
+highscore_lb.score_for('david')
+ => 1338.0
+```
+
+NOTE: Use a lambda and not a proc, otherwise you will get a `LocalJumpError` as a return statement in the proc will return from the method enclosing the proc.
+
 ### Ranking multiple members in a leaderboard at once
 
 Insert multiple data items for members and their associated scores:
@@ -280,7 +310,7 @@ Use this method to do bulk insert of data, but be mindful of the amount of data
   intersect_leaderboards(destination, keys, options = {:aggregate => :min}): Intersect leaderboards given by keys with this leaderboard into destination
 ```
 
-Check the [online documentation](http://rubydoc.info/github/agoragames/leaderboard/master/frames) for more detail on each method.
+Check the [online documentation](http://rubydoc.info/gems/leaderboard/frames) for more detail on each method.
 
 ## Performance Metrics
 

data/lib/leaderboard.rb

@@ -127,6 +127,46 @@ class Leaderboard
     end
   end
 
+  # Rank a member in the leaderboard based on execution of the +rank_conditional+. 
+  #
+  # The +rank_conditional+ is passed the following parameters:
+  #   member: Member name.
+  #   current_score: Current score for the member in the leaderboard.
+  #   score: Member score.
+  #   member_data: Optional member data.
+  #   leaderboard_options: Leaderboard options, e.g. :reverse => Value of reverse option
+  #
+  # @param rank_conditional [lambda] Lambda which must return +true+ or +false+ that controls whether or not the member is ranked in the leaderboard.
+  # @param member [String] Member name.
+  # @param score [String] Member score.
+  # @param member_data [Hash] Optional member_data.
+  def rank_member_if(rank_conditional, member, score, member_data = nil)
+    rank_member_if_in(@leaderboard_name, rank_conditional, member, score, member_data)
+  end
+
+  # Rank a member in the named leaderboard based on execution of the +rank_conditional+. 
+  #
+  # The +rank_conditional+ is passed the following parameters:
+  #   member: Member name.
+  #   current_score: Current score for the member in the leaderboard.
+  #   score: Member score.
+  #   member_data: Optional member data.
+  #   leaderboard_options: Leaderboard options, e.g. :reverse => Value of reverse option
+  #
+  # @param leaderboard_name [String] Name of the leaderboard.
+  # @param rank_conditional [lambda] Lambda which must return +true+ or +false+ that controls whether or not the member is ranked in the leaderboard.
+  # @param member [String] Member name.
+  # @param score [String] Member score.
+  # @param member_data [Hash] Optional member_data.
+  def rank_member_if_in(leaderboard_name, rank_conditional, member, score, member_data = nil)
+    current_score = @redis_connection.zscore(leaderboard_name, member) 
+    current_score = current_score.to_f if current_score
+
+    if rank_conditional.call(member, current_score, score, member_data, {:reverse => @reverse})
+      rank_member_in(leaderboard_name, member, score, member_data)
+    end
+  end
+
   # Retrieve the optional member data for a given member in the leaderboard.
   #
   # @param member [String] Member name.

data/lib/leaderboard/version.rb

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

data/spec/leaderboard_spec.rb

@@ -642,4 +642,21 @@ describe 'Leaderboard' do
     ranked_members[0][:score].should be_nil
     ranked_members[0][:rank].should be_nil
   end
+
+  it 'should rank a member in the leaderboard with conditional execution' do
+    highscore_check = lambda do |member, current_score, score, member_data, leaderboard_options|
+      return true if current_score.nil?
+      return true if score > current_score
+      false
+    end
+
+    @leaderboard.total_members.should be(0)
+    @leaderboard.rank_member_if(highscore_check, 'david', 1337)
+    @leaderboard.total_members.should be(1)
+    @leaderboard.score_for('david').should eql(1337.0)
+    @leaderboard.rank_member_if(highscore_check, 'david', 1336)
+    @leaderboard.score_for('david').should eql(1337.0)
+    @leaderboard.rank_member_if(highscore_check, 'david', 1338)
+    @leaderboard.score_for('david').should eql(1338.0)
+  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 == '3.0.0.rc2'
+    Leaderboard::VERSION.should == '3.0.0'
   end
 end

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: leaderboard
 version: !ruby/object:Gem::Version
-  version: 3.0.0.rc2
-  prerelease: 6
+  version: 3.0.0
+  prerelease: 
 platform: ruby
 authors:
 - David Czarnecki
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-11-27 00:00:00.000000000 Z
+date: 2012-12-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -96,9 +96,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>'
+  - - ! '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: leaderboard
 rubygems_version: 1.8.24