couchmodel 0.1.0.beta2

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Philipp Brüll
+
+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,156 @@
+
+= CouchModel
+
+The intent of CouchModel is, to provide an easy interface handle CouchDB documents. It also comes with a ActiveModel
+implementation to integrate into an Rails 3 application.
+
+The current version is under development and open for everyone to find bugs and post them into the issue tracker.
+
+The code has been tested Ruby 1.9.1, CouchDB 0.10.0 and Rails 3.0.0.beta.
+
+== Dependencies
+
+If CouchModel is used without Rails, the ruby standard library (tested with 1.9.1) if the only requirement.
+
+If the activemodel gem is installed, CouchModel automatically provides an interface to Rails 3.
+
+To run the test suite, <tt>rspec</tt> (tested with 1.2.9) is required. A CouchDB instance is just required for the
+integration tests (task <tt>spec:integration</tt>).
+
+== Installation
+
+The gem is part of the gemcutter archive. It can be installed by simply type
+
+  gem install couchmodel
+
+== Defining a model
+
+To define a model, it's necessary to create a subclass of <tt>CouchModel::Base</tt>
+
+  class User < CouchModel::Base
+
+    setup_database :url                     => "http://localhost:5984/test",
+                   :setup_on_initialization => true,
+                   :delete_if_exists        => false
+
+    key_accessor :name
+    key_accessor :email
+
+  end
+
+The <tt>setup_database</tt> method defines a database for the model. The +url+ option is required and specifies the url
+of the database in the scheme <em>http://[host]:[port]/[database_name]</em>. If the option
+<tt>setup_on_initialization</tt> is set to true, CouchModel will try to create the database when the model is
+initialized. If the option <tt>delete_if_exists</tt> is specified, the database will be deleted and re-created. If the
+option <tt>setup_on_initialization</tt> is not specified or false, the database setup be done manually by calling
+<tt>CouchModel::Configuration.setup_databases</tt> and <tt>CouchModel::Configuration.setup_designs</tt>.
+
+The method <tt>key_accessor</tt> defined access methods to the given keys of the CouchDB document. It's also possible
+to use <tt>key_reader</tt> and <tt>key_writer</tt> here.
+
+== Design documents
+
+Each defined model has a realted design document, that keeps all the views for that model. Via the command
+
+  CouchModel::Configuration.design_directory = "[directory]"
+
+a directory is specfied that keeps all the design document. CouchModel will watch out for a file with the name
+<em>[design directory]/[model_name].design</em> and will use it as the related design document. If no such file exists,
+a design document will be created (but not saved to the file). The design ducument can be asscessed via
+<tt>Model.design</tt>.
+
+A design document should look like this
+
+  :id:        "test_design"
+  :language:  "javascript"
+  :views:
+    "view_name_1":
+      :map:
+        function(document) {
+          ...
+        };
+      :reduce:
+        function(key, values, rereduce) {
+          ...
+        };
+    "view_name_2":
+      :keys: [ "key_one", "key_two" ]
+    ...
+
+It will create the methods <tt>Model.view_name_1</tt> and <tt>Model.view_name_2</tt>, which returns the result of the
+related view. It's also possible to pass some extra options like <tt>startkey</tt> or <tt>key</tt> to these methods.
+
+The view can be defined by write down a map and a reduce function or provide the <tt>keys</tt> array. If the
+<tt>keys</tt> array is given, CouchModel will generate a map function that emits the given array of document keys. The
+reduce function will be set to null.
+
+CouchModel also creates by default a class view. This view simply selects all documents from the corresponding model
+and is assigned to the method <tt>Model.all</tt>.
+
+== Associations
+
+CouchModel provides support for simple association definition. Currently, the method <tt>belongs_to</tt> and
+<tt>has_many</tt> are implmented.
+
+  class User < CouchModel::Base
+
+    ...
+
+    belongs_to :session, :class_name => "UserSession"
+
+    has_many :memberships,
+             :class_name => "Membership",
+             :view_name  => :by_user_id_and_created_at
+             :query      => proc { |created_at| { :startkey => [ self.id, (create_at || nil) ], :endkey => [ self.id, (created_at || { }) ] } }
+
+  end
+
+In this example, the <tt>belongs_to</tt> adds a <tt>key_accessor</tt> named <tt>session_id</tt> to the user and also
+generates getters and setters for the session object itself (<tt>session</tt> and <tt>session=</tt>).
+
+The <tt>has_many</tt> acts as a wrapper for the specified view. The previously defined view
+<em>by_user_id_and_created_at</em> emits membership-documents by thier <tt>user_id</tt> and the <tt>created_at</tt>
+date. The given query option specifes a method that returns a query hash for the specifed view. The arguments for this
+method can be passed membership association method.
+
+  user.membership(created_at)
+
+The returned <tt>CouchModel::Collection</tt> can be treated as an (read-only) array.
+
+== Rails integration
+
+The following steps has been tested with the first beta version of Rails 3 (activemodel-3.0.0.beta).
+
+First of all, the <tt>couchmodel</tt> gem has to added to the dependencies. This can be done by adding
+
+  gem "couchmodel", :require => "couch_model"
+
+to the <tt>Gemfile</tt>.
+
+The configuration can be done by creating an initializer. Here is an example file
+(e.g. <tt>config/initializer/couch_model.rb</tt>).
+
+  CouchModel::Configuration.design_directory = File.join(Rails.root, "app", "models", "designs")
+
+  DATABASE = {
+    :test        => { :url => "http://localhost:5984/test",        :setup_on_initialization => true, :delete_if_exists => true  }
+    :development => { :url => "http://localhost:5984/development", :setup_on_initialization => true, :delete_if_exists => false },
+    :production  => { :url => "http://localhost:5984/production",  :setup_on_initialization => true, :delete_if_exists => false }
+  }[Rails.env.to_sym] unless defined?(DATABASE)
+
+This example uses an sub-directory of <tt>app/models</tt> to search for the design documents. It also defined a constant
+named <tt>DATABASE</tt> that is initialized with the right database setup for the each environment. This constant can
+then be used to define the models.
+
+  class User < CouchModel::Base
+
+    setup_database DATABASE
+
+    ...
+
+  end
+
+== Development
+
+CouchModel is still under development and needs to be tested. Any contribution is welcome!
+

data/Rakefile

@@ -0,0 +1,20 @@
+require 'rubygems'
+gem 'rspec'
+require 'spec'
+require 'spec/rake/spectask'
+
+task :default => :spec
+
+desc "Run all specs in spec directory"
+Spec::Rake::SpecTask.new do |task|
+  task.spec_files = FileList["spec/lib/**/*_spec.rb"]
+end
+
+namespace :spec do
+  
+  desc "Run all integration specs in spec/integration directory"
+  Spec::Rake::SpecTask.new(:integration) do |task|
+    task.spec_files = FileList["spec/integration/**/*_spec.rb"]
+  end
+
+end

data/lib/core_extension/array.rb

@@ -0,0 +1,14 @@
+
+class Array
+
+  def self.wrap(object)
+    if object.nil?
+      []
+    elsif object.respond_to?(:to_ary)
+      object.to_ary
+    else
+      [object]
+    end
+  end
+  
+end

data/lib/core_extension/string.rb

@@ -0,0 +1,12 @@
+
+class String
+
+  def underscore
+    self.gsub(/([a-z][A-Z])/){ |match| "#{match[0]}_#{match[1]}" }.downcase
+  end
+
+  def camelize
+    self.gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase }
+  end
+
+end

data/lib/couch_model/active_model.rb

@@ -0,0 +1,86 @@
+require File.expand_path(File.join(File.dirname(__FILE__), "..", "core_extension", "array"))
+require File.expand_path(File.join(File.dirname(__FILE__), "base"))
+gem 'activemodel'
+require 'active_model'
+
+module CouchModel
+
+  class Base
+    extend ::ActiveModel::Naming
+    extend ::ActiveModel::Callbacks
+    extend ::ActiveModel::Translation
+    include ::ActiveModel::Conversion
+    include ::ActiveModel::Dirty
+    include ::ActiveModel::Validations
+    include ::ActiveModel::Serializers::JSON
+    include ::ActiveModel::Serializers::Xml
+
+    CALLBACKS = [ :initialize, :save, :create, :update, :destroy ].freeze unless defined?(CALLBACKS)
+
+    define_model_callbacks *CALLBACKS
+
+    CALLBACKS.each do |method_name|
+
+      alias :"#{method_name}_without_callbacks" :"#{method_name}"
+
+      define_method :"#{method_name}" do |*arguments|
+        send :"_run_#{method_name}_callbacks" do
+          send :"#{method_name}_without_callbacks", *arguments
+        end
+      end
+
+    end
+
+    alias new_record? new?
+
+    alias destroyed? new?
+
+    alias save_without_dirty save
+
+    def save
+      result = save_without_dirty
+      discard_changes!
+      result
+    end
+
+    private
+
+    def discard_changes!
+      @previously_changed = changes
+      @changed_attributes = { }
+    end
+
+    class << self
+
+      alias key_accessor_without_dirty key_accessor
+
+      def key_accessor(key)
+        add_key key
+        redefine_attribute_methods
+
+        key_accessor_without_dirty key
+
+        alias_method :"#{key}_without_dirty=", :"#{key}="
+        define_method :"#{key}=" do |value|
+          send :"#{key}_will_change!"
+          send :"#{key}_without_dirty=", value
+        end
+      end
+
+      private
+
+      def add_key(key)
+        @keys ||= [ ]
+        @keys << key
+      end
+
+      def redefine_attribute_methods
+        undefine_attribute_methods
+        define_attribute_methods @keys
+      end
+
+    end
+
+  end
+
+end

data/lib/couch_model/base/accessor.rb

@@ -0,0 +1,39 @@
+
+module CouchModel
+
+  class Base
+
+    module Accessor
+
+      def self.included(base_class)
+        base_class.class_eval do
+          extend ClassMethods
+        end
+      end
+
+      module ClassMethods
+
+        def key_reader(key)
+          define_method :"#{key}" do
+            @attributes[key.to_s]
+          end
+        end
+
+        def key_writer(key)
+          define_method :"#{key}=" do |value|
+            @attributes[key.to_s] = value
+          end
+        end
+
+        def key_accessor(key)
+          key_reader key
+          key_writer key
+        end
+
+      end
+
+    end
+
+  end
+
+end

data/lib/couch_model/base/association.rb

@@ -0,0 +1,63 @@
+
+module CouchModel
+
+  class Base
+
+    module Association
+
+      def self.included(base_class)
+        base_class.class_eval do
+          extend ClassMethods
+        end
+      end
+
+      module ClassMethods
+
+        def belongs_to(name, options = { })
+          class_name  = options[:class_name]  || name.to_s.camelize
+          key         = options[:key]         || "#{name}_id"
+
+          key_accessor key
+
+          define_method :"#{name}" do
+            klass = Object.const_get class_name
+            klass.find self.send(key)
+          end
+
+          define_method :"#{name}=" do |value|
+            klass = Object.const_get class_name
+            if value
+              raise ArgumentError, "only objects of class #{klass} are accepted" unless value.is_a?(klass)
+              self.send :"#{key}=", value.id
+            else
+              self.send :"#{key}=", nil
+            end
+          end
+        end
+
+        def has_many(name, options = { })
+          class_name  = options[:class_name]  || name.to_s.camelize
+          view_name   = options[:view_name]   || raise(ArgumentError, "no view_name is given")
+          query       = options[:query]
+
+          define_method :"#{name}_query", &query if query.is_a?(Proc)
+
+          define_method :"#{name}" do |*arguments|
+            klass = Object.const_get class_name
+            query = if self.respond_to?(:"#{name}_query")
+              arguments << nil while arguments.length < self.method(:"#{name}_query").arity
+              self.send :"#{name}_query", *arguments
+            else
+              { :key => "\"#{self.id}\"" }
+            end
+            klass.send :"#{view_name}", query
+          end
+        end
+
+      end
+
+    end
+
+  end
+
+end

data/lib/couch_model/base/finder.rb

@@ -0,0 +1,28 @@
+
+module CouchModel
+
+  class Base
+
+    module Finder
+
+      def self.included(base_class)
+        base_class.class_eval do
+          extend ClassMethods
+        end
+      end
+
+      module ClassMethods
+
+        def find(id)
+          document = new :id => id
+          document.load
+          document
+        end
+
+      end
+
+    end
+
+  end
+
+end

data/lib/couch_model/base/setup.rb

@@ -0,0 +1,88 @@
+
+module CouchModel
+
+  class Base
+
+    module Setup
+
+      def self.included(base_class)
+        base_class.class_eval do
+          include InstanceMethods
+          extend ClassMethods
+        end
+      end
+
+      module InstanceMethods
+
+        def database
+          self.class.database
+        end
+        
+      end
+
+      module ClassMethods
+
+        def setup_database(options = { })
+          initialize_database options
+          initialize_design
+          generate_class_view
+          push_design options
+        end
+
+        def database
+          @database || raise(StandardError, "no database defined!")
+        end
+
+        def design
+          @design || raise(StandardError, "no database defined!")
+        end
+
+        def method_missing(method_name, *arguments, &block)
+          view = find_view method_name
+          view ? view.collection(*arguments) : super
+        end
+
+        def respond_to?(method_name)
+          view = find_view method_name
+          view ? true : super
+        end
+
+        private
+
+        def initialize_database(options)
+          url                     = options[:url] || raise(ArgumentError, "no url was given to define the database")
+          setup_on_initialization = options[:setup_on_initialization] || false
+
+          uri = URI.parse url
+          server = Server.new :host => uri.host, :port => uri.port
+          database = Database.new :server => server, :name => uri.path.gsub("/", "")
+          @database = Configuration.register_database database
+
+          @database.setup! options if setup_on_initialization && @database === database
+        end
+
+        def initialize_design
+          @design = Design.new @database, self, :id => self.to_s.underscore
+          Configuration.register_design @design
+        end
+
+        def generate_class_view
+          @design.generate_view Configuration::CLASS_VIEW_NAME
+        end
+
+        def push_design(options)
+          setup_on_initialization = options[:setup_on_initialization] || false
+          @design.push if setup_on_initialization
+        end
+
+        def find_view(name)
+          @design ? @design.views.select{ |view| view.name == name.to_s }.first : nil
+        end
+
+      end
+
+    end
+
+  end
+
+end

data/lib/couch_model/base.rb

@@ -0,0 +1,117 @@
+require File.expand_path(File.join(File.dirname(__FILE__), "..", "core_extension", "string"))
+require File.join(File.dirname(__FILE__), "configuration")
+require File.join(File.dirname(__FILE__), "transport")
+require File.join(File.dirname(__FILE__), "server")
+require File.join(File.dirname(__FILE__), "database")
+require File.join(File.dirname(__FILE__), "design")
+require File.join(File.dirname(__FILE__), "base", "setup")
+require File.join(File.dirname(__FILE__), "base", "accessor")
+require File.join(File.dirname(__FILE__), "base", "finder")
+require File.join(File.dirname(__FILE__), "base", "association")
+require 'uri'
+
+module CouchModel
+
+  class Base
+    include CouchModel::Base::Setup
+    include CouchModel::Base::Accessor
+    include CouchModel::Base::Finder
+    include CouchModel::Base::Association
+
+    class Error < StandardError; end
+    class NotFoundError < StandardError; end
+
+    attr_reader :attributes
+
+    def initialize(attributes = { })
+      @attributes = { Configuration::CLASS_KEY => self.class.to_s }
+      self.attributes = attributes
+    end
+
+    def attributes=(attributes)
+      attributes.each { |key, value| self.send :"#{key}=", value if self.respond_to?(:"#{key}=") }
+    end
+
+    def id
+      @attributes["_id"]
+    end
+    alias :_id :id
+
+    def id=(value)
+      @attributes["_id"] = value
+    end
+
+    def rev
+      @attributes["_rev"]
+    end
+    alias :_rev :rev
+
+    def ==(other)
+      self.id == other.id
+    end
+
+    def new?
+      self.rev.nil?
+    end
+
+    def load
+      response = Transport.request :get, url, :expected_status_code => 200
+
+      self.rev = response["_rev"]
+      [ "_id", "_rev", Configuration::CLASS_KEY ].each { |key| response.delete key }
+      self.attributes = response
+      true
+    rescue Transport::UnexpectedStatusCodeError => e
+      raise NotFoundError if e.status_code == 404
+      raise e
+    end
+
+    def save
+      new? ? create : update
+    end
+
+    def destroy
+      return false if new?
+      Transport.request :delete, self.url, :parameters => { "rev" => self.rev }, :expected_status_code => 200
+      self.rev = nil
+      true
+    rescue Transport::UnexpectedStatusCodeError => e
+      raise NotFoundError if e.status_code == 404
+      raise e
+    end
+
+    def url
+      "#{self.database.url}/#{self.id}"
+    end
+
+    def method_missing(method_name, *arguments, &block)
+      return @attributes[Configuration::CLASS_KEY] if Configuration::CLASS_KEY == method_name.to_s
+      super
+    end
+
+    private
+
+    def rev=(value)
+      @attributes["_rev"] = value      
+    end
+
+    def create
+      response = Transport.request :post, self.database.url, :json => self.attributes, :expected_status_code => 201
+      self.id  = response["id"]
+      self.rev = response["rev"]
+      true
+    rescue Transport::UnexpectedStatusCodeError
+      false
+    end
+
+    def update
+      response = Transport.request :put, self.url, :json => self.attributes, :expected_status_code => 200
+      self.rev = response["rev"]
+      true
+    rescue Transport::UnexpectedStatusCodeError
+      false
+    end
+
+  end
+
+end