cheer 1.0.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3fbc7d10a59452417daeb9b6556e483a239e5cb4
+  data.tar.gz: 625f081e1de184703ec2b8b22f60b0ccce6c6e59
+SHA512:
+  metadata.gz: be88f6e3d1d420ee199a771d06000fcf8c5ff190fd9aef2c3020f880a524caaf4ddbafcee90ba61162ae3153a86e7e8d956e2b3c5f624d4933e44445ee7a950e
+  data.tar.gz: b17a8987079615013178485f2cf4ac75af61149e3bbca52c23a34a0feeea5613e50a9f543489347601305f6f6702291059624736b810d16c12698e7c21191c83

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+vendor

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/.ruby-gemset

@@ -0,0 +1 @@
+cheer

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.0.0-p353

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in user-ranking.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 TODO: Write your name
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,158 @@
+# Cheer
+
+A ruby gem to quickly add leaderboard functionality to any existing model in a rails application. This gem makes it easy to add leaderboards not only in games, where they are usually used but also into any other application which contains rankable models.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+    gem 'cheer'
+```
+
+And then execute:
+
+```
+    $ bundle
+```
+
+Or install it yourself as:
+
+```
+    $ gem install cheer
+```
+
+## Basic Usage
+
+Consider a `Movie` model which has a `views` column that stores the number of times users have viewed the movie and a `profit` column that contains the total profit made by that movie.
+
+```ruby
+class Movie < ActiveRecord::Base
+  extend Cheer::ModelAdditions
+
+  leaderboard :viewership_leaderboard, column_name: :views
+end
+```
+
+For example consider the following movies in the database:
+
+<table>
+    <tr>
+        <th>Name</th>
+        <th>Views</th>
+        <th>Profit</th>
+    </tr>
+    <tr>
+        <td>Pulp Fiction</td>
+        <td>50</td>
+        <td>$500</td>
+    </tr>
+    <tr>
+        <td>Reservoir Dogs</td>
+        <td>40</td>
+        <td>$600</td>
+    </tr>
+    <tr>
+        <td>Kill Bill</td>
+        <td>30</td>
+        <td>$200</td>
+    </tr>
+    <tr>
+        <td>Death Proof</td>
+        <td>20</td>
+        <td>$100</td>
+    </tr>
+    <tr>
+        <td>Jackie Brown</td>
+        <td>10</td>
+        <td>$400</td>
+    </tr>
+</table>
+
+## leaderboard class method
+
+The gem will automatically add the `leaderboard` class method to the Movie class which will allow
+you to configure custom leaderboards.
+This method takes these arguments: `name`, `column_name`, `sort_order`, `around_limit`.
+
+```ruby
+class Movie < ActiveRecord::Base
+  extend Cheer::ModelAdditions
+
+  leaderboard :profitability_leaderboard, column_name: :profit,
+                                          sort_order: %w(name),
+                                          around_limit: 1
+
+  # This will add the :profitability_leaderboard instance method.
+  # It also takes an optional argument(integer) to limit the number of records returned from `top_movies` method.
+end
+
+pulp_fiction   = Movie.find_by_name("Pulp Fiction")
+reservoir_dogs = Movie.find_by_name("Reservoir Dogs")
+kill_bill      = Movie.find_by_name("Kill Bill")
+death_proof    = Movie.find_by_name("Death Proof")
+jackie_brown   = Movie.find_by_name("Jackie Brown")
+
+pulp_fiction.profitability_leaderboard # => #<Cheer::Leaderboard:0xb121a14>
+pulp_fiction.profitability_leaderboard.current_movie_rank # => 2
+pulp_fiction.profitability_leaderboard.movies_around # => [reservoir_dogs, pulp_fiction, jackie_brown]
+pulp_fiction.profitability_leaderboard.top_movies # => [pulp_fiction, reservoir_dogs, kill_bill]
+pulp_fiction.profitability_leaderboard.top_movies(2) # => [pulp_fiction, reservoir_dogs]
+
+pulp_fiction.profitability_leaderboard.to_hash # => {current_movie_rank: 2, movies_around: [reservoir_dogs, pulp_fiction, jackie_brown], top_movies: [pulp_fiction, reservoir_dogs, kill_bill]}
+
+death_proof.profitability_leaderboard.to_hash(2) # => {current_movie_rank: 6, movies_around: [kill_bill, death_proof], top_movies: [pulp_fiction, reservoir_dogs]}
+```
+
+
+## Additional Options
+
+### :sort_order
+
+```ruby
+class Movie < ActiveRecord::Base
+  extend Cheer::ModelAdditions
+
+  leaderboard :viewership_leaderboard, column_name: :views,
+                                       sort_order: ["released_on asc", "number_of_awards desc"]
+end
+```
+
+The gem also allows you to specify additional sort orders to resolve conflicts when there are a bunch of movies with the same number of views. The additional sort order can be specified as shown above. In this case, if two movies have the same number of views, the one released earlier will have a higher ranking. In case the number of views and the release date is the same, the one with more awards will have a higher ranking.
+
+If the `:sort_order` is not specified, the conflicts will be resolved using the `id asc` sort order.
+
+### :around_limit
+
+The default number of objects returned by `movies_around` can be overwritten using the option `around_limit`. In the example below, we set the option to 1 forcing the gem to return at most 1 movie before and after the current movie:
+
+```ruby
+class Movie < ActiveRecord::Base
+  extend Cheer::ModelAdditions
+
+  leaderboard :viewership_leaderboard, column_name: :views,
+                                       around_limit: 1
+end
+
+kill_bill = Movie.find_by_name("Kill Bill")
+kill_bill.viewership_leaderboard.movies_around # => [reservoir_dogs, kill_bill, death_proof]
+```
+
+
+## Roadmap
+* Scopes - Calculate leaderboards and ranking for a specific scope. For example, this will help us generate leaderboards for all movies released in 2012 or for all movies produced by DreamWorks, etc.
+
+
+## Authors
+* Karthik C: https://github.com/karthikc
+* Nitin Misra: https://github.com/nitinstp23
+* Rakesh Verma: https://github.com/rakesh87
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,5 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
+task :default => :spec

data/cheer.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/cheer/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.name          = 'cheer'
+  gem.version       = Cheer::VERSION
+  gem.authors       = ['Eos Software Systems Pvt Ltd']
+  gem.email         = ['info@eossys.com']
+  gem.description   = %q{A ruby gem to quickly add rankings & leaderboards to existing models in a rails application}
+  gem.summary       = gem.description
+  gem.homepage      = 'https://github.com/eossys/cheer'
+  gem.license       = 'MIT'
+
+  gem.files         = `git ls-files`.split($INPUT_RECORD_SEPARATOR)
+  gem.executables   = gem.files.grep(%r{^bin/}).map { |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ['lib']
+
+  # Runtime Dependencies
+  gem.add_runtime_dependency 'activerecord', '>= 3.0'
+
+  # Development dependencies
+  gem.add_development_dependency 'rspec', '~> 2.14'
+  gem.add_development_dependency 'sqlite3', '~> 1.3'
+end

data/lib/cheer.rb

@@ -0,0 +1,7 @@
+require 'cheer/version' # created by Bundler
+
+require 'cheer/error'
+require 'cheer/argument'
+require 'cheer/leaderboard'
+require 'cheer/rank_evaluator'
+require 'cheer/model_additions'

data/lib/cheer/argument.rb

@@ -0,0 +1,56 @@
+module Cheer
+  class Argument
+
+    attr_reader :column_name, :sort_order, :around_limit, :model_klass
+
+    def initialize(args = {})
+      @model_klass  = args[:model_klass]
+      @column_name  = parse_column_name(args[:column_name])
+      @sort_order   = parse_sort_order(args[:sort_order])
+      @around_limit = parse_around_limit(args[:around_limit])
+
+      validate_column_name
+      validate_sort_order
+      validate_around_limit
+
+      merge_sort_order
+    end
+
+    def parse_column_name(column_name)
+      [String, Symbol].include?(column_name.class) ? column_name.to_s : ''
+    end
+
+    def parse_sort_order(sort_order)
+      sort_order.present? ? sort_order : ['id']
+    end
+
+    def parse_around_limit(around_limit)
+      around_limit ? around_limit : 2
+    end
+
+    def validate_column_name
+      return if column_name.present? && column_exists_in_db?
+      raise Error::InvalidColumnName
+    end
+
+    def validate_around_limit
+      return if around_limit.to_i > 0
+      raise Error::InvalidAroundLimit
+    end
+
+    def validate_sort_order
+      return if sort_order.is_a?(Array)
+      raise Error::InvalidSortOrder
+    end
+
+    def column_exists_in_db?
+      model_klass.column_names.include?(column_name)
+    end
+
+    def merge_sort_order
+      # Ensure 'id' is always present in Sort Order.
+      @sort_order | ['id']
+      @sort_order = @sort_order.join(',')
+    end
+  end
+end

data/lib/cheer/error.rb

@@ -0,0 +1,23 @@
+module Cheer
+  module Error
+
+    class InvalidColumnName < ArgumentError
+      def message
+        ':column_name option is not a symbol or string'
+      end
+    end
+
+    class InvalidSortOrder < ArgumentError
+      def message
+        ':sort_order option is not an array of symbols or strings'
+      end
+    end
+
+    class InvalidAroundLimit < ArgumentError
+      def message
+        ':around_limit option is not an integer'
+      end
+    end
+
+  end
+end

data/lib/cheer/leaderboard.rb

@@ -0,0 +1,48 @@
+module Cheer
+  class Leaderboard
+
+    def initialize(attributes = {})
+      @model_klass    = attributes[:model_klass]
+      @rank_evaluator = attributes[:rank_evaluator]
+
+      define_public_methods
+    end
+
+    def to_hash(user_limit = 3)
+      {
+        standing_methods[:current_rank] => self.public_send(standing_methods[:current_rank]),
+        standing_methods[:rank_around]  => self.public_send(standing_methods[:rank_around]),
+        standing_methods[:top_rankers]  => self.public_send(standing_methods[:top_rankers], user_limit)
+      }
+    end
+
+    private
+
+    attr_reader :model_klass, :rank_evaluator
+
+    def standing_methods
+      @standing_methods ||= model_klass.standing_methods
+    end
+
+    def define_public_methods
+      current_rank_method = standing_methods[:current_rank]
+      rank_around_method  = standing_methods[:rank_around]
+      top_rankers_method  = standing_methods[:top_rankers]
+
+      self.class_eval do
+        define_method current_rank_method do
+          rank_evaluator.current_rank
+        end
+
+        define_method rank_around_method do
+          rank_evaluator.rank_around
+        end
+
+        define_method top_rankers_method do |user_limit = 3|
+          rank_evaluator.top_rankers(user_limit)
+        end
+      end
+    end
+
+  end
+end

data/lib/cheer/model_additions.rb

@@ -0,0 +1,34 @@
+module Cheer
+  module ModelAdditions
+
+    # Hookup event for ModelAdditions Module
+    def self.extended(base)
+      base.class_eval do
+        model_name = self.name.underscore
+
+        define_singleton_method :standing_methods do
+          {
+            current_rank: "current_#{model_name}_rank".to_sym,
+            rank_around: "#{model_name.pluralize}_around".to_sym,
+            top_rankers: "top_#{model_name.pluralize}".to_sym
+          }
+        end
+      end
+    end
+
+    def leaderboard(name, args = {})
+      define_method name.to_sym do |user_limit = 3|
+        rank_evaluator = RankEvaluator.new(
+          model_object: self,
+          config: Argument.new(args.merge(model_klass: self.class))
+        )
+
+        Leaderboard.new(
+          model_klass: self.class,
+          rank_evaluator: rank_evaluator
+        )
+      end
+    end
+
+  end
+end

data/lib/cheer/rank_evaluator.rb

@@ -0,0 +1,67 @@
+module Cheer
+  class RankEvaluator
+    extend Forwardable
+
+    def_delegator :@config, :column_name, :column_name
+    def_delegator :@config, :sort_order, :sort_order
+    def_delegator :@config, :around_limit, :around_limit
+    def_delegator :@config, :model_klass, :model_klass
+
+    def initialize(attributes = {})
+      @model_object = attributes[:model_object]
+      @config       = attributes[:config]
+    end
+
+    def current_rank
+      return high_rankers unless equal_rankers?
+      high_rankers + position_amongst_equal_rankers
+    end
+
+    def rank_around
+      offset = current_rank - (around_limit + 1)
+      limit_setting = around_limit * 2 + 1
+
+      if offset < 0
+        limit_setting += offset
+        offset = 0
+      end
+
+      top_rankers(limit_setting).offset(offset)
+    end
+
+    def top_rankers(user_limit)
+      model_klass.order("#{column_name} DESC, #{sort_order}")
+                 .limit(user_limit)
+    end
+
+    private
+
+    attr_reader :model_object
+
+    def column_value
+      @column_value ||= model_object.public_send(column_name)
+    end
+
+    def high_rankers
+      rankers = model_klass.where("#{column_name} > ?", column_value)
+                           .order("#{column_name} DESC")
+
+      @high_rankers ||= rankers.count + 1
+    end
+
+    def equal_rankers?
+      equal_rankers && equal_rankers.count > 1
+    end
+
+    def equal_rankers
+      @equal_rankers ||= model_klass.where("#{column_name} = ?", column_value)
+                                    .order(sort_order)
+                                    .select(:id)
+    end
+
+    def position_amongst_equal_rankers
+      equal_rankers.index(model_object).to_i
+    end
+
+  end
+end

data/lib/cheer/version.rb

@@ -0,0 +1,4 @@
+module Cheer
+  # cheer version
+  VERSION = '1.0.4'
+end

data/spec/cheer_spec.rb

@@ -0,0 +1,362 @@
+require 'spec_helper'
+
+describe Cheer do
+
+  context "Students With Equal Score" do
+    before do
+      Student.delete_all
+      @subrat   = Student.create!(name: 'Subrat Behera', score: 23)
+      @rakesh   = Student.create!(name: 'Rakesh Verma', score: 22)
+      @girish   = Student.create!(name: 'Girish Kumar', score: 21)
+      @nitin    = Student.create!(name: 'Nitin Misra', score: 22)
+      @bhanu    = Student.create!(name: 'Bhanu Chander', score: 19)
+      @prateeth = Student.create!(name: 'Prateeth S', score: 20)
+    end
+
+    it "returns leaderboard objects" do
+      @subrat.topers.should be_an_instance_of(Cheer::Leaderboard)
+      @rakesh.topers.should be_an_instance_of(Cheer::Leaderboard)
+      @girish.topers.should be_an_instance_of(Cheer::Leaderboard)
+      @nitin.topers.should be_an_instance_of(Cheer::Leaderboard)
+      @bhanu.topers.should be_an_instance_of(Cheer::Leaderboard)
+      @prateeth.topers.should be_an_instance_of(Cheer::Leaderboard)
+    end
+
+    it "returns the current student rank if students with equal score exists" do
+      # For students with equal scores, sorting should be done on the basis of id,
+      # since the Student model doesn't define sort_order array.
+      @bhanu.topers.current_student_rank.should    == 6
+      @nitin.topers.current_student_rank.should    == 3
+      @subrat.topers.current_student_rank.should   == 1
+      @rakesh.topers.current_student_rank.should   == 2
+      @girish.topers.current_student_rank.should   == 4
+      @prateeth.topers.current_student_rank.should == 5
+    end
+  end
+
+  context "GameUsers" do
+    before do
+      GameUser.delete_all
+      @dark_lord         = GameUser.create!(name: 'Dark Lord', score: 11)
+      @tom_riddle        = GameUser.create!(name: 'Tom Riddle', score: 25)
+      @ron_weasely       = GameUser.create!(name: 'Ron Weasely', score: 23)
+      @harry_potter      = GameUser.create!(name: 'Harry Potter', score: 14)
+      @jack_sparrow      = GameUser.create!(name: 'Jack Sparrow', score: 12)
+      @albus_dumbelldore = GameUser.create!(name: 'Albus Dumbelldore', score: 2)
+    end
+
+    it "returns leaderboard objects" do
+      @dark_lord.high_scorers.should be_an_instance_of(Cheer::Leaderboard)
+      @tom_riddle.high_scorers.should be_an_instance_of(Cheer::Leaderboard)
+      @ron_weasely.high_scorers.should be_an_instance_of(Cheer::Leaderboard)
+      @harry_potter.high_scorers.should be_an_instance_of(Cheer::Leaderboard)
+      @jack_sparrow.high_scorers.should be_an_instance_of(Cheer::Leaderboard)
+      @albus_dumbelldore.high_scorers.should be_an_instance_of(Cheer::Leaderboard)
+    end
+
+    it "returns the current user rank" do
+      @dark_lord.high_scorers.current_game_user_rank.should         == 5
+      @tom_riddle.high_scorers.current_game_user_rank.should        == 1
+      @ron_weasely.high_scorers.current_game_user_rank.should       == 2
+      @jack_sparrow.high_scorers.current_game_user_rank.should      == 4
+      @harry_potter.high_scorers.current_game_user_rank.should      == 3
+      @albus_dumbelldore.high_scorers.current_game_user_rank.should == 6
+    end
+
+    it "returns the top rank users" do
+      @dark_lord.high_scorers.top_game_users.should       == [@tom_riddle, @ron_weasely, @harry_potter]
+      @tom_riddle.high_scorers.top_game_users(2).should   == [@tom_riddle, @ron_weasely]
+      @ron_weasely.high_scorers.top_game_users(5).should  == [@tom_riddle, @ron_weasely, @harry_potter, @jack_sparrow, @dark_lord]
+      @jack_sparrow.high_scorers.top_game_users(4).should == [@tom_riddle, @ron_weasely, @harry_potter, @jack_sparrow]
+      @harry_potter.high_scorers.top_game_users(1).should == [@tom_riddle]
+    end
+
+    it "returns user around to current user according score descending" do
+      @tom_riddle.high_scorers.game_users_around.should        == [@tom_riddle, @ron_weasely, @harry_potter]
+      @harry_potter.high_scorers.game_users_around.should      == [@tom_riddle, @ron_weasely, @harry_potter, @jack_sparrow, @dark_lord]
+      @albus_dumbelldore.high_scorers.game_users_around.should == [@jack_sparrow, @dark_lord, @albus_dumbelldore]
+    end
+  end
+
+  context "GameUsers With Equal Score" do
+    before do
+      GameUser.delete_all
+      @dark_lord           = GameUser.create!(name: 'Dark Lord', score: 11)
+      @tom_riddle          = GameUser.create!(name: 'Tom Riddle', score: 25)
+      @ivan_potter         = GameUser.create!(name: 'Ivan Potter', score: 14)
+      @ron_weasely         = GameUser.create!(name: 'Ron Weasely', score: 23)
+      @harry_potter        = GameUser.create!(name: 'Harry Potter', score: 14)
+      @jerry_potter        = GameUser.create!(name: 'Jerry Potter', score: 14)
+      @jack_sparrow_1      = GameUser.create!(name: 'Jack Sparrow', score: 12, age: 22)
+      @jack_sparrow_2      = GameUser.create!(name: 'Jack Sparrow', score: 12, age: 23)
+      @albus_dumbelldore   = GameUser.create!(name: 'Albus Dumbelldore', score: 2)
+      @duglous_dumbelldore = GameUser.create!(name: 'Duglous Dumbelldore', score: 2)
+    end
+
+    it "returns the current user rank if users with equal score exists" do
+      @dark_lord.high_scorers.current_game_user_rank.should           == 8
+      @tom_riddle.high_scorers.current_game_user_rank.should          == 1
+      @ivan_potter.high_scorers.current_game_user_rank.should         == 4
+      @ron_weasely.high_scorers.current_game_user_rank.should         == 2
+      @harry_potter.high_scorers.current_game_user_rank.should        == 3
+      @jerry_potter.high_scorers.current_game_user_rank.should        == 5
+      @jack_sparrow_1.high_scorers.current_game_user_rank.should      == 7
+      @jack_sparrow_2.high_scorers.current_game_user_rank.should      == 6
+      @albus_dumbelldore.high_scorers.current_game_user_rank.should   == 9
+      @duglous_dumbelldore.high_scorers.current_game_user_rank.should == 10
+    end
+
+    it "returns the top rank users if equal score users exists" do
+      @dark_lord.high_scorers.top_game_users.should       == [@tom_riddle, @ron_weasely, @harry_potter]
+      @tom_riddle.high_scorers.top_game_users(1).should   == [@tom_riddle]
+      @ivan_potter.high_scorers.top_game_users(2).should  == [@tom_riddle, @ron_weasely]
+      @ron_weasely.high_scorers.top_game_users(4).should  == [@tom_riddle, @ron_weasely, @harry_potter, @ivan_potter]
+      @harry_potter.high_scorers.top_game_users(5).should == [@tom_riddle, @ron_weasely, @harry_potter, @ivan_potter, @jerry_potter]
+    end
+
+    it "returns user around current user if users with equal score exists" do
+      @dark_lord.high_scorers.game_users_around.should           == [@jack_sparrow_2, @jack_sparrow_1, @dark_lord, @albus_dumbelldore, @duglous_dumbelldore]
+      @tom_riddle.high_scorers.game_users_around.should          == [@tom_riddle, @ron_weasely, @harry_potter]
+      @ivan_potter.high_scorers.game_users_around.should         == [@ron_weasely, @harry_potter, @ivan_potter, @jerry_potter, @jack_sparrow_2]
+      @ron_weasely.high_scorers.game_users_around.should         == [@tom_riddle, @ron_weasely, @harry_potter, @ivan_potter]
+      @harry_potter.high_scorers.game_users_around.should        == [@tom_riddle, @ron_weasely, @harry_potter, @ivan_potter, @jerry_potter]
+      @jerry_potter.high_scorers.game_users_around.should        == [@harry_potter, @ivan_potter, @jerry_potter, @jack_sparrow_2, @jack_sparrow_1]
+      @jack_sparrow_1.high_scorers.game_users_around.should      == [@jerry_potter, @jack_sparrow_2, @jack_sparrow_1, @dark_lord, @albus_dumbelldore]
+      @jack_sparrow_2.high_scorers.game_users_around.should      == [@ivan_potter, @jerry_potter, @jack_sparrow_2, @jack_sparrow_1, @dark_lord]
+      @albus_dumbelldore.high_scorers.game_users_around.should   == [@jack_sparrow_1, @dark_lord, @albus_dumbelldore, @duglous_dumbelldore]
+      @duglous_dumbelldore.high_scorers.game_users_around.should == [@dark_lord, @albus_dumbelldore, @duglous_dumbelldore]
+    end
+  end
+
+  context "Products" do
+    before do
+      Product.delete_all
+      @cell  = Product.create!(name: 'cell', price: 122)
+      @ring  = Product.create!(name: 'ring', price: 14)
+      @shoe  = Product.create!(name: 'shoe', price: 235)
+      @belt  = Product.create!(name: 'belt', price: 21)
+      @watch = Product.create!(name: 'watch', price: 267)
+      @food  = Product.create!(name: 'food', price: 9)
+    end
+
+    it "returns leaderboard objects" do
+      @cell.costliest.should be_an_instance_of(Cheer::Leaderboard)
+      @ring.costliest.should be_an_instance_of(Cheer::Leaderboard)
+      @shoe.costliest.should be_an_instance_of(Cheer::Leaderboard)
+      @belt.costliest.should be_an_instance_of(Cheer::Leaderboard)
+      @watch.costliest.should be_an_instance_of(Cheer::Leaderboard)
+      @food.costliest.should be_an_instance_of(Cheer::Leaderboard)
+    end
+
+    it "returns the current product rank" do
+      @cell.costliest.current_product_rank.should  == 3
+      @ring.costliest.current_product_rank.should  == 5
+      @shoe.costliest.current_product_rank.should  == 2
+      @belt.costliest.current_product_rank.should  == 4
+      @watch.costliest.current_product_rank.should == 1
+      @food.costliest.current_product_rank.should  == 6
+    end
+
+    it "returns the Top products" do
+      @cell.costliest.top_products(2).should == [@watch, @shoe]
+      @cell.costliest.top_products(3).should == [@watch, @shoe, @cell]
+      @cell.costliest.top_products(4).should == [@watch, @shoe, @cell, @belt]
+      @cell.costliest.top_products(5).should == [@watch, @shoe, @cell, @belt, @ring]
+      @cell.costliest.top_products(6).should == [@watch, @shoe, @cell, @belt, @ring, @food]
+      @cell.costliest.top_products(7).should == [@watch, @shoe, @cell, @belt, @ring, @food]
+    end
+
+    it "returns product around the current product" do
+      @cell.costliest.products_around.should  == [@watch, @shoe, @cell, @belt, @ring, @food]
+      @ring.costliest.products_around.should  == [@shoe, @cell, @belt, @ring, @food]
+      @shoe.costliest.products_around.should  == [@watch, @shoe, @cell, @belt, @ring]
+      @belt.costliest.products_around.should  == [@watch, @shoe, @cell, @belt, @ring, @food]
+      @watch.costliest.products_around.should == [@watch, @shoe, @cell, @belt]
+      @food.costliest.products_around.should  == [@cell, @belt, @ring, @food]
+    end
+
+    it "returns leaderboard for the current product" do
+      @cell.costliest.to_hash.should == {
+        current_product_rank: 3,
+        products_around: [@watch, @shoe, @cell, @belt, @ring, @food],
+        top_products: [@watch, @shoe, @cell]
+      }
+
+      @ring.costliest.to_hash(5).should == {
+        current_product_rank: 5,
+        products_around: [@shoe, @cell, @belt, @ring, @food],
+        top_products: [@watch, @shoe, @cell, @belt, @ring]
+      }
+
+      @shoe.costliest.to_hash(2).should == {
+        current_product_rank: 2,
+        products_around: [@watch, @shoe, @cell, @belt, @ring],
+        top_products: [@watch, @shoe]
+      }
+
+      @belt.costliest.to_hash.should == {
+        current_product_rank: 4,
+        products_around: [@watch, @shoe, @cell, @belt, @ring, @food],
+        top_products: [@watch, @shoe, @cell]
+      }
+
+      @watch.costliest.to_hash(4).should == {
+        current_product_rank: 1,
+        products_around: [@watch, @shoe, @cell, @belt],
+        top_products: [@watch, @shoe, @cell, @belt]
+      }
+
+      @food.costliest.to_hash(3).should == {
+        current_product_rank: 6,
+        products_around: [@cell, @belt, @ring, @food],
+        top_products: [@watch, @shoe, @cell]
+      }
+    end
+  end
+
+  # Bad Configurations
+  context "Bad Configuration Options" do
+    before do
+      @klass = Class.new do
+        include ActiveModel::Model
+
+        def self.name; "anonymus"; end
+
+        attr_accessor :score
+
+        extend Cheer::ModelAdditions
+
+        def self.column_names; ["score"]; end
+      end
+    end
+
+    it "fails if column_name is blank" do
+      @klass.class_eval do
+        # Without primary column name
+        leaderboard :bad_config, column_name: '',
+                                 sort_order: ["name", "age DESC"],
+                                 around_limit: 2
+      end
+
+      lambda {
+        @klass.new(score: 5).bad_config
+      }.should raise_error(Cheer::Error::InvalidColumnName)
+    end
+
+    it "fails if column_name is not a database column" do
+      @klass.class_eval do
+        leaderboard :bad_config, column_name: :im_not_in_db,
+                                 sort_order: ["name", "age DESC"],
+                                 around_limit: 2
+      end
+
+      lambda {
+        @klass.new(score: 5).bad_config
+      }.should raise_error(Cheer::Error::InvalidColumnName)
+    end
+
+    it "fails if sort_order is not an array" do
+      @klass.class_eval do
+        # Invalid sort order
+        leaderboard :bad_config, column_name: :score,
+                                 sort_order: "name",
+                                 around_limit: 2
+      end
+
+      lambda {
+        @klass.new(score: 5).bad_config
+      }.should raise_error(Cheer::Error::InvalidSortOrder)
+    end
+
+    it "fails if around_limit is zero or less" do
+      @klass.class_eval do
+        # Invalid around limit
+        leaderboard :bad_config, column_name: :score,
+                                 sort_order: ["name", "age DESC"],
+                                 around_limit: [0, -1, -2].sample
+      end
+
+      lambda {
+        @klass.new(score: 5).bad_config
+      }.should raise_error(Cheer::Error::InvalidAroundLimit)
+    end
+  end
+
+  describe ".leaderboard" do
+    before do
+      Developer.delete_all
+      @aaron = Developer.create!(name: 'Aaron Patterson', ruby_gems_created: 100, total_experience: 15)
+      @corey = Developer.create!(name: 'Corey Haines', ruby_gems_created: 90, total_experience: 20)
+      @jim   = Developer.create!(name: 'Jim Weirich', ruby_gems_created: 50, total_experience: 30)
+    end
+
+    it "returns leaderboard objects" do
+      @aaron.ruby_heroes.should be_an_instance_of(Cheer::Leaderboard)
+      @corey.ruby_heroes.should be_an_instance_of(Cheer::Leaderboard)
+      @jim.ruby_heroes.should be_an_instance_of(Cheer::Leaderboard)
+    end
+
+    context "#current_developer_rank" do
+      it "returns current rank" do
+        @aaron.ruby_heroes.current_developer_rank == 1
+        @corey.ruby_heroes.current_developer_rank == 2
+        @jim.ruby_heroes.current_developer_rank   == 3
+      end
+    end
+
+    context "#developers_around" do
+      it "returns developers around" do
+        @aaron.ruby_heroes.developers_around == [ @aaron, @corey, @jim ]
+        @corey.ruby_heroes.developers_around == [ @aaron, @corey, @jim ]
+        @jim.ruby_heroes.developers_around   == [ @aaron, @corey, @jim ]
+      end
+    end
+
+    context "#top_developers" do
+      it "returns top developers" do
+        @aaron.ruby_heroes.top_developers    == [ @aaron, @corey, @jim ]
+        @corey.ruby_heroes.top_developers(2) == [ @aaron, @corey ]
+        @jim.ruby_heroes.top_developers(1)   == [ @aaron ]
+      end
+    end
+
+    context "#to_hash method" do
+      it "returns leaderboard hash" do
+        @aaron.ruby_heroes.to_hash.should == {
+          current_developer_rank: 1,
+          developers_around: [ @aaron, @corey, @jim ],
+          top_developers: [ @aaron, @corey, @jim ]
+        }
+        @corey.ruby_heroes.to_hash(1).should == {
+          current_developer_rank: 2,
+          developers_around: [ @aaron, @corey, @jim ],
+          top_developers: [ @aaron ]
+        }
+        @jim.ruby_heroes.to_hash(2).should == {
+          current_developer_rank: 3,
+          developers_around: [ @aaron, @corey, @jim ],
+          top_developers: [ @aaron, @corey ]
+        }
+      end
+
+      it "returns leaderboard hash" do
+        @aaron.veterans.to_hash(2).should == {
+          current_developer_rank: 3,
+          developers_around: [ @corey, @aaron ],
+          top_developers: [ @jim, @corey ]
+        }
+        @corey.veterans.to_hash.should == {
+          current_developer_rank: 2,
+          developers_around: [ @jim, @corey, @aaron ],
+          top_developers: [ @jim, @corey, @aaron ]
+        }
+        @jim.veterans.to_hash(1).should == {
+          current_developer_rank: 1,
+          developers_around: [ @jim, @corey ],
+          top_developers: [ @jim ]
+        }
+      end
+    end
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,96 @@
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# Require this file using `require "spec_helper"` to ensure that it is only
+# loaded once.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+$:.unshift File.dirname(__FILE__) + '/../lib'
+
+require 'active_record'
+require 'sqlite3'
+require 'cheer'
+
+ActiveRecord::Base.establish_connection(
+  adapter: "sqlite3",
+  database: ":memory:"
+)
+
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.order = 'random'
+  config.filter_run :focus
+  config.run_all_when_everything_filtered = true
+end
+
+ActiveRecord::Migration.verbose = false
+
+ActiveRecord::Schema.define do
+  create_table :game_users do |t|
+    t.string :name
+    t.float :score, default: 0.0
+    t.integer :age, default: 20
+    t.timestamps
+  end
+
+  create_table :products do |t|
+    t.string :name
+    t.float :price, default: 0.0
+    t.integer :review, default: 1
+    t.timestamps
+  end
+
+  create_table :students do |t|
+    t.string :name
+    t.float :score, default: 0.0
+    t.integer :age, default: 5
+    t.timestamps
+  end
+
+  create_table :developers do |t|
+    t.string :name
+    t.float :total_experience, default: 0.0
+    t.integer :ruby_gems_created, default: 0
+    t.timestamps
+  end
+end
+
+class GameUser < ActiveRecord::Base
+  extend Cheer::ModelAdditions
+
+  # leaderboard leaderboard_name, {:column_name, :sort_order, :around_limit}
+  # Default Sort Order will be ID for game_users with equal score.
+  leaderboard :high_scorers, column_name: :score,
+                             sort_order: ["name", "age DESC"],
+                             around_limit: 2
+end
+
+class Product < ActiveRecord::Base
+  extend Cheer::ModelAdditions
+
+  # leaderboard leaderboard_name, {:column_name, :sort_order, :around_limit}
+  # Default Sort Order will be ID for products with equal price.
+  leaderboard :costliest, column_name: :price,
+                          sort_order: %w(name),
+                          around_limit: 3
+end
+
+class Student < ActiveRecord::Base
+  extend Cheer::ModelAdditions
+
+  # leaderboard leaderboard_name, {:column_name, :sort_order, :around_limit}
+  # Default Sort Order will be ID for students with equal score.
+  leaderboard :topers, column_name: :score
+end
+
+class Developer < ActiveRecord::Base
+  extend Cheer::ModelAdditions
+
+  # leaderboard leaderboard_name, {:column_name, :sort_order, :around_limit}
+  leaderboard :ruby_heroes, column_name: :ruby_gems_created,
+                            sort_order: %w(name),
+                            around_limit: 3
+
+  leaderboard :veterans, column_name: 'total_experience',
+                         sort_order: %w(name),
+                         around_limit: 1
+end

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: cheer
+version: !ruby/object:Gem::Version
+  version: 1.0.4
+platform: ruby
+authors:
+- Eos Software Systems Pvt Ltd
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-02-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.14'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+description: A ruby gem to quickly add rankings & leaderboards to existing models
+  in a rails application
+email:
+- info@eossys.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- .ruby-gemset
+- .ruby-version
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- cheer.gemspec
+- lib/cheer.rb
+- lib/cheer/argument.rb
+- lib/cheer/error.rb
+- lib/cheer/leaderboard.rb
+- lib/cheer/model_additions.rb
+- lib/cheer/rank_evaluator.rb
+- lib/cheer/version.rb
+- spec/cheer_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/eossys/cheer
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.1
+signing_key: 
+specification_version: 4
+summary: A ruby gem to quickly add rankings & leaderboards to existing models in a
+  rails application
+test_files:
+- spec/cheer_spec.rb
+- spec/spec_helper.rb