couchrest_model 1.0.0 → 1.1.0.beta

data/.gitignore

@@ -2,7 +2,7 @@
 html/*
 pkg
 *.swp
-.rvmrc
+.rvmrc*
 .bundle
 couchdb.std*
 *.*~

data/Gemfile.lock

@@ -1,52 +1,51 @@
 PATH
   remote: .
   specs:
-    couchrest_model (1.0.0)
+    couchrest_model (1.1.0.beta)
       activemodel (~> 3.0.0)
-      couchrest (~> 1.0.1)
+      couchrest (~> 1.0.2)
       mime-types (~> 1.15)
       railties (~> 3.0.0)
-      rspec (>= 2.0.0)
       tzinfo (~> 0.3.22)
 
 GEM
   remote: http://rubygems.org/
   specs:
     abstract (1.0.0)
-    actionpack (3.0.3)
-      activemodel (= 3.0.3)
-      activesupport (= 3.0.3)
+    actionpack (3.0.4)
+      activemodel (= 3.0.4)
+      activesupport (= 3.0.4)
       builder (~> 2.1.2)
       erubis (~> 2.6.6)
       i18n (~> 0.4)
       rack (~> 1.2.1)
       rack-mount (~> 0.6.13)
-      rack-test (~> 0.5.6)
+      rack-test (~> 0.5.7)
       tzinfo (~> 0.3.23)
-    activemodel (3.0.3)
-      activesupport (= 3.0.3)
+    activemodel (3.0.4)
+      activesupport (= 3.0.4)
       builder (~> 2.1.2)
       i18n (~> 0.4)
-    activesupport (3.0.3)
+    activesupport (3.0.4)
     builder (2.1.2)
-    couchrest (1.0.1)
-      json (>= 1.4.6)
-      mime-types (>= 1.15)
-      rest-client (>= 1.5.1)
+    couchrest (1.0.2)
+      json (~> 1.5.1)
+      mime-types (~> 1.15)
+      rest-client (~> 1.6.1)
     diff-lcs (1.1.2)
     erubis (2.6.6)
       abstract (>= 1.0.0)
     i18n (0.5.0)
-    json (1.4.6)
+    json (1.5.1)
     mime-types (1.16)
     rack (1.2.1)
     rack-mount (0.6.13)
       rack (>= 1.0.0)
     rack-test (0.5.7)
       rack (>= 1.0)
-    railties (3.0.3)
-      actionpack (= 3.0.3)
-      activesupport (= 3.0.3)
+    railties (3.0.4)
+      actionpack (= 3.0.4)
+      activesupport (= 3.0.4)
       rake (>= 0.8.7)
       thor (~> 0.14.4)
     rake (0.8.7)
@@ -61,14 +60,14 @@ GEM
       diff-lcs (~> 1.1.2)
     rspec-mocks (2.3.0)
     thor (0.14.6)
-    tzinfo (0.3.23)
+    tzinfo (0.3.24)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   activemodel (~> 3.0.0)
-  couchrest (~> 1.0.1)
+  couchrest (~> 1.0.2)
   couchrest_model!
   mime-types (~> 1.15)
   rack-test (>= 0.5.7)

data/README.md

@@ -9,7 +9,7 @@ for validations and callbacks.
 If your project is still running Rails 2.3, you'll have to continue using ExtendedDocument as 
 it is not possible to load ActiveModel into programs that do not use ActiveSupport 3.0.
 
-CouchRest Model is only tested on CouchDB 1.0.0 or newer.
+CouchRest Model is only properly tested on CouchDB version 1.0 or newer.
 
 ## Install
 
@@ -19,15 +19,20 @@ CouchRest Model is only tested on CouchDB 1.0.0 or newer.
 
 ### Bundler
 
-If you're using bundler, just define a line similar to the following in your project's Gemfile:
+If you're using bundler, define a line similar to the following in your project's Gemfile:
 
     gem 'couchrest_model'
 
-You might also consider using the latest git repository. All tests should pass in the master code branch
-but no guarantees!
+You might also consider using the latest git repository. We try to make sure the current version in git is stable and at the very least all tests should pass.
 
     gem 'couchrest_model', :git => 'git://github.com/couchrest/couchrest_model.git'
 
+### Setup
+
+There is currently no standard way for telling CouchRest Model how it should access your database, this is something we're still working on. For the time being, the easiest way is to set a COUCHDB_DATABASE global variable to an instance of CouchRest Database, and call `use_database COUCHDB_DATABASE` in each model.
+
+TODO: Add an example!
+
 ### Development
 
 CouchRest Model now comes with a Gemfile to help with development. If you want to make changes to the code, download a copy then run:
@@ -94,7 +99,7 @@ be type casted and other options such as the default value. These replace your t
 `add_column` methods found in relational database migrations.
 
 Attributes with a property definition will have setter and getter methods defined for them. Any other attibute
-can be set in the same way you'd update a Hash, this funcionality is inherited from CouchRest Documents.
+can be set as if the model were a Hash, this funcionality is inherited from CouchRest Documents.
 
 Here are a few examples of the way properties are used:
 
@@ -216,7 +221,7 @@ you'd like to use. For example:
       property :toys, [CatToy]
     end
 
-    @cat = Cat.new(:name => 'Felix', :toys => [{:name => 'mouse', :purchases => 1.month.ago}])
+    @cat = Cat.new(:name => 'Felix', :toys => [{:name => 'mouse', :purchased => 1.month.ago}])
     @cat.toys.first.class == CatToy
     @cat.toys.first.name == 'mouse'
 
@@ -232,9 +237,9 @@ you'd like to model, CouchRest Model supports creating anonymous classes:
     class Cat < CouchRest::Model::Base
       property :name, String
 
-      property :toys do |toy|
-        toy.property :name, String
-        toy.property :rating, Integer
+      property :toys do
+        property :name, String
+        property :rating, Integer
       end
     end
 
@@ -242,7 +247,136 @@ you'd like to model, CouchRest Model supports creating anonymous classes:
     @cat.toys.last.rating == 5
     @cat.toys.last.name == 'catnip ball'
 
-Anonymous classes will *only* create arrays of objects.
+Anonymous classes will *only* create arrays of objects. If you're more of the traditional type, a block parameter
+can be provided allowing you to use this variable before each method call inside the anonymous class. This is useful
+if you need to access variables outside of the block.
+
+## Views
+
+CouchDB views can be quite difficult to get grips with at first as they are quite different from what you'd expect with SQL queries in a normal Relational Database. Checkout some of the [CouchDB documentation on views](http://wiki.apache.org/couchdb/Introduction_to_CouchDB_views) to get to grips with the basics. The key is to remember that CouchDB will only generate indexes from which you can extract consecutive rows of data, filtering other than between two points in a data set is not possible.
+
+CouchRest Model has great support for views, and since version 1.1.0 we added support for a View objects that make accessing your data even easier. 
+
+### The Old Way
+
+Here's an example of adding a view to our Cat class:
+
+    class Cat < CouchRest::Model::Base
+      property :name, String
+      property :toys, [CatToy]
+
+      view_by :name
+    end
+
+The `view_by` method will create a view in the Cat's design document called "by_name". This will allow searches to be made for the Cat's name attribute. Calling `Cat.by_name` will send a query of to the database and return an array of all the Cat objects available. Internally, a map function is generated automatically and stored in CouchDB's design document for the current model, it'll look something like the following:
+
+    function(doc) {
+      if (doc['couchrest-type'] == 'Cat' && doc['name']) {
+        emit(doc.name, null);
+      }
+    }
+
+By default, a special view called `all` is created and added to all couchrest models that allows you access to all the documents in the database that match the model. By default, these will be ordered by each documents id field.
+
+It is also possible to create views of multiple keys, for example:
+
+    view_by :birthday, :name
+
+This will create an view of all the cats' birthdays and their names called `by_birthday_and_name`.
+
+Sometimes the automatically generate map function might not be sufficient for more complicated queries. To customize, add the :map and :reduce functions when creating the view:
+
+    view_by :tags,
+      :map =>
+        "function(doc) {
+          if (doc['model'] == 'Post' && doc.tags) {
+            doc.tags.forEach(function(tag){
+              emit(doc.tag, 1);
+            });
+          }
+        }",
+      :reduce =>
+        "function(keys, values, rereduce) {
+          return sum(values);
+        }"
+
+Calling a view will return document objects by default, to get access to the raw CouchDB result add the `:raw => true` option to get a hash instead. Custom views can also be queried with `:reduce => true` to return reduce results. The default is to query with `:reduce => false`.
+ 
+Views are generated (on a per-model basis) lazily on first-access. This means that if you are deploying changes to a view, the views for
+that model won't be available until generation is complete. This can take some time with large databases. Strategies are in the works.
+
+### View Objects
+
+Since CouchRest Model 1.1.0 it is now possible to create views that return objects chainable objects, similar to those you'd find in the Sequel Ruby library or Rails 3's Arel. Heres an example of creating a few views:
+
+    class Post < CouchRest::Model::Base
+      property :title
+      property :body
+      property :posted_at, DateTime
+      property :tags, [String]
+
+      design do
+        view :by_title
+        view :by_posted_at_and_title
+        view :tag_list,
+          :map =>
+            "function(doc) {
+              if (doc['model'] == 'Post' && doc.tags) {
+                doc.tags.forEach(function(tag){
+                  emit(doc.tag, 1);
+                });
+              }
+            }",
+          :reduce =>
+            "function(keys, values, rereduce) {
+              return sum(values);
+            }"
+      end
+
+You'll see that this new syntax requires all views to be defined inside a design block. Unlike the old version, the keys to be used in a query are determined from the name of the view, not the other way round. Acessing data is the fun part:
+
+    # Prepare a query:
+    view = Post.by_posted_at_and_title.skip(5).limit(10)
+
+    # Fetch the results:
+    view.each do |post|
+      puts "Title: #{post.title}"
+    end
+
+    # Grab the CouchDB result information with the same object:
+    view.total_rows   => 10
+    view.offset       => 5
+
+    # Re-use and add new filters
+    filter = view.startkey([1.month.ago]).endkey([Date.current, {}])
+
+    # Fetch row results without the documents:
+    filter.rows.each do |row|
+      puts "Row value: #{row.value} Doc ID: #{row.id}"
+    end
+
+    # Lazily load documents (take last row from previous example):
+    row.doc      => Fetch last Post document from database
+
+    # Using reduced queries is also easy:
+    tag_usage = Post.tag_list.reduce.group_level(1)
+    tag_usage.rows.each do |row|
+      puts "Tag: #{row.key}  Uses: #{row.value}"
+    end
+
+#### Pagination
+
+The view objects have built in support for pagination based on the [kaminari](https://github.com/amatsuda/kaminari) gem. Methods are provided to match those required by the library to peform pagination.
+
+For your view to support paginating the results, it must use a reduce function that provides a total count of the documents in the result set. By default, auto-generated views include a reduce function that supports this.
+
+Use pagination as follows:
+
+    # Prepare a query:
+    @posts = Post.by_title.page(params[:page]).per(10)
+    
+    # In your view, with the kaminari gem loaded:
+    paginate @posts
 
 
 ## Assocations
@@ -253,7 +387,7 @@ Two types at the moment:
 
     collection_of :tags
 
-This is a somewhat controvesial feature of CouchRest Model that some document database purists may fringe at. CouchDB does not yet povide many features to support relationships between documents but the fact of that matter is that its a very useful paradigm for modelling data systems.
+This is a somewhat controvesial feature of CouchRest Model that some document database purists may cringe at. CouchDB does not yet povide many features to support relationships between documents but the fact of that matter is that its a very useful paradigm for modelling data systems.
 
 In the near future we hope to add support for a `has_many` relationship that takes of the _Linked Documents_ feature that arrived in CouchDB 0.11.
 
@@ -394,15 +528,6 @@ Options currently avilable are:
 None at the moment...
 
 
-## Ruby on Rails
-
-CouchRest Model is compatible with rails and provides some ActiveRecord-like methods.
-
-The CouchRest companion rails project [http://github.com/hpoydar/couchrest-rails](http://github.com/hpoydar/couchrest-rails) is great for providing default connection details for your database. At the time of writting however it does not provide explicit support for CouchRest Model.
-
-CouchRest Model and the original CouchRest ExtendedDocument do not share the same namespace, as such you should not have any problems using them both at the same time. This might help with migrations.
-
-
 ## Testing
 
 The most complete documentation is the spec/ directory. To validate your CouchRest install, from the project root directory run `rake`, or `autotest` (requires RSpec and optionally ZenTest for autotest support).

data/VERSION

@@ -1 +1 @@
-1.0.0
+1.1.0.beta

data/couchrest_model.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{couchrest_model}
-  s.version = "1.0.0"
+  s.version = `cat VERSION`.strip
 
   s.required_rubygems_version = Gem::Requirement.new("> 1.3.1") if s.respond_to? :required_rubygems_version=
   s.authors = ["J. Chris Anderson", "Matt Aimonetti", "Marcos Tapajos", "Will Leinweber", "Sam Lown"]
@@ -23,12 +23,11 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
   
-  s.add_dependency(%q<couchrest>, "~> 1.0.1")
+  s.add_dependency(%q<couchrest>, "~> 1.0.2")
   s.add_dependency(%q<mime-types>, "~> 1.15")
   s.add_dependency(%q<activemodel>, "~> 3.0.0")
   s.add_dependency(%q<tzinfo>, "~> 0.3.22")
   s.add_dependency(%q<railties>, "~> 3.0.0")
-  s.add_dependency(%q<rspec>, ">= 2.0.0")
   s.add_development_dependency(%q<rspec>, ">= 2.0.0")
   s.add_development_dependency(%q<rack-test>, ">= 0.5.7")
 end

data/history.txt

@@ -1,3 +1,17 @@
+== 1.1.0.beta
+
+* Epic enhancements:
+  * Added "View" object for dynamic view queries
+  * Added easy to use proxy_for and proxied_by class methods for proxying data
+
+* Minor enhancements:
+  * A yield parameter in an anonymous casted model property block is no longer required (@samlown)
+  * Narrow the rescued exception to avoid catching class evaluation errors that has nothing to to with the association (thanks Simone Carletti)
+  * Fix validate uniqueness test that was never executed (thanks Simone Carletti)
+  * Adds a #reload method to reload document attributes (thanks Simone Carletti)
+  * Numeric types can be casted from strings with leading or trailing whitespace (thanks chrisdurtschi)
+  * CollectionProxy no longer provided by default with simple views (pending deprication)
+
 == CouchRest Model 1.0.0
 
 * Major enhancements

data/lib/couchrest/model/associations.rb

@@ -25,8 +25,8 @@ module CouchRest
 
           begin
             opts[:class] = opts[:class_name].constantize
-          rescue
-            raise "Unable to convert class name into Constant for #{self.name}##{attrib}"
+          rescue NameError
+            raise NameError, "Unable to convert class name into Constant for #{self.name}##{attrib}"
           end
 
           prop = property(opts[:foreign_key], opts)
@@ -109,7 +109,7 @@ module CouchRest
           base = options[:proxy] || options[:class_name]
           class_eval <<-EOS, __FILE__, __LINE__ + 1
             def #{attrib}
-              @#{attrib} ||= #{options[:foreign_key]}.nil? ? nil : #{base}.get(self.#{options[:foreign_key]})
+              @#{attrib} ||= #{options[:foreign_key]}.nil? ? nil : (model_proxy || #{base}).get(self.#{options[:foreign_key]})
             end
           EOS
         end
@@ -140,7 +140,7 @@ module CouchRest
           class_eval <<-EOS, __FILE__, __LINE__ + 1
             def #{attrib}(reload = false)
               return @#{attrib} unless @#{attrib}.nil? or reload
-              ary = self.#{options[:foreign_key]}.collect{|i| #{base}.get(i)}
+              ary = self.#{options[:foreign_key]}.collect{|i| (model_proxy || #{base}).get(i)}
               @#{attrib} = ::CouchRest::CollectionOfProxy.new(ary, self, '#{options[:foreign_key]}')
             end
           EOS

data/lib/couchrest/model/base.rb

@@ -12,10 +12,12 @@ module CouchRest
       include CouchRest::Model::DesignDoc
       include CouchRest::Model::ExtendedAttachments
       include CouchRest::Model::ClassProxy
+      include CouchRest::Model::Proxyable
       include CouchRest::Model::Collection
       include CouchRest::Model::PropertyProtection
       include CouchRest::Model::Associations
       include CouchRest::Model::Validations
+      include CouchRest::Model::Designs
 
       def self.subclasses
         @subclasses ||= []
@@ -45,9 +47,12 @@ module CouchRest
       # Options supported:
       # 
       # * :directly_set_attributes: true when data comes directly from database
+      # * :database: provide an alternative database
       #
       def initialize(doc = {}, options = {})
         doc = prepare_all_attributes(doc, options)
+        # set the instances database, if provided
+        self.database = options[:database] unless options[:database].nil?
         super(doc)
         unless self['_id'] && self['_rev']
           self[self.model_type_key] = self.class.to_s

data/lib/couchrest/model/callbacks.rb

@@ -12,8 +12,7 @@ module CouchRest #:nodoc:
           :create,
           :destroy,
           :save,
-          :update,
-          :validate
+          :update
 
       end
 

data/lib/couchrest/model/collection.rb

@@ -222,7 +222,7 @@ module CouchRest
           if @container_class.nil?
             results
           else
-            results['rows'].collect { |row| @container_class.create_from_database(row['doc']) } unless results['rows'].nil?
+            results['rows'].collect { |row| @container_class.build_from_database(row['doc']) } unless results['rows'].nil?
           end
         end