activerecord-reputation-system 1.5.1 → 2.0.0

data/README.md

@@ -4,10 +4,12 @@ The Active Record Reputation System helps you discover more about your applicati
 
 ## Installation
 
+* If you are updating to version 2 from version older, you should check out [migration guide](https://github.com/twitter/activerecord-reputation-system/wiki/Migrate-to-Version-2.0).
+
 Add to Gemfile:
 
 ```ruby
-gem 'activerecord-reputation-system', :require => 'reputation_system'
+gem 'activerecord-reputation-system'
 ```
 
 Run:
@@ -20,7 +22,7 @@ rake db:migrate
 
 * Please do the installation on every upgrade as it may include new migration files.
 
-## Usage Example
+## Quick Start 
 
 Let's say we want to keep track of user karma in Q&A site where user karma is sum of questioning skill and answering skill. Questioning skill is sum of votes for user's questions and Answering skill is sum of average rating of user's answers. This can be defined as follow:
 ```ruby
@@ -31,16 +33,13 @@ class User < ActiveRecord::Base
   has_reputation :karma,
       :source => [
           { :reputation => :questioning_skill, :weight => 0.8 },
-          { :reputation => :answering_skill }],
-      :aggregated_by => :sum
+          { :reputation => :answering_skill }]
 
   has_reputation :questioning_skill,
-      :source => { :reputation => :votes, :of => :questions },
-      :aggregated_by => :sum
+      :source => { :reputation => :votes, :of => :questions }
 
   has_reputation :answering_skill,
-      :source => { :reputation => :avg_rating, :of => :answers },
-      :aggregated_by => :sum
+      :source => { :reputation => :avg_rating, :of => :answers }
 end
 
 class Answer < ActiveRecord::Base
@@ -57,8 +56,7 @@ class Question < ActiveRecord::Base
   belongs_to :user
 
   has_reputation :votes,
-      :source => :user,
-      :aggregated_by => :sum
+      :source => :user
 end
 ```
 
@@ -70,204 +68,46 @@ Once reputation system is defined, evaluations for answers and questions can be
 
 Reputation value can be accessed as follow:
 ```ruby
-@answer.reptuation_for(:avg_rating)
-@question.reptuation_for(:votes)
+@answer.reptuation_for(:avg_rating) #=> 3
+@question.reptuation_for(:votes) #=> 1
 @user.reptuation_for(:karma)
 ```
 
-## Defining Reputation System
-
-All reputations can be defined in their target ActiveRecord models like this:
-```ruby
-# Primary Reputation
-has_reputation  :name,
-        :source => source,
-        :aggregated_by => process,
-        :source_of => [{:reputation => name, :of => attribute}, ...],
-        :init_value => initial_value
-
-# Non Primary Reputation
-has_reputation  :name,
-        :source => [{:reputation => name, :of => attribute, :weight => weight}, ...],
-        :aggregated_by => process,
-        :source_of => [{:reputation => name, :of => attribute}, ...],
-        :init_value => initial_value
-```
-* `:name` is the name of the reputation.
-* `:source` is a source of the reputation. If it is primary reputation, it takes a class name as input. If it's a non-primary reputation, it takes one or more source definitions, which consist of:
-    * `:reputation` - name of reputation to be used as a source.
-    * `:of` - attribute name (It also accepts a proc as an argument) of the ActiveRecord model which has the source reputation. (default: :self)
-    * `:weight` (optional) - weight value to be used for aggregation (default: 1).
-* `:aggregated_by` is a mathematical process to be used to aggregate reputation or evaluation values. The following processes are available (each value is weighted by a predefined weight):
-    * average - averages all values received.
-    * sum - sums up all the values received.
-    * product - multiplies all the values received.
-* `:source_of` (optional) - just like active record association, you don't need to define this if a name can be derived from class name; otherwise if the reputation is used as a part of a source belonging to other reputations, you must define. It takes one or more source definitions, which consists of:
-    * `:reputation` - name of the reputation to be used as a source.
-    * `:of` - attribute name (It also accepts a proc as an argument) of the ActiveRecord model which has the source reputation. (default: :self)
-* `:init_value` (optional) - initial reputation value assigned to new reputation. It is 0 for average and sum process and 1 for product by default.
-
-## Evaluation
+You can query for records using reputation value:
 ```ruby
-# Adds an evaluation to the reputation with the specified name.
-add_evaluation(reputation_name, evaluation_value, source)
-
-# Updates an existing evaluation of the reputation with the specified name by the specified source.
-update_evaluation(reputation_name, evaluation_value, source)
-
-# Adds an evaluation to the reputation with the specified name if it exists; otherwise it updates the existing reputation.
-add_or_update_evaluation(reputation_name, evaluation_value, source)
-
-# Deletes an evaluation from the reputation with the specified name submitted by the specified source. It returns nil if it does not exist.
-delete_evaluation(reputation_name, source)
-
-# Deletes an evaluation from the reputation with the specified name submitted by specified source. Raises an exception if it does not exist.
-delete_evaluation!(reputation_name, source)
-
-# Increase an evaluation value of the reputation with the specified name by given value.
-increase_evaluation(reputation_name, value, source)
-
-# Decrease an evaluation value of the reputation with the specified name by given value.
-decrease_evaluation(reputation_name, value, source)
+@user.with_reputation(:karma).where('karma > 10')
 ```
 
-## Reputation
+You can get source records that have evaluated the target record:
 ```ruby
-# Returns the reputation value of the reputation with the given name.
-reptuation_for(reputation_name)
-
-# Returns the reputation rank of the reputation with the given name.
-rank_for(reputation_name)
-
-# Returns the normalized reputation value of the reputation with the given name. The normalization is computed using the following equation (assuming linear distribution):
-# normalized_value = (x - min) / (max - min) if max - min&nbsp;is not 0
-# normalized_value = 1 if max - min is 0
-normalized_reptuation_for(reputation_name)
-
-# Activates all reputations in the record. Active reputations are used when computing ranks or normalized reputation values.
-activate_all_reputations
-
-# Deactivates all reputations in the record. Inactive reputations are not used when computing ranks or normalized reputation values.
-deactivate_all_reputations
-
-# Checks if reputation is active.
-reputations_activated?(reputation_name)
+@question.evaluators_for(:votes) #=> [@user]
 ```
 
-## Querying with Reputation
-
-``` ruby
-# Includes the specified reputation value for the given name.
-ActiveRecord::Base.with_reputation(reputation_name, scope)
-# For example:
-User.with_reputation(:karma).where("karma > ?", 3).order("karma")
-
-# Includes the specified normalized reputation value for the given name.
-ActiveRecord::Base.with_normalized_reputation(reputation, scope)
-# For example:
-User.with_normalized_reputation(:karma).where("karma > ?" > 0.5).order("karma")
-```
-Note: Above query methods does not support calcualtion methods such as count, sum and etc yet.
-
+You can get target records that have been evaluated by a given source record:
 ```ruby
-# Includes the specified reputation value for the given name via a normal Active Record find query.
-ActiveRecord::Base.find_with_reputation(reputation_name, find_scope, options)
-# For example:
-User.find_with_reputation(:karma, :all, {:select => "id", :conditions => ["karma > ?", 3], :order => "karma"})
-
-# Includes the specified normalized reputation value for the given name via a normal Active Record find query.
-ActiveRecord::Base.find_with_normalized_reputation(reputation_name, find_options)
-# For example:
-User.find_with_normalized_reputation(:karma, :all, {:select => "id", :conditions => ["karma > ?", 0.5], :order => "karma"})
-
-# Includes the specified reputation value for the given name via a normal Active Record count query.
-ActiveRecord::Base.count_with_reputation(reputation_name, find_options)
-
-# This method returns a SQL statement rather than a query result.
-ActiveRecord::Base.find_with_reputation_sql(reputation_name, find_options)
+Question.evaluated_by(:votes, @user) #=> [@question]
 ```
 
-## Querying for Evaluated ActiveRecord
-```ruby
-# Returns all active record instances evaluated by a given source for a given reputation name.
-ActiveRecord::Base.evaluated_by(reputation_name, source)
-# For example:
-Question.evaluated_by(:votes, @user)
-```
-
-## Advanced Topics
-### Scope
-Reputations can have different scopes to provide additional context.
+## Documentation
 
-For example, let's say `question` has a reputation called `difficulty`.  You might want to keep track of that reputation by country, such that each question has a different difficulty rating in each country.
+Please refer [Wiki](https://github.com/twitter/activerecord-reputation-system/wiki) for available APIs.
 
-Scopes can be defined like this:
-```ruby
-has_reputation :name,
-    ...
-    :scopes => [:scope1, :scope2, ...]
-```
-Once scopes are defined, evaluations can be added in the context of defined scopes:
-```ruby
-add_evaluation(:reputation_name, evaluation_value, source, :scope)
-```
-Also, reputations can be accessed in the context of scopes:
-```ruby
-reptuation_for(:reputation_name, :scope)
-```
-To use a scoped reputation as a source in another reputation, try this:
-```ruby
-has_reputation :rep1,
-    :source => {:reputation => :rep2, :scope => :scope1}
-    ...
-has_reputation :rep2,
-    ...
-    :scopes => [:scope1, :scope2, ...],
-    :source_of => {:reputation => :rep1, :defined_for_scope => [:scope1]}
-```
-To execute an Active Record query using a scoped reputation, try this:
-```ruby
-ActiveRecord::Base.find_with_reputation(:reputation_name, :scope, :find_options)
-```
-To find active records evaluated by a given source for a scoped reputation, try this:
-```ruby
-ActiveRecord::Base.evaluated_by(:reputation_name, source, :scope)
-```
-There are a few more helper methods available for scopes:
-```ruby
-# Allows you to add a scope dynamically.
-add_scope_for(reputation_name, scope)
-
-# Returns true if the reputation has scopes.
-has_scopes?(reputation_name)
-
-# Returns true if the reputation has a given scope.
-has_scope?(reputation_name, scope)
-```
-
-### Performance
-
-For applications with large data set, computation of reputation values can be expensive. Therefore, it is common to perform the computation asynchronously (in batch). If you wish to asynchronously compute reputation values, I strongly recommend you to use [collectiveidea's Delayed Job](https://github.com/collectiveidea/delayed_job). For example:
-
-```ruby
-class User < ActiveRecord
-  has_reputation :karma,
-    :source => :user,
-    :aggregated_by => :sum
+## Authors
 
-  handle_asynchronously :add_evaluation
-  handle_asynchronously :update_evaluation
-  handle_asynchronously :delete_evaluation
-end
-```
+Katsuya Noguchi
+* [http://twitter.com/kn](http://twitter.com/kn)
+* [http://github.com/katsuyan](http://github.com/katsuyan)
 
-### Reflect Past Data
+## Contributors
 
-If you wish to reflect past data into new reputation system, I recommend you write a script which simulates all evaluations that would have happened in the past. You probably want to use [collectiveidea's Delayed Job](https://github.com/collectiveidea/delayed_job) to enqueue those past evaluation tasks first and then new ongoing evaluation task so that evaluations are performed in proper time sequence.
+1. [NARKOZ (Nihad Abbasov)](https://github.com/NARKOZ) - 4 commits
+2. [elitheeli (Eli Fox-Epstein)](https://github.com/elitheeli) - 1 commit
+3. [amrnt (Amr Tamimi)](https://github.com/amrnt) - 1 commit
 
-## Running Tests
+## Related Links
 
-`rake` should do the trick. Tests are written in RSpec.
+* RailsCasts: http://railscasts.com/episodes/364-active-record-reputation-system
+* Inspired by ["Building Web Reputation Systems" by Randy Farmer and Bryce Glass](http://shop.oreilly.com/product/9780596159801.do)
 
 ## Versioning
 
@@ -283,15 +123,6 @@ And constructed with the following guidelines:
 
 For more information on semantic versioning, please visit http://semver.org/.
 
-## Authors
-
-* Katsuya Noguchi: http://github.com/katsuyan
-* Inspired by ["Building Web Reputation Systems" by Randy Farmer and Bryce Glass](http://shop.oreilly.com/product/9780596159801.do)
-
-## Related Links
-
-* RailsCasts: http://railscasts.com/episodes/364-active-record-reputation-system
-
 ## License
 
 Copyright 2012 Twitter, Inc.

data/lib/activerecord-reputation-system.rb

@@ -0,0 +1 @@
+require 'reputation_system'

data/lib/reputation_system.rb

@@ -18,12 +18,12 @@ require 'reputation_system/base'
 require 'reputation_system/query_methods'
 require 'reputation_system/finder_methods'
 require 'reputation_system/query_builder'
-require 'reputation_system/evaluation'
+require 'reputation_system/evaluation_methods'
 require 'reputation_system/network'
-require 'reputation_system/reputation'
-require 'reputation_system/scope'
-require 'models/rs_evaluation'
-require 'models/rs_reputation'
-require 'models/rs_reputation_message'
+require 'reputation_system/reputation_methods'
+require 'reputation_system/scope_methods'
+require 'reputation_system/models/evaluation'
+require 'reputation_system/models/reputation'
+require 'reputation_system/models/reputation_message'
 
 ActiveRecord::Base.send(:include, ReputationSystem::Base)

data/lib/reputation_system/base.rb

@@ -40,7 +40,7 @@ module ReputationSystem
 
     module ClassMethods
       def has_reputation(reputation_name, options)
-        has_valid_input = reputation_name && options[:aggregated_by] && options[:source]
+        has_valid_input = reputation_name && options[:source]
 
         raise ArgumentError, "has_reputation method received invalid arguments." unless has_valid_input
         # Overwrites reputation if the same reputation name is declared in the same model.
@@ -48,19 +48,29 @@ module ReputationSystem
         ReputationSystem::Network.remove_reputation_def(name, reputation_name) if has_reputation_for?(reputation_name)
 
         # If it is first time to be called
-        unless ancestors.include?(ReputationSystem::Reputation)
-          has_many :reputations, :as => :target, :class_name => "RSReputation", :dependent => :destroy
+        unless ancestors.include?(ReputationSystem::ReputationMethods)
+          has_many :reputations, :as => :target, :class_name => "ReputationSystem::Reputation", :dependent => :destroy do
+            def for(reputation_name)
+              self.where(:reputation_name => reputation_name)
+            end
+          end
+          has_many :evaluations, :as => :target, :class_name => "ReputationSystem::Evaluation", :dependent => :destroy do
+            def for(reputation_name)
+              self.where(:reputation_name => reputation_name)
+            end
+          end
+
           include ReputationSystem::QueryBuilder
           include ReputationSystem::QueryMethods
           include ReputationSystem::FinderMethods
-          include ReputationSystem::Reputation
-          include ReputationSystem::Scope
+          include ReputationSystem::ReputationMethods
+          include ReputationSystem::ScopeMethods
         end
 
         ReputationSystem::Network.add_reputation_def(name, reputation_name, options)
 
         # evaluation related methods are defined only for primary reputations
-        include ReputationSystem::Evaluation if ReputationSystem::Network.is_primary_reputation?(name, reputation_name) && !ancestors.include?(ReputationSystem::Evaluation)
+        include ReputationSystem::EvaluationMethods if ReputationSystem::Network.is_primary_reputation?(name, reputation_name) && !ancestors.include?(ReputationSystem::EvaluationMethods)
       end
 
       def has_reputation_for?(reputation_name)

data/lib/reputation_system/{evaluation.rb → evaluation_methods.rb}

@@ -15,7 +15,7 @@
 ##
 
 module ReputationSystem
-  module Evaluation
+  module EvaluationMethods
     module ClassMethods
       def evaluated_by(reputation_name, source, *args)
         scope = args.first
@@ -33,13 +33,26 @@ module ReputationSystem
       klass.extend ClassMethods
     end
 
+    def has_evaluation?(reputation_name, source, *args)
+      scope = args.first
+      srn = ReputationSystem::Network.get_scoped_reputation_name(self.class.name, reputation_name, scope)
+      !!ReputationSystem::Evaluation.find_by_reputation_name_and_source_and_target(srn, source, self)
+    end
+
+
+    def evaluators_for(reputation_name, *args)
+      scope = args.first
+      srn = ReputationSystem::Network.get_scoped_reputation_name(self.class.name, reputation_name, scope)
+      self.evaluations.for(srn).includes(:source).map(&:source)
+    end
+
     def add_evaluation(reputation_name, value, source, *args)
       scope = args.first
       srn = ReputationSystem::Network.get_scoped_reputation_name(self.class.name, reputation_name, scope)
       process = ReputationSystem::Network.get_reputation_def(self.class.name, srn)[:aggregated_by]
-      evaluation = RSEvaluation.create_evaluation(srn, value, source, self)
-      rep = RSReputation.find_or_create_reputation(srn, self, process)
-      RSReputation.update_reputation_value_with_new_source(rep, evaluation, 1, process)
+      evaluation = ReputationSystem::Evaluation.create_evaluation(srn, value, source, self)
+      rep = ReputationSystem::Reputation.find_or_create_reputation(srn, self, process)
+      ReputationSystem::Reputation.update_reputation_value_with_new_source(rep, evaluation, 1, process)
     end
 
     def update_evaluation(reputation_name, value, source, *args)
@@ -48,13 +61,14 @@ module ReputationSystem
       evaluation.value = value
       evaluation.save!
       process = ReputationSystem::Network.get_reputation_def(self.class.name, srn)[:aggregated_by]
-      rep = RSReputation.find_by_reputation_name_and_target(srn, self)
-      RSReputation.update_reputation_value_with_updated_source(rep, evaluation, oldValue, 1, process)
+      rep = ReputationSystem::Reputation.find_by_reputation_name_and_target(srn, self)
+      newSize = rep.received_messages.size
+      ReputationSystem::Reputation.update_reputation_value_with_updated_source(rep, evaluation, oldValue, newSize, 1, process)
     end
 
     def add_or_update_evaluation(reputation_name, value, source, *args)
       srn, evaluation = find_srn_and_evaluation(reputation_name, source, args.first)
-      if RSEvaluation.exists? :reputation_name => srn, :source_id => source.id, :source_type => source.class.name, :target_id => self.id, :target_type => self.class.name
+      if ReputationSystem::Evaluation.exists? :reputation_name => srn, :source_id => source.id, :source_type => source.class.name, :target_id => self.id, :target_type => self.class.name
         self.update_evaluation(reputation_name, value, source, *args)
       else
         self.add_evaluation(reputation_name, value, source, *args)
@@ -63,7 +77,11 @@ module ReputationSystem
 
     def delete_evaluation(reputation_name, source, *args)
       srn, evaluation = find_srn_and_evaluation(reputation_name, source, args.first)
-      delete_evaluation_without_validation(srn, evaluation) if evaluation
+      if evaluation
+        !!delete_evaluation_without_validation(srn, evaluation)
+      else
+        false
+      end
     end
 
     def delete_evaluation!(reputation_name, source, *args)
@@ -82,7 +100,7 @@ module ReputationSystem
     protected
       def find_srn_and_evaluation(reputation_name, source, scope)
         srn = ReputationSystem::Network.get_scoped_reputation_name(self.class.name, reputation_name, scope)
-        evaluation = RSEvaluation.find_by_reputation_name_and_source_and_target(srn, source, self)
+        evaluation = ReputationSystem::Evaluation.find_by_reputation_name_and_source_and_target(srn, source, self)
         return srn, evaluation
       end
 
@@ -93,7 +111,7 @@ module ReputationSystem
       end
 
       def find_evaluation!(reputation_name, srn, source)
-        evaluation = RSEvaluation.find_by_reputation_name_and_source_and_target(srn, source, self)
+        evaluation = ReputationSystem::Evaluation.find_by_reputation_name_and_source_and_target(srn, source, self)
         raise ArgumentError, "Given instance of #{source.class.name} has not evaluated #{reputation_name} of the instance of #{self.class.name} yet." unless evaluation
         evaluation
       end
@@ -102,15 +120,16 @@ module ReputationSystem
         process = ReputationSystem::Network.get_reputation_def(self.class.name, srn)[:aggregated_by]
         oldValue = evaluation.value
         evaluation.value = process == :product ? 1 : 0
-        rep = RSReputation.find_by_reputation_name_and_target(srn, self)
-        RSReputation.update_reputation_value_with_updated_source(rep, evaluation, oldValue, 1, process)
+        rep = ReputationSystem::Reputation.find_by_reputation_name_and_target(srn, self)
+        newSize = rep.received_messages.size - 1
+        ReputationSystem::Reputation.update_reputation_value_with_updated_source(rep, evaluation, oldValue, newSize, 1, process)
         evaluation.destroy
       end
 
       def change_evaluation_value_by(reputation_name, value, source, *args)
         scope = args.first
         srn = ReputationSystem::Network.get_scoped_reputation_name(self.class.name, reputation_name, scope)
-        evaluation = RSEvaluation.find_by_reputation_name_and_source_and_target(srn, source, self)
+        evaluation = ReputationSystem::Evaluation.find_by_reputation_name_and_source_and_target(srn, source, self)
         if evaluation.nil?
           self.add_evaluation(reputation_name, value, source, scope)
         else