samflores-couchrest 0.2.1 → 0.12.3

data/README.md

@@ -6,7 +6,8 @@ which I find to be concise, clear, and well designed. CouchRest lightly wraps
 CouchDB's HTTP API, managing JSON serialization, and remembering the URI-paths
 to CouchDB's API endpoints so you don't have to.
 
-CouchRest is designed to make a simple base for application and framework-specific object oriented APIs. CouchRest is Object-Mapper agnostic, the parsed JSON it returns from CouchDB shows up as subclasses of Ruby's Hash. Naked JSON, just as it was mean to be.
+CouchRest's lighweight is designed to make a simple base for application and
+framework-specific object oriented APIs.
 
 ## Easy Install
 
@@ -31,7 +32,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_doc({:key => 'value', 'another key' => 'another value'})
+    response = @db.save({:key => 'value', 'another key' => 'another value'})
     doc = @db.get(response['id'])
     puts doc.inspect
 
@@ -47,7 +48,7 @@ Bulk Save:
 
 Creating and Querying Views:
 
-    @db.save_doc({
+    @db.save({
       "_id" => "_design/first", 
       :views => {
         :test => {
@@ -59,35 +60,10 @@ Creating and Querying Views:
 
 ## CouchRest::Model
 
-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 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

@@ -23,15 +23,18 @@ 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", "Matt Aimonetti"]
+  s.authors = ["J. Chris Anderson"]
   s.files = %w( LICENSE README.md Rakefile THANKS.md ) + 
-    Dir["{examples,lib,spec,utils}/**/*"] - 
+    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 << 'couchdir'
   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
 
 

data/bin/couchdir

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+
+unless ARGV.length >= 2
+  puts "usage: couchdir path/to/directory db-name [docid]"
+  exit
+end
+
+require 'rubygems'
+require 'couchrest'
+
+dirname = ARGV[0]
+dbname = ARGV[1]
+docid = ARGV[2]
+
+puts "Create attachments for the files in #{dirname} in database #{dbname}."
+
+fm = CouchRest::FileManager.new(dbname)
+fm.loud = true
+puts "Pushing views from directory #{dirname} to database #{fm.db}"
+fm.push_directory(dirname, docid)

data/examples/model/example.rb

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

data/examples/word_count/word_count.rb

@@ -1,5 +1,4 @@
-require 'rubygems'
-require 'couchrest'
+require File.dirname(__FILE__) + '/../../couchrest'
 
 couch = CouchRest.new("http://127.0.0.1:5984")
 db = couch.database('word-count-example')
@@ -40,7 +39,29 @@ books.keys.each do |book|
     end
   end
 end
+ 
+# word_count = {
+#   :map => 'function(doc){
+#     var words = doc.text.split(/\W/);
+#     words.forEach(function(word){
+#       if (word.length > 0) emit([word,doc.title],1);
+#     });
+#   }',
+#   :reduce => 'function(key,combine){
+#     return sum(combine);
+#   }'
+# }
+# 
+# db.delete db.get("_design/word_count") rescue nil
+# 
+# db.save({
+#   "_id" => "_design/word_count",
+#   :views => {
+#     :count => word_count,
+#     :words => {:map => word_count[:map]}
+#   }
+# })
 
 # 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,23 +1,22 @@
-require 'rubygems'
-require 'couchrest'
+require File.dirname(__FILE__) + '/../../couchrest'
 
 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."
 puts "\nThe simplest query we can run is the total word count for all words in all documents:"
-puts "this will take a few minutes the first time. if it times out, just rerun this script in a few few minutes."
-puts db.view('word_count/words').inspect
+
+puts db.view('word_count/count').inspect
 
 puts "\nWe can also narrow the query down to just one word, across all documents. Here is the count for 'flight' in all three books:"
 
 word = 'flight'
 params = {
   :startkey => [word], 
-  :endkey => [word,{}]
+  :endkey => [word,'Z']
   }
 
-puts db.view('word_count/words',params).inspect
+puts db.view('word_count/count',params).inspect
 
 puts "\nWe scope the query using startkey and endkey params to take advantage of CouchDB's collation ordering. Here are the params for the last query:"
 puts params.inspect
@@ -29,7 +28,7 @@ params = {
   :key => [word, title]
   }
   
-puts db.view('word_count/words',params).inspect
+puts db.view('word_count/count',params).inspect
 
 
 puts "\nHere are the params for 'flight' in the da-vinci book:"

data/lib/couchrest/core/database.rb

@@ -3,7 +3,7 @@ require "base64"
 
 module CouchRest
   class Database
-    attr_reader :server, :host, :name, :root, :uri
+    attr_reader :server, :host, :name, :root
     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
-      @uri = @root = "#{host}/#{name}"
+      @root = "#{host}/#{name}"
       @streamer = Streamer.new(self)
       @bulk_save_cache = []
-      @bulk_save_cache_limit = 500  # must be smaller than the uuid count
+      @bulk_save_cache_limit = 50
     end
     
     # returns the database's uri
     def to_s
-      @uri
+      @root
     end
     
     # GET the database info from CouchDB
     def info
-      CouchRest.get @uri
+      CouchRest.get @root
     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 "#{@uri}/_all_docs", params
+      url = CouchRest.paramify_url "#{@root}/_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 "#{@uri}/_temp_view", params
+      url = CouchRest.paramify_url "#{@root}/_slow_view", params
       JSON.parse(RestClient.post(url, funcs.to_json, {"Content-Type" => 'application/json'}))
     end
     
@@ -59,17 +59,14 @@ 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)
-      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
+      url = CouchRest.paramify_url "#{@root}/_view/#{name}", params
       if keys
         CouchRest.post(url, {:keys => keys})
       else
         if block_given?
-          @streamer.view("_design/#{dname}/_view/#{vname}", params, &block)
+          @streamer.view(name, params, &block)
         else
           CouchRest.get url
         end
@@ -77,9 +74,9 @@ module CouchRest
     end
     
     # GET a document from CouchDB, by id. Returns a Ruby Hash.
-    def get(id)
+    def get id
       slug = escape_docid(id)
-      hash = CouchRest.get("#{@uri}/#{slug}")
+      hash = CouchRest.get("#{@root}/#{slug}")
       doc = if /^_design/ =~ hash["_id"]
         Design.new(hash)
       else
@@ -90,29 +87,25 @@ module CouchRest
     end
     
     # GET an attachment directly from CouchDB
-    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}"
+    def fetch_attachment docid, name
+      slug = escape_docid(docid)        
+      name = CGI.escape(name)
+      RestClient.get "#{@root}/#{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 = uri_for_attachment(doc, name)       
+      uri = if doc['_rev']
+        "#{@root}/#{docid}/#{name}?rev=#{doc['_rev']}"
+      else
+        "#{@root}/#{docid}/#{name}"
+      end
+        
       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
@@ -122,7 +115,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(doc, bulk = false)
+    def save (doc, bulk = false)
       if doc['_attachments']
         doc['_attachments'] = encode_attachments(doc['_attachments'])
       end
@@ -135,13 +128,13 @@ module CouchRest
       end
       result = if doc['_id']
         slug = escape_docid(doc['_id'])        
-        CouchRest.put "#{@uri}/#{slug}", doc
+        CouchRest.put "#{@root}/#{slug}", doc
       else
         begin
           slug = doc['_id'] = @server.next_uuid
-          CouchRest.put "#{@uri}/#{slug}", doc
+          CouchRest.put "#{@root}/#{slug}", doc
         rescue #old version of couchdb
-          CouchRest.post @uri, doc
+          CouchRest.post @root, doc
         end
       end
       if result['ok']
@@ -152,40 +145,30 @@ 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, use_uuids = true)
+    def bulk_save (docs = nil)
       if docs.nil?
         docs = @bulk_save_cache
         @bulk_save_cache = []
       end
-      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
+      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
-      CouchRest.post "#{@uri}/_bulk_docs", {:docs => docs}
+      CouchRest.post "#{@root}/_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(doc, bulk = false)
+    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 }
@@ -193,19 +176,13 @@ module CouchRest
         return { "ok" => true } # Mimic the non-deferred version
       end
       slug = escape_docid(doc['_id'])        
-      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)
+      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(doc, dest)
+    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']
@@ -213,19 +190,13 @@ module CouchRest
       else
         dest
       end
-      CouchRest.copy "#{@uri}/#{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)
+      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(doc, dest)
+    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']
@@ -233,75 +204,27 @@ module CouchRest
       else
         dest
       end
-      CouchRest.move "#{@uri}/#{slug}?rev=#{doc['_rev']}", destination
-    end
-    
-    ### DEPRECATION NOTICE
-    def move(doc, dest)
-      puts "CouchRest::Database's move method is being deprecated, please use move_doc instead"
-      move_doc(doc, dest)
+      CouchRest.move "#{@root}/#{slug}?rev=#{doc['_rev']}", destination
     end
     
     # Compact the database, removing old document revisions and optimizing space use.
     def 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
+      CouchRest.post "#{@root}/_compact"
     end
-    
+
     # DELETE the database itself. This is not undoable and could be rather
     # catastrophic. Use with care!
     def delete!
-      CouchRest.delete @uri
+      CouchRest.delete @root
     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'])
@@ -309,7 +232,7 @@ module CouchRest
       attachments
     end
 
-    def base64(data)
+    def base64 data
       Base64.encode64(data).gsub(/\s/,'')
     end
   end