couchrest 0.12.4 → 0.23

data/README.md

@@ -31,7 +31,7 @@ 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({:key => 'value', 'another key' => 'another value'})
+    response = @db.save_doc({:key => 'value', 'another key' => 'another value'})
     doc = @db.get(response['id'])
     puts doc.inspect
 
@@ -47,7 +47,7 @@ Bulk Save:
 
 Creating and Querying Views:
 
-    @db.save({
+    @db.save_doc({
       "_id" => "_design/first", 
       :views => {
         :test => {
@@ -59,10 +59,35 @@ Creating and Querying Views:
 
 ## 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 has been deprecated and replaced by CouchRest::ExtendedDocument
+
+
+## CouchRest::ExtendedDocument
+
+### Callbacks
+
+`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"]
 
-CouchRest::Model will be removed from this package.

data/Rakefile

@@ -23,7 +23,7 @@ spec = Gem::Specification.new do |s|
   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.authors = ["J. Chris Anderson", "Matt Aimonetti"]
   s.files = %w( LICENSE README.md Rakefile THANKS.md ) + 
     Dir["{examples,lib,spec,utils}/**/*"] - 
     Dir["spec/tmp"]
@@ -35,7 +35,7 @@ spec = Gem::Specification.new do |s|
 end
 
 
-desc "create .gemspec file (useful for github)"
+desc "Create .gemspec file (useful for github)"
 task :gemspec do
   filename = "#{spec.name}.gemspec"
   File.open(filename, "w") do |f|
@@ -43,6 +43,15 @@ task :gemspec do
   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}}
+end
+
 desc "Run all specs"
 Spec::Rake::SpecTask.new('spec') do |t|
 	t.spec_files = FileList['spec/**/*_spec.rb']

data/examples/model/example.rb

@@ -1,31 +1,38 @@
-require 'rubygems'
-require 'couchrest'
+require File.join(File.dirname(__FILE__), '..', '..', 'lib', 'couchrest')
 
 def show obj
   puts obj.inspect
   puts
 end
 
-CouchRest::Model.default_database = CouchRest.database!('couchrest-model-example')
+SERVER = CouchRest.new
+SERVER.default_database = 'couchrest-extendeddoc-example'
 
-class Author < CouchRest::Model
-  key_accessor :name
+class Author < CouchRest::ExtendedDocument
+  use_database SERVER.default_database
+  property :name
+  
   def drink_scotch
     puts "... glug type glug ... I'm #{name} ... type glug glug ..."
   end
 end
 
-class Post < CouchRest::Model
-  key_accessor :title, :body, :author
-
-  cast :author, :as => 'Author'
+class Post < CouchRest::ExtendedDocument
+  use_database SERVER.default_database
+  
+  property :title
+  property :body
+  property :author, :cast_as => 'Author'
 
   timestamps!
 end
 
-class Comment < CouchRest::Model
-  cast :commenter, :as => 'Author'
-
+class Comment < CouchRest::ExtendedDocument
+  use_database SERVER.default_database
+  
+  property :commenter, :cast_as => 'Author'
+  timestamps!
+  
   def post= post
     self["post_id"] = post.id
   end
@@ -33,7 +40,6 @@ class Comment < CouchRest::Model
     Post.get(self['post_id']) if self['post_id']
   end
   
-  timestamps!
 end
 
 puts "Act I: CRUD"

data/lib/couchrest.rb

@@ -13,35 +13,74 @@
 #    limitations under the License.
 
 require "rubygems"
+gem 'json'
 require 'json'
+gem 'rest-client'
 require 'rest_client'
 
 $:.unshift File.dirname(__FILE__) unless
   $:.include?(File.dirname(__FILE__)) ||
   $:.include?(File.expand_path(File.dirname(__FILE__)))
   
+$COUCHREST_DEBUG ||= false
   
 require 'couchrest/monkeypatches'
 
 # = CouchDB, close to the metal
 module CouchRest
-  VERSION = '0.12.4'
+  VERSION    = '0.23' unless self.const_defined?("VERSION")
   
   autoload :Server,       'couchrest/core/server'
   autoload :Database,     'couchrest/core/database'
+  autoload :Response,     'couchrest/core/response'
   autoload :Document,     'couchrest/core/document'
-  autoload :Design,     'couchrest/core/design'
+  autoload :Design,       'couchrest/core/design'
   autoload :View,         'couchrest/core/view'
   autoload :Model,        'couchrest/core/model'
   autoload :Pager,        'couchrest/helper/pager'
   autoload :FileManager,  'couchrest/helper/file_manager'
   autoload :Streamer,     'couchrest/helper/streamer'
+  autoload :Upgrade,      'couchrest/helper/upgrade'
+  
+  autoload :ExtendedDocument,     'couchrest/more/extended_document'
+  autoload :CastedModel,          'couchrest/more/casted_model'
+  
+  require File.join(File.dirname(__FILE__), 'couchrest', 'mixins')
   
   # The CouchRest module methods handle the basic JSON serialization 
   # and deserialization, as well as query parameters. The module also includes
   # some helpers for tasks like instantiating a new Database or Server instance.
   class << self
 
+    # extracted from Extlib
+    #
+    # Constantize tries to find a declared constant with the name specified
+    # in the string. It raises a NameError when the name is not in CamelCase
+    # or is not initialized.
+    #
+    # @example
+    # "Module".constantize #=> Module
+    # "Class".constantize #=> Class
+    def constantize(camel_cased_word)
+      unless /\A(?:::)?([A-Z]\w*(?:::[A-Z]\w*)*)\z/ =~ camel_cased_word
+        raise NameError, "#{camel_cased_word.inspect} is not a valid constant name!"
+      end
+
+      Object.module_eval("::#{$1}", __FILE__, __LINE__)
+    end
+    
+    # extracted from Extlib
+    #    
+    # Capitalizes the first word and turns underscores into spaces and strips _id.
+    # Like titleize, this is meant for creating pretty output.
+    #
+    # @example
+    #   "employee_salary" #=> "Employee salary"
+    #   "author_id" #=> "Author"
+    def humanize(lower_case_and_underscored_word)
+      lower_case_and_underscored_word.to_s.gsub(/_id$/, "").gsub(/_/, " ").capitalize
+    end
+    
     # todo, make this parse the url and instantiate a Server or Database instance
     # depending on the specificity.
     def new(*opts)
@@ -99,18 +138,42 @@ module CouchRest
       cr.database(parsed[:database])
     end
     
-    def put uri, doc = nil
+    def put(uri, doc = nil)
       payload = doc.to_json if doc
-      JSON.parse(RestClient.put(uri, payload))
+      begin
+        JSON.parse(RestClient.put(uri, payload))
+      rescue Exception => e
+        if $COUCHREST_DEBUG == true
+          raise "Error while sending a PUT request #{uri}\npayload: #{payload.inspect}\n#{e}"
+        else
+          raise e
+        end
+      end
     end
 
-    def get uri
-      JSON.parse(RestClient.get(uri), :max_nesting => false)
+    def get(uri)
+      begin
+        JSON.parse(RestClient.get(uri), :max_nesting => false)
+      rescue => e
+        if $COUCHREST_DEBUG == true
+          raise "Error while sending a GET request #{uri}\n: #{e}"
+        else
+          raise e
+        end
+      end
     end
   
     def post uri, doc = nil
       payload = doc.to_json if doc
-      JSON.parse(RestClient.post(uri, payload))
+      begin
+        JSON.parse(RestClient.post(uri, payload))
+      rescue Exception => e
+        if $COUCHREST_DEBUG == true
+          raise "Error while sending a POST request #{uri}\npayload: #{payload.inspect}\n#{e}"
+        else
+          raise e
+        end
+      end
     end
   
     def delete uri
@@ -120,10 +183,6 @@ module CouchRest
     def copy uri, destination
       JSON.parse(RestClient.copy(uri, {'Destination' => destination}))
     end
-    
-    def move uri, destination
-      JSON.parse(RestClient.move(uri, {'Destination' => destination}))
-    end
   
     def paramify_url url, params = {}
       if params && !params.empty?

data/lib/couchrest/core/database.rb

@@ -3,7 +3,7 @@ require "base64"
 
 module CouchRest
   class Database
-    attr_reader :server, :host, :name, :root
+    attr_reader :server, :host, :name, :root, :uri
     attr_accessor :bulk_save_cache_limit
      
     # Create a CouchRest::Database adapter for the supplied CouchRest::Server
@@ -13,30 +13,30 @@ module CouchRest
     # server<CouchRest::Server>:: database host
     # name<String>:: database name
     #
-    def initialize server, name
+    def initialize(server, name)
       @name = name
       @server = server
       @host = server.uri
-      @root = "#{host}/#{name}"
+      @uri = @root = "#{host}/#{name.gsub('/','%2F')}"
       @streamer = Streamer.new(self)
       @bulk_save_cache = []
-      @bulk_save_cache_limit = 50
+      @bulk_save_cache_limit = 500  # must be smaller than the uuid count
     end
     
     # returns the database's uri
     def to_s
-      @root
+      @uri
     end
     
     # GET the database info from CouchDB
     def info
-      CouchRest.get @root
+      CouchRest.get @uri
     end
     
     # Query the <tt>_all_docs</tt> view. Accepts all the same arguments as view.
-    def documents params = {}
+    def documents(params = {})
       keys = params.delete(:keys)
-      url = CouchRest.paramify_url "#{@root}/_all_docs", params
+      url = CouchRest.paramify_url "#{@uri}/_all_docs", params
       if keys
         CouchRest.post(url, {:keys => keys})
       else
@@ -47,10 +47,10 @@ 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 slow_view funcs, params = {}
+    def slow_view(funcs, params = {})
       keys = params.delete(:keys)
       funcs = funcs.merge({:keys => keys}) if keys
-      url = CouchRest.paramify_url "#{@root}/_slow_view", params
+      url = CouchRest.paramify_url "#{@uri}/_temp_view", params
       JSON.parse(RestClient.post(url, funcs.to_json, {"Content-Type" => 'application/json'}))
     end
     
@@ -59,14 +59,17 @@ module CouchRest
   
     # Query a CouchDB view as defined by a <tt>_design</tt> document. Accepts
     # paramaters as described in http://wiki.apache.org/couchdb/HttpViewApi
-    def view name, params = {}, &block
+    def view(name, params = {}, &block)
       keys = params.delete(:keys)
-      url = CouchRest.paramify_url "#{@root}/_view/#{name}", params
+      name = name.split('/') # I think this will always be length == 2, but maybe not...
+      dname = name.shift
+      vname = name.join('/')
+      url = CouchRest.paramify_url "#{@uri}/_design/#{dname}/_view/#{vname}", params
       if keys
         CouchRest.post(url, {:keys => keys})
       else
         if block_given?
-          @streamer.view(name, params, &block)
+          @streamer.view("_design/#{dname}/_view/#{vname}", params, &block)
         else
           CouchRest.get url
         end
@@ -74,38 +77,44 @@ module CouchRest
     end
     
     # GET a document from CouchDB, by id. Returns a Ruby Hash.
-    def get id
+    def get(id, params = {})
       slug = escape_docid(id)
-      hash = CouchRest.get("#{@root}/#{slug}")
-      doc = if /^_design/ =~ hash["_id"]
-        Design.new(hash)
+      url = CouchRest.paramify_url("#{@uri}/#{slug}", params)
+      result = CouchRest.get(url)
+      return result unless result.is_a?(Hash)
+      doc = if /^_design/ =~ result["_id"]
+        Design.new(result)
       else
-        Document.new(hash)
+        Document.new(result)
       end
       doc.database = self
       doc
     end
     
     # GET an attachment directly from CouchDB
-    def fetch_attachment docid, name
-      slug = escape_docid(docid)        
-      name = CGI.escape(name)
-      RestClient.get "#{@root}/#{slug}/#{name}"
+    def fetch_attachment(doc, name)
+      # slug = escape_docid(docid)        
+      # name = CGI.escape(name)
+      uri = uri_for_attachment(doc, name)
+      RestClient.get uri
+      # "#{@uri}/#{slug}/#{name}"
     end
     
     # PUT an attachment directly to CouchDB
-    def put_attachment doc, name, file, options = {}
+    def put_attachment(doc, name, file, options = {})
       docid = escape_docid(doc['_id'])
       name = CGI.escape(name)
-      uri = if doc['_rev']
-        "#{@root}/#{docid}/#{name}?rev=#{doc['_rev']}"
-      else
-        "#{@root}/#{docid}/#{name}"
-      end
-        
+      uri = uri_for_attachment(doc, name)       
       JSON.parse(RestClient.put(uri, file, options))
     end
     
+    # DELETE an attachment directly from CouchDB
+    def delete_attachment doc, name
+      uri = uri_for_attachment(doc, name)
+      # this needs a rev
+      JSON.parse(RestClient.delete(uri))
+    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
@@ -115,7 +124,7 @@ 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, bulk = false)
+    def save_doc(doc, bulk = false)
       if doc['_attachments']
         doc['_attachments'] = encode_attachments(doc['_attachments'])
       end
@@ -128,13 +137,13 @@ module CouchRest
       end
       result = if doc['_id']
         slug = escape_docid(doc['_id'])        
-        CouchRest.put "#{@root}/#{slug}", doc
+        CouchRest.put "#{@uri}/#{slug}", doc
       else
         begin
           slug = doc['_id'] = @server.next_uuid
-          CouchRest.put "#{@root}/#{slug}", doc
+          CouchRest.put "#{@uri}/#{slug}", doc
         rescue #old version of couchdb
-          CouchRest.post @root, doc
+          CouchRest.post @uri, doc
         end
       end
       if result['ok']
@@ -145,30 +154,40 @@ 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)
+    end
+    
+    
     # POST an array of documents to CouchDB. If any of the documents are
     # missing ids, supply one from the uuid cache.
     #
     # If called with no arguments, bulk saves the cache of documents to be bulk saved.
-    def bulk_save (docs = nil)
+    def bulk_save(docs = nil, use_uuids = true)
       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|
-        nextid = @server.next_uuid(uuid_count) rescue nil
-        doc['_id'] = nextid if nextid
+      if (use_uuids) 
+        ids, noids = docs.partition{|d|d['_id']}
+        uuid_count = [noids.length, @server.uuid_batch_count].max
+        noids.each do |doc|
+          nextid = @server.next_uuid(uuid_count) rescue nil
+          doc['_id'] = nextid if nextid
+        end
       end
-      CouchRest.post "#{@root}/_bulk_docs", {:docs => docs}
+      CouchRest.post "#{@uri}/_bulk_docs", {:docs => docs}
     end
+    alias :bulk_delete :bulk_save
     
     # DELETE the document from CouchDB that has the given <tt>_id</tt> and
     # <tt>_rev</tt>.
     #
     # 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)
+    def delete_doc(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 }
@@ -176,13 +195,19 @@ module CouchRest
         return { "ok" => true } # Mimic the non-deferred version
       end
       slug = escape_docid(doc['_id'])        
-      CouchRest.delete "#{@root}/#{slug}?rev=#{doc['_rev']}"
+      CouchRest.delete "#{@uri}/#{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
-    def copy doc, dest
+    def copy_doc(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']
@@ -190,41 +215,75 @@ module CouchRest
       else
         dest
       end
-      CouchRest.copy "#{@root}/#{slug}", destination
+      CouchRest.copy "#{@uri}/#{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
+    ### 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"
+      CouchRest.post "#{@uri}/_compact"
     end
-
+    
+    # Create the database
+    def create!
+      bool = server.create_db(@name) rescue false
+      bool && true
+    end
+    
+    # Delete and re create the database
+    def recreate!
+      delete!
+      create!
+    rescue RestClient::ResourceNotFound
+    ensure
+      create!
+    end
+    
+    # Replicates via "pulling" from another database to this database. Makes no attempt to deal with conflicts.
+    def replicate_from other_db
+      raise ArgumentError, "must provide a CouchReset::Database" unless other_db.kind_of?(CouchRest::Database)
+      CouchRest.post "#{@host}/_replicate", :source => other_db.root, :target => name
+    end
+    
+    # Replicates via "pushing" to another database. Makes no attempt to deal with conflicts.
+    def replicate_to other_db
+      raise ArgumentError, "must provide a CouchReset::Database" unless other_db.kind_of?(CouchRest::Database)
+      CouchRest.post "#{@host}/_replicate", :target => other_db.root, :source => name
+    end
+    
     # DELETE the database itself. This is not undoable and could be rather
     # catastrophic. Use with care!
     def delete!
-      CouchRest.delete @root
+      CouchRest.delete @uri
     end
 
     private
-
+    
+    def uri_for_attachment(doc, name)
+      if doc.is_a?(String)
+        puts "CouchRest::Database#fetch_attachment will eventually require a doc as the first argument, not a doc.id"
+        docid = doc
+        rev = nil
+      else
+        docid = doc['_id']
+        rev = doc['_rev']
+      end
+      docid = escape_docid(docid)
+      name = CGI.escape(name)
+      rev = "?rev=#{doc['_rev']}" if rev
+      "#{@root}/#{docid}/#{name}#{rev}"
+    end
+    
     def escape_docid id      
       /^_design\/(.*)/ =~ id ? "_design/#{CGI.escape($1)}" : CGI.escape(id) 
     end
 
-    def encode_attachments attachments
+    def encode_attachments(attachments)
       attachments.each do |k,v|
         next if v['stub']
         v['data'] = base64(v['data'])
@@ -232,7 +291,7 @@ module CouchRest
       attachments
     end
 
-    def base64 data
+    def base64(data)
       Base64.encode64(data).gsub(/\s/,'')
     end
   end