recommendable 0.1.2

data/.gitignore

@@ -0,0 +1,57 @@
+# RVM / rbenv version files
+.rvmrc
+.rbenv-version
+
+# rcov generated
+coverage
+
+# rdoc generated
+rdoc
+
+# yard generated
+doc
+.yardoc
+
+# bundler
+.bundle
+vendor/bundle
+
+# jeweler generated
+pkg
+
+# logging
+*.log
+
+# Have editor/IDE/OS specific files you need to ignore? Consider using a global gitignore: 
+#
+# * Create a file at ~/.gitignore
+# * Include files you want ignored
+# * Run: git config --global core.excludesfile ~/.gitignore
+#
+# After doing this, these files will be ignored in all your git projects,
+# saving you from having to 'pollute' every project you touch with them
+#
+# Not sure what to needs to be ignored for particular editors/OSes? Here's some ideas to get you started. (Remember, remove the leading # of the line)
+#
+# For MacOS:
+
+.DS_Store
+
+# For TextMate
+*.tmproj
+tmtags
+
+# For emacs:
+#*~
+#\#*
+#.\#*
+
+# For vim:
+*.swp
+
+# For redcar:
+#.redcar
+
+# For rubinius:
+#*.rbc
+.rake_tasks*

data/.travis.yml

@@ -0,0 +1,3 @@
+rvm:
+  - 1.9.2
+  - 1.9.3

data/Gemfile

@@ -0,0 +1,17 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+gem "rails",        ">= 3.0.0"
+gem "redis",        "~> 2.2.0"
+gem "resque",       "~> 1.19.0"
+gem "resque-loner", "~> 1.2.0"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "sqlite3"
+  gem "minitest"
+  gem "shoulda"
+  gem "miniskirt"
+  gem "yard",    "~> 0.6.0"
+  gem "bundler", "~> 1.0.0"
+end

data/Gemfile.lock

@@ -0,0 +1,118 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    actionmailer (3.2.0)
+      actionpack (= 3.2.0)
+      mail (~> 2.4.0)
+    actionpack (3.2.0)
+      activemodel (= 3.2.0)
+      activesupport (= 3.2.0)
+      builder (~> 3.0.0)
+      erubis (~> 2.7.0)
+      journey (~> 1.0.0)
+      rack (~> 1.4.0)
+      rack-cache (~> 1.1)
+      rack-test (~> 0.6.1)
+      sprockets (~> 2.1.2)
+    activemodel (3.2.0)
+      activesupport (= 3.2.0)
+      builder (~> 3.0.0)
+    activerecord (3.2.0)
+      activemodel (= 3.2.0)
+      activesupport (= 3.2.0)
+      arel (~> 3.0.0)
+      tzinfo (~> 0.3.29)
+    activeresource (3.2.0)
+      activemodel (= 3.2.0)
+      activesupport (= 3.2.0)
+    activesupport (3.2.0)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
+    arel (3.0.0)
+    builder (3.0.0)
+    erubis (2.7.0)
+    hike (1.2.1)
+    i18n (0.6.0)
+    journey (1.0.0)
+    json (1.6.5)
+    mail (2.4.1)
+      i18n (>= 0.4.0)
+      mime-types (~> 1.16)
+      treetop (~> 1.4.8)
+    mime-types (1.17.2)
+    miniskirt (1.1.1)
+      activesupport (>= 2.2)
+    minitest (2.10.1)
+    multi_json (1.0.4)
+    polyglot (0.3.3)
+    rack (1.4.0)
+    rack-cache (1.1)
+      rack (>= 0.4)
+    rack-protection (1.2.0)
+      rack
+    rack-ssl (1.3.2)
+      rack
+    rack-test (0.6.1)
+      rack (>= 1.0)
+    rails (3.2.0)
+      actionmailer (= 3.2.0)
+      actionpack (= 3.2.0)
+      activerecord (= 3.2.0)
+      activeresource (= 3.2.0)
+      activesupport (= 3.2.0)
+      bundler (~> 1.0)
+      railties (= 3.2.0)
+    railties (3.2.0)
+      actionpack (= 3.2.0)
+      activesupport (= 3.2.0)
+      rack-ssl (~> 1.3.2)
+      rake (>= 0.8.7)
+      rdoc (~> 3.4)
+      thor (~> 0.14.6)
+    rake (0.9.2.2)
+    rdoc (3.12)
+      json (~> 1.4)
+    redis (2.2.2)
+    redis-namespace (1.0.3)
+      redis (< 3.0.0)
+    resque (1.19.0)
+      multi_json (~> 1.0)
+      redis-namespace (~> 1.0.2)
+      sinatra (>= 0.9.2)
+      vegas (~> 0.1.2)
+    resque-loner (1.2.0)
+      resque (~> 1.0)
+    shoulda (2.11.3)
+    sinatra (1.3.2)
+      rack (~> 1.3, >= 1.3.6)
+      rack-protection (~> 1.2)
+      tilt (~> 1.3, >= 1.3.3)
+    sprockets (2.1.2)
+      hike (~> 1.2)
+      rack (~> 1.0)
+      tilt (~> 1.1, != 1.3.0)
+    sqlite3 (1.3.5)
+    thor (0.14.6)
+    tilt (1.3.3)
+    treetop (1.4.10)
+      polyglot
+      polyglot (>= 0.3.1)
+    tzinfo (0.3.31)
+    vegas (0.1.11)
+      rack (>= 1.0.0)
+    yard (0.6.8)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0.0)
+  miniskirt
+  minitest
+  rails (>= 3.0.0)
+  redis (~> 2.2.0)
+  resque (~> 1.19.0)
+  resque-loner (~> 1.2.0)
+  shoulda
+  sqlite3
+  yard (~> 0.6.0)

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012 David Celis
+
+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.markdown

@@ -0,0 +1,340 @@
+# recommendable [![Build Status](https://secure.travis-ci.org/davidcelis/recommendable.png)](http://travis-ci.org/davidcelis/recommendable)
+
+Recommendable is a Rails Engine to add Like/Dislike functionality to your 
+application. It uses Redis to generate recommendations quickly through a
+collaborative filtering algorithm that I modified myself. Your users' tastes
+are compared with one another and used to give them great recommendations!
+Yes, Redis is required. Scroll to the end of the README for more info on that.
+
+Why Likes and Dislikes?
+-----------------------
+
+[I hate five-star rating scales][0].
+
+**tl;dr:** Binary voting habits are most certainly not an odd phenomenon. 
+People tend to vote in only two different ways. Some folks give either 1 star 
+or 5 stars. Some people fluctuate between 3 and 4 stars. There are always 
+outliers, but what it comes down to is this: a person's binary votes indicate, 
+in general, a dislike or like of what they're voting on. I'm just giving the 
+people what they want.
+
+Installation
+------------
+
+Add the following to your Rails application's `Gemfile`:
+
+``` ruby
+  gem "recommendable"
+```
+
+After your `bundle install`, you can then run:
+
+    $ rails g recommendable:install (--user-class=User)
+
+After running the installation generator, you should double check
+`config/initializers/recommendable.rb` for options on configuring your Redis
+connection.
+
+Finally, Recommendable uses Resque to place users in a queue. Users must wait
+their turn to regenerate recommendations so that your application does not get
+throttled. Don't worry, though! Most of the time, your users will barely have
+to wait. In fact, you can run multiple resque workers if you wish.
+
+Assuming you have `redis-server` running...
+
+    $ QUEUE=recommendable rake environment resque:work
+
+You can run this command multiple times if you wish to start more than one
+worker. This is the standard rake task for starting a Resque worker so, for
+more options on this task, head over to [defunkt/resque][1]
+
+Usage
+-----
+
+In your Rails model that represents your application's user:
+
+``` ruby
+class User < ActiveRecord::Base
+  acts_as_recommended_to
+  
+  # ...
+end
+```
+
+Then, from any Rails model you wish your `user` to be able to `like` or `dislike`:
+
+``` ruby
+class Movie < ActiveRecord::Base
+  acts_as_recommendable
+  
+  # ...
+end
+
+class Show < ActiveRecord::Base
+  acts_as_recommendable
+  
+  # ...
+end
+````
+
+And that's it!
+
+### Liking/Disliking
+
+At this point, your user will be ready to `like` movies...
+
+``` ruby
+current_user.like Movie.create(:title => '2001: A Space Odyssey', :year => 1968)
+#=> true
+```
+
+... or `dislike` them:
+
+``` ruby
+current_user.dislike Movie.create(:title => 'Star Wars: Episode I - The Phantom Menace', :year => 1999)
+#=> true
+```
+
+In addition, several helpful methods are available to your user now:
+
+``` ruby
+current_user.likes? Movie.find_by_title('2001: A Space Odyssey')
+#=> true
+current_user.dislikes? Movie.find_by_title('Star Wars: Episode I - The Phantom Menace')
+#=> true
+other_movie = Movie.create('Back to the Future', :year => 1985)
+current_user.dislikes? other_movie
+#=> false
+current_user.like other_movie
+#=> true
+current_user.liked
+#=> [#<Movie name: '2001: A Space Odyssey', year: 1968>, #<Movie name: 'Back to the Future', :year => 1985>]
+current_user.disliked
+#=> [#<Movie name: 'Star Wars: Episode I - The Phantom Menace', year: 1999>]
+```
+
+Because you are allowed to declare multiple models as recommendable, you may
+wish to return a set of liked or disliked objects for only one of those
+models.
+
+``` ruby
+current_user.liked_for(Movie)
+#=> [#<Movie name: '2001: A Space Odyssey', year: 1968>, #<Movie name: 'Back to the Future', :year => 1985>]
+current_user.disliked_for(Show)
+#=> []
+```
+
+### Ignoring
+
+If you want to give your user the ability to `ignore` recommendations or even
+just hide stuff on your website that they couldn't care less about, you can!
+
+``` ruby
+weird_movie_nobody_wants_to_watch = Movie.create(:title => 'Cool World', :year => 1998)
+current_user.ignore weird_movie_nobody_wants_to_watch
+#=> true
+current_user.ignored
+#=> [#<Movie name: 'Cool World', year: 1998>]
+current_user.ignored_for(Show)
+#=> []
+```
+
+Do what you will with this list of records. The power is yours.
+
+### Saving for later
+
+Your user might want to maintain a list of items to try later but still receive
+new recommendations. For this, you can use Recommendable::StashedItems. Note that
+adding an item to a user's stash will remove it from their list of recommendations.
+Additionally, an item can not be stashed if the user already likes or dislikes it.
+
+``` ruby
+movie_to_watch_later = Movie.create(:title => 'The Descendants', :year => 2011)
+current_user.stash(movie_to_watch_later)
+#=> true
+current_user.stashed
+#=> [#<Movie name: 'The Descendants', year: 2011>]
+# Later...
+current_user.like(movie_to_watch_later)
+#=> true
+current_user.stash(movie_to_watch_later)
+#=> nil
+current_user.has_stashed?(movie_to_watch_later)
+#=> false
+```
+
+### Unliking/Undisliking/Unignoring/Unstashing
+
+Note that liking a movie that has already been disliked (or vice versa) will
+simply destroy the old rating and create a new one. If a user attempts to `like`
+a movie that they already like, however, nothing happens and `nil` is returned.
+If you wish to manually remove an item from a user's likes or dislikes or
+ignored records, you can:
+
+``` ruby
+current_user.like Movie.create(:title => 'Avatar', :year => 2009)
+#=> true
+current_user.unlike Movie.find_by_title('Avatar')
+#=> true
+current_user.liked
+#=> []
+```
+
+You can use `undislike`, `unignore` and `unstash` in the same fashion. So, as 
+far as the Likes and Dislikes go, do you think that's enough? Because I didn't.
+
+``` ruby
+friend = User.create(:username => 'joeblow')
+awesome_movie = Movie.find_by_title('2001: A Space Odyssey')
+friend.like awesome_movie
+#=> true
+awesome_movie.liked_by
+#=> [#<User username: 'davidcelis'>, #<User username: 'joeblow'>]
+Movie.find_by_title('Star Wars: Episode I - The Phantom Menace').disliked_by
+#=> [#<User username: 'davidcelis'>]
+current_user.common_likes_with(friend)
+#=> [#<Movie title: '2001: A Space Odyssey', year: 1968>]
+```
+
+`common_dislikes_with` and `disagreements_with` are available for similar use.
+
+Recommendations
+---------------
+
+When a user submits a new `Like` or `Dislike`, they enter a queue to have their
+recommendations refreshed. Once that user exits the queue, you can retrieve
+these like so:
+
+``` ruby
+current_user.recommendations
+#=> [#<Movie highly_recommended>, #<Show somewhat_recommended>, #<Movie meh>]
+current_user.recommendations_for(Show)
+#=> [#<Show somewhat_recommended>]
+```
+
+The top recommendations are returned in an array ordered by how good recommendable
+believes the recommendation to be (from best to worst).
+
+``` ruby
+current_user.like somewhat_recommended_show
+#=> true
+current_user.recommendations
+#=> [#<Movie highly_recommended>, #<Movie meh>]
+```
+  
+Finally, you can also get a list of the users found to be most similar to your
+current user:
+
+``` ruby
+current_user.similar_raters
+#=> [#<User username: 'joe-blow'>, #<User username: 'less-so-than-joe-blow']
+```
+
+Likewise, this list is ordered from most similar to least similar.
+
+Documentation
+-------------
+
+Some of the above methods are tweakable with options. For example, you can
+adjust the number of recommendations returned to you (the default is 10) and
+the number of similar uses returned (also 10). To see these options, check
+the documentation.
+
+A note on Redis
+---------------
+
+Recommendable currently depends on [Redis](http://redis.io/). It will install 
+the redis-rb gem as a dependency, but you must install Redis and run it
+yourself. Also note that your Redis database must be persistent. Recommendable
+will use Redis to permanently store sorted sets to quickly access recommendations.
+Please take care with your Redis database! Fortunately, if you do lose your
+Redis database, there's hope (more on that later).
+
+Installing Redis
+----------------
+
+Recommendable requires Redis to deliver recommendations. Why? Because my
+collaborative filtering algorithm is based almost entirely on set math, and
+Ruby's Set class just won't cut it for fast recommendations.
+
+### Homebrew
+
+For Mac OS X users, homebrew is by far the easiest way to install Redis.
+
+    $ brew install redis
+    $ redis-server /usr/local/etc/redis.conf
+
+You should now have Redis running as a daemon on localhost:6379
+
+### Via Resque
+
+Resque (which is also a dependency of recommendable) includes Rake tasks that
+will install and run Redis for you:
+
+    $ git clone git://github.com/defunkt/resque.git
+    $ cd resque
+    $ rake redis:install dtach:install
+    $ rake redis:start
+
+If you do not have admin rights to your machine:
+
+    $ git clone git://github.com/defunkt/resque.git
+    $ cd resque
+    $ PREFIX=<your_prefix> rake redis:install dtach:install
+    $ rake redis:start
+
+Redis will now be running on localhost:6379. After a second, you can hit `ctrl-\`
+to detach and keep Redis running in the background.
+
+(Thanks to [defunkt][1] for mentioning this
+method, and thanks to [ezmobius][2] for
+making it possible)
+
+Manually regenerating recommendations
+-------------------------------------
+
+If a catastrophe occurs and your Redis database is either destroyed or rendered
+unusable in some other way, there is hope. You can run the following from your
+application's console (assuming your user class is User):
+
+    User.all.each do |user|
+      user.update_similarities
+      user.update_recommendations
+    end
+
+But please try not to have to do this manually!
+
+Contributing to recommendable
+-----------------------------
+ 
+Read the [Contributing][3] wiki page first. 
+
+Once you've made your great commits:
+
+1. [Fork][4] recommendable
+2. Create a feature branch
+3. Write your code (and tests please)
+4. Push to your branch's origin
+5. Create a [Pull Request][5] from your branch
+6. That's it!
+
+Links
+-----
+* Code: `git clone git://github.com/davidcelis/recommendable.git`
+* Home: <http://github.com/davidcelis/recommendable>
+* Docs: <http://rubydoc.info/gems/recommendable/0.1.0/frames>
+* Bugs: <http://github.com/davidcelis/recommendable/issues>
+* Gems: <http://rubygems.org/gems/recommendable>
+
+Copyright
+---------
+
+Copyright © 2012 David Celis. See LICENSE.txt for
+further details.
+
+[0]: http://davidcelis.com/blog/2012/02/01/why-i-hate-five-star-ratings/
+[1]: https://github.com/defunkt/resque
+[2]: https://github.com/ezmobius/redis-rb
+[3]: http://wiki.github.com/defunkt/resque/contributing
+[4]: http://help.github.com/forking/
+[5]: http://help.github.com/pull-requests/