couchmodel 0.1.0.beta3 → 0.1.0.beta4

data/README.rdoc

@@ -36,6 +36,7 @@ To define a model, it's necessary to create a subclass of <tt>CouchModel::Base</
 
     key_accessor :name
     key_accessor :email
+    key_accessor :language, :default => "en"
 
   end
 
@@ -49,7 +50,8 @@ 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.
+to use <tt>key_reader</tt> and <tt>key_writer</tt> here. If the <tt>:default</tt> option is passed, the key will get
+a default value assigned during initialization of the class.
 
 == Design documents
 
@@ -67,7 +69,7 @@ A design document should look like this
   :id:        "test_design"
   :language:  "javascript"
   :views:
-    "view_name_1":
+    :view_name_1:
       :map:
         function(document) {
           ...
@@ -76,7 +78,7 @@ A design document should look like this
         function(key, values, rereduce) {
           ...
         };
-    "view_name_2":
+    :view_name_2:
       :keys: [ "key_one", "key_two" ]
     ...
 
@@ -113,12 +115,25 @@ generates getters and setters for the session object itself (<tt>session</tt> an
 
 The <tt>has_many</tt> acts as a wrapper for the specified view. The previously defined view
 <tt>by_user_id_and_created_at</tt> 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.
+date.
+Basically, the association can be accessed by a reader method. Options for querying the view can be passed by a hash.
 
-  user.membership(created_at)
+  user.membership(:startkey => [ ... ], :endkey => [ ... ], :descending => false)
 
-The returned <tt>CouchModel::Collection</tt> can be treated as an (read-only) array.
+The possible keys for that query hash can be taken from http://wiki.apache.org/couchdb/HTTP_view_API (Section Querying
+Options).
+
+If a <tt>:query</tt> option is defined (like in the example above), the given method is used to generate this query
+hash. When querying a view, the first arguments will be passed to that method and the result of the generator-method
+will be merged with the additionally given query hash.
+
+  user.membership(created_at, :returns => :rows)
+
+The <tt>:returns</tt> option extends the possible keys defined by CouchDB. If not given or specified as
+<tt>:models</tt>, CouchModel will try to cast the returned rows into model classes. It also automatically passes the
+<tt>:include_docs</tt> option to CouchDB. If this option is specified as <tt>:rows</tt>, a collection of
+<tt>CouchModel::Row</tt> objects is returned that wraps the CouchDB result rows. That's maybe useful for views with a
+reduce function.
 
 == Rails integration
 

data/lib/core_extension/array.rb

@@ -1,13 +1,29 @@
 
+# Extention of ruby's standard array.
 class Array
 
+  def resize(length, element = nil)
+    case size <=> length
+      when 1
+        slice 0, length
+      when -1
+        result = self.dup
+        result << element while result.size < length
+        result
+      when 0
+        self
+    end
+  end
+
+  # This wrap method is taken from ActiveSupport and simply
+  # wraps an object into an array.
   def self.wrap(object)
     if object.nil?
-      []
+      [ ]
     elsif object.respond_to?(:to_ary)
       object.to_ary
     else
-      [object]
+      [ object ]
     end
   end
   

data/lib/core_extension/string.rb

@@ -1,12 +1,22 @@
 
-class String
+class String # :nodoc:
 
+  # This method converts a CamelCaseString into an underscore_string.
   def underscore
     self.gsub(/([a-z][A-Z])/){ |match| "#{match[0]}_#{match[1]}" }.downcase
   end
 
+  # This method converts an underscore_string into a CamelCaseString.
   def camelize
-    self.gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase }
+    self.camelize_path.camelize_name
+  end
+
+  def camelize_path
+    self.gsub(/\/(.?)/) { "::#{$1.upcase}" }
+  end
+
+  def camelize_name
+    self.gsub(/(?:^|_)(.)/) { $1.upcase }
   end
 
 end

data/lib/couch_model/active_model.rb

@@ -5,6 +5,7 @@ require 'active_model'
 
 module CouchModel
 
+  # Extension of class Base to implement the ActiveModel interface.
   class Base
     extend ::ActiveModel::Naming
     extend ::ActiveModel::Callbacks
@@ -15,13 +16,16 @@ module CouchModel
     include ::ActiveModel::Serializers::JSON
     include ::ActiveModel::Serializers::Xml
 
+    # The InvalidModelError is raised, e. g. if the save! method is called on an invalid model.
+    class InvalidModelError < StandardError; end
+
     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}"
+      alias_method :"#{method_name}_without_callbacks", :"#{method_name}"
 
       define_method :"#{method_name}" do |*arguments|
         send :"_run_#{method_name}_callbacks" do
@@ -35,6 +39,10 @@ module CouchModel
 
     alias destroyed? new?
 
+    def to_param
+      id
+    end
+
     alias save_without_active_model save
 
     def save
@@ -44,6 +52,12 @@ module CouchModel
       result
     end
 
+    def save!
+      raise InvalidModelError, "errors: #{errors.full_messages.join(' / ')}" unless valid?
+      raise StandardError, "unknown error while saving model" unless save
+      true
+    end
+
     private
 
     def discard_changes!
@@ -55,17 +69,18 @@ module CouchModel
 
       alias key_accessor_without_dirty key_accessor
 
-      def key_accessor(key)
+      def key_accessor(key, options = { })
         add_key key
         redefine_attribute_methods
 
-        key_accessor_without_dirty key
+        key_accessor_without_dirty key, options
+        redefine_key_writer key
+      end
 
-        alias_method :"#{key}_without_dirty=", :"#{key}="
-        define_method :"#{key}=" do |value|
-          send :"#{key}_will_change!"
-          send :"#{key}_without_dirty=", value
-        end
+      def create!(*arguments)
+        model = new *arguments
+        model.save!
+        model
       end
 
       private
@@ -80,6 +95,14 @@ module CouchModel
         define_attribute_methods @keys
       end
 
+      def redefine_key_writer(key)
+        alias_method :"#{key}_without_dirty=", :"#{key}="
+        define_method :"#{key}=" do |value|
+          send :"#{key}_will_change!"
+          send :"#{key}_without_dirty=", value
+        end        
+      end
+
     end
 
   end

data/lib/couch_model/base/accessor.rb

@@ -1,6 +1,7 @@
 
 module CouchModel
 
+  # This should extend the Base class to provide key_accessor methods.
   class Base
 
     module Accessor
@@ -13,21 +14,23 @@ module CouchModel
 
       module ClassMethods
 
-        def key_reader(key)
+        def key_reader(key, options = { })
+          set_default key, options[:default] if options.has_key?(:default)
           define_method :"#{key}" do
             @attributes[key.to_s]
           end
         end
 
-        def key_writer(key)
+        def key_writer(key, options = { })
+          set_default key, options[:default] if options.has_key?(:default)
           define_method :"#{key}=" do |value|
             @attributes[key.to_s] = value
           end
         end
 
-        def key_accessor(key)
-          key_reader key
-          key_writer key
+        def key_accessor(*arguments)
+          key_reader *arguments
+          key_writer *arguments
         end
 
       end

data/lib/couch_model/base/association.rb

@@ -1,6 +1,8 @@
+require File.expand_path(File.join(File.dirname(__FILE__), "..", "..", "core_extension", "array"))
 
 module CouchModel
 
+  # This should extend the Base class to provide association methods.
   class Base
 
     module Association
@@ -18,13 +20,30 @@ module CouchModel
           key         = options[:key]         || "#{name}_id"
 
           key_accessor key
+          define_belongs_to_reader name, class_name, key
+          define_belongs_to_writer name, class_name, key
+        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_has_many_query name, query
+          define_has_many_reader name, class_name, view_name
+        end
+
+        private
 
-          define_method :"#{name}" do
+        def define_belongs_to_reader(reader_name, class_name, key)
+          define_method :"#{reader_name}" do
             klass = Object.const_get class_name
             klass.find self.send(key)
-          end
+          end          
+        end
 
-          define_method :"#{name}=" do |value|
+        def define_belongs_to_writer(writer_name, class_name, key)
+          define_method :"#{writer_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)
@@ -35,22 +54,24 @@ module CouchModel
           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]
+        def define_has_many_query(query_name, query)
+          define_method :"#{query_name}_query", &query if query.is_a?(Proc)
+        end
 
-          define_method :"#{name}_query", &query if query.is_a?(Proc)
+        def define_has_many_reader(reader_name, class_name, view_name)
+          define_method :"#{reader_name}" do |*arguments|
+            last_argument = arguments.last
+            hash_argument = last_argument.is_a?(Hash) && last_argument
 
-          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
+            arity = 0
+            query = if self.respond_to?(:"#{reader_name}_query")
+              arity = self.method(:"#{reader_name}_query").arity
+              self.send :"#{reader_name}_query", *arguments.resize(arity)
             else
-              { :key => "\"#{self.id}\"" }
+              hash_argument || { :key => self.id }
             end
-            klass.send :"#{view_name}", query
+            query.merge! hash_argument if hash_argument && arity < arguments.size
+            Object.const_get(class_name).send :"#{view_name}", query
           end
         end
 

data/lib/couch_model/base/finder.rb

@@ -1,6 +1,7 @@
 
 module CouchModel
 
+  # This should extend the Base class to provide basic find methods.
   class Base
 
     module Finder

data/lib/couch_model/base/setup.rb

@@ -1,6 +1,7 @@
 
 module CouchModel
 
+  # This should extend the Base class to provide setup methods.
   class Base
 
     module Setup
@@ -37,12 +38,16 @@ module CouchModel
           @design || raise(StandardError, "no database defined!")
         end
 
+        def count
+          all.total_count
+        end
+
         def method_missing(method_name, *arguments, &block)
           view = find_view method_name
           view ? view.collection(*arguments) : super
         end
 
-        def respond_to?(method_name)
+        def respond_to?(method_name, *arguments)
           view = find_view method_name
           view ? true : super
         end

data/lib/couch_model/base.rb

@@ -12,20 +12,28 @@ require 'uri'
 
 module CouchModel
 
+  # Base is the main super class of all models that should be stored in CouchDB.
+  # See the README file for more informations.
   class Base
     include CouchModel::Base::Setup
     include CouchModel::Base::Accessor
     include CouchModel::Base::Finder
     include CouchModel::Base::Association
 
-    class Error < StandardError; end
+    # The NotFoundError will be raised if an operation is tried on a document that
+    # dosen't exists.
     class NotFoundError < StandardError; end
 
     attr_reader :attributes
 
     def initialize(attributes = { })
-      @attributes = { Configuration::CLASS_KEY => self.class.to_s }
+      klass = self.class
+      @attributes = { Configuration::CLASS_KEY => klass.to_s }
       self.attributes = attributes
+
+      klass.defaults.each do |key, value|
+        @attributes[key] = value unless @attributes.has_key?(key)
+      end      
     end
 
     def attributes=(attributes)
@@ -55,29 +63,25 @@ module CouchModel
     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
+      load_response Transport.request(:get, url, :expected_status_code => 200)
       true
-    rescue Transport::UnexpectedStatusCodeError => e
-      raise NotFoundError if e.status_code == 404
-      raise e
+    rescue Transport::UnexpectedStatusCodeError => error
+      upgrade_unexpected_status_error error
     end
 
+    alias reload load
+
     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
+      Transport.request :delete, self.url, :headers => { "If-Match" => self.rev }, :expected_status_code => 200
+      clear_rev
       true
-    rescue Transport::UnexpectedStatusCodeError => e
-      raise NotFoundError if e.status_code == 404
-      raise e
+    rescue Transport::UnexpectedStatusCodeError => error
+      upgrade_unexpected_status_error error
     end
 
     def url
@@ -95,8 +99,13 @@ module CouchModel
       @attributes["_rev"] = value      
     end
 
+    def load_response(response)
+      self.rev = response["_rev"]
+      self.attributes = response
+    end
+
     def create
-      response = Transport.request :post, self.database.url, :json => self.attributes, :expected_status_code => 201
+      response = Transport.request :post, self.database.url, :body => self.attributes, :expected_status_code => 201
       self.id  = response["id"]
       self.rev = response["rev"]
       true
@@ -105,13 +114,42 @@ module CouchModel
     end
 
     def update
-      response = Transport.request :put, self.url, :json => self.attributes, :expected_status_code => 201
+      response = Transport.request :put, self.url, :body => self.attributes, :expected_status_code => 201
       self.rev = response["rev"]
       true
     rescue Transport::UnexpectedStatusCodeError
       false
     end
 
+    def clear_rev
+      self.rev = nil
+    end
+
+    def upgrade_unexpected_status_error(error)
+      raise NotFoundError if error.status_code == 404
+      raise error
+    end
+
+    def self.set_default(key, value)
+      @defaults ||= { }
+      @defaults[key.to_s] = value
+    end
+
+    def self.defaults
+      @defaults || { }
+    end    
+
+    def self.create(*arguments)
+      model = new *arguments
+      model.save ? model : nil
+    end
+
+    def self.destroy_all
+      all.each do |model|
+        model.destroy
+      end
+    end
+
   end
 
 end

data/lib/couch_model/collection.rb

@@ -1,9 +1,11 @@
-require File.join(File.dirname(__FILE__), "configuration")
 require File.join(File.dirname(__FILE__), "transport")
-require 'json'
+require File.join(File.dirname(__FILE__), "row")
 
 module CouchModel
 
+  # Collection is a proxy class for the resultset of a CouchDB view. It provides
+  # all read-only methods of an array. The loading of content is lazy and
+  # will be triggerd on the first request.
   class Collection
 
     REQUEST_PARAMETER_KEYS = [
@@ -25,10 +27,11 @@ module CouchModel
 
     def initialize(url, options = { })
       @url, @options = url, options
+      @options[:returns] ||= :models
     end
 
     def total_count
-      fetch :meta => true unless @total_count
+      fetch_meta unless @total_count
       @total_count
     end
 
@@ -47,38 +50,55 @@ module CouchModel
 
     private
 
-    def fetch(options = { })
-      meta = options[:meta] || false
+    def fetch
+      fetch_response
+      evaluate_total_count
+      evaluate_entries
+      true
+    end
 
-      evaluate Transport.request(
+    def fetch_meta
+      fetch_meta_response
+      evaluate_total_count
+      true
+    end
+
+    def fetch_response
+      @response = Transport.request(
         :get, url,
-        :parameters            => request_parameters.merge(meta ? { "limit" => "0" } : { }),
+        :parameters            => request_parameters,
         :expected_status_code  => 200
       )
-      
-      true
     end
 
-    def evaluate(response)
-      @total_count = response["total_rows"]
-      @entries = response["rows"].select do |row|
-        row["doc"].has_key?(Configuration::CLASS_KEY) && Object.const_defined?(row["doc"][Configuration::CLASS_KEY])
-      end.map do |row|
-        model_class = Object.const_get row["doc"][Configuration::CLASS_KEY]
-        model = model_class.new
-        model.instance_variable_set :@attributes, row["doc"]
-        model
-      end
+    def fetch_meta_response
+      @response = Transport.request(
+        :get, url,
+        :parameters            => request_parameters.merge(:limit => 0),
+        :expected_status_code  => 200
+      )
     end
 
     def request_parameters
-      parameters = { "include_docs" => "true" }
+      parameters = @options[:returns] == :models ? { :include_docs => true } : { }
       REQUEST_PARAMETER_KEYS.each do |key|
-        parameters[ key.to_s ] = @options[key].is_a?(Array) ? JSON.dump(@options[key]) : @options[key].to_s if @options[key]
+        parameters[ key ] = @options[key] if @options.has_key?(key)
       end
       parameters
     end
 
+    def evaluate_total_count
+      @total_count = @response["total_rows"]
+    end
+    
+    def evaluate_entries
+      returns = @options[:returns]
+      @entries = @response["rows"].map do |row_hash|
+        row = CouchModel::Row.new row_hash
+        returns == :models ? row.model : row
+      end
+    end
+
   end
 
 end