ballot 1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3e3564be4388ab88e50ea55774e611d5d0598c9d
+  data.tar.gz: da67d065297bcc36f747a3cd4467451571c6c100
+SHA512:
+  metadata.gz: 95bf6920d2045a5f42d1c5037801828d18b0f353d8fc2d029691b16e9528606edef1d009f2d83a21217cd25d8a66c6de1d80e062138a061b25fe52aac33309b0
+  data.tar.gz: d1b34a989316f61be094b22a9763c1f4d7ba35132a9d4f1b737815395498f06f144cb456cd320bfa0c4d8fd6d054dd08e4315bef56fe864b8170a077e59ed157

data/Contributing.md

@@ -0,0 +1,68 @@
+## Contributing
+
+We value any contribution to Ballot you can provide: a bug report, a feature
+request, or code contributions. Your contribution
+
+Ballot is reasonably complex code, so there are a few code guidelines:
+
+* Changes *will not* be accepted without tests. The test suite is written
+  with [Minitest][].
+* Changes *probably* require documentation updates.
+* Match our coding style.
+* Use a thoughtfully-named topic branch that contains your change. Rebase your
+  commits into logical chunks as necessary.
+* Use [quality commit messages][].
+* Do not change the version number; when your patch is accepted and a release
+  is made, the version will be updated at that point.
+* Submit a GitHub pull request with your changes.
+
+### Test Dependencies
+
+Ballot uses Ryan Davis’s [Hoe][] to manage the release process, and it adds a
+number of rake tasks. You will mostly be interested in:
+
+    $ rake
+
+which runs the tests the same way that:
+
+    $ rake test
+    $ rake travis
+
+will do.
+
+To assist with the installation of the development dependencies for Ballot, I
+have provided the simplest possible Gemfile pointing to the (generated)
+`ballot.gemspec` file. This will permit you to do:
+
+    $ bundle install
+
+to get the development dependencies. If you aleady have `hoe` installed, you
+can accomplish the same thing with:
+
+    $ rake newb
+
+This task will install any missing dependencies, run the tests/specs, and
+generate the RDoc.
+
+### Workflow
+
+Here's the most direct way to get your work merged into the project:
+
+* Fork the project.
+* Clone down your fork (`git clone git://github.com/KineticCafe/ruby-ballot.git`).
+* Create a topic branch to contain your change (`git checkout -b my_awesome_feature`).
+* Hack away, add tests. Not necessarily in that order.
+* Make sure everything still passes by running `rake`.
+* If necessary, rebase your commits into logical chunks, without errors.
+* Push the branch up (`git push origin my_awesome_feature`).
+* Create a pull request against KineticCafe/ruby-ballot and describe
+  what your change does and the why you think it should be merged.
+
+=== Contributors
+
+* Austin Ziegler created Ballot.
+
+[Minitest]: https://github.com/seattlerb/minitest
+[quality commit messages]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
+[Hoe]: https://github.com/seattlerb/hoe
+[kccoc]: https://github.com/KineticCafe/code-of-conduct

data/History.md

@@ -0,0 +1,5 @@
+### 1.0 / 2016-05-12
+
+*   1 major enhancement!
+
+    *   Birthday! Forked from acts_as_votable 0.10.

data/Licence.md

@@ -0,0 +1,27 @@
+## Licence
+
+This software is available under an MIT-style licence.
+
+* Copyright 2016 Kinetic Cafe
+
+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 names of its contributors may not be used to endorse or promote
+  products derived from this software without specific prior written
+  permission.
+
+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/Manifest.txt

@@ -0,0 +1,68 @@
+Contributing.md
+History.md
+Licence.md
+Manifest.txt
+README.rdoc
+Rakefile
+bin/ballot_generator
+lib/ballot.rb
+lib/ballot/action_controller.rb
+lib/ballot/active_record.rb
+lib/ballot/active_record/votable.rb
+lib/ballot/active_record/vote.rb
+lib/ballot/active_record/voter.rb
+lib/ballot/railtie.rb
+lib/ballot/sequel.rb
+lib/ballot/sequel/vote.rb
+lib/ballot/votable.rb
+lib/ballot/vote.rb
+lib/ballot/voter.rb
+lib/ballot/words.rb
+lib/generators/ballot.rb
+lib/generators/ballot/install/install_generator.rb
+lib/generators/ballot/install/templates/active_record/migration.rb
+lib/generators/ballot/install/templates/sequel/migration.rb
+lib/generators/ballot/standalone.rb
+lib/generators/ballot/standalone/support.rb
+lib/generators/ballot/summary/summary_generator.rb
+lib/generators/ballot/summary/templates/active_record/migration.rb
+lib/generators/ballot/summary/templates/sequel/migration.rb
+lib/sequel/plugins/ballot_votable.rb
+lib/sequel/plugins/ballot_voter.rb
+test/active_record/ballot_votable_test.rb
+test/active_record/ballot_voter_test.rb
+test/active_record/rails_generator_test.rb
+test/active_record/votable_voter_test.rb
+test/generators/rails-activerecord/Rakefile
+test/generators/rails-activerecord/app/.keep
+test/generators/rails-activerecord/bin/rails
+test/generators/rails-activerecord/config/application.rb
+test/generators/rails-activerecord/config/boot.rb
+test/generators/rails-activerecord/config/database.yml
+test/generators/rails-activerecord/config/environment.rb
+test/generators/rails-activerecord/config/routes.rb
+test/generators/rails-activerecord/config/secrets.yml
+test/generators/rails-activerecord/db/seeds.rb
+test/generators/rails-activerecord/log/.keep
+test/generators/rails-sequel/Rakefile
+test/generators/rails-sequel/app/.keep
+test/generators/rails-sequel/bin/rails
+test/generators/rails-sequel/config/application.rb
+test/generators/rails-sequel/config/boot.rb
+test/generators/rails-sequel/config/database.yml
+test/generators/rails-sequel/config/environment.rb
+test/generators/rails-sequel/config/routes.rb
+test/generators/rails-sequel/config/secrets.yml
+test/generators/rails-sequel/db/seeds.rb
+test/generators/rails-sequel/log/.keep
+test/minitest_config.rb
+test/sequel/ballot_votable_test.rb
+test/sequel/ballot_voter_test.rb
+test/sequel/rails_generator_test.rb
+test/sequel/votable_voter_test.rb
+test/sequel/vote_test.rb
+test/support/active_record_setup.rb
+test/support/generators_setup.rb
+test/support/sequel_setup.rb
+test/support/shared_examples/votable_examples.rb
+test/support/shared_examples/voter_examples.rb

data/README.rdoc

@@ -0,0 +1,264 @@
+= Ballot by Kinetic Cafe
+
+code :: https://github.com/KineticCafe/ruby-ballot/
+issues :: https://github.com/KineticCafe/ruby-ballot/issues
+docs :: http://www.rubydoc.info/github/KineticCafe/ruby-ballot/master
+continuous integration :: {<img src="https://travis-ci.org/KineticCafe/ruby-ballot.svg?branch=master" alt="Build Status" />}[https://travis-ci.org/KineticCafe/ruby-ballot]
+
+== Description
+
+Ballot provides a two-way polymorphic scoped voting mechanism for both
+ActiveRecord (4 or later) and Sequel (4 or later).
+
+=== Overview
+
+-   Two-way polymorphic: any model can be a voter or a votable.
+-   Scoped: multiple votes can be recorded for a votable, under different
+    scopes.
+
+Ballot started as an opinionated port of
+{acts_as_votable}[https://github.com/ryanto/acts_as_votable] to
+{Sequel}[http://sequel.jeremyevans.net/]. As the port formed, we made
+aggressive changes to both the data models and API which we wanted to share
+between our various applications, whether they used ActiveRecord or Sequel. The
+design decisions made here may not suit your needs, and we heartily recommend
+acts\_as\_votable if they do not.
+
+Ballot has been written to be able to coexist with acts\_as\_votable.
+
+Ballot does not provide a direct migration from acts\_as\_votable; it uses a
+different table (+ballot_votes+), so can coexist with acts\_as\_votable.
+
+== Synopsis
+
+The API for Ballot is consistent for both ActiveRecord and Sequel.
+
+=== ActiveRecord
+
+    class Post < ActiveRecord::Base
+      acts_as_ballot :votable # or acts_as_ballot_votable
+    end
+
+    class User < ActiveRecord::Base
+      acts_as_ballot :voter # or acts_as_ballot_voter
+    end
+
+    post = Post.create(name: 'My amazing post!')
+    current_user.cast_ballot_for post # An up-vote by current_user!
+    post.ballots_for.count # => 1
+    current_user.ballots_by.count # => 1
+    current_user.remove_ballot_for post # Remove the vote! :(
+    post.ballots_for.any? # => false
+    current_user.ballots_by.none? # => true
+
+=== Sequel
+
+    class Post < Sequel::Model
+      plugin :ballot_votable
+      # or acts_as_ballot :votable or acts_as_ballot_votable
+    end
+
+    class User < Sequel::Model
+      plugin :ballot_voter
+      # or acts_as_ballot :voter or acts_as_ballot_voter
+    end
+
+    post = Post.create(title: 'My amazing post!')
+    current_user.cast_ballot_for post # An up-vote by current_user!
+    post.ballots_for_dataset.count # => 1
+    current_user.ballots_by_dataset.count # => 1
+    current_user.remove_ballot_for post # Remove the vote! :(
+    post.ballots_for_dataset.any? # => false
+    current_user.ballots_by_dataset.none? # => true
+
+=== Exploring the API
+
+==== Ballot Words
+
+Unless otherwise specified, votes are positive. This can be specified by using
+the `vote` parameter, which will be parsed through Ballot::Words#truthy? for
+interpretation.
+
+    # All of these mean the same thing
+    post.ballot_by current_user, vote: 'bad'
+    post.ballot_by current_user, vote: '0'
+    post.ballot_by current_user, vote: 'false'
+    post.ballot_by current_user, vote: false
+    post.ballot_by current_user, vote: -1
+    post.down_ballot_by current_user
+    current_user.cast_down_ballot_for(post)
+
+==== Scoped Votes
+
+Scopes provide _purpose_ or _reasons_ for votes. These are isolated vote
+collections. One could emulate Facebook reactions with scopes:
+
+    current_user.ballot_for post # default, unspecified scope
+    current_user.ballot_for post, scope: 'love' # 'love' scope
+    current_user.ballot_for post, scope: 'haha' # 'haha' scope
+    current_user.ballot_for post, scope: 'wow' # 'wow' scope
+    current_user.ballot_for post, scope: 'sad' # 'sad' scope
+    current_user.ballot_for post, scope: 'angry' # 'angry' scope
+
+Ballot does not provide uniqueness across scopes so that a voter can only have
+one reaction to a votable.
+
+Queries are segregated by scopes as well:
+
+    current_user.cast_ballot_for? post # default, unspecified scope
+    current_user.cast_ballot_for? post, scope: 'love' # 'love' scope
+
+==== Weighted Votes
+
+Votes may be weighted so that some votes count more than others (the default
+weight is 1). This affects the _score_ of ballots, which is a distinct concept
+from the _count_ of ballots.
+
+    current_user.cast_ballot_for post, weight: 2
+    post.total_ballots # => 1
+    post.ballot_score # => 2
+
+==== Registered Votes and Duplicate Votes
+
+By default, voters can only vote a particular once per model in a given vote
+scope.
+
+    current_user.cast_ballot_for post
+    current_user.cast_ballot_for post
+    post.total_ballots # => 1
+
+A votable can be checked after voting to see if the vote counted; this is true
+only when a vote has been _created_ or _changed_.
+
+    current_user.cast_ballot_for post
+    post.vote_registered? # => true
+    current_user.cast_ballot_for post
+    post.vote_registered? # => false
+    current_user.cast_down_ballot_for post
+    post.vote_registered? # => true
+    post.total_ballots # => 1
+
+Duplicate votes may be permitted through the use of the keyword argument
++duplicate+ when casting the vote:
+
+    current_user.cast_ballot_for post
+    post.vote_registered? # => true
+    current_user.cast_ballot_for post, duplicate: true
+    post.vote_registered? # => true
+    current_user.cast_down_ballot_for post, duplicate: true
+    post.vote_registered? # => true
+    post.total_ballots # => 3
+
+Not all methods properly handle duplicate votes (as the
+<tt>post.total_ballots</tt> line demonstrates), and it has a negative impact on
+performance at a large enough scale. Its use is discouraged.
+
+==== Cached Ballot Summary
+
+Performance for some common queries can be sped up by adding a JSON field to a
+Votable model, +cached_ballot_summary+. This is updated after each vote on a
+votable. When added, this caches the results for *all* vote scopes.
+
+    user1.cast_ballot_for post, weight: 4
+    user2.cast_ballot_for post, vote: false
+    post.total_ballots # => 2
+    post.total_up_ballots # => 1
+    post.total_down_ballots # => 1
+    post.ballot_score # => 0
+    post.weighted_ballot_total # => 5
+    post.weighted_ballot_score # => 3
+    post.weighted_ballot_average # => 1.5
+
+=== API Differences with acts\_as\_votable
+
+There are a number of API differences between acts\_as\_votable and
+Ballot:
+
+1.  Ballot has an orthogonal API between Votable and Voter objects. Votable
+    objects receive <tt>#ballot_by</tt> to cast a vote, Voter objects receive
+    <tt>#cast_ballot_for</tt> to cast a vote (or <tt>#ballot_for</tt>). None of
+    the aliases added by acts\_as\_votable exist in Ballot.
+
+2.  Votable objects are associated on <tt>#ballots_for</tt> (themselves) and
+    ask whether a ballot was cast <tt>*_by</tt> Voter objects. Voter objects
+    are associated on <tt>#ballots_by</tt> (themselves) and ask whether a
+    ballot was cast <tt>*_for</tt> Votable objects.
+
+3.  Validation is performed on the votables or voters passed to vote methods,
+    ensuring that the object is a Votable or a Voter.
+
+4.  Votables can cache summary data about votes made for the votable, enabled
+    with a *single* JSON column per votable, +cached_ballot_summary+. It
+    implicitly provides caching for all scopes.
+
+5.  Vote scopes are completely isolated, even on queries. The _unspecified_
+    (default) vote scope is independent of named vote scopes. Under
+    acts\_as\_votable, you could ask <tt>votable.voted_on_by?(voter)</tt> and
+    the answer would be provided without regard to the vote scope. This is not
+    supported by Ballot, where the same question
+    (<tt>votable.ballot_by?(voter)</tt>) is explicitly in the _unspecified_
+    vote scope. If this behaviour is required, it is easy enough to ask
+    using query methods provided by \ActiveRecord or \Sequel:
+
+        # ActiveRecord
+        votable.ballots_for(voter_id: voter.id, voter_type: voter.type).any?
+        # Sequel
+        votable.ballots_for_dataset(voter_id: voter.id, voter_type: voter.type).any?
+
+== Planned Improvements
+
+* Batch voting.
+
+== Install
+
+Add Ballot to your Gemfile:
+
+    gem 'ballot', '~> 1.0'
+
+Or manually install:
+
+    % gem install ballot
+
+=== Supported Versions
+
+Ballot is written using Ruby 2 syntax and supports Active Record 4, Active
+Record 5, and Sequel 4.
+
+Ballot is tested with these combinations of Ruby interpreters and ORMs:
+
+- Ruby 2.0, 2.1; ActiveRecord 4; Sequel 4
+- Ruby 2.2; ActiveRecord 4, 5; Sequel 4
+- JRuby 9.0, 9.1; ActiveRecord 4; Sequel 4
+
+=== Database Migrations
+
+Ballot uses a table (+ballot_votes+) to store all votes. When using Rails, you
+can generate the migration as normal:
+
+    rails generate ballot:install
+    rake db:migrate
+
+Performance can be increased by adding the +cached_ballot_summary+ column to
+your votable tables. This can be added with a different migration:
+
+    rails generate ballot:summary VOTABLE
+
+When not using Rails, you can use the ballot_generator binary.
+
+    ballot_generator [--orm ORM] --install
+    ballot_generator [--orm ORM] --summary NAME
+
+== Ballot Semantic Versioning
+
+Ballot uses a {Semantic Versioning}[http://semver.org/] scheme with one
+significant change:
+
+* When PATCH is zero (+0+), it will be omitted from version references.
+
+== Community and Contributing
+
+Ballot welcomes your contributions as described in
+{Contributing.md}[https://github.com/KineticCafe/ballot/blob/master/Contributing.md].
+This project, like all Kinetic Cafe {open source
+projects}[https://github.com/KineticCafe], is under the Kinetic Cafe Open
+Source {Code of Conduct}[https://github.com/KineticCafe/code-of-conduct].

data/Rakefile

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'rubygems'
+require 'hoe'
+require 'rake/clean'
+
+Hoe.plugin :doofus
+Hoe.plugin :email unless ENV['CI'] || ENV['TRAVIS']
+Hoe.plugin :gemspec2
+Hoe.plugin :git
+Hoe.plugin :minitest
+Hoe.plugin :rubygems
+Hoe.plugin :travis
+
+spec = Hoe.spec 'ballot' do
+  developer('Austin Ziegler', 'aziegler@kineticcafe.com')
+
+  self.history_file = 'History.md'
+  self.readme_file = 'README.rdoc'
+
+  license 'MIT'
+
+  ruby20!
+
+  extra_dev_deps << ['rake', '>= 10.0']
+  extra_dev_deps << ['rdoc', '~> 4.2']
+  extra_dev_deps << ['hoe-doofus', '~> 1.0']
+  extra_dev_deps << ['hoe-gemspec2', '~> 1.1']
+  extra_dev_deps << ['hoe-git', '~> 1.5']
+  extra_dev_deps << ['hoe-travis', '~> 1.2']
+  extra_dev_deps << ['minitest', '~> 5.4']
+  extra_dev_deps << ['minitest-autotest', '~> 1.0']
+  extra_dev_deps << ['minitest-bisect', '~> 1.2']
+  extra_dev_deps << ['minitest-bonus-assertions', '~> 2.0']
+  extra_dev_deps << ['minitest-focus', '~> 1.1']
+  extra_dev_deps << ['minitest-hooks', '~> 1.4']
+  extra_dev_deps << ['minitest-moar', '~> 0.0']
+  extra_dev_deps << ['simplecov', '~> 0.7']
+end
+
+ENV['RDOCOPT'] = "-x #{%r{lib/generators/.+/templates/.+\.rb}}"
+ENV['RUBYOPT'] = '-W0'
+
+module Hoe::Publish #:nodoc:
+  alias __make_rdoc_cmd__ballot__ make_rdoc_cmd
+
+  def make_rdoc_cmd(*extra_args) # :nodoc:
+    spec.extra_rdoc_files.delete_if { |f| f == 'Manifest.txt' }
+    __make_rdoc_cmd__ballot__(*extra_args)
+  end
+end
+
+namespace :test do
+  if File.exist?('.simplecov-prelude.rb')
+    task :coverage do
+      spec.test_prelude = 'load ".simplecov-prelude.rb"'
+
+      Rake::Task['test'].execute
+    end
+  end
+
+  desc 'Include the generator tests'
+  task :generators do
+    ENV['TEST_GENERATORS'] = '1'
+    Rake::Task['test'].execute
+  end
+
+  CLOBBER << 'coverage'
+end
+
+CLOBBER << 'tmp'