correlate 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,23 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC
+doc/
+.yardoc

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Kenneth Kalmer
+
+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.rdoc

@@ -0,0 +1,137 @@
+= Correlate
+
+Correlate is an experiment in loosely expressing relationsips between documents
+stored in CouchDB using couchrest.
+
+Correlate stores all the relationships in an array of links, similar to the link
+elements found in HTML:
+
+  {
+    ...
+    "links" : [
+     { "rel" : "another_doc", "href" : "<uuid>" },
+     { "rel" : "important", "href" : "<uuid>" }
+     ...
+    ]
+    ...
+  }
+
+Inspired by looking for ways to express the loosened relationships that exists
+between documents inside CouchDB, but to not mimic the nature of an RDBMS.
+
+== Documentation
+
+* http://rdoc.info/projects/kennethkalmer/correlata
+* spec directory
+
+== Installation and dependencies
+
+Use:
+
+* couchrest 0.33 or later
+
+Development:
+
+* jeweler
+* rspec
+* activerecord
+* yard
+
+Installation:
+
+  $ gem install correlate
+
+Correlate does not depend on ActiveRecord and can be safely used in any project
+that doesn't use ActiveRecord.
+
+== Usage
+
+  require 'correlate'
+
+  class MyDocument < CouchRest::ExtendedDocument
+
+    include Correlate
+
+    related_to do
+      some :other_documents, :class => 'OtherDocument', :rel => 'other_doc'
+    end
+  end
+
+This sets up a +links+ property on the document, with some accessors for loading
+and ammending relationships:
+
+  my_doc = MyDocument.new
+
+  my_doc.other_documents << other_document_instance
+
+  my_doc.other_documents #=> [ other_document_instance ]
+
+== Associations with ActiveRecord models
+
+When transitioning from ActiveRecord to CouchDB it is inevitable that relationships
+will exist across the boundaries of each database. Correlate helps you to express
+these relationships:
+
+== CouchDB to ActiveRecord
+
+Pretty much the same as the examples above:
+
+  class MyDocument < CouchRest::ExtendedDocument
+
+    include Correlate
+
+    related_to do
+      a :model, :class => 'Model', :rel => 'model'
+    end
+  end
+
+== ActiveRecord to CouchDB
+
+When using an 'a' relationship, you don't need to specify any additional 
+information, but when specifying a 'some' relationship you'll want to supply
+the name of the view.
+
+  class SomeModel < ActiveRecord::Base
+
+    include Correlate
+
+    related_to do
+      some :documents, :class => 'Document', :view => 'some_model_id', :key => :id
+      some :notes, :class => 'Note', :rel => 'some_model'
+    end
+  end
+
+  class Document < CouchRest::ExtendedDocument
+
+    property :some_model_id
+
+    view_by :some_model_id
+  end
+
+  class Note < CouchRest::ExtendedDocument
+
+    include Correlate
+
+    related_to do
+      a :some_model, :class => 'SomeModel', :rel => 'some_model'
+    end
+  end
+
+== Status
+
+This project is highly experimental, but is in use in a few applications in one
+form or another.
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2009 Kenneth Kalmer. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,48 @@
+require 'rubygems'
+require 'rake'
+require File.dirname(__FILE__) + '/lib/correlate'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.version = Correlate::VERSION
+    gem.name = "correlate"
+    gem.summary = %Q{Help correlate individual documents in a No/Less-SQL environment}
+    gem.email = "kenneth.kalmer@gmail.com"
+    gem.homepage = "http://github.com/kennethkalmer/correlate"
+    gem.authors = ["Kenneth Kalmer"]
+    gem.add_dependency "couchrest", ">= 0.33"
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    gem.add_development_dependency "yard", ">= 0"
+    gem.add_development_dependency "activerecord", ">= 2.3.2"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yardoc do
+    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+  end
+end

data/correlate.gemspec

@@ -0,0 +1,101 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{correlate}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Kenneth Kalmer"]
+  s.date = %q{2009-12-13}
+  s.email = %q{kenneth.kalmer@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "correlate.gemspec",
+     "lib/correlate.rb",
+     "lib/correlate/correlation.rb",
+     "lib/correlate/links.rb",
+     "lib/correlate/relationships.rb",
+     "lib/correlate/relationships/active_record.rb",
+     "lib/correlate/relationships/active_record/collection_proxy.rb",
+     "lib/correlate/relationships/couchrest.rb",
+     "lib/correlate/validator.rb",
+     "spec/active_record_spec.rb",
+     "spec/activerecord_helper.rb",
+     "spec/correlate_spec.rb",
+     "spec/fixtures/article.rb",
+     "spec/fixtures/blank_doc.rb",
+     "spec/fixtures/comment.rb",
+     "spec/fixtures/course.rb",
+     "spec/fixtures/crawler.rb",
+     "spec/fixtures/news_feed.rb",
+     "spec/fixtures/note.rb",
+     "spec/fixtures/person.rb",
+     "spec/fixtures/project.rb",
+     "spec/fixtures/reader.rb",
+     "spec/fixtures/student.rb",
+     "spec/links_spec.rb",
+     "spec/relationships_spec.rb",
+     "spec/spec.opts",
+     "spec/spec_helper.rb",
+     "spec/validation_spec.rb"
+  ]
+  s.homepage = %q{http://github.com/kennethkalmer/correlate}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Help correlate individual documents in a No/Less-SQL environment}
+  s.test_files = [
+    "spec/active_record_spec.rb",
+     "spec/activerecord_helper.rb",
+     "spec/correlate_spec.rb",
+     "spec/fixtures/article.rb",
+     "spec/fixtures/blank_doc.rb",
+     "spec/fixtures/comment.rb",
+     "spec/fixtures/course.rb",
+     "spec/fixtures/crawler.rb",
+     "spec/fixtures/news_feed.rb",
+     "spec/fixtures/note.rb",
+     "spec/fixtures/person.rb",
+     "spec/fixtures/project.rb",
+     "spec/fixtures/reader.rb",
+     "spec/fixtures/student.rb",
+     "spec/links_spec.rb",
+     "spec/relationships_spec.rb",
+     "spec/spec_helper.rb",
+     "spec/validation_spec.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<couchrest>, [">= 0.33"])
+      s.add_development_dependency(%q<rspec>, [">= 1.2.9"])
+      s.add_development_dependency(%q<yard>, [">= 0"])
+      s.add_development_dependency(%q<activerecord>, [">= 2.3.2"])
+    else
+      s.add_dependency(%q<couchrest>, [">= 0.33"])
+      s.add_dependency(%q<rspec>, [">= 1.2.9"])
+      s.add_dependency(%q<yard>, [">= 0"])
+      s.add_dependency(%q<activerecord>, [">= 2.3.2"])
+    end
+  else
+    s.add_dependency(%q<couchrest>, [">= 0.33"])
+    s.add_dependency(%q<rspec>, [">= 1.2.9"])
+    s.add_dependency(%q<yard>, [">= 0"])
+    s.add_dependency(%q<activerecord>, [">= 2.3.2"])
+  end
+end
+

data/lib/correlate.rb

@@ -0,0 +1,97 @@
+# = Correlate
+#
+# Correlate is an experiment in loosely defining relationships between documents
+# stored in CouchDB using CouchRest's ExtendedDocument, as well as relationships
+# between these documents and ActiveRecord models.
+#
+# == Overview
+#
+# Relationships are defined as an array of hashes, each hash containing a +rel+
+# and +href+ key. This is modelled on HTML's success in loosely defining
+# relationships between different documents.
+#
+# A sample might look like this:
+#
+#
+#  {
+#    ...
+#    "links" : [
+#     { "rel" : "another_doc", "href" : "<uuid>" },
+#     { "rel" : "important", "href" : "<uuid>" }
+#     ...
+#    ]
+#    ...
+#  }
+#
+# == Using correlate
+#
+# Correlate presents itself as a mixin for CouchRest::ExtendedDocument classes,
+# as well as ActiveRecord models.
+#
+# === Using with CouchRest::ExtendedDocument
+#
+#   class SomeDocument < CouchRest::ExtendedDocument
+#     include Correlate
+#
+#     related_to do
+#       some :other_documents, :class => 'OtherDocument', :rel => 'other_document'
+#       a :parent_document, :class => 'ParentDocument'
+#     end
+#   end
+#
+#
+# === Using with ActiveRecord::Base
+#
+#   class Model < ActiveRecord::Base
+#     include Correlate
+#
+#     related_to do
+#       some :documents, :class => 'Document', :rel => 'model'
+#     end
+#   end
+#
+# When correlating ActiveRecord models with CouchRest documents, it is required
+# that the 'reverse correlation' is specified in the CouchRest class.
+#
+# @see Correlate::Relationships::CouchRest
+# @see Correlate::Relationships::ActiveRecord
+module Correlate
+
+  VERSION = '0.1.0'
+
+  autoload :Relationships, 'correlate/relationships'
+  autoload :Links,         'correlate/links'
+  autoload :Correlation,   'correlate/correlation'
+  autoload :Validator,     'correlate/validator'
+
+  def self.included( base )
+    base.extend( ClassMethods )
+  end
+
+  module ClassMethods
+
+    # Depending on the containing class, this method configures either a
+    # Correlate::Relationships::CouchRest or a
+    # Correlate::Relationships::ActiveRecord.
+    #
+    # @see Correlate::Relationships::CouchRest
+    # @see Correlate::Relationships::ActiveRecord
+    def related_to( &block )
+      Correlate::Relationships.configure!( self, &block )
+    end
+
+    # @private
+    def correlations
+      @correlations ||= []
+    end
+
+    # Determine the matching correlation for the provided object.
+    # @return [ Correlate::Correlation, nil ]
+    # @see Correlate::Correlation#matches?
+    def correlation_for( object )
+      self.correlations.detect { |c| c.matches?( object ) }
+    end
+
+  end
+
+end

data/lib/correlate/correlation.rb

@@ -0,0 +1,116 @@
+module Correlate
+  class Correlation
+    # Class owning the correlation
+    attr_accessor :source
+
+    # Name of the correlation
+    attr_accessor :name
+
+    # Type of relationship
+    attr_accessor :type
+
+    # Class the relationship targets
+    attr_accessor :target
+
+    # +rel+ attribute used to distinguish this correlation
+    attr_accessor :rel
+
+    # Method used to extract the 'id' from instances add to the correlation (defaults to +id+)
+    attr_accessor :id_method
+
+    # For +some+ relationships specify how many instances are required
+    attr_accessor :requires
+
+    # For +a+ relationships specify if required
+    attr_accessor :required
+
+    # Class method on the target class used when loading single instances
+    # (defaults to +get+ for CouchRest docs, and +find+ for ActiveRecord models)
+    attr_accessor :load_via
+
+    # Name of a view used to load documents from ActiveRecord's side
+    attr_accessor :view
+
+    # Determine if this correlation can be used for the provided object
+    def matches?( obj )
+      case obj
+      when CouchRest::ExtendedDocument
+        target == obj['couchrest-type']
+      when Hash
+        obj['rel'] == rel
+      else
+        target == obj.class.name
+      end
+    end
+
+    # Return the +rel+ used for this correlation. Uses #name if #rel is nil
+    def rel
+      (@rel || @name).to_s
+    end
+
+    # Return the method name used for determining the href value of the correlation.
+    # Defaults to +:id+.
+    def id_method
+      @id_method || :id
+    end
+
+    # Correlate the object from its rel/href values.
+    def correlate( object )
+
+      if direction == { :active_record => :couchdb }
+
+        raise ArgumentError, "#{target} doesn't correlate with #{source}" unless bidirectional?
+
+        return target_class.by_rel :key => [ opposite.rel, object.send( opposite.id_method ) ]
+      end
+
+      return target_class.send( load_via, object['href'] )
+    end
+
+    # Correlate the objects from their rel/href values
+    def bulk_correlate( objects )
+      results = objects.inject([]) do |results, obj|
+        results << target_class.send( load_via, obj['href'] )
+      end.compact
+    end
+
+    # Do we have a mutual correlation (ie defined in both classes)
+    def bidirectional?
+      target_class.included_modules.include?( Correlate ) && !opposite.nil?
+    end
+
+    # Determine the 'reverse correlation' from the target class
+    def opposite
+      target_class.correlations.detect { |c| c.target == source.name }
+    end
+
+    # Conveniently show the 'direction' of the correlation in terms of classes
+    # @return [ Hash ] { :couchdb => :activerecord } or vice versa or couch to couch.
+    def direction
+      f = source_class.ancestors.include?( CouchRest::ExtendedDocument ) ? :couchdb : :active_record
+      t = target_class.ancestors.include?( CouchRest::ExtendedDocument ) ? :couchdb : :active_record
+
+      { f => t }
+    end
+
+    private
+
+    # The class method used to load instances of the documents.
+    def load_via
+      @load_via ||= (
+        target_class.ancestors.include?( CouchRest::ExtendedDocument ) ? :get : :find
+      )
+    end
+
+    def target_class
+      raise "Class #{target} not found" if !Object.const_defined?( target.to_sym )
+
+      Object.const_get( target.to_sym )
+    end
+
+    def source_class
+      source
+    end
+
+  end
+end