couchrest 0.33 → 0.34

data/README.md

@@ -14,11 +14,6 @@ Note: CouchRest only support CouchDB 0.9.0 or newer.
 
     $ sudo gem install couchrest
    
-Alternatively, you can install from Github:
-    
-    $ gem sources -a http://gems.github.com (you only have to do this once)
-    $ sudo gem install couchrest-couchrest
-
 ### Relax, it's RESTful
 
 CouchRest rests on top of a HTTP abstraction layer using by default Heroku’s excellent REST Client Ruby HTTP wrapper.
@@ -30,136 +25,22 @@ 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).
 
-## Examples (CouchRest Core)
-
-Quick Start:
-
-    # with !, it creates the database if it doesn't already exist
-    @db = CouchRest.database!("http://127.0.0.1:5984/couchrest-test")
-    response = @db.save_doc({:key => 'value', 'another key' => 'another value'})
-    doc = @db.get(response['id'])
-    puts doc.inspect
-
-Bulk Save:
-
-    @db.bulk_save([
-        {"wild" => "and random"},
-        {"mild" => "yet local"},
-        {"another" => ["set","of","keys"]}
-      ])
-    # returns ids and revs of the current docs
-    puts @db.documents.inspect 
-
-Creating and Querying Views:
-
-    @db.save_doc({
-      "_id" => "_design/first", 
-      :views => {
-        :test => {
-          :map => "function(doc){for(var w in doc){ if(!w.match(/^_/))emit(w,doc[w])}}"
-          }
-        }
-      })
-    puts @db.view('first/test')['rows'].inspect 
-
-
-## CouchRest::ExtendedDocument  
-
-CouchRest::ExtendedDocument is a DSL/ORM for CouchDB. Basically, ExtendedDocument seats on top of CouchRest Core to add the concept of Model.
-ExtendedDocument offers a lot of the usual ORM tools such as optional yet defined schema, validation, callbacks, pagination, casting and much more.
-
-### Model example
-
-Check spec/couchrest/more and spec/fixtures/more for more examples
-
-    class Article < CouchRest::ExtendedDocument
-      use_database DB
-      unique_id :slug
-
-      view_by :date, :descending => true
-      view_by :user_id, :date
-
-      view_by :tags,
-        :map => 
-          "function(doc) {
-            if (doc['couchrest-type'] == 'Article' && doc.tags) {
-              doc.tags.forEach(function(tag){
-                emit(tag, 1);
-              });
-            }
-          }",
-        :reduce => 
-          "function(keys, values, rereduce) {
-            return sum(values);
-          }"  
+## Docs
 
-      property :date
-      property :slug, :read_only => true
-      property :title
-      property :tags, :cast_as => ['String']
+API: [http://rdoc.info/projects/couchrest/couchrest](http://rdoc.info/projects/couchrest/couchrest)
 
-      timestamps!
+Check the wiki for documentation and examples [http://wiki.github.com/couchrest/couchrest](http://wiki.github.com/couchrest/couchrest)
 
-      save_callback :before, :generate_slug_from_title
+## Contact
 
-      def generate_slug_from_title
-        self['slug'] = title.downcase.gsub(/[^a-z0-9]/,'-').squeeze('-').gsub(/^\-|\-$/,'') if new_document?
-      end
-    end
+Please post bugs, suggestions and patches to the bug tracker at <http://jchris.lighthouseapp.com/projects/17807-couchrest/overview>.
 
-### Callbacks
+Follow us on Twitter: http://twitter.com/couchrest
 
-`CouchRest::ExtendedDocuments` instances have 2 callbacks already defined for you:
-    `create_callback`, `save_callback`, `update_callback` and `destroy_callback`
-    
-In your document inherits from `CouchRest::ExtendedDocument`, define your callback as follows:
-
-    save_callback :before, :generate_slug_from_name
-    
-CouchRest uses a mixin you can find in lib/mixins/callbacks which is extracted from Rails 3, here are some simple usage examples:
-
-    save_callback :before, :before_method
-    save_callback :after,  :after_method, :if => :condition
-    save_callback :around {|r| stuff; yield; stuff }
-    
-Check the mixin or the ExtendedDocument class to see how to implement your own callbacks.
-
-### Casting
-
-Often, you will want to store multiple objects within a document, to be able to retrieve your objects when you load the document, 
-you can define some casting rules. 
-
-    property :casted_attribute, :cast_as => 'WithCastedModelMixin'
-    property :keywords,         :cast_as => ["String"]
-
-If you want to cast an array of instances from a specific Class, use the trick shown above ["ClassName"]
-
-### Pagination
-
-Pagination is available in any ExtendedDocument classes. Here are some usage examples:
-
-basic usage:
-
-    Article.all.paginate(:page => 1, :per_page => 5)
-    
-note: the above query will look like: `GET /db/_design/Article/_view/all?include_docs=true&skip=0&limit=5&reduce=false` and only fetch 5 documents. 
-    
-Slightly more advance usage:
-  
-    Article.by_name(:startkey => 'a', :endkey => {}).paginate(:page => 1, :per_page => 5)
-    
-note: the above query will look like: `GET /db/_design/Article/_view/by_name?startkey=%22a%22&limit=5&skip=0&endkey=%7B%7D&include_docs=true`    
-Basically, you can paginate through the articles starting by the letter a, 5 articles at a time.
-
-
-Low level usage:        
-
-    Article.paginate(:design_doc => 'Article', :view_name => 'by_date',
-      :per_page => 3, :page => 2, :descending => true, :key => Date.today, :include_docs => true)
-      
+Also, check http://twitter.com/#search?q=%23couchrest
       
 ## Ruby on Rails
 
 CouchRest is compatible with rails and can even be used a Rails plugin.
 However, you might be interested in the CouchRest companion rails project:
-[http://github.com/hpoydar/couchrest-rails](http://github.com/hpoydar/couchrest-rails)      
+[http://github.com/hpoydar/couchrest-rails](http://github.com/hpoydar/couchrest-rails)      

data/Rakefile

@@ -1,9 +1,7 @@
 require 'rake'
 require "rake/rdoctask"
-require 'rake/gempackagetask'
 require File.join(File.expand_path(File.dirname(__FILE__)),'lib','couchrest')
 
-
 begin
   require 'spec/rake/spectask'
 rescue LoadError
@@ -14,45 +12,31 @@ EOS
   exit(0)
 end
 
-spec = Gem::Specification.new do |s|
-  s.name = "couchrest"
-  s.version = CouchRest::VERSION
-  s.date = "2008-11-22"
-  s.summary = "Lean and RESTful interface to CouchDB."
-  s.email = "jchris@apache.org"
-  s.homepage = "http://github.com/jchris/couchrest"
-  s.description = "CouchRest provides a simple interface on top of CouchDB's RESTful HTTP API, as well as including some utility scripts for managing views and attachments."
-  s.has_rdoc = true
-  s.authors = ["J. Chris Anderson", "Matt Aimonetti"]
-  s.files = %w( LICENSE README.md Rakefile THANKS.md history.txt) + 
-    Dir["{examples,lib,spec,utils}/**/*"] - 
-    Dir["spec/tmp"]
-  s.extra_rdoc_files = %w( README.md LICENSE THANKS.md )
-  s.require_path = "lib"
-  s.add_dependency("rest-client", ">= 0.5")
-  s.add_dependency("mime-types", ">= 1.15")
-end
-
-
-desc "Create .gemspec file (useful for github)"
-task :gemspec do
-  filename = "#{spec.name}.gemspec"
-  File.open(filename, "w") do |f|
-    f.puts spec.to_ruby
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "couchrest"
+    gemspec.summary = "Lean and RESTful interface to CouchDB."
+    gemspec.description = "CouchRest provides a simple interface on top of CouchDB's RESTful HTTP API, as well as including some utility scripts for managing views and attachments."
+    gemspec.email = "jchris@apache.org"
+    gemspec.homepage = "http://github.com/couchrest/couchrest"
+    gemspec.authors = ["J. Chris Anderson", "Matt Aimonetti", "Marcos Tapajos"]
+    gemspec.extra_rdoc_files = %w( README.md LICENSE THANKS.md )
+    gemspec.files = %w( LICENSE README.md Rakefile THANKS.md history.txt) + Dir["{examples,lib,spec,utils}/**/*"] - Dir["spec/tmp"]
+    gemspec.has_rdoc = true
+    gemspec.add_dependency("rest-client", ">= 0.5")
+    gemspec.add_dependency("mime-types", ">= 1.15")
+    gemspec.version = CouchRest::VERSION
+    gemspec.date = "2008-11-22"
+    gemspec.require_path = "lib"
   end
-end
-
-Rake::GemPackageTask.new(spec) do |pkg|
-  pkg.gem_spec = spec
-end
-
-desc "Install the gem locally"
-task :install => [:package] do
-  sh %{sudo gem install pkg/couchrest-#{CouchRest::VERSION}}
+rescue LoadError
+  puts "Jeweler not available. Install it with: gem install jeweler"
 end
 
 desc "Run all specs"
 Spec::Rake::SpecTask.new('spec') do |t|
+	t.spec_opts = ["--color"]
 	t.spec_files = FileList['spec/**/*_spec.rb']
 end
 

data/THANKS.md

@@ -12,7 +12,8 @@ changes. A list of these people is included below.
  * [Jonathan S. Katz](http://github.com/jkatz)
  * [Matt Lyon](http://mattly.tumblr.com/)
  * Simon Rozet (simon /at/ rozet /dot/ name)
+ * [Marcos Tapajós](http://tapajos.me)
  
-Patches are welcome. The primary source for this software project is [on Github](http://github.com/jchris/couchrest/tree/master)
+Patches are welcome. The primary source for this software project is [on Github](http://github.com/couchrest/couchrest)
 
 A lot of people have active forks - thank you all - even the patches I don't end up using are helpful.

data/history.txt

@@ -1,3 +1,28 @@
+== 0.34
+
+* Major enhancements
+
+  * Added support for https database URIs. (Mathias Meyer)
+  * Changing some validations to be compatible with activemodel. (Marcos Tapajós)
+  * Adds attribute protection to properties. (Will Leinweber)
+  * Improved CouchRest::Database#save_doc, added "batch" mode to significantly speed up saves at cost of lower durability gurantees. (Igal Koshevoy)
+  * Added CouchRest::Database#bulk_save_doc and #batch_save_doc as human-friendlier wrappers around #save_doc. (Igal Koshevoy)
+  
+* Minor enhancements 
+  
+  * Fix content_type handling for attachments
+  * Fixed a bug in the pagination code that caused it to paginate over records outside of the scope of the view parameters.(John Wood)
+  * Removed amount_pages calculation for the pagination collection, since it cannot be reliably calculated without a view.(John Wood)
+  * Bug fix: http://github.com/couchrest/couchrest/issues/#issue/2 (Luke Burton)
+  * Bug fix: http://github.com/couchrest/couchrest/issues/#issue/1 (Marcos Tapajós)
+  * Removed the Database class deprecation notices (Matt Aimonetti)
+  * Adding support to :cast_as => 'Date'.  (Marcos Tapajós)
+  * Improve documentation  (Marcos Tapajós)
+  * Streamer fixes (Julien Sanchez)
+  * Fix Save on Document & ExtendedDocument crashed if bulk (Julien Sanchez)
+  * Fix Initialization of ExtendentDocument model shouldn't failed on a nil value in argument (deepj)
+  * Change to use Jeweler and Gemcutter (Marcos Tapajós)
+
 == 0.33
 
 * Major enhancements

data/lib/couchrest.rb

@@ -28,7 +28,7 @@ require 'couchrest/monkeypatches'
 
 # = CouchDB, close to the metal
 module CouchRest
-  VERSION    = '0.33' unless self.const_defined?("VERSION")
+  VERSION    = '0.34' unless self.const_defined?("VERSION")
   
   autoload :Server,       'couchrest/core/server'
   autoload :Database,     'couchrest/core/database'
@@ -48,6 +48,7 @@ module CouchRest
   require File.join(File.dirname(__FILE__), 'couchrest', 'core', 'rest_api')
   require File.join(File.dirname(__FILE__), 'couchrest', 'core', 'http_abstraction')
   require File.join(File.dirname(__FILE__), 'couchrest', 'mixins')
+  require File.join(File.dirname(__FILE__), 'couchrest', 'support', 'rails') if defined?(Rails)
 
   # we extend CouchRest with the RestAPI module which gives us acess to
   # the get, post, put, delete and copy
@@ -95,14 +96,14 @@ module CouchRest
     
     def parse url
       case url
-      when /^http:\/\/(.*)\/(.*)\/(.*)/
+      when /^https?:\/\/(.*)\/(.*)\/(.*)/
         host = $1
         db = $2
         docid = $3
-      when /^http:\/\/(.*)\/(.*)/
+      when /^https?:\/\/(.*)\/(.*)/
         host = $1
         db = $2
-      when /^http:\/\/(.*)/
+      when /^https?:\/\/(.*)/
         host = $1
       when /(.*)\/(.*)\/(.*)/
         host = $1

data/lib/couchrest/core/database.rb

@@ -129,7 +129,7 @@ module CouchRest
         end
       end
     end
-    
+
     # Save a document to CouchDB. This will use the <tt>_id</tt> field from
     # the document as the id for PUT, or request a new UUID from CouchDB, if
     # no <tt>_id</tt> is present on the document. IDs are attached to
@@ -139,13 +139,25 @@ module CouchRest
     #
     # If <tt>bulk</tt> is true (false by default) the document is cached for bulk-saving later.
     # Bulk saving happens automatically when #bulk_save_cache limit is exceded, or on the next non bulk save.
-    def save_doc(doc, bulk = false)
+    #
+    # If <tt>batch</tt> is true (false by default) the document is saved in
+    # batch mode, "used to achieve higher throughput at the cost of lower
+    # guarantees. When [...] sent using this option, it is not immediately
+    # written to disk. Instead it is stored in memory on a per-user basis for a
+    # second or so (or the number of docs in memory reaches a certain point).
+    # After the threshold has passed, the docs are committed to disk. Instead
+    # of waiting for the doc to be written to disk before responding, CouchDB
+    # sends an HTTP 202 Accepted response immediately. batch=ok is not suitable
+    # for crucial data, but it ideal for applications like logging which can
+    # accept the risk that a small proportion of updates could be lost due to a
+    # crash."
+    def save_doc(doc, bulk = false, batch = false)
       if doc['_attachments']
         doc['_attachments'] = encode_attachments(doc['_attachments'])
       end
       if bulk
         @bulk_save_cache << doc
-        return bulk_save if @bulk_save_cache.length >= @bulk_save_cache_limit
+        bulk_save if @bulk_save_cache.length >= @bulk_save_cache_limit
         return {"ok" => true} # Compatibility with Document#save
       elsif !bulk && @bulk_save_cache.length > 0
         bulk_save
@@ -153,7 +165,9 @@ module CouchRest
       result = if doc['_id']
         slug = escape_docid(doc['_id'])
         begin     
-          CouchRest.put "#{@root}/#{slug}", doc
+          uri = "#{@root}/#{slug}"
+          uri << "?batch=ok" if batch
+          CouchRest.put uri, doc
         rescue HttpAbstraction::ResourceNotFound
           p "resource not found when saving even tho an id was passed"
           slug = doc['_id'] = @server.next_uuid
@@ -175,12 +189,15 @@ module CouchRest
       result
     end
     
-    ### DEPRECATION NOTICE
-    def save(doc, bulk=false)
-      puts "CouchRest::Database's save method is being deprecated, please use save_doc instead"
-      save_doc(doc, bulk)
+    # Save a document to CouchDB in bulk mode. See #save_doc's +bulk+ argument.
+    def bulk_save_doc(doc)
+      save_doc(doc, true)
+    end
+
+    # Save a document to CouchDB in batch mode. See #save_doc's +batch+ argument.
+    def batch_save_doc(doc)
+      save_doc(doc, false, true)
     end
-    
     
     # POST an array of documents to CouchDB. If any of the documents are
     # missing ids, supply one from the uuid cache.
@@ -219,12 +236,6 @@ module CouchRest
       CouchRest.delete "#{@root}/#{slug}?rev=#{doc['_rev']}"
     end
     
-    ### DEPRECATION NOTICE
-    def delete(doc, bulk=false)
-      puts "CouchRest::Database's delete method is being deprecated, please use delete_doc instead"
-      delete_doc(doc, bulk)
-    end
-    
     # COPY an existing document to a new id. If the destination id currently exists, a rev must be provided.
     # <tt>dest</tt> can take one of two forms if overwriting: "id_to_overwrite?rev=revision" or the actual doc
     # hash with a '_rev' key
@@ -239,12 +250,6 @@ module CouchRest
       CouchRest.copy "#{@root}/#{slug}", destination
     end
     
-    ### DEPRECATION NOTICE
-    def copy(doc, dest)
-      puts "CouchRest::Database's copy method is being deprecated, please use copy_doc instead"
-      copy_doc(doc, dest)
-    end
-    
     # Compact the database, removing old document revisions and optimizing space use.
     def compact!
       CouchRest.post "#{@root}/_compact"

data/lib/couchrest/core/document.rb

@@ -23,9 +23,10 @@ module CouchRest
     end
     
     # returns true if the document has never been saved
-    def new_document?
+    def new?
       !rev
     end
+    alias :new_document? :new?
     
     # Saves the document to the db using create or update. Also runs the :save
     # callbacks. Sets the <tt>_id</tt> and <tt>_rev</tt> fields based on
@@ -63,8 +64,8 @@ module CouchRest
     
     # Returns the CouchDB uri for the document
     def uri(append_rev = false)
-      return nil if new_document?
-      couch_uri = "http://#{database.root}/#{CGI.escape(id)}"
+      return nil if new?
+      couch_uri = "#{database.root}/#{CGI.escape(id)}"
       if append_rev == true
         couch_uri << "?rev=#{rev}"
       elsif append_rev.kind_of?(Integer)

data/lib/couchrest/helper/streamer.rb

@@ -7,15 +7,22 @@ module CouchRest
     
     # Stream a view, yielding one row at a time. Shells out to <tt>curl</tt> to keep RAM usage low when you have millions of rows.
     def view name, params = nil, &block
-      urlst = /^_/.match(name) ? "#{@db.root}/#{name}" : "#{@db.root}/_view/#{name}"
+      urlst = if /^_/.match(name) then
+        "#{@db.root}/#{name}"
+      else
+        name = name.split('/')
+        dname = name.shift
+        vname = name.join('/')
+        "#{@db.root}/_design/#{dname}/_view/#{vname}"
+      end
       url = CouchRest.paramify_url urlst, params
       # puts "stream #{url}"
       first = nil
-      IO.popen("curl --silent #{url}") do |view|
+      IO.popen("curl --silent \"#{url}\"") do |view|
         first = view.gets # discard header
         while line = view.gets 
           row = parse_line(line)
-          block.call row
+          block.call row unless row.nil? # last line "}]" discarded
         end
       end
       parse_first(first)
@@ -41,4 +48,4 @@ module CouchRest
     end
     
   end
-end
+end