opinions 0.0.1

data/.autotest

@@ -0,0 +1,18 @@
+require 'autotest/restart'
+
+class Autotest
+
+#  def get_to_green
+#    begin
+#      rerun_all_tests
+#      wait_for_changes unless all_good
+#    end until all_good
+#  end
+
+end
+
+Autotest.add_hook :initialize do |at|
+  at.add_mapping(/^test.*\/.*_test_.*rb$/) do |filename, _|
+    filename  
+  end
+end

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in emotions.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Lee Hambley
+
+MIT License
+
+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.md

@@ -0,0 +1,183 @@
+# Opinions
+
+**Store opinions in Redis.** *Opinions* allows the storage of opinions in
+Redis, a fast and atomic structured data store. If one's users *hate*, *love*,
+*appreciate*, *despise* or *just-don-t-care*, one can store that easily via a
+simple API.
+
+It is not bound to *ActiveRecord*, or any other big libraries, any class exposing a
+public `id` method can be used. The `id` method is not required to be
+numerical.
+
+``` ruby
+class CatPicture < ActiveRecord::Base
+
+  include Opinions::Pollable
+  opinions :like, :dislike
+
+end
+```
+
+This simple example shows that in our logical model cat pictures can either be
+liked, or disliked. The following methods are available to all instances of `CatPicture`:
+
+ * `like_by(...)`
+ * `cancel_like_by(...)`
+ * `like_votes()`
+ * `dialike_by(...)`
+ * `cancel_dislike_by(...)`
+ * `dislike_votes()`
+
+On the flip-side, one needs a way to share one's feelings, from the model representing
+a user, or rater, or similar, one can easily use the opposite:
+
+``` ruby
+class User < ActiveRecord::Base
+
+  include Opinions::Opinionated
+  opinions :like, :dislike
+
+end
+```
+
+This module will mix-into the `User` the following methods:
+
+ * `like(...)`
+ * `dislike(...)`
+ * `cancel_like(...)`
+ * `cancel_dislike(...)`
+ * `like_opinions()`
+ * `dislike_opinions()`
+ * `have_like_on(...)`
+ * `have_dislike_on(...)`
+
+These methods can be passed instances of any class which has those opinions defined.
+
+It should be absolutely trivial to extend these to any behaviour you
+need. 
+
+**Note:** It is by design that these methods do not read particularly
+naturally, you are invited to read the source, and tests of the
+Pollable, and Opinionated modules and implement them in a way which
+better reflects the grammar of your application, and desired *Opinions*.
+Think of these modules as examples, something to expand upon.
+
+## Inspiration
+
+*Opinions* is inspired by [`schneems/likeable`](https://github.com/schneems/Likeable). A few
+things concerned me about that project, so I wrote *opinions* after contributing
+significant fixes to *likeable*.
+
+### What's different from *Likeable*?
+
+* There are no hard-coded assumptions about which opinions you'll be using, that's
+  up to your project needs.
+
+* There are no callbacks, these are better handled with observers, either in the
+  classical OOP meaning of the word, or your framework's pattern. (In Rails they're
+  the same thing)
+
+* A *very* comprehensive test suite, written with *MiniTest*. *Likeable* is quite
+  simple, and has about ~35 tests, that might be OK for you, and Gowalla, but I'd
+  feel better with real unit, functional and integration tests.
+
+* It's not *totally* bound to Redis. Internally there's a Key/Value store proxy, this
+  uses Redis out of the box, but it should be easy for someone to replace this with
+  MongoDB, Riak, DynamoDB, SQLite, etc.
+
+* It does not depend on *ActiveSupport*, *likeable* depends on *keytar*, which depends
+  on `ActiveSupport` for inflection and *ActiveSupport::Concern.*
+
+* It does not depend on `Keytar`, Keytar is a handy tool for building NoSQL keys for
+  objects, however it's a little bit over-featured for this use-case.
+
+* *Likeable* stores timestamps as floating point numbers, I'm confused
+  by this. Sub-second resoltion seems unusual here, and isn't easy for a
+  human being to read. *Opinions* uses the time format: `%Y-%m-%d %H:%M:%S %z`.
+
+* *Likeable* doesn't store *symetrical* relationships, using *Likeable*
+  it's only possible to have one type of object sharing opinions on any
+  other (*Users*). *Opinions* stores the relationship symetrically, so
+  many kinds of objects can store many kinds of opinions.
+
+* *Likeable* stores the class name unaltered, this can cause problems
+  with namespaced classes as the class namespace separator in Ruby is
+  `::`, this conflicts with the sepatator traditionally used in Redis.
+  *Opinions* stores the class names processed with an *ActiveSupport*
+  inspired `underscore` method which uses the forward slash character to
+  represent a namespace delimiter.
+
+## Migrating from *Likeable*
+
+Unfortunately the key structure is sufficiently different that you'll
+need to explicitly migrate, there's no shortcut. The key to migrating
+sucessfully is that the `vote(target)` and `vote_by(object)` methods
+take an optional time parameter in the second position. If this is
+passed then it will
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'opinions'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install opinions
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+
+## Sample Key Structure
+
+Given the following example, the key
+structure would be:
+
+``` ruby
+class Recommendation
+  iclude Opinions::Pollable
+  opinions :like
+end
+
+class User
+  include Opinions::Opinionated
+
+end
+
+User.find(123).like(Recommendation.find(789)
+User.find(123).like(Recommendation.find(987)
+
+User.find(321).like(Recommendation.find(789)
+```
+
+The resulting Redis structure would be something like this:
+
+``` text
+user:like:123:recommendation
+  "789" "2012-11-13 00:01:02 +01:00"
+  "987" "2011-02-01 00:03:01 +01:00"
+
+user:like:321:recommendation
+  "789" "2014-02-01 17:15:01 +01:00"
+
+recommendation:like:789:user
+  "123" "2012-11-13 00:01:02 +01:00"
+  "321" "2014-02-01 17:15:01 +01:00"
+
+recommendation:like:987:user
+  "123" "2011-02-01 00:03:01 +01:00"
+```

data/Rakefile

@@ -0,0 +1,30 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+namespace :test do
+
+  Rake::TestTask.new(:units) do |t|
+    t.libs << "test"
+    t.test_files = FileList['test/unit_test*.rb']
+  end
+
+  Rake::TestTask.new(:acceptance) do |t|
+    t.libs << "test"
+    t.test_files = FileList['test/acceptance_test*.rb']
+  end
+
+  Rake::TestTask.new(:integration) do |t|
+    t.libs << "test"
+    t.test_files = FileList['test/integration_test*.rb']
+  end
+
+  task :default do
+    Rake::Task['test:units'].execute
+    Rake::Task['test:acceptance'].execute
+    Rake::Task['test:integration'].execute
+  end
+
+end
+
+task :default => 'test:default'

data/lib/opinions.rb

@@ -0,0 +1,270 @@
+require 'opinions/version'
+require 'singleton'
+require 'redis'
+
+module Opinions
+
+  class << self
+    attr_accessor :backend
+  end
+
+  module KeyBuilderExtensions
+
+    def generate_key(scope, id = nil)
+      [self.class.name, scope, id].compact.join(':')
+    end
+
+  end
+
+  class KeyBuilder
+
+    def initialize(args)
+      @object  = args.fetch(:object)
+      @target  = args.fetch(:target, nil)
+      @opinion = args.fetch(:opinion)
+    end
+
+    def key
+      object = @object.dup
+      object.class.send(:include, KeyBuilderExtensions)
+      key = object.generate_key(@opinion, object.id)
+      if @target
+        tcn = @target.class == Class ? @target.name : @target.class.name
+        key += ":#{tcn}"
+      end
+      key
+    end
+
+  end
+
+  class OpinionFactory
+    attr_reader :key_name
+    def initialize(args)
+      @direction = args.has_key?(:from_target) ? :ot : :to
+      @key_name  = args.first[1]
+    end
+    def opinion
+      Opinions.backend.read_key(key_name).collect do |object_id, time|
+        target_class_name, opinion, target_id, object_class_name = key_name.split ':'
+        target_class, object_class = Kernel.const_get(target_class_name), Kernel.const_get(object_class_name)
+        Opinion.new(target: (@direction == :to ? object_class.find(object_id) : target_class.find(target_id)),
+                    object: (@direction == :to ? target_class.find(target_id) : object_class.find(object_id)),
+                    opinion: opinion.to_sym,
+                    created_at: time)
+      end
+    end
+  end
+
+  class RedisBackend
+
+    attr_accessor :redis
+
+    def write_keys(key_hashes)
+      redis.multi do
+        key_hashes.each do |key_name, hash|
+          write_key(key_name, hash)
+        end
+      end
+    end
+
+    def write_key(key_name, hash)
+      hash.each do |hash_key, hash_value|
+        redis.hset key_name, hash_key, hash_value
+      end
+    end
+    private :write_key
+
+    def read_key(key_name)
+      redis.hgetall(key_name)
+    end
+
+    def read_sub_key(key_name, key)
+      redis.hget(key_name, key)
+    end
+
+    def remove_sub_keys(key_pairs)
+      redis.multi do
+        key_pairs.each do |key_name, key|
+          redis.hdel(key_name, key.to_s)
+        end
+      end
+    end
+
+    def keys_matching(argument)
+      redis.keys(argument)
+    end
+
+  end
+
+  class KeyLoader
+
+    def initialize(key)
+      @object_class, @opinion, @object_id, @target_class = key.split(':')
+    end
+
+    def object
+      Object.const_get(@object_class).find(_object_id)
+    end
+
+    private
+
+      def _object_id
+        @object_id.to_i == @object_id ? @object_id : @object_id.to_i
+      end
+
+  end
+
+  class Opinion
+
+    attr_accessor :target, :object, :opinion, :created_at
+
+    def initialize(args = {})
+      @target, @object, @opinion, @created_at =
+        args.fetch(:target), args.fetch(:object), args.fetch(:opinion), args.fetch(:created_at, nil)
+      self
+    end
+
+    def persist(args = {time: Time.now.utc})
+      backend.write_keys({
+        target_key => {object.id.to_s => args.fetch(:time)},
+        object_key => {target.id.to_s => args.fetch(:time)},
+      })
+    end
+
+    def object_key
+      KeyBuilder.new(object: object, opinion: opinion, target: target).key
+    end
+
+    def target_key
+      KeyBuilder.new(object: target, opinion: opinion, target: object).key
+    end
+
+    def exists?
+      tk = backend.read_sub_key(target_key, object.id.to_s)
+      ok = backend.read_sub_key(object_key, target.id.to_s)
+      tk && ok
+    end
+
+    def remove
+      backend.remove_sub_keys([[target_key, object.id.to_s],
+                               [object_key, target.id.to_s]])
+    end
+
+    def ==(other_opinion)
+      raise ArgumentError, "Can't compare a #{other_opinion} with #{self}" unless other_opinion.is_a?(Opinion)
+      opinion_equal  = self.opinion == other_opinion.opinion
+      opinion_target = self.target  == other_opinion.target
+      opinion_object = self.object  == other_opinion.object
+      opinion_equal && opinion_target && opinion_object
+    end
+
+    private
+
+      def backend
+        Opinions.backend
+      end
+
+  end
+
+  module Pollable
+
+    class << self
+
+      def included(klass)
+        klass.send(:include, InstanceMethods)
+        klass.send(:extend,  ClassMethods)
+      end
+
+    end
+
+    module ClassMethods
+      def opinions(*opinions)
+        opinions.each { |opinion| register_opinion(opinion.to_sym) }
+      end
+      def register_opinion(name)
+        @registered_opinions ||= Array.new
+        @registered_opinions <<  name
+      end
+      def registered_opinions
+        @registered_opinions
+      end
+    end
+
+    module InstanceMethods
+
+      def initialize(*args)
+        super
+        self.class.registered_opinions.each do |opinion|
+          self.class.send :define_method, :"#{opinion}_by" do |*args|
+            opinionated, time = *args
+            time              = time || Time.now.utc
+            e = Opinion.new(object: opinionated, target: self, opinion: opinion)
+            true & e.persist(time: time)
+          end
+          self.class.send :define_method, :"cancel_#{opinion}_by" do |opinionated|
+            true & Opinion.new(object: opinionated, target: self, opinion: opinion).remove
+          end
+         self.class.send :define_method, :"#{opinion}_votes" do
+           lookup_key_builder = KeyBuilder.new(object: self, opinion: opinion)
+           keys = Opinions.backend.keys_matching(lookup_key_builder.key + "*")
+           keys.collect do |key_name|
+             OpinionFactory.new(from_target: key_name).opinion
+           end.flatten
+         end
+        end
+      end
+
+    end
+
+  end
+
+  module Opinionated
+
+    def self.included(klass)
+      klass.send(:include, InstanceMethods)
+      klass.send(:extend,  ClassMethods)
+    end
+
+    module ClassMethods
+      def opinions(*opinions)
+        opinions.each { |opinion| register_opinion(opinion.to_sym) }
+      end
+      def register_opinion(name)
+        @registered_opinions ||= Array.new
+        @registered_opinions <<  name
+      end
+      def registered_opinions
+        @registered_opinions
+      end
+    end
+
+    module InstanceMethods
+      def initialize(*args)
+        super
+        self.class.registered_opinions.each do |opinion|
+          self.class.send :define_method, :"#{opinion}" do |*args|
+            target, time = *args
+            time         = time || Time.now.utc
+            e = Opinion.new(object: self, target: target, opinion: opinion)
+            true & e.persist(time: time)
+          end
+          self.class.send :define_method, :"cancel_#{opinion}" do |pollable|
+            true & Opinion.new(object: self, target: pollable, opinion: opinion).remove
+          end
+          self.class.send :define_method, :"have_#{opinion}_on" do |pollable|
+            send("#{opinion}_opinions").collect { |o| o.target == pollable }.any?
+          end
+          self.class.send :define_method, :"#{opinion}_opinions" do
+            lookup_key_builder = KeyBuilder.new(object: self, opinion: opinion)
+            keys = Opinions.backend.keys_matching(lookup_key_builder.key + "*")
+            keys.collect do |key_name|
+              OpinionFactory.new(from_object: key_name).opinion
+            end.flatten
+          end
+        end
+      end
+    end
+
+  end
+
+end