ballot 1.0

data/lib/ballot/vote.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+#--
+# This file exists for documentation purposes only. Ballot::Vote is an optional
+# constant, and may be one of these values:
+#
+# *  Ballot::Sequel::Vote (when using *only* Sequel in an application);
+# *  Ballot::ActiveRecord::Vote (when using *only* ActiveRecord in an application)
+#++
+unless defined?(Ballot::Sequel::Vote) || defined?(Ballot::ActiveRecord::Vote)
+  fail 'ballot/vote cannot be required directly'
+end
+
+##
+module Ballot
+  # A Vote represents the votes stored in the +ballot_votes+ table, holding
+  # votes for Votable objects by Voter objects.
+  #
+  # \ActiveRecord:: This is implemented as the Ballot::ActiveRecord::Vote
+  #                 class.
+  # \Sequel:: This is implemented as the Ballot::Sequel::Vote class.
+  #
+  #
+  # NOTE:: Ballot::Vote is implemented as a method returning the primary
+  #        implementation of the vote class. If _only_ Ballot::Sequel::Vote is
+  #        defined, it will be returned. If _only_ Ballot::ActiveRecord::Vote
+  #        is defined, it will be returned. If _both_ are defined, +nil+ will
+  #        be returned.
+  class Vote
+    #-----
+    # :section: Scope / Dataset Methods
+    #-----
+
+    ##
+    # Returns all positive votes.
+    #
+    # \ActiveRecord:: This is a scope.
+    # \Sequel:: This is a dataset module subset.
+    def self.up; end
+
+    ##
+    # Returns all negative votes.
+    #
+    # \ActiveRecord:: This is a scope.
+    # \Sequel:: This is a dataset module subset.
+    def self.down; end
+
+    ##
+    # Returns all votes for Votable objects of the provided +model_class+. The
+    # +model_class+ is resolved to the canonical name for the model, which
+    # differs if the model is STI-enabled.
+    #
+    # \ActiveRecord:: This is a scope.
+    # \Sequel:: This is a dataset module method.
+    def self.for_type(model_class); end
+
+    ##
+    # Returns all votes for Voter objects of the provided +model_class+. The
+    # +model_class+ is resolved to the canonical name for the model, which
+    # differs if the model is STI-enabled.
+    #
+    # \ActiveRecord:: This is a scope.
+    # \Sequel:: This is a dataset module method.
+    def self.by_type(model_class); end
+
+    #-----
+    # :section:
+    #-----
+
+    ##
+    # :attr_accessor: voter_id
+    # The id of the Voter record for this Vote.
+
+    ##
+    # :attr_accessor: voter_type
+    # The canonical model name for the Voter record for this Vote.
+
+    ##
+    # :attr_accessor: votable_id
+    # The id of the Votable record for this Vote.
+
+    ##
+    # :attr_accessor: votable_type
+    # The canonical model name for the Votable record for this Vote.
+
+    ##
+    # :attr_accessor: vote
+    # The state of the Vote; +true+ if a positive vote, +false+ if a negative
+    # vote.
+
+    ##
+    # :attr_accessor: scope
+    # The optional scope for this Vote.
+
+    ##
+    # :attr_accessor: weight
+    # The optional weight for this Vote. If missing, defaults to 1, but may be
+    # any integer value.
+
+    ##
+    # :attr_reader: created_at
+    # When this Vote record was created.
+
+    ##
+    # :attr_reader: updated_at
+    # When this Vote record was last updated.
+
+    ##
+    # :attr_accessor: voter
+    # The associated Voter for this Vote. Determined from #voter_id and
+    # #voter_type.
+
+    ##
+    # :attr_accessor: votable
+    # The associated Votable for this Vote. Determined from #votable_id and
+    # #votable_type.
+  end
+  remove_const :Vote
+
+  #--
+  def self.Vote # :nodoc:
+    if defined?(Ballot::Sequel::Vote) && !defined?(Ballot::ActiveRecord::Vote)
+      Ballot::Sequel::Vote
+    elsif defined?(Ballot::ActiveRecord::Vote)
+      Ballot::ActiveRecord::Vote
+    end
+  end
+  #++
+end

data/lib/ballot/voter.rb

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+##
+module Ballot
+  # Methods added to a model that is marked as a Voter.
+  module Voter
+    #-----
+    # :section: Recording Votes
+    #-----
+
+    ##
+    # :method: cast_ballot_for
+    # :call-seq:
+    #    cast_ballot_for(votable = nil, kwargs = {})
+    #    cast_ballot_for(votable)
+    #    cast_ballot_for(votable_id: id, votable_type: type)
+    #    cast_ballot_for(votable_gid: gid)
+    #    cast_ballot_for(votable, scope: scope, vote: false, weight: true)
+    #
+    # Record a Vote for this Voter on the provided +votable+. The +votable+ may
+    # be specified as its own parameter, or through the keyword arguments
+    # +votable_id+, +votable_type+, +votable_gid+, or +votable+ (note that the
+    # parameter +votable+ will override the keyword argument +votable+, if both
+    # are provided).
+    #
+    # Additional named arguments may be provided through +kwargs+:
+    #
+    # scope:: The scope of the vote to be recorded. Defaults to +nil+.
+    # vote:: The vote to be recorded. Defaults to +true+ and is parsed through
+    #        Ballot::Words.truthy?.
+    # weight:: The weight of the vote to be recorded. Defaults to +1+.
+    # duplicate:: Allow a duplicate vote to be recorded. This is not
+    #             recommended as it has negative performance implications at
+    #             scale.
+    #
+    # Other arguments are ignored.
+    #
+    # \ActiveRecord:: There are no special notes for ActiveRecord.
+    # \Sequel:: GlobalID does not currently provide support for Sequel. The use
+    #           of +votable_gid+ in this case will probably fail.
+    #
+    # <em>Also aliased as: #ballot_for.</em>
+
+    ##
+    # :method: ballot_for
+    # :call-seq:
+    #    ballot_for(votable = nil, kwargs = {})
+    #    ballot_for(votable)
+    #    ballot_for(votable_id: id, votable_type: type)
+    #    ballot_for(votable_gid: gid)
+    #    ballot_for(votable, scope: scope, vote: false, weight: true)
+    #
+    # <em>Alias for: #cast_ballot_for.</em>
+
+    ##
+    # Records a positive vote by this Voter on the provided +votable+ with
+    # options provided in +kwargs+. Any value passed to the +vote+ keyword
+    # argument will be ignored. See #cast_ballot_for for more details.
+    def cast_up_ballot_for(votable = nil, kwargs = {})
+      cast_ballot_for(votable, kwargs.merge(vote: true))
+    end
+    alias up_ballot_for cast_up_ballot_for
+
+    ##
+    # Records a negative vote by this Voter on the provided +votable+ with
+    # options provided in +kwargs+. Any value passed to the +vote+ keyword
+    # argument will be ignored. See #cast_ballot_for for more details.
+    def cast_down_ballot_for(votable = nil, kwargs = {})
+      cast_ballot_for(votable, kwargs.merge(vote: false))
+    end
+    alias down_ballot_for cast_down_ballot_for
+
+    ##
+    # :method: remove_ballot_for
+    # :call-seq:
+    #    remove_ballot_for(votable = nil, kwargs = {})
+    #    remove_ballot_for(votable)
+    #    remove_ballot_for(votable_id: id, votable_type: type)
+    #    remove_ballot_for(votable_gid: gid)
+    #    remove_ballot_for(votable, scope: scope)
+    #
+    # Remove any votes by this Voter for the provided +votable+. The +votable+
+    # may be specified as its own parameter, or through the keyword arguments
+    # +votable_id+, +votable_type+, +votable_gid+, or +votable+ (note that the
+    # parameter +votable+ will override the keyword argument +votable+, if both
+    # are provided).
+    #
+    # Only the +scope+ argument is available through +kwargs+:
+    #
+    # scope:: The scope of the vote to be recorded. Defaults to +nil+.
+    #
+    # Other arguments are ignored.
+    #
+    # \ActiveRecord:: There are no special notes for \ActiveRecord.
+    # \Sequel:: GlobalID does not currently provide support for \Sequel, so
+    #           there are many cases where attempting to use +votable_gid+ will
+    #           fail.
+
+    #-----
+    # :section: Finding Votes
+    #-----
+
+    ##
+    # :method: ballots_by
+    #
+    # The votes attached to this Votable.
+    #
+    # \ActiveRecord:: This is generated by the polymorphic association
+    #                 <tt>has_many :ballots_by</tt>.
+    # \Sequel:: This is generated by the polymorphic association
+    #           <tt>one_to_many :ballots_by</tt>
+
+    ##
+    # :method: ballots_for_dataset
+    #
+    # The \Sequel association dataset for votes attached to this Voter.
+    #
+    # \ActiveRecord:: This does not exist for \ActiveRecord.
+    # \Sequel:: This is generated by the polymorphic association
+    #           <tt>one_to_many :ballots_for</tt>
+
+    ##
+    # Returns ballots by this Voter where the recorded vote is positive.
+    #
+    # \ActiveRecord:: There are no special notes for ActiveRecord.
+    # \Sequel:: This method returns the _dataset_; if vote objects are desired,
+    #           use <tt>up_ballots_by.all</tt>.
+    def up_ballots_by(kwargs = {})
+      find_ballots_by(vote: true, scope: kwargs[:scope])
+    end
+
+    ##
+    # Returns ballots by this Voter where the recorded vote is negative.
+    #
+    # \ActiveRecord:: There are no special notes for ActiveRecord.
+    # \Sequel:: This method returns the _dataset_; if vote objects are desired,
+    #           use <tt>down_ballots_by.all</tt>.
+    def down_ballots_by(kwargs = {})
+      find_ballots_by(vote: false, scope: kwargs[:scope])
+    end
+
+    #-----
+    # :section: Votable Inquiries
+    #-----
+
+    ##
+    # :method: cast_ballot_for?
+    # :call-seq:
+    #    ballot_for?(votable = nil, kwargs = {})
+    #    ballot_for?(votable)
+    #    ballot_for?(votable_id: id, votable_type: type)
+    #    ballot_for?(votable_gid: gid)
+    #    ballot_for?(votable, scope: scope, vote: false, weight: true)
+    #
+    # Returns +true+ if this Voter has voted for the provided +votable+
+    # matching the provided criteria. The +votable+ may be specified as its own
+    # parameter, or through the keyword arguments +votable_id+, +votable_type+,
+    # +votable_gid+, or +votable+ (note that the parameter +votable+ will
+    # override the keyword argument +votable+, if both are provided).
+    #
+    # Additional named arguments may be provided through +kwargs+:
+    #
+    # scope:: The scope of the vote to be recorded. Defaults to +nil+.
+    # vote:: The vote to be queried. If present, is parsed through
+    #        Ballot::Words.truthy?.
+    #
+    # Other arguments are ignored.
+    #
+    # \ActiveRecord:: There are no special notes for ActiveRecord.
+    # \Sequel:: GlobalID does not currently provide support for Sequel. The use
+    #           of +votable_gid+ in this case will probably fail.
+    #
+    # <em>Also aliased as: #ballot_for?.</em>
+
+    ##
+    # :method: ballot_for?
+    # :call-seq:
+    #    ballot_for?(votable = nil, kwargs = {})
+    #    ballot_for?(votable)
+    #    ballot_for?(votable_id: id, votable_type: type)
+    #    ballot_for?(votable_gid: gid)
+    #    ballot_for?(votable, scope: scope, vote: false, weight: true)
+    #
+    # <em>Alias for: #cast_ballot_for?.</em>
+
+    ##
+    # Returns +true+ if this Voter has made positive votes for the provided
+    # +votable+. Any value passed to the +vote+ keyword argument will be
+    # ignored. See #cast_ballot_for? for more details.
+    def cast_up_ballot_for?(votable = nil, kwargs = {})
+      cast_ballot_for?(votable, kwargs.merge(vote: true))
+    end
+    alias up_ballot_for? cast_up_ballot_for?
+
+    ##
+    # Returns +true+ if this Voter has made negative votes for the provided
+    # +votable+. Any value passed to the +vote+ keyword argument will be
+    # ignored. See #cast_ballot_for? for more details.
+    def cast_down_ballot_for?(votable = nil, kwargs = {})
+      cast_ballot_for?(votable, kwargs.merge(vote: false))
+    end
+    alias down_ballot_for? cast_down_ballot_for?
+
+    ##
+    # :method: ballot_as_cast_for
+    # :call-seq:
+    #    ballot_as_cast_for(votable = nil, kwargs = {})
+    #    ballot_as_cast_for(votable)
+    #    ballot_as_cast_for(votable_id: id, votable_type: type)
+    #    ballot_as_cast_for(votable_gid: gid)
+    #    ballot_as_cast_for(votable, scope: scope, vote: false, weight: true)
+    #
+    # Returns the Ballot::Vote#vote value of the ballot cast by this Voter
+    # against the provided +votable+. The +votable+ may be specified as its own
+    # parameter, or through the keyword arguments +votable_id+, +votable_type+,
+    # +votable_gid+, or +votable+ (note that the parameter +votable+ will
+    # override the keyword argument +votable+, if both are provided).
+    #
+    # If this Voter has not cast a ballot against the +votable+, returns +nil+.
+    #
+    # Additional named arguments may be provided through +kwargs+:
+    #
+    # scope:: The scope of the vote to be query. Defaults to +nil+.
+    # vote:: The vote to be queried. If present, is parsed through
+    #        Ballot::Words.truthy?.
+    #
+    # Other arguments are ignored.
+    #
+    # \ActiveRecord:: There are no special notes for ActiveRecord.
+    # \Sequel:: GlobalID does not currently provide support for Sequel. The use
+    #           of +votable_gid+ in this case will probably fail.
+
+    ##
+    # :method: ballots_for_class(model_class, kwargs = {})
+    #
+    # Find ballots cast by this Voter matching the canonical name of the
+    # +model_class+ as the type of Votable.
+    #
+    # Additional named arguments may be provided through +kwargs+:
+    #
+    # scope:: The scope of the vote to be recorded. Defaults to +nil+.
+    # vote:: The vote to be queried. If present, is parsed through
+    #        Ballot::Words.truthy?.
+    #
+    # Other arguments are ignored.
+
+    ##
+    # Find positive ballots cast by this Voter matching the canonical name of
+    # the +model_class+ as the type of Votable. Any value passed to the +vote+
+    # keyword argument will be ignored. See #ballots_for_class for more
+    # details.
+    def up_ballots_for_class(model_class, kwargs = {})
+      ballots_for_class(model_class, kwargs.merge(vote: true))
+    end
+
+    ##
+    # Find negative ballots cast by this Voter matching the canonical name of
+    # the +model_class+ as the type of Votable. Any value passed to the +vote+
+    # keyword argument will be ignored. See #ballots_for_class for more
+    # details.
+    def down_ballots_for_class(model_class, kwargs = {})
+      ballots_for_class(model_class, kwargs.merge(vote: false))
+    end
+
+    ##
+    # Returns the Votable objects that this Voter has voted on. Additional
+    # query conditions may be specified in +conds+, or in the +block+ if
+    # supported by the ORM. The Voter objects are eager loaded to minimize the
+    # number of queries required to satisfy this request.
+    #
+    # \ActiveRecord:: Polymorphic eager loading is directly supported, using
+    #                 <tt>ballots_for.includes(:votable)</tt>. Normal
+    #                 +where+-clause conditions may be provided in +conds+.
+    # \Sequel:: Polymorphic eager loading is not supported by \Sequel, but has
+    #           been implemented in Ballot for this method. Normal
+    #           +where+-clause conditions may be provided in +conds+ or in
+    #           +block+ for \Sequel virtual row support.
+    def ballot_votables(*conds, &block)
+      __eager_ballot_votables(find_ballots_by(*conds, &block))
+    end
+
+    ##
+    # Returns the Votable objects that this Voter has made positive votes on.
+    # See #ballot_voters for how +conds+ and +block+ apply.
+    def ballot_up_votables(*conds, &block)
+      __eager_ballot_votables(
+        find_ballots_by(*conds, &block).where(vote: true)
+      )
+    end
+
+    ##
+    # Returns the Votable objects that this Voter has made negative votes on.
+    # See #ballot_voters for how +conds+ and +block+ apply.
+    def ballot_down_votables(*conds, &block)
+      __eager_ballot_votables(
+        find_ballots_by(*conds, &block).where(vote: false)
+      )
+    end
+
+    private
+
+    def __ballot_voter_kwargs(votable, kwargs = {})
+      if votable.kind_of?(Hash)
+        kwargs.merge(votable)
+      elsif votable.nil?
+        kwargs
+      else
+        kwargs.merge(votable: votable)
+      end
+    end
+
+    # Methods added to the Voter model class.
+    module ClassMethods
+      # The class is now a voter record.
+      def ballot_voter?
+        true
+      end
+    end
+  end
+end

data/lib/ballot/words.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'set'
+
+##
+module Ballot
+  # Methods to determine whether the value of the vote word in question is
+  # positive (#truthy?) or negative (#falsy?).
+  module Words
+    module_function
+
+    # The list of 'words' recognized as falsy values for voting purposes. This
+    # set can be added to for localization purposes. Any word *not* in this
+    # list is considered truthy.
+    FALSY = Set.new(
+      [
+        'down', 'downvote', 'dislike', 'disliked', 'negative', 'no', 'bad',
+        'false', '0', '-1'
+      ]
+    )
+
+    # Returns +true+ if the word supplied is not #falsy?.
+    def truthy?(word)
+      !falsy?(word)
+    end
+
+    # Returns +true+ if the word supplied is in the FALSY set.
+    def falsy?(word)
+      FALSY.include?(word.to_s.downcase)
+    end
+  end
+end