leaderboard 2.0.1 → 2.0.2

data/.gitignore

@@ -0,0 +1,8 @@
+coverage
+rdoc
+doc
+.yardoc
+.bundle
+pkg
+Gemfile.lock
+test/db/*

data/.rvmrc

@@ -1,2 +1,3 @@
 rvm --create 1.8.7@leaderboard_gem
 rvm --create 1.9.2@leaderboard_gem
+rvm --create 1.9.3@leaderboard_gem

data/CHANGELOG.markdown

@@ -1,9 +1,16 @@
-# leaderboard 2.0.1 (2011-11-07)
+# CHANGELOG
+
+## leaderboard 2.0.2 (2012-02-03)
+
+ * Fix for checking to see if a member actually exists in the leaderboard for the `around_me` calls
+ * Return appropriate `nil` in data returned for calls such as `percentile_for` and `ranked_in_list` for non-existent members
+
+## leaderboard 2.0.1 (2011-11-07)
 
  * Allow for only single options to be passed to `leaders`, `around_me` and `ranked_in_list` methods - https://github.com/agoragames/leaderboard/issues/4
  * Added `percentile_for(member)` and `percentile_for_in(leaderboard_name, member)` methods to calculate percentile for a given member
  
-# leaderboard 2.0.0 (2011-08-05)
+## leaderboard 2.0.0 (2011-08-05)
  
  * Change `add_member` to `rank_member` - https://github.com/agoragames/leaderboard/issues/3
  * Added `delete_leaderboard` and `delete_leaderboard_named` - https://github.com/agoragames/leaderboard/issues/2
@@ -12,33 +19,33 @@
  * Updated initializer to take a leaderboard name, `options` hash and `redis_options` hash
  * Simplified `leaders`, `around_me` and `ranked_in_list` to use an `options` hash with defaults for the previously individual parameters
  
-# leaderboard 1.0.6 (unreleased)
+## leaderboard 1.0.6 (unreleased)
 
  * Added `disconnect` method
  * Check for invalid page size when changing
 
-# leaderboard 1.0.5 (2011-05-04)
+## leaderboard 1.0.5 (2011-05-04)
 
  * Updated Rakefile to run tests under ruby 1.8.7 and ruby 1.9.2
  * Added `page_size` parameter to `total_pages_in` to allow for checking what if values in that scenario
  * Added `page_size` parameter to `leaders` and `around_me` calls
 
-# leaderboard 1.0.4 (2011-04-26)
+## leaderboard 1.0.4 (2011-04-26)
 
  * Minor bug fix
 
-# leaderboard 1.0.3 (2011-04-26)
+## leaderboard 1.0.3 (2011-04-26)
 
  * Fixing issue using total_pages in leaderboard_in call
  * Internal `massage_leader_data` method will now respect `with_scores`
  
-# leaderboard 1.0.2 (2011-02-25)
+## leaderboard 1.0.2 (2011-02-25)
 
  * Adding `XXX_to`, `XXX_for`, `XXX_in` and `XXX_from` methods that will allow you to set the leaderboard name to interact with outside of creating a new object
  * Added `merge_leaderboards(destination, keys, options = {:aggregate => :min})` method to merge leaderboards given by keys with this leaderboard into destination
  * Added `intersect_leaderboards(destination, keys, options = {:aggregate => :min})` method to intersect leaderboards given by keys with this leaderboard into destination
 
-# leaderboard 1.0.1 (2011-02-16)
+## leaderboard 1.0.1 (2011-02-16)
 
  * `redis_options` can be passed in the initializer to pass options for the connection to Redis
  * `page_size` is now settable outside of the initializer
@@ -46,6 +53,6 @@
  * `score_and_rank_for(member, use_zero_index_for_rank = false)`: Retrieve the score and rank for a member in a single call
  * `remove_members_in_score_range(min_score, max_score)`: Remove members from the leaderboard within a score range
 
-# leaderboard 1.0.0
+## leaderboard 1.0.0
 
  * Initial release

data/Gemfile

@@ -1,13 +1,3 @@
 source "http://rubygems.org"
 
-# Add dependencies to develop your gem here.
-# Include everything needed to run rake, tests, features, etc.
-group :development do
-  gem "bundler"
-  gem "jeweler"
-  gem "rcov"
-  gem "rdoc"
-end
-
-gem 'redis'
-
+gemspec

data/{README.rdoc → README.markdown}

@@ -1,114 +1,143 @@
-= leaderboard
+# leaderboard
 
 Leaderboards backed by Redis in Ruby, http://redis.io.
 
 Builds off ideas proposed in http://blog.agoragames.com/2011/01/01/creating-high-score-tables-leaderboards-using-redis/.
 
-== Installation
+## Installation
 
 Install the gem:
 
-  gem "leaderboard", "~> 2.0.1"
-	
+```ruby
+gem "leaderboard"
+```
+
 Make sure your redis server is running! Redis configuration is outside the scope of this README, but 
 check out the Redis documentation, http://redis.io/documentation.
 
-== Compatibility
+## Compatibility
 
-The gem has been built and tested under Ruby 1.8.7 and Ruby 1.9.2
+The gem has been built and tested under Ruby 1.8.7, Ruby 1.9.2 and Ruby 1.9.3
 	
-== Usage
+## Usage
 
 Create a new leaderboard or attach to an existing leaderboard named 'highscores':
 
+```ruby
   ruby-1.9.2-p180 :002 > highscore_lb = Leaderboard.new('highscores')
    => #<Leaderboard:0x0000010307b530 @leaderboard_name="highscores", @page_size=25, @redis_connection=#<Redis client v2.2.2 connected to redis://localhost:6379/0 (Redis v2.2.5)>>
+```
     
 If you need to pass in options for Redis, you can do this in the initializer:
 
+```ruby
   ruby-1.9.2-p180 :007 > redis_options = {:host => 'localhost', :port => 6379, :db => 1}
    => {:host=>"localhost", :port=>6379, :db=>1} 
   ruby-1.9.2-p180 :008 > highscore_lb = Leaderboard.new('highscores', Leaderboard::DEFAULT_OPTIONS, redis_options)
    => #<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)>> 
+```
 
 You can pass in an existing connection to Redis using :redis_connection in the Redis options hash:
 
+```ruby
   ruby-1.9.2-p180 :009 > redis = Redis.new
    => #<Redis client v2.2.2 connected to redis://127.0.0.1:6379/0 (Redis v2.2.5)> 
   ruby-1.9.2-p180 :010 > 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)>} 
   ruby-1.9.2-p180 :011 > highscore_lb = Leaderboard.new('highscores', Leaderboard::DEFAULT_OPTIONS, redis_options)
    => #<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)>> 
+```
  
 You can set the page size to something other than the default page size (25):
 
+```ruby
   ruby-1.9.2-p180 :012 > highscore_lb.page_size = 5
    => 5 
   ruby-1.9.2-p180 :013 > 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)>> 
+```
   
 Add members to your leaderboard using rank_member:
 
+```ruby
   ruby-1.9.2-p180 :014 > 1.upto(10) do |index|
   ruby-1.9.2-p180 :015 >     highscore_lb.rank_member("member_#{index}", index)
   ruby-1.9.2-p180 :016?>   end
    => 1 
+```
 
 You can call rank_member with the same member and the leaderboard will be updated automatically.
 
 Get some information about your leaderboard:
 
+```ruby
   ruby-1.9.2-p180 :020 > highscore_lb.total_members
    => 10 
   ruby-1.9.2-p180 :021 > highscore_lb.total_pages
    => 1 
+```
   
 Get some information about a specific member(s) in the leaderboard:
 
+```ruby
   ruby-1.9.2-p180 :022 > highscore_lb.score_for('member_4')
    => 4.0 
   ruby-1.9.2-p180 :023 > highscore_lb.rank_for('member_4')
    => 7 
   ruby-1.9.2-p180 :024 > highscore_lb.rank_for('member_10')
    => 1 
+```
   
 Get page 1 in the leaderboard:
 
+```ruby
   ruby-1.9.2-p180 :025 > highscore_lb.leaders(1)
    => [{: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:
 
+```ruby
   ruby-1.9.2-p180 :026 > highscore_lb.leaders(1, :with_rank => false)
    => [{:member=>"member_10", :score=>9.0}, {:member=>"member_9", :score=>7.0}, {:member=>"member_8", :score=>5.0}, {:member=>"member_7", :score=>3.0}, {:member=>"member_6", :score=>1.0}, {:member=>"member_5", :score=>0.0}, {:member=>"member_4", :score=>0.0}, {:member=>"member_3", :score=>0.0}, {:member=>"member_2", :score=>0.0}, {:member=>"member_1", :score=>0.0}] 
+```
 
 Below is an example of retrieving the first page in the leaderboard without scores or ranks:
 
+```ruby
   ruby-1.9.2-p180 :028 > highscore_lb.leaders(1, :with_scores => false, :with_rank => false)
    => [{:member=>"member_10"}, {:member=>"member_9"}, {:member=>"member_8"}, {:member=>"member_7"}, {:member=>"member_6"}, {:member=>"member_5"}, {:member=>"member_4"}, {:member=>"member_3"}, {:member=>"member_2"}, {:member=>"member_1"}] 
+```
 
 Add more members to your leaderboard:
 
+```ruby
   ruby-1.9.2-p180 :029 > 50.upto(95) do |index|
   ruby-1.9.2-p180 :030 >     highscore_lb.rank_member("member_#{index}", index)
   ruby-1.9.2-p180 :031?>   end
    => 50 
   ruby-1.9.2-p180 :032 > highscore_lb.total_pages
    => 3 
+```
   
 Get an "Around Me" leaderboard for a member:
 
+```ruby
   ruby-1.9.2-p180 :033 > highscore_lb.around_me('member_53')
    => [{:member=>"member_65", :rank=>31, :score=>65.0}, {:member=>"member_64", :rank=>32, :score=>64.0}, {:member=>"member_63", :rank=>33, :score=>63.0}, {:member=>"member_62", :rank=>34, :score=>62.0}, {:member=>"member_61", :rank=>35, :score=>61.0}, {:member=>"member_60", :rank=>36, :score=>60.0}, {:member=>"member_59", :rank=>37, :score=>59.0}, {:member=>"member_58", :rank=>38, :score=>58.0}, {:member=>"member_57", :rank=>39, :score=>57.0}, {:member=>"member_56", :rank=>40, :score=>56.0}, {:member=>"member_55", :rank=>41, :score=>55.0}, {:member=>"member_54", :rank=>42, :score=>54.0}, {:member=>"member_53", :rank=>43, :score=>53.0}, {:member=>"member_52", :rank=>44, :score=>52.0}, {:member=>"member_51", :rank=>45, :score=>51.0}, {:member=>"member_50", :rank=>46, :score=>50.0}, {:member=>"member_10", :rank=>47, :score=>10.0}, {:member=>"member_9", :rank=>48, :score=>9.0}, {:member=>"member_8", :rank=>49, :score=>8.0}, {:member=>"member_7", :rank=>50, :score=>7.0}, {:member=>"member_6", :rank=>51, :score=>6.0}, {:member=>"member_5", :rank=>52, :score=>5.0}, {:member=>"member_4", :rank=>53, :score=>4.0}, {:member=>"member_3", :rank=>54, :score=>3.0}, {:member=>"member_2", :rank=>55, :score=>2.0}] 
+```
 	
 Get rank and score for an arbitrary list of members (e.g. friends):
 
+```ruby
   ruby-1.9.2-p180 :034 > highscore_lb.ranked_in_list(['member_1', 'member_62', 'member_67'])
    => [{:member=>"member_1", :rank=>56, :score=>1.0}, {:member=>"member_62", :rank=>34, :score=>62.0}, {:member=>"member_67", :rank=>29, :score=>67.0}]
-   
-=== Other useful methods
+```   
+
+### Other useful methods
 
+```
   delete_leaderboard: Delete the current leaderboard  
   remove_member(member): Remove a member from the leaderboard
   total_members: Total # of members in the leaderboard
@@ -123,13 +152,15 @@ Get rank and score for an arbitrary list of members (e.g. friends):
   percentile_for(member): Calculate the percentile for a given member
   merge_leaderboards(destination, keys, options = {:aggregate => :min}): Merge leaderboards given by keys with this leaderboard into destination
   intersect_leaderboards(destination, keys, options = {:aggregate => :min}): Intersect leaderboards given by keys with this leaderboard into destination
+```
 
-Check the online documentation for more detail, http://rubydoc.info/gems/leaderboard/
+Check the [online documentation](http://rubydoc.info/github/agoragames/leaderboard/master/frames) for more detail on each method.
       
-== Performance Metrics
+## Performance Metrics
 
 10 million sequential scores insert:
 
+```ruby
   ruby-1.9.2-p180 :003 > highscore_lb = Leaderboard.new('highscores')
    => #<Leaderboard:0x0000010205fc50 @leaderboard_name="highscores", @page_size=25, @redis_connection=#<Redis client v2.2.2 connected to redis://localhost:6379/0 (Redis v2.2.5)>> 
   ruby-1.9.2-p180 :004 > insert_time = Benchmark.measure do
@@ -138,9 +169,11 @@ Check the online documentation for more detail, http://rubydoc.info/gems/leaderb
   ruby-1.9.2-p180 :007?>     end
   ruby-1.9.2-p180 :008?>   end
    => 323.070000 148.560000 471.630000 (942.068307)
+```
   
 Average time to request an arbitrary page from the leaderboard:
 
+```ruby
   ruby-1.9.2-p180 :009 > requests_to_make = 50000
    => 50000 
   ruby-1.9.2-p180 :010 > lb_request_time = 0
@@ -154,18 +187,22 @@ Average time to request an arbitrary page from the leaderboard:
   ruby-1.9.2-p180 :016 > p lb_request_time / requests_to_make
   0.001513999999999998
    => 0.001513999999999998 
+```
      
 10 million random scores insert:
 
+```ruby
   ruby-1.9.2-p180 :018 > insert_time = Benchmark.measure do
   ruby-1.9.2-p180 :019 >     1.upto(10000000) do |index|
   ruby-1.9.2-p180 :020 >       highscore_lb.rank_member("member_#{index}", rand(50000000))
   ruby-1.9.2-p180 :021?>     end
   ruby-1.9.2-p180 :022?>   end
    => 338.480000 155.200000 493.680000 (2188.702475)
+```
   
 Average time to request an arbitrary page from the leaderboard:
 
+```ruby
   ruby-1.9.2-p180 :007 > 1.upto(requests_to_make) do
   ruby-1.9.2-p180 :008 >     lb_request_time += Benchmark.measure do
   ruby-1.9.2-p180 :009 >       highscore_lb.leaders(rand(highscore_lb.total_pages))
@@ -175,12 +212,13 @@ Average time to request an arbitrary page from the leaderboard:
   ruby-1.9.2-p180 :012 > p lb_request_time / requests_to_make
   0.0014615999999999531
    => 0.0014615999999999531 
+```
 
-== Future Ideas
+## Future Ideas
 
 * Bulk insert
 
-== Ports
+## Ports
 
 The following ports have been made of the leaderboard gem.
 
@@ -190,7 +228,7 @@ The following ports have been made of the leaderboard gem.
 * Python: https://github.com/agoragames/python-leaderboard
 * Scala: https://github.com/agoragames/scala-leaderboard
   
-== Contributing to leaderboard
+## Contributing to leaderboard
  
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
 * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
@@ -200,7 +238,7 @@ The following ports have been made of the leaderboard gem.
 * Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
 * Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
 
-== Copyright
+## Copyright
 
 Copyright (c) 2011 David Czarnecki. See LICENSE.txt for further details.
 

data/Rakefile

@@ -1,31 +1,7 @@
-require 'rubygems'
 require 'bundler'
-begin
-  Bundler.setup(:default, :development)
-rescue Bundler::BundlerError => e
-  $stderr.puts e.message
-  $stderr.puts "Run `bundle install` to install missing gems"
-  exit e.status_code
-end
-require 'rake'
-
-require 'jeweler'
-Jeweler::Tasks.new do |gem|
-  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
-  gem.name = "leaderboard"
-  gem.homepage = "http://github.com/agoragames/leaderboard"
-  gem.license = "MIT"
-  gem.summary = %Q{Leaderboards backed by Redis in Ruby}
-  gem.description = %Q{Leaderboards backed by Redis in Ruby}
-  gem.email = "dczarnecki@agoragames.com"
-  gem.authors = ["David Czarnecki"]
-  # Include your dependencies below. Runtime dependencies are required when using your gem,
-  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
-  #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
-  #  gem.add_development_dependency 'rspec', '> 1.2.3'
-end
-Jeweler::RubygemsDotOrgTasks.new
+Bundler::GemHelper.install_tasks
 
+require 'rake'
 require 'rake/testtask'
 Rake::TestTask.new(:test) do |test|
   test.libs << 'lib' << 'test'
@@ -33,23 +9,6 @@ Rake::TestTask.new(:test) do |test|
   test.verbose = true
 end
 
-require 'rcov/rcovtask'
-Rcov::RcovTask.new do |test|
-  test.libs << 'test'
-  test.pattern = 'test/**/test_*.rb'
-  test.verbose = true
-end
-
-require 'rdoc/task'
-RDoc::Task.new do |rdoc|
-  version = File.exist?('VERSION') ? File.read('VERSION') : ""
-
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "leaderboard #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
-
 REDIS_DIR = File.expand_path(File.join("..", "test"), __FILE__)
 REDIS_CNF = File.join(REDIS_DIR, "test.conf")
 REDIS_PID = File.join(REDIS_DIR, "db", "redis.pid")
@@ -58,7 +17,7 @@ REDIS_LOCATION = ENV['REDIS_LOCATION']
 task :default => :run
 
 desc "Run tests and manage server start/stop"
-task :run => [:start, :test_rubies, :stop]
+task :run => [:start, :test, :stop]
 
 desc "Run rcov and manage server start/stop"
 task :rcoverage => [:start, :rcov, :stop]
@@ -89,5 +48,7 @@ task :stop do
 end
 
 task :test_rubies do
-  system "rvm 1.8.7@leaderboard_gem,1.9.2@leaderboard_gem do rake test"
+  Rake::Task['start'].execute
+  system "rvm 1.8.7@leaderboard_gem,1.9.2@leaderboard_gem,1.9.3@leaderboard_gem do rake test"
+  Rake::Task['stop'].execute
 end

data/leaderboard.gemspec

@@ -1,69 +1,27 @@
-# Generated by jeweler
-# DO NOT EDIT THIS FILE DIRECTLY
-# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+
+require 'leaderboard/version'
 
 Gem::Specification.new do |s|
-  s.name = "leaderboard"
-  s.version = "2.0.1"
+  s.name        = "leaderboard"
+  s.version     = Leaderboard::VERSION.dup
+  s.authors     = ["David Czarnecki"]
+  s.email       = ["dczarnecki@agoragames.com"]
+  s.homepage    = "https://github.com/agoragames/leaderboard"
+  s.summary     = %q{Leaderboards backed by Redis in Ruby}
+  s.description = %q{Leaderboards backed by Redis in Ruby}
 
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["David Czarnecki"]
-  s.date = "2011-11-07"
-  s.description = "Leaderboards backed by Redis in Ruby"
-  s.email = "dczarnecki@agoragames.com"
-  s.extra_rdoc_files = [
-    "LICENSE.txt",
-    "README.rdoc"
-  ]
-  s.files = [
-    ".document",
-    ".rvmrc",
-    "CHANGELOG.markdown",
-    "Gemfile",
-    "LICENSE.txt",
-    "README.rdoc",
-    "Rakefile",
-    "VERSION",
-    "leaderboard.gemspec",
-    "lib/leaderboard.rb",
-    "test/db/.gitkeep",
-    "test/helper.rb",
-    "test/test.conf",
-    "test/test_leaderboard.rb"
-  ]
-  s.homepage = "http://github.com/agoragames/leaderboard"
-  s.licenses = ["MIT"]
-  s.require_paths = ["lib"]
-  s.rubygems_version = "1.8.11"
-  s.summary = "Leaderboards backed by Redis in Ruby"
-  s.test_files = [
-    "test/helper.rb",
-    "test/test_leaderboard.rb"
-  ]
+  s.rubyforge_project = "leaderboard"
 
-  if s.respond_to? :specification_version then
-    s.specification_version = 3
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
 
-    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<redis>, [">= 0"])
-      s.add_development_dependency(%q<bundler>, [">= 0"])
-      s.add_development_dependency(%q<jeweler>, [">= 0"])
-      s.add_development_dependency(%q<rcov>, [">= 0"])
-      s.add_development_dependency(%q<rdoc>, [">= 0"])
-    else
-      s.add_dependency(%q<redis>, [">= 0"])
-      s.add_dependency(%q<bundler>, [">= 0"])
-      s.add_dependency(%q<jeweler>, [">= 0"])
-      s.add_dependency(%q<rcov>, [">= 0"])
-      s.add_dependency(%q<rdoc>, [">= 0"])
-    end
-  else
-    s.add_dependency(%q<redis>, [">= 0"])
-    s.add_dependency(%q<bundler>, [">= 0"])
-    s.add_dependency(%q<jeweler>, [">= 0"])
-    s.add_dependency(%q<rcov>, [">= 0"])
-    s.add_dependency(%q<rdoc>, [">= 0"])
+  s.add_dependency('redis')
+  s.add_development_dependency('rake')
+  if '1.8.7'.eql?(RUBY_VERSION)
+    s.add_development_dependency('SystemTimer')
   end
 end
-

data/lib/leaderboard.rb

@@ -1,15 +1,17 @@
 require 'redis'
+require 'leaderboard/version'
 
 class Leaderboard
-  VERSION = '2.0.1'.freeze
-  
   DEFAULT_PAGE_SIZE = 25
+  
   DEFAULT_OPTIONS = {
     :page_size => DEFAULT_PAGE_SIZE
   }
 
   DEFAULT_REDIS_HOST = 'localhost'
+  
   DEFAULT_REDIS_PORT = 6379  
+  
   DEFAULT_REDIS_OPTIONS = {
     :host => DEFAULT_REDIS_HOST,
     :port => DEFAULT_REDIS_PORT
@@ -22,9 +24,22 @@ class Leaderboard
     :page_size => nil
   }
   
+  # Name of the leaderboard.
   attr_reader :leaderboard_name
+
+  # Page size to be used when paging through the leaderboard. 
   attr_reader :page_size
   
+  # 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)
     @leaderboard_name = leaderboard_name
     
@@ -40,78 +55,156 @@ class Leaderboard
         
     @redis_connection = Redis.new(redis_options) if @redis_connection.nil?
   end
-      
+  
+  # Set the page size to be used when paging through the leaderboard. This method 
+  # also has the side effect of setting the page size to the +DEFAULT_PAGE_SIZE+ 
+  # if the page size is less than 1.
+  # 
+  # @param page_size [int] Page size.
   def page_size=(page_size)
     page_size = DEFAULT_PAGE_SIZE if page_size < 1
 
     @page_size = page_size
   end
   
+  # Disconnect the Redis connection.
   def disconnect
     @redis_connection.client.disconnect
   end
   
+  # Delete the current leaderboard.
   def delete_leaderboard
     delete_leaderboard_named(@leaderboard_name)
   end
   
+  # Delete the named leaderboard.
+  #
+  # @param leaderboard_name [String] Name of the leaderboard.
   def delete_leaderboard_named(leaderboard_name)
     @redis_connection.del(leaderboard_name)
   end
       
+  # Rank a member in the leaderboard.
+  # 
+  # @param member [String] Member name.
+  # @param score [float] Member score.
   def rank_member(member, score)
     rank_member_in(@leaderboard_name, member, score)
   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.
   def rank_member_in(leaderboard_name, member, score)
     @redis_connection.zadd(leaderboard_name, score, member)
   end
   
+  # Remove a member from the leaderboard.
+  #
+  # @param member [String] Member name.
   def remove_member(member)
     remove_member_from(@leaderboard_name, member)
   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)
     @redis_connection.zrem(leaderboard_name, member)
   end
   
+  # Retrieve the total number of members in the leaderboard.
+  # 
+  # @return total number of members in the leaderboard.
   def total_members
     total_members_in(@leaderboard_name)
   end
   
+  # Retrieve the total number of members in the named leaderboard.
+  # 
+  # @param leaderboard_name [String] Name of the leaderboard.
+  #
+  # @return the total number of members in the named leaderboard.
   def total_members_in(leaderboard_name)
     @redis_connection.zcard(leaderboard_name)
   end
   
+  # Retrieve the total number of pages in the leaderboard.
+  #
+  # @return the total number of pages in the leaderboard.
   def total_pages
     total_pages_in(@leaderboard_name)
   end
   
+  # Retrieve the total number of pages in the named leaderboard.
+  # 
+  # @param leaderboard_name [String] Name of the leaderboard.
+  # @param page_size [int] Page size to be used when paging through the leaderboard.
+  # 
+  # @return the total number of pages in the named leaderboard.
   def total_pages_in(leaderboard_name, page_size = nil)
     page_size ||= @page_size.to_f
     (total_members_in(leaderboard_name) / page_size.to_f).ceil
   end
   
+  # Retrieve the total members in a given score range from the leaderboard.
+  #
+  # @param min_score [float] Minimum score.
+  # @param max_score [float] Maximum score.
+  #
+  # @return the total members in a given score range from the leaderboard.
   def total_members_in_score_range(min_score, max_score)
     total_members_in_score_range_in(@leaderboard_name, min_score, max_score)
   end
   
+  # Retrieve the total members in a given score range from the named leaderboard.
+  #
+  # @param leaderboard_name Name of the leaderboard.
+  # @param min_score [float] Minimum score.
+  # @param max_score [float] Maximum score.
+  #
+  # @return the total members in a given score range from the named leaderboard.
   def total_members_in_score_range_in(leaderboard_name, min_score, max_score)
     @redis_connection.zcount(leaderboard_name, min_score, max_score)
   end
   
+  # Change the score for a member in the leaderboard by a score delta which can be positive or negative.
+  #
+  # @param member [String] Member name.
+  # @param delta [float] Score change.
   def change_score_for(member, delta)    
     change_score_for_member_in(@leaderboard_name, member, delta)
   end
   
+  # Change the score for a member in the named leaderboard by a delta which can be positive or negative.
+  #
+  # @param leaderboard_name [String] Name of the leaderboard.
+  # @param member [String] Member name.
+  # @param delta [float] Score change.
   def change_score_for_member_in(leaderboard_name, member, delta)
     @redis_connection.zincrby(leaderboard_name, delta, member)
   end
   
+  # Retrieve the rank for a member in the leaderboard.
+  # 
+  # @param member [String] Member name.
+  # @param use_zero_index_for_rank [boolean, false] If the returned rank should be 0-indexed.
+  # 
+  # @return the rank for a member in the leaderboard.
   def rank_for(member, use_zero_index_for_rank = false)
     rank_for_in(@leaderboard_name, member, use_zero_index_for_rank)
   end
   
+  # Retrieve the rank for a member in the named leaderboard.
+  # 
+  # @param leaderboard_name [String] Name of the leaderboard.
+  # @param member [String] Member name.
+  # @param use_zero_index_for_rank [boolean, false] If the returned rank should be 0-indexed.
+  # 
+  # @return the rank for a member in the leaderboard.
   def rank_for_in(leaderboard_name, member, use_zero_index_for_rank = false)
     if use_zero_index_for_rank
       return @redis_connection.zrevrank(leaderboard_name, member)
@@ -120,26 +213,61 @@ class Leaderboard
     end
   end
   
+  # Retrieve the score for a member in the leaderboard.
+  # 
+  # @param member Member name.
+  #
+  # @return the score for a member in the leaderboard.
   def score_for(member)
     score_for_in(@leaderboard_name, member)
   end
   
+  # Retrieve the score for a member in the named leaderboard.
+  # 
+  # @param leaderboard_name Name of the leaderboard.
+  # @param member [String] Member name.
+  #
+  # @return the score for a member in the leaderboard.
   def score_for_in(leaderboard_name, member)
     @redis_connection.zscore(leaderboard_name, member).to_f
   end
 
+  # Check to see if a member exists in the leaderboard.
+  #
+  # @param member [String] Member name.
+  #
+  # @return +true+ if the member exists in the leaderboard, +false+ otherwise.
   def check_member?(member)
     check_member_in?(@leaderboard_name, member)
   end
   
+  # Check to see if a member exists in the named leaderboard.
+  #
+  # @param leaderboard_name [String] Name of the leaderboard.
+  # @param member [String] Member name.
+  #
+  # @return +true+ if the member exists in the named leaderboard, +false+ otherwise.
   def check_member_in?(leaderboard_name, member)
     !@redis_connection.zscore(leaderboard_name, member).nil?
   end
   
+  # Retrieve the score and rank for a member in the leaderboard.
+  #
+  # @param member [String] Member name.
+  # @param use_zero_index_for_rank [boolean, false] If the returned rank should be 0-indexed.
+  #
+  # @return the score and rank for a member in the leaderboard as a Hash.
   def score_and_rank_for(member, use_zero_index_for_rank = false)
     score_and_rank_for_in(@leaderboard_name, member, use_zero_index_for_rank)
   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.
+  # @param use_zero_index_for_rank [boolean, false] If the returned rank should be 0-indexed.
+  #
+  # @return the score and rank for a member in the named leaderboard as a Hash.
   def score_and_rank_for_in(leaderboard_name, member, use_zero_index_for_rank = false)
     responses = @redis_connection.multi do |transaction|
       transaction.zscore(leaderboard_name, member)
@@ -154,19 +282,41 @@ class Leaderboard
     {:member => member, :score => responses[0], :rank => responses[1]}    
   end
   
+  # Remove members from the leaderboard in a given score range.
+  #
+  # @param min_score [float] Minimum score.
+  # @param max_score [float] Maximum score.
   def remove_members_in_score_range(min_score, max_score)
     remove_members_in_score_range_in(@leaderboard_name, min_score, max_score)
   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.zremrangebyscore(leaderboard_name, min_score, max_score)
   end
   
+  # Retrieve the percentile for a member in the leaderboard.
+  # 
+  # @param member [String] Member name.
+  # 
+  # @return the percentile for a member in the leaderboard. Return +nil+ for a non-existent member.
   def percentile_for(member)
     percentile_for_in(@leaderboard_name, member)
   end
  
+  # Retrieve the percentile for a member in the named leaderboard.
+  # 
+  # @param leaderboard_name [String] Name of the leaderboard.
+  # @param member [String] Member name.
+  # 
+  # @return the percentile for a member in the named leaderboard.
   def percentile_for_in(leaderboard_name, member)
+    return nil unless check_member_in?(leaderboard_name, member)
+
     responses = @redis_connection.multi do |transaction|
       transaction.zcard(leaderboard_name)     
       transaction.zrevrank(leaderboard_name, member)
@@ -175,10 +325,23 @@ class Leaderboard
     ((responses[0] - responses[1] - 1).to_f / responses[0].to_f * 100).ceil
   end
     
+  # Retrieve a page of leaders from the leaderboard.
+  # 
+  # @param current_page [int] Page to retrieve from the leaderboard.
+  # @param options [Hash] Options to be used when retrieving the page from the leaderboard.
+  # 
+  # @return a page of leaders from the leaderboard.
   def leaders(current_page, options = {})
     leaders_in(@leaderboard_name, current_page, options)
   end
 
+  # Retrieve a page of leaders from the named leaderboard.
+  # 
+  # @param leaderboard_name [String] Name of the leaderboard.
+  # @param current_page [int] Page to retrieve from the named leaderboard.
+  # @param options [Hash] Options to be used when retrieving the page from the named leaderboard.
+  # 
+  # @return a page of leaders from the named leaderboard.
   def leaders_in(leaderboard_name, current_page, options = {})
     leaderboard_options = DEFAULT_LEADERBOARD_REQUEST_OPTIONS.dup
     leaderboard_options.merge!(options)
@@ -210,15 +373,30 @@ class Leaderboard
     end
   end
   
+  # Retrieve a page of leaders from the leaderboard around a given member.
+  #
+  # @param member [String] Member name.
+  # @param options [Hash] Options to be used when retrieving the page from the leaderboard.
+  # 
+  # @return a page of leaders from the leaderboard around a given member.
   def around_me(member, options = {})
     around_me_in(@leaderboard_name, member, options)
   end
   
+  # Retrieve a page of leaders from the named leaderboard around a given member.
+  #
+  # @param leaderboard_name [String] Name of the leaderboard.
+  # @param member [String] Member name.
+  # @param options [Hash] Options to be used when retrieving the page from the named leaderboard.
+  # 
+  # @return a page of leaders from the named leaderboard around a given member. Returns an empty array for a non-existent member.
   def around_me_in(leaderboard_name, member, options = {})
     leaderboard_options = DEFAULT_LEADERBOARD_REQUEST_OPTIONS.dup
     leaderboard_options.merge!(options)
     
     reverse_rank_for_member = @redis_connection.zrevrank(leaderboard_name, member)
+
+    return [] unless reverse_rank_for_member
     
     page_size = validate_page_size(leaderboard_options[:page_size]) || @page_size
     
@@ -237,10 +415,23 @@ class Leaderboard
     end
   end
   
+  # Retrieve a page of leaders from the leaderboard for a given list of members.
+  # 
+  # @param members [Array] Member names.
+  # @param options [Hash] Options to be used when retrieving the page from the leaderboard.
+  # 
+  # @return a page of leaders from the leaderboard for a given list of members.
   def ranked_in_list(members, options = {})
     ranked_in_list_in(@leaderboard_name, members, options)
   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)
@@ -262,7 +453,7 @@ class Leaderboard
           if leaderboard_options[:use_zero_index_for_rank]
             data[:rank] = responses[index * 2]
           else
-            data[:rank] = responses[index * 2] + 1
+            data[:rank] = responses[index * 2] + 1 rescue nil
           end
           
           data[:score] = responses[index * 2 + 1].to_f
@@ -274,7 +465,7 @@ class Leaderboard
           if leaderboard_options[:use_zero_index_for_rank]
             data[:rank] = responses[index]
           else
-            data[:rank] = responses[index] + 1
+            data[:rank] = responses[index] + 1 rescue nil
           end
         end
       end
@@ -285,18 +476,31 @@ class Leaderboard
     ranks_for_members
   end
   
-  # Merge leaderboards given by keys with this leaderboard into destination
+  # Merge leaderboards given by keys with this leaderboard into a named destination leaderboard.
+  #
+  # @param destination [String] Destination leaderboard name.
+  # @param keys [Array] Leaderboards to be merged with the current leaderboard.
+  # @param options [Hash] Options for merging the leaderboards. 
   def merge_leaderboards(destination, keys, options = {:aggregate => :sum})
     @redis_connection.zunionstore(destination, keys.insert(0, @leaderboard_name), options)
   end
   
-  # Intersect leaderboards given by keys with this leaderboard into destination
+  # Intersect leaderboards given by keys with this leaderboard into a named destination leaderboard.
+  # 
+  # @param destination [String] Destination leaderboard name.
+  # @param keys [Array] Leaderboards to be merged with the current leaderboard.
+  # @param options [Hash] Options for intersecting the leaderboards.
   def intersect_leaderboards(destination, keys, options = {:aggregate => :sum})
     @redis_connection.zinterstore(destination, keys.insert(0, @leaderboard_name), options)
   end
   
   private 
   
+  # 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.
+  #
+  # @return the page size. Returns the +DEFAULT_PAGE_SIZE+ if the page size is less than 1.
   def validate_page_size(page_size)
     if page_size && page_size < 1
       page_size = DEFAULT_PAGE_SIZE

data/lib/leaderboard/version.rb

@@ -0,0 +1,3 @@
+class Leaderboard
+  VERSION = '2.0.2'.freeze
+end

data/test/test_helper.rb

@@ -0,0 +1,4 @@
+require 'rubygems'
+require 'test/unit'
+
+require 'leaderboard'

data/test/test_leaderboard.rb

@@ -1,4 +1,4 @@
-require 'helper'
+require 'test_helper'
 
 class TestLeaderboard < Test::Unit::TestCase
   def setup    
@@ -13,7 +13,7 @@ class TestLeaderboard < Test::Unit::TestCase
   end
   
   def test_version
-    assert_equal '2.0.1', Leaderboard::VERSION
+    assert_equal '2.0.2', Leaderboard::VERSION
   end
   
   def test_initialize_with_defaults  
@@ -418,7 +418,44 @@ class TestLeaderboard < Test::Unit::TestCase
     assert_equal 25, @leaderboard.percentile_for('member_4')
     assert_equal 92, @leaderboard.percentile_for('member_12')
   end
+
+  def test_around_me_for_invalid_member
+    rank_members_in_leaderboard(Leaderboard::DEFAULT_PAGE_SIZE * 3 + 1)
+    
+    leaders_around_me = @leaderboard.around_me('jones', Leaderboard::DEFAULT_LEADERBOARD_REQUEST_OPTIONS.merge({:page_size => 3}))
+    assert_equal 0, leaders_around_me.size
+  end
+
+  def test_score_and_rank_for_non_existent_member
+    score_and_rank_for_member = @leaderboard.score_and_rank_for('jones')
   
+    assert_equal 'jones', score_and_rank_for_member[:member]
+    assert_equal 0.0, score_and_rank_for_member[:score]
+    assert_nil score_and_rank_for_member[:rank]
+  end
+
+  def test_ranked_in_list_for_non_existent_member
+    rank_members_in_leaderboard
+
+    members = ['member_1', 'member_5', 'jones']
+    ranked_members = @leaderboard.ranked_in_list(members)
+
+    assert_equal 3, ranked_members.size    
+    assert_nil ranked_members[2][:rank]
+  end
+
+  def test_percentile_for_non_existent_member
+    percentile = @leaderboard.percentile_for('jones')
+
+    assert_nil percentile
+  end
+
+  def test_change_score_for_non_existent_member
+    assert_equal 0.0, @leaderboard.score_for('jones')
+    @leaderboard.change_score_for('jones', 5)
+    assert_equal 5.0, @leaderboard.score_for('jones')
+  end
+
   private
   
   def rank_members_in_leaderboard(members_to_add = 5)

metadata

@@ -1,126 +1,92 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: leaderboard
-version: !ruby/object:Gem::Version 
+version: !ruby/object:Gem::Version
+  version: 2.0.2
   prerelease: 
-  version: 2.0.1
 platform: ruby
-authors: 
+authors:
 - David Czarnecki
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-11-07 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2012-02-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: redis
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &70115900454580 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: bundler
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: *70115900454580
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &70115900454140 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
   prerelease: false
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: jeweler
-  requirement: &id003 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
-  type: :development
-  prerelease: false
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
-  name: rcov
-  requirement: &id004 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
-  type: :development
-  prerelease: false
-  version_requirements: *id004
-- !ruby/object:Gem::Dependency 
-  name: rdoc
-  requirement: &id005 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
-  type: :development
-  prerelease: false
-  version_requirements: *id005
+  version_requirements: *70115900454140
 description: Leaderboards backed by Redis in Ruby
-email: dczarnecki@agoragames.com
+email:
+- dczarnecki@agoragames.com
 executables: []
-
 extensions: []
-
-extra_rdoc_files: 
-- LICENSE.txt
-- README.rdoc
-files: 
+extra_rdoc_files: []
+files:
 - .document
+- .gitignore
 - .rvmrc
 - CHANGELOG.markdown
 - Gemfile
 - LICENSE.txt
-- README.rdoc
+- README.markdown
 - Rakefile
-- VERSION
 - leaderboard.gemspec
 - lib/leaderboard.rb
+- lib/leaderboard/version.rb
 - test/db/.gitkeep
-- test/helper.rb
 - test/test.conf
+- test/test_helper.rb
 - test/test_leaderboard.rb
-homepage: http://github.com/agoragames/leaderboard
-licenses: 
-- MIT
+homepage: https://github.com/agoragames/leaderboard
+licenses: []
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 2535082084974160649
-      segments: 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
       - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+      hash: 822397651931818712
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 822397651931818712
 requirements: []
-
-rubyforge_project: 
-rubygems_version: 1.8.11
+rubyforge_project: leaderboard
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: Leaderboards backed by Redis in Ruby
-test_files: 
-- test/helper.rb
+test_files:
+- test/db/.gitkeep
+- test/test.conf
+- test/test_helper.rb
 - test/test_leaderboard.rb

data/VERSION

@@ -1 +0,0 @@
-2.0.1

data/test/helper.rb

@@ -1,17 +0,0 @@
-require 'rubygems'
-require 'bundler'
-begin
-  Bundler.setup(:default, :development)
-rescue Bundler::BundlerError => e
-  $stderr.puts e.message
-  $stderr.puts "Run `bundle install` to install missing gems"
-  exit e.status_code
-end
-require 'test/unit'
-
-$LOAD_PATH.unshift(File.dirname(__FILE__))
-$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
-require 'leaderboard'
-
-class Test::Unit::TestCase
-end