ballot 1.0

data/bin/ballot_generator

@@ -0,0 +1,9 @@
+#! /usr/bin/env ruby
+# frozen_string_literal: true
+
+git_path = File.expand_path('../../.git', __FILE__)
+$LOAD_PATH.unshift(File.expand_path('../../lib', __FILE__)) if File.exist?(git_path)
+
+require 'generators/ballot/standalone'
+
+exit Ballot::Generators::Standalone.run(ARGV).to_i

data/lib/ballot.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+##
+# Ballot provides a two-way polymorphic scoped voting mechanism for both
+# ActiveRecord (4 or later) and Sequel (4 or later).
+#
+# -   Two-way polymorphic: any model can be a voter or a votable.
+# -   Scoped: multiple votes can be recorded for a votable, under different
+#     scopes.
+#
+# The API for Ballot is consistent across both supported ORMs.
+module Ballot
+  VERSION = '1.0' #:nodoc:
+end
+
+#:stopdoc:
+require 'ballot/words'
+require 'ballot/sequel' if defined?(::Sequel::Model)
+if defined?(::Rails)
+  require 'ballot/railtie'
+elsif defined?(::ActiveRecord::Base)
+  require 'ballot/active_record'
+  Ballot::ActiveRecord.inject!
+end
+#:startdoc:

data/lib/ballot/action_controller.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+##
+module Ballot
+  # Extensions to \ActionController to support the use of Ballot in a Rails
+  # application.
+  module ActionController
+    # Provide a consistent way to extract ballot parameters from request
+    # parameters. The +ballot+ defaults to <tt>params[:ballot]</tt>.
+    #
+    # It permits:
+    #
+    # *   Votables to be described by type and id (+:votable_type+,
+    #     +:votable_id+), a GlobalID locator (+:votable_gid+), or an object
+    #     (+:votable+).
+    # *   Voters to be described by type and id (+:voter_type+, +:voter_id+), a
+    #     GlobalID locator (+:voter_gid+), or an object (+:voter+).
+    # *   The recorded vote (+:vote+, a word or value that means true or false,
+    #     see Ballot::Words).
+    # *   The scope for the vote (+:scope+).
+    # *   The weight for the vote (+:weight+).
+    def ballot_params(ballot = params[:ballot])
+      ballot.permit(
+        :votable_type, :votable_id, :votable_gid, :votable,
+        :voter_type, :voter_id, :voter_gid, :voter,
+        :vote,
+        :scope,
+        :weight
+      )
+    end
+  end
+end

data/lib/ballot/active_record.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+##
+module Ballot
+  # Extensions to \ActiveRecord to support Ballot.
+  module ActiveRecord
+    # Class method extensions to \ActiveRecord to support Ballot.
+    module ClassMethods
+      # ActiveRecord classes are not votable by default.
+      def ballot_votable?
+        false
+      end
+
+      # ActiveRecord classes are not voters by default.
+      def ballot_voter?
+        false
+      end
+
+      # The primary macro for marking an ActiveRecord class as votable.
+      def acts_as_ballot(*types)
+        types.each do |type|
+          case type.to_s
+          when 'votable'
+            require 'ballot/active_record/votable'
+            next if self < Ballot::ActiveRecord::Votable
+            include Ballot::ActiveRecord::Votable
+          when 'voter'
+            require 'ballot/active_record/voter'
+            next if self < Ballot::ActiveRecord::Voter
+            include Ballot::ActiveRecord::Voter
+          end
+        end
+      end
+
+      # A shorthand version of <tt>acts_as_ballot :votable</tt>.
+      def acts_as_ballot_votable
+        acts_as_ballot :votable
+      end
+
+      # A shorthand version of <tt>acts_as_ballot :voter</tt>.
+      def acts_as_ballot_voter
+        acts_as_ballot :voter
+      end
+    end
+
+    # Delegate the question of #votable? to the class.
+    def ballot_votable?
+      self.class.ballot_votable?
+    end
+
+    # Delegate the question of #voter? to the class.
+    def ballot_voter?
+      self.class.ballot_voter?
+    end
+
+    class << self
+      # Put Ballot into ActiveRecord::Base.
+      def inject!
+        ::ActiveRecord::Base.instance_eval do
+          return if self < Ballot::ActiveRecord
+
+          include ::Ballot::ActiveRecord
+          extend ::Ballot::ActiveRecord::ClassMethods
+        end
+        require 'ballot/active_record/vote'
+      end
+
+      # Respond with the canonical name for this model. Will be the root class
+      # if an STI model.
+      def type_name(model)
+        return model if model.kind_of?(String)
+        model = model.class if model.kind_of?(::ActiveRecord::Base)
+        model.base_class.name
+      end
+
+      # Return a valid Votable object from the provided item or +nil+.
+      # Permitted values are a Votable, a hash with the key +:votable+, or a
+      # hash with the keys +:votable_type+ and +:votable_id+.
+      def votable_for(item)
+        votable =
+          if item.kind_of?(::Ballot::ActiveRecord::Votable)
+            item
+          elsif item.kind_of?(Hash)
+            if item[:votable]
+              item[:votable]
+            elsif item[:votable_type] && item[:votable_id]
+              __instance_of_model(item[:votable_type], item[:votable_id])
+            elsif item[:votable_gid]
+              fail 'GlobalID is not enabled.' unless defined?(::GlobalID)
+
+              # This should actually be GlobalID::Sequel::Locator when I
+              # get that ported.
+              GlobalID::Locator.locate(item[:votable_gid])
+            end
+          end
+
+        votable if votable && votable.kind_of?(::ActiveRecord::Base) &&
+            votable.ballot_votable?
+      end
+
+      # Return the id and canonical votable type name for the item, using
+      # #votable_for.
+      def votable_id_and_type_name_for(item)
+        __id_and_type_name(votable_for(item))
+      end
+
+      # Return a valid Voter object from the provided item or +nil+. Permitted
+      # values are a Voter, a hash with the key +:voter+, or a hash with the
+      # keys +:voter_type+ and +:voter_id+.
+      def voter_for(item)
+        voter =
+          if item.kind_of?(::Ballot::ActiveRecord::Voter)
+            item
+          elsif item.kind_of?(Hash)
+            if item[:voter]
+              item[:voter]
+            elsif item[:voter_type] && item[:voter_id]
+              __instance_of_model(item[:voter_type], item[:voter_id])
+            elsif item[:voter_gid]
+              fail 'GlobalID is not enabled.' unless defined?(::GlobalID)
+
+              # This should actually be GlobalID::Sequel::Locator when I
+              # get that ported.
+              GlobalID::Locator.locate(item[:voter_gid])
+            end
+          end
+
+        voter if voter && voter.kind_of?(::ActiveRecord::Base) &&
+            voter.ballot_voter?
+      end
+
+      # Return the id and canonical voter type name for the item, using
+      # #voter_for.
+      def voter_id_and_type_name_for(item)
+        __id_and_type_name(voter_for(item))
+      end
+
+      private
+
+      # Return the id and canonical type name for the item.
+      def __id_and_type_name(item)
+        [ item.id, type_name(item) ] if item
+      end
+
+      def __instance_of_model(model, id)
+        model.constantize.find(id)
+      rescue
+        nil
+      end
+    end
+  end
+end

data/lib/ballot/active_record/votable.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+##
+module Ballot
+  module ActiveRecord
+    # The Ballot::ActiveRecord::Votable module is the ActiveRecord-specific
+    # implementation to enable Ballot::Votable for ActiveRecord.
+    module Votable
+      def self.included(model) #:nodoc:
+        require 'ballot/active_record/vote'
+        require 'ballot/words'
+        require 'ballot/votable'
+
+        model.class_eval do
+          # NOTE: This should only be done when Postgres JSON support is not
+          # enabled.
+          serialize :cached_ballot_summary, JSON
+
+          has_many :ballots_for,
+            class_name: '::Ballot::ActiveRecord::Vote',
+            as: :votable,
+            dependent: :destroy
+
+          include Ballot::Votable
+          extend Ballot::Votable::ClassMethods
+        end
+      end
+
+      def ballot_by(voter = nil, kwargs = {}) #:nodoc:
+        kwargs = { vote: true, scope: nil }.
+          merge(__ballot_votable_kwargs(voter, kwargs))
+        self.ballot_registered = false
+
+        voter_id, voter_type = Ballot::ActiveRecord.voter_id_and_type_name_for(kwargs)
+        return false unless voter_id
+
+        votes_ = find_ballots_for(
+          scope: kwargs[:scope],
+          voter_id: voter_id,
+          voter_type: voter_type
+        )
+
+        vote = if votes_.none? || kwargs[:duplicate]
+                 Ballot::ActiveRecord::Vote.new(
+                   votable: self,
+                   voter_id: voter_id,
+                   voter_type: voter_type,
+                   scope: kwargs[:scope]
+                 )
+               else
+                 votes_.last
+               end
+
+        flag = Ballot::Words.truthy?(kwargs[:vote])
+        weight = kwargs[:weight] && kwargs[:weight].to_i || 1
+
+        return false if vote.vote == flag && vote.weight == weight
+
+        vote.vote = flag
+        vote.weight = weight
+
+        transaction do
+          if vote.save
+            self.ballot_registered = true
+            update_cached_votes kwargs[:scope]
+            true
+          end
+        end
+      end
+
+      def remove_ballot_by(voter = nil, kwargs = {}) #:nodoc:
+        kwargs = __ballot_votable_kwargs(voter, kwargs)
+        voter_id, voter_type = Ballot::ActiveRecord.voter_id_and_type_name_for(kwargs)
+        return false unless voter_id
+
+        votes_ = find_ballots_for(
+          scope: kwargs[:scope],
+          voter_id: voter_id,
+          voter_type: voter_type
+        )
+
+        return true if votes_.none?
+
+        transaction do
+          votes_.each(&:destroy)
+          update_cached_votes kwargs[:scope]
+          self.ballot_registered = ballots_for.any?
+          true
+        end
+      end
+
+      def ballot_by?(voter = nil, kwargs = {}) #:nodoc:
+        kwargs = __ballot_votable_kwargs(voter, kwargs)
+        voter_id, voter_type = Ballot::ActiveRecord.voter_id_and_type_name_for(kwargs)
+        return false unless voter_id
+
+        cond = {
+          voter_id: voter_id,
+          voter_type: voter_type,
+          scope: kwargs[:scope]
+        }
+        cond[:vote] = Ballot::Words.truthy?(kwargs[:vote]) if kwargs.key?(:vote)
+
+        find_ballots_for(cond).any?
+      end
+
+      def ballots_by_class(klass, kwargs = {}) #:nodoc:
+        cond = {
+          voter_type: Ballot::ActiveRecord.type_name(klass),
+          scope: kwargs[:scope]
+        }
+        cond[:vote] = Ballot::Words.truthy?(kwargs[:vote]) if kwargs.key?(:vote)
+
+        find_ballots_for(cond)
+      end
+
+      private
+
+      def caching_ballot_summary?
+        attribute_names.include?('cached_ballot_summary')
+      end
+
+      def find_ballots_for(*cond, &block)
+        if cond.empty? && block.nil?
+          ballots_for
+        else
+          ballots_for.where(*cond, &block)
+        end
+      end
+
+      def update_cached_votes(scope = nil)
+        return false unless caching_ballot_summary?
+
+        lock!
+        summary = cached_ballot_summary.merge(calculate_summary(scope))
+        self.cached_ballot_summary = summary
+        save!
+      end
+
+      def __eager_ballot_voters(ds)
+        ds.includes(:voter).map(&:voter)
+      end
+    end
+  end
+end

data/lib/ballot/active_record/vote.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+##
+module Ballot
+  module ActiveRecord
+    # The ActiveRecord implementation of Ballot::Vote.
+    class Vote < ::ActiveRecord::Base
+      self.table_name = 'ballot_votes'
+
+      scope :up, -> { where(vote: true) }
+      scope :down, -> { where(vote: false) }
+
+      scope :for_type, ->(model_class) {
+        where(votable_type: Ballot::ActiveRecord.type_name(model_class))
+      }
+      scope :by_type, ->(model_class) {
+        where(voter_type: Ballot::ActiveRecord.type_name(model_class))
+      }
+
+      if defined?(::ProtectedAttributes)
+        attr_accessible :votable_id, :votable_type, :votable,
+          :voter_id, :voter_type, :voter,
+          :vote, :scope, :weight
+      end
+
+      belongs_to :votable, polymorphic: true
+      belongs_to :voter, polymorphic: true
+
+      validates :votable_type, presence: { allow_blank: false }
+      validates :votable_id, presence: { allow_blank: false }
+      validates :voter_type, presence: { allow_blank: false }
+      validates :voter_id, presence: { allow_blank: false }
+    end
+  end
+end

data/lib/ballot/active_record/voter.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+##
+module Ballot
+  module ActiveRecord
+    # The Ballot::ActiveRecord::Voter module is the ActiveRecord-specific
+    # implementation to enable Ballot::Voter for ActiveRecord.
+    # for full details.
+    module Voter
+      def self.included(model) # :nodoc:
+        require 'ballot/active_record/vote'
+        require 'ballot/words'
+        require 'ballot/voter'
+
+        model.class_eval do
+          has_many :ballots_by,
+            class_name: '::Ballot::ActiveRecord::Vote',
+            as: :voter,
+            dependent: :destroy
+
+          include Ballot::Voter
+          extend Ballot::Voter::ClassMethods
+        end
+      end
+
+      def cast_ballot_for(votable = nil, kwargs = {}) #:nodoc:
+        kwargs = __ballot_voter_kwargs(votable, kwargs)
+        votable = Ballot::ActiveRecord.votable_for(kwargs)
+        return false unless votable
+        votable.ballot_by(kwargs.merge(voter: self))
+      end
+      alias ballot_for cast_ballot_for
+
+      def remove_ballot_for(votable = nil, kwargs = {}) #:nodoc:
+        kwargs = __ballot_voter_kwargs(votable, kwargs)
+        votable = Ballot::ActiveRecord.votable_for(kwargs)
+        return false unless votable
+        votable.remove_ballot_by voter: self, scope: kwargs[:scope]
+      end
+
+      def cast_ballot_for?(votable = nil, kwargs = {}) #:nodoc:
+        kwargs = __ballot_voter_kwargs(votable, kwargs)
+        votable_id, votable_type =
+          Ballot::ActiveRecord.votable_id_and_type_name_for(kwargs)
+        return false unless votable_id
+
+        cond = {
+          votable_id: votable_id,
+          votable_type: votable_type,
+          scope: kwargs[:scope]
+        }
+        cond[:vote] = Ballot::Words.truthy?(kwargs[:vote]) if kwargs.key?(:vote)
+
+        find_ballots_by(cond).any?
+      end
+      alias ballot_for? cast_ballot_for?
+
+      def ballot_as_cast_for(votable = nil, kwargs = {}) # :nodoc:
+        kwargs = __ballot_voter_kwargs(votable, kwargs)
+        votable = Ballot::ActiveRecord.votable_for(kwargs)
+        return nil unless votable
+
+        cond = {
+          votable_id: votable.id,
+          votable_type: Ballot::ActiveRecord.type_name(votable),
+          scope: kwargs[:scope]
+        }
+        cond[:vote] = Ballot::Words.truthy?(kwargs[:vote]) if kwargs.key?(:vote)
+
+        vote = find_ballots_by(cond).last
+        vote && vote.vote
+      end
+
+      def ballots_for_class(klass, kwargs = {}) #:nodoc:
+        cond = {
+          votable_type: Ballot::ActiveRecord.type_name(klass),
+          scope: kwargs[:scope]
+        }
+        cond[:vote] = Ballot::Words.truthy?(kwargs[:vote]) if kwargs.key?(:vote)
+
+        find_ballots_by(cond)
+      end
+
+      private
+
+      def find_ballots_by(*cond, &block)
+        if cond.empty? && block.nil?
+          ballots_by
+        else
+          ballots_by.where(*cond, &block)
+        end
+      end
+
+      def __eager_ballot_votables(ds)
+        ds.includes(:votable).map(&:votable)
+      end
+    end
+  end
+end