jchris-couchrest 0.9.12 → 0.12.2

data/{README.rdoc → README.md}

@@ -1,4 +1,4 @@
-== CouchRest - CouchDB, close to the metal
+# CouchRest: CouchDB, close to the metal
 
 CouchRest is based on [CouchDB's couch.js test
 library](http://svn.apache.org/repos/asf/incubator/couchdb/trunk/share/www/script/couch.js),
@@ -9,29 +9,29 @@ to CouchDB's API endpoints so you don't have to.
 CouchRest's lighweight is designed to make a simple base for application and
 framework-specific object oriented APIs.
 
-=== Easy Install
+## Easy Install
 
-  sudo gem install jchris-couchrest -s http://gems.github.com
+Easy Install is moving to RubyForge, heads up for the gem.
 
-=== Relax, it's RESTful
+### Relax, it's RESTful
 
 The core of Couchrest is Heroku’s excellent REST Client Ruby HTTP wrapper.
 REST Client takes all the nastyness of Net::HTTP and gives is a pretty face,
 while still giving you more control than Open-URI. I recommend it anytime
 you’re interfacing with a well-defined web service.
 
-=== Running the Specs
+### Running the Specs
 
 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
+## Examples
 
 Quick Start:
 
     # with !, it creates the database if it doesn't already exist
-    @db = CouchRest.database!("http://localhost:5984/couchrest-test")
+    @db = CouchRest.database!("http://127.0.0.1:5984/couchrest-test")
     response = @db.save({:key => 'value', 'another key' => 'another value'})
     doc = @db.get(response['id'])
     puts doc.inspect
@@ -58,10 +58,12 @@ Creating and Querying Views:
       })
     puts @db.view('first/test')['rows'].inspect 
 
-== CouchRest::Model
+## CouchRest::Model
 
 CouchRest::Model is a module designed along the lines of DataMapper::Resource.
 By subclassing, suddenly you get all sorts of powerful sugar, so that working
 with CouchDB in your Rails or Merb app is no harder than working with the
 standard SQL alternatives. See the CouchRest::Model documentation for an
 example article class that illustrates usage.
+
+CouchRest::Model will be removed from this package.

data/Rakefile

@@ -1,64 +1,85 @@
 require 'rake'
 require "rake/rdoctask"
-require 'spec/rake/spectask'
+require 'rake/gempackagetask'
+require File.join(File.expand_path(File.dirname(__FILE__)),'lib','couchrest')
 
 
+begin
+  require 'spec/rake/spectask'
+rescue LoadError
+  puts <<-EOS
+To use rspec for testing you must install rspec gem:
+    gem install rspec
+EOS
+  exit(0)
+end
+
 spec = Gem::Specification.new do |s|
   s.name = "couchrest"
-  s.version = "0.9.12"
-  s.date = "2008-10-14"
+  s.version = CouchRest::VERSION
+  s.date = "2008-11-22"
   s.summary = "Lean and RESTful interface to CouchDB."
-  s.email = "jchris@grabb.it"
+  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"]
-  s.files = %w( LICENSE README.rdoc Rakefile THANKS ) + Dir["{bin,examples,lib,spec,utils}/**/*"]
-  s.extra_rdoc_files = %w( README.rdoc LICENSE THANKS )
+  s.files = %w( LICENSE README.md Rakefile THANKS.md ) + 
+    Dir["{bin,examples,lib,spec,utils}/**/*"] - 
+    Dir["spec/tmp"]
+  s.extra_rdoc_files = %w( README.md LICENSE THANKS.md )
   s.require_path = "lib"
   s.bindir = 'bin'
-  s.executables << 'couchview'
   s.executables << 'couchdir'
-  s.executables << 'couchapp'
   s.add_dependency("json", ">= 1.1.2")
   s.add_dependency("rest-client", ">= 0.5")
+  s.add_dependency("mime-types", ">= 1.15")
   s.add_dependency("extlib", ">= 0.9.6")
 end
 
-desc "Update Github Gemspec"
-task :gemspec do
-  skip_fields = %w(new_platform original_platform)
-  integer_fields = %w(specification_version)
 
-  result = "Gem::Specification.new do |s|\n"
-  spec.instance_variables.each do |ivar|
-    value = spec.instance_variable_get(ivar)
-    name  = ivar.split("@").last
-    next if skip_fields.include?(name) || value.nil? || value == "" || (value.respond_to?(:empty?) && value.empty?)
-    if name == "dependencies"
-      value.each do |d|
-        dep, *ver = d.to_s.split(" ")
-        result <<  "  s.add_dependency #{dep.inspect}, [#{ /\(([^\,]*)/ . match(ver.join(" "))[1].inspect}]\n"
-      end
-    else        
-      case value
-      when Array
-        value =  name != "files" ? value.inspect : value.inspect.split(",").join(",\n")
-      when Fixnum
-        # leave as-is
-      when String
-        value = value.to_i if integer_fields.include?(name)
-        value = value.inspect
-      else
-        value = value.to_s.inspect
-      end
-      result << "  s.#{name} = #{value}\n"
-    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
   end
-  result << "end"
-  File.open(File.join(File.dirname(__FILE__), "#{spec.name}.gemspec"), "w"){|f| f << result}
 end
 
+# desc "Update Github Gemspec"
+# task :gemspec do
+#   skip_fields = %w(new_platform original_platform)
+#   integer_fields = %w(specification_version)
+# 
+#   result = "Gem::Specification.new do |s|\n"
+#   spec.instance_variables.each do |ivar|
+#     value = spec.instance_variable_get(ivar)
+#     name  = ivar.split("@").last
+#     next if skip_fields.include?(name) || value.nil? || value == "" || (value.respond_to?(:empty?) && value.empty?)
+#     if name == "dependencies"
+#       value.each do |d|
+#         dep, *ver = d.to_s.split(" ")
+#         result <<  "  s.add_dependency #{dep.inspect}, [#{ /\(([^\,]*)/ . match(ver.join(" "))[1].inspect}]\n"
+#       end
+#     else        
+#       case value
+#       when Array
+#         value =  name != "files" ? value.inspect : value.inspect.split(",").join(",\n")
+#       when Fixnum
+#         # leave as-is
+#       when String
+#         value = value.to_i if integer_fields.include?(name)
+#         value = value.inspect
+#       else
+#         value = value.to_s.inspect
+#       end
+#       result << "  s.#{name} = #{value}\n"
+#     end
+#   end
+#   result << "end"
+#   File.open(File.join(File.dirname(__FILE__), "#{spec.name}.gemspec"), "w"){|f| f << result}
+# end
+
 desc "Run all specs"
 Spec::Rake::SpecTask.new('spec') do |t|
 	t.spec_files = FileList['spec/**/*_spec.rb']
@@ -78,5 +99,5 @@ Rake::RDocTask.new do |rdoc|
   rdoc.title = "CouchRest: Ruby CouchDB, close to the metal"
 end
 
-desc "Generate the gemspec"
+desc "Run the rspec"
 task :default => :spec

data/THANKS.md

@@ -0,0 +1,18 @@
+CouchRest THANKS
+=====================
+
+CouchRest was originally developed by J. Chris Anderson <jchris@grabb.it>
+and a number of other contributors. Many people further contributed to 
+CouchRest by reporting problems, suggesting various improvements or submitting
+changes. A list of these people is included below.
+
+ * [Matt Aimonetti](http://merbist.com/about/)
+ * [Greg Borenstein](http://ideasfordozens.com)
+ * [Geoffrey Grosenbach](http://nubyonrails.com/)
+ * [Jonathan S. Katz](http://github.com/jkatz)
+ * [Matt Lyon](http://mattly.tumblr.com/)
+ * Simon Rozet (simon /at/ rozet /dot/ name)
+ 
+Patches are welcome. The primary source for this software project is [on Github](http://github.com/jchris/couchrest/tree/master)
+
+A lot of people have active forks - thank you all - even the patches I don't end up using are helpful.

data/examples/word_count/markov

@@ -2,7 +2,7 @@
 
 require File.expand_path(File.dirname(__FILE__)) + '/../../couchrest'
 
-cr = CouchRest.new("http://localhost:5984")
+cr = CouchRest.new("http://127.0.0.1:5984")
 @db = cr.database('word-count-example')
 @word_memoizer = {}
 

data/examples/word_count/views/word_count/count-reduce.js

@@ -1,3 +1,3 @@
-function(key,combine){
-  return sum(combine);
+function(key,values){
+  return sum(values);
 }

data/examples/word_count/word_count.rb

@@ -1,6 +1,6 @@
 require File.dirname(__FILE__) + '/../../couchrest'
 
-couch = CouchRest.new("http://localhost:5984")
+couch = CouchRest.new("http://127.0.0.1:5984")
 db = couch.database('word-count-example')
 db.delete! rescue nil
 db = couch.create_db('word-count-example')
@@ -62,6 +62,6 @@ end
 #   }
 # })
 
-# puts "The books have been stored in your CouchDB. To initiate the MapReduce process, visit http://localhost:5984/_utils/ in your browser and click 'word-count-example', then select view 'words' or 'count'. The process could take about 15 minutes on an average MacBook."
+# puts "The books have been stored in your CouchDB. To initiate the MapReduce process, visit http://127.0.0.1:5984/_utils/ in your browser and click 'word-count-example', then select view 'words' or 'count'. The process could take about 15 minutes on an average MacBook."
 # 
 

data/examples/word_count/word_count_query.rb

@@ -1,6 +1,6 @@
 require File.dirname(__FILE__) + '/../../couchrest'
 
-couch = CouchRest.new("http://localhost:5984")
+couch = CouchRest.new("http://127.0.0.1:5984")
 db = couch.database('word-count-example')
 
 puts "Now that we've parsed all those books into CouchDB, the queries we can run are incredibly flexible."
@@ -35,5 +35,5 @@ puts "\nHere are the params for 'flight' in the da-vinci book:"
 puts params.inspect
 puts
 puts 'The url looks like this:'
-puts 'http://localhost:5984/word-count-example/_view/word_count/count?key=["flight","da-vinci"]'
+puts 'http://127.0.0.1:5984/word-count-example/_view/word_count/count?key=["flight","da-vinci"]'
 puts "\nTry dropping that in your browser..."

data/lib/couchrest/commands/push.rb

@@ -10,7 +10,11 @@ module CouchRest
         
         fm      = CouchRest::FileManager.new(database)
         fm.loud = options[:loud]
-        puts "Pushing views from directory #{directory} to database #{fm.db}"
+
+        if options[:loud]
+          puts "Pushing views from directory #{directory} to database #{fm.db}"
+        end
+
         fm.push_views(directory)
       end
 
@@ -48,7 +52,7 @@ module CouchRest
         foo-project/bar-views/my-design/viewname-reduce.js
         foo-project/bar-views/my-design/noreduce-map.js
 
-        Pushed to => http://localhost:5984/baz-database/_design/my-design
+        Pushed to => http://127.0.0.1:5984/baz-database/_design/my-design
 
         And the design document:
         {
@@ -77,11 +81,11 @@ module CouchRest
         (for project global libs). These libraries are only inserted into views which
         include the text
 
-        //include-lib
+        // !include lib
 
         or
 
-        #include-lib
+        # !include lib
 
         Couchview is a result of scratching my own itch. I'd be happy to make it more
         general, so please contact me at jchris@grabb.it if you'd like to see anything

data/lib/couchrest/core/database.rb

@@ -4,6 +4,7 @@ require "base64"
 module CouchRest
   class Database
     attr_reader :server, :host, :name, :root
+    attr_accessor :bulk_save_cache_limit
      
     # Create a CouchRest::Database adapter for the supplied CouchRest::Server
     # and database name.
@@ -18,6 +19,8 @@ module CouchRest
       @host = server.uri
       @root = "#{host}/#{name}"
       @streamer = Streamer.new(self)
+      @bulk_save_cache = []
+      @bulk_save_cache_limit = 50
     end
     
     # returns the database's uri
@@ -44,12 +47,15 @@ module CouchRest
     # POST a temporary view function to CouchDB for querying. This is not
     # recommended, as you don't get any performance benefit from CouchDB's
     # materialized views. Can be quite slow on large databases.
-    def temp_view funcs, params = {}
+    def slow_view funcs, params = {}
       keys = params.delete(:keys)
       funcs = funcs.merge({:keys => keys}) if keys
-      url = CouchRest.paramify_url "#{@root}/_temp_view", params
+      url = CouchRest.paramify_url "#{@root}/_slow_view", params
       JSON.parse(RestClient.post(url, funcs.to_json, {"Content-Type" => 'application/json'}))
     end
+    
+    # backwards compatibility is a plus
+    alias :temp_view :slow_view
   
     # Query a CouchDB view as defined by a <tt>_design</tt> document. Accepts
     # paramaters as described in http://wiki.apache.org/couchdb/HttpViewApi
@@ -69,20 +75,27 @@ module CouchRest
     
     # GET a document from CouchDB, by id. Returns a Ruby Hash.
     def get id
-      slug = CGI.escape(id) 
-      CouchRest.get "#{@root}/#{slug}"
+      slug = escape_docid(id)
+      hash = CouchRest.get("#{@root}/#{slug}")
+      doc = if /^_design/ =~ hash["_id"]
+        Design.new(hash)
+      else
+        Document.new(hash)
+      end
+      doc.database = self
+      doc
     end
     
     # GET an attachment directly from CouchDB
-    def fetch_attachment doc, name
-      doc = CGI.escape(doc)
+    def fetch_attachment docid, name
+      slug = escape_docid(docid)        
       name = CGI.escape(name)
-      RestClient.get "#{@root}/#{doc}/#{name}"
+      RestClient.get "#{@root}/#{slug}/#{name}"
     end
     
     # PUT an attachment directly to CouchDB
     def put_attachment doc, name, file, options = {}
-      docid = CGI.escape(doc['_id'])
+      docid = escape_docid(doc['_id'])
       name = CGI.escape(name)
       uri = if doc['_rev']
         "#{@root}/#{docid}/#{name}?rev=#{doc['_rev']}"
@@ -99,12 +112,22 @@ module CouchRest
     # documents on the client side because POST has the curious property of
     # being automatically retried by proxies in the event of network
     # segmentation and lost responses.
-    def save doc
+    #
+    # 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, bulk = false)
       if doc['_attachments']
         doc['_attachments'] = encode_attachments(doc['_attachments'])
       end
-      if doc['_id']
-        slug = CGI.escape(doc['_id'])
+      if bulk
+        @bulk_save_cache << doc
+        return 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
+      end
+      result = if doc['_id']
+        slug = escape_docid(doc['_id'])        
         CouchRest.put "#{@root}/#{slug}", doc
       else
         begin
@@ -114,11 +137,23 @@ module CouchRest
           CouchRest.post @root, doc
         end
       end
+      if result['ok']
+        doc['_id'] = result['id']
+        doc['_rev'] = result['rev']
+        doc.database = self if doc.respond_to?(:database=)
+      end
+      result
     end
     
     # POST an array of documents to CouchDB. If any of the documents are
     # missing ids, supply one from the uuid cache.
-    def bulk_save docs
+    #
+    # If called with no arguments, bulk saves the cache of documents to be bulk saved.
+    def bulk_save (docs = nil)
+      if docs.nil?
+        docs = @bulk_save_cache
+        @bulk_save_cache = []
+      end
       ids, noids = docs.partition{|d|d['_id']}
       uuid_count = [noids.length, @server.uuid_batch_count].max
       noids.each do |doc|
@@ -130,11 +165,53 @@ module CouchRest
     
     # DELETE the document from CouchDB that has the given <tt>_id</tt> and
     # <tt>_rev</tt>.
-    def delete doc
-      slug = CGI.escape(doc['_id'])
+    #
+    # If <tt>bulk</tt> is true (false by default) the deletion is recorded for bulk-saving (bulk-deletion :) later.
+    # Bulk saving happens automatically when #bulk_save_cache limit is exceded, or on the next non bulk save.
+    def delete (doc, bulk = false)
+      raise ArgumentError, "_id and _rev required for deleting" unless doc['_id'] && doc['_rev']      
+      if bulk
+        @bulk_save_cache << { '_id' => doc['_id'], '_rev' => doc['_rev'], '_deleted' => true }
+        return bulk_save if @bulk_save_cache.length >= @bulk_save_cache_limit
+        return { "ok" => true } # Mimic the non-deferred version
+      end
+      slug = escape_docid(doc['_id'])        
       CouchRest.delete "#{@root}/#{slug}?rev=#{doc['_rev']}"
     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
+    def copy doc, dest
+      raise ArgumentError, "_id is required for copying" unless doc['_id']
+      slug = escape_docid(doc['_id'])        
+      destination = if dest.respond_to?(:has_key?) && dest['_id'] && dest['_rev']
+        "#{dest['_id']}?rev=#{dest['_rev']}"
+      else
+        dest
+      end
+      CouchRest.copy "#{@root}/#{slug}", destination
+    end
+    
+    # MOVE 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
+    def move doc, dest
+      raise ArgumentError, "_id and _rev are required for moving" unless doc['_id'] && doc['_rev']
+      slug = escape_docid(doc['_id'])        
+      destination = if dest.respond_to?(:has_key?) && dest['_id'] && dest['_rev']
+        "#{dest['_id']}?rev=#{dest['_rev']}"
+      else
+        dest
+      end
+      CouchRest.move "#{@root}/#{slug}?rev=#{doc['_rev']}", destination
+    end
+    
+    # Compact the database, removing old document revisions and optimizing space use.
+    def compact!
+      CouchRest.post "#{@root}/_compact"
+    end
+
     # DELETE the database itself. This is not undoable and could be rather
     # catastrophic. Use with care!
     def delete!
@@ -143,6 +220,10 @@ module CouchRest
 
     private
 
+    def escape_docid id      
+      /^_design\/(.*)/ =~ id ? "_design/#{CGI.escape($1)}" : CGI.escape(id) 
+    end
+
     def encode_attachments attachments
       attachments.each do |k,v|
         next if v['stub']

data/lib/couchrest/core/design.rb

@@ -0,0 +1,89 @@
+module CouchRest  
+  class Design < Document
+    def view_by *keys
+      opts = keys.pop if keys.last.is_a?(Hash)
+      opts ||= {}
+      self['views'] ||= {}
+      method_name = "by_#{keys.join('_and_')}"
+      
+      if opts[:map]
+        view = {}
+        view['map'] = opts.delete(:map)
+        if opts[:reduce]
+          view['reduce'] = opts.delete(:reduce)
+          opts[:reduce] = false
+        end
+        self['views'][method_name] = view
+      else
+        doc_keys = keys.collect{|k|"doc['#{k}']"} # this is where :require => 'doc.x == true' would show up
+        key_emit = doc_keys.length == 1 ? "#{doc_keys.first}" : "[#{doc_keys.join(', ')}]"
+        guards = opts.delete(:guards) || []
+        guards.concat doc_keys
+        map_function = <<-JAVASCRIPT
+function(doc) {
+  if (#{guards.join(' && ')}) {
+    emit(#{key_emit}, null);
+  }
+}
+JAVASCRIPT
+        self['views'][method_name] = {
+          'map' => map_function
+        }
+      end
+      self['views'][method_name]['couchrest-defaults'] = opts unless opts.empty?
+      method_name
+    end
+    
+    # Dispatches to any named view.
+    def view view_name, query={}, &block
+      view_name = view_name.to_s
+      view_slug = "#{name}/#{view_name}"
+      defaults = (self['views'][view_name] && self['views'][view_name]["couchrest-defaults"]) || {}
+      fetch_view(view_slug, defaults.merge(query), &block)
+    end
+
+    def name
+      id.sub('_design/','') if id
+    end
+
+    def name= newname
+      self['_id'] = "_design/#{newname}"
+    end
+
+    def save
+      raise ArgumentError, "_design docs require a name" unless name && name.length > 0
+      super
+    end
+
+    private
+
+    # returns stored defaults if the there is a view named this in the design doc
+    def has_view?(view)
+      view = view.to_s
+      self['views'][view] &&
+        (self['views'][view]["couchrest-defaults"]||{})
+    end
+
+    # def fetch_view_with_docs name, opts, raw=false, &block
+    #   if raw
+    #     fetch_view name, opts, &block
+    #   else
+    #     begin
+    #       view = fetch_view name, opts.merge({:include_docs => true}), &block
+    #       view['rows'].collect{|r|new(r['doc'])} if view['rows']
+    #     rescue
+    #       # fallback for old versions of couchdb that don't 
+    #       # have include_docs support
+    #       view = fetch_view name, opts, &block
+    #       view['rows'].collect{|r|new(database.get(r['id']))} if view['rows']
+    #     end
+    #   end
+    # end
+
+    def fetch_view view_name, opts, &block
+      database.view(view_name, opts, &block)
+    end
+
+  end
+  
+end

data/lib/couchrest/core/document.rb

@@ -0,0 +1,63 @@
+module CouchRest
+  class Response < Hash
+    def initialize keys = {}
+      keys.each do |k,v|
+        self[k.to_s] = v
+      end
+    end
+    def []= key, value
+      super(key.to_s, value)
+    end
+    def [] key
+      super(key.to_s)
+    end
+  end
+  
+  class Document < Response
+
+    attr_accessor :database
+
+    # alias for self['_id']
+    def id
+      self['_id']
+    end
+
+    # alias for self['_rev']      
+    def rev
+      self['_rev']
+    end
+
+    # returns true if the document has never been saved
+    def new_document?
+      !rev
+    end
+
+    # 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
+    # CouchDB's response.
+    # If <tt>bulk</tt> is <tt>true</tt> (defaults to false) the document is cached for bulk save.
+    def save(bulk = false)
+      raise ArgumentError, "doc.database required for saving" unless database
+      result = database.save self, bulk
+      result['ok']
+    end
+
+    # Deletes the document from the database. Runs the :delete callbacks.
+    # Removes the <tt>_id</tt> and <tt>_rev</tt> fields, preparing the
+    # document to be saved to a new <tt>_id</tt>.
+    # If <tt>bulk</tt> is <tt>true</tt> (defaults to false) the document won't 
+    # actually be deleted from the db until bulk save.
+    def destroy(bulk = false)
+      raise ArgumentError, "doc.database required to destroy" unless database
+      result = database.delete(self, bulk)
+      if result['ok']
+        self['_rev'] = nil
+        self['_id'] = nil
+      end
+      result['ok']
+    end
+
+  end
+
+  
+end