akdubya-cushion 0.5.2 → 0.6.0

data/README.rdoc

@@ -1,226 +1,146 @@
 = Cushion: A slim CouchDB client
 
-Cushion is a minimalist Ruby client for accessing CouchDB servers. Originally
-extracted from CouchRest (http://github.com/jchrist/couchrest), Cushion strips
-out the extras while supporting more native CouchDB commands.
+Cushion is a Ruby client for accessing CouchDB servers that's light on the
+extras and heavy on the syntatical sugar.
+
+Credit goes to CouchRest (http://github.com/jchris/couchrest/tree/master) for
+the inspiration.
 
 == Getting Started
 
   # myapp.rb
   require 'cushion'
 
-  db = Cushion.db!('http://127.0.0.1:5984/mydb')
-  db.save_doc("_id" => "abc", "foo" => "bar")
-  db.open_doc("abc")
-
-== Servers
-
-The server location defaults to http://127.0.0.1:5984, so you may omit the host
-when initializing a server if you are satisfied with the default.
-
-  Cushion.server
-  Cushion.server('http://myhost:6969')
-
-Display the server welcome message:
-
-  server.info
-
-Get a list of all databases on the server:
+  db = Cushion!(mydb)
 
-  server.all_dbs
+== Document Basics
 
-Display any running tasks (such as replication):
+Storing documents is simple. Just supply a hash of attributes. Leave out the
+<tt>_id</tt> attribute if you want to use an auto-generated UUID. Set the
+<tt>_rev</tt> attribute to update a document:
 
-  server.active_tasks
+  db.store("baz" => "bat")
+  # => {"ok"=>true, "id"=> "bdd39a3f9a1e5894d3d1283aa0d0f53f", "rev"=> "2699240268"}
 
-Get the server configuration hash:
+  response = db.store("_id" => "mydoc", "foo" => "bar")
+  # => {"ok"=>true, "id"=>"mydoc", "rev"=>"882534292"}
 
-  server.config
+  db.store("_id" => "mydoc", "foo" => "baz", "_rev" => response['rev'])
+  # => {"ok"=>true, "id"=>"mydoc", "rev"=>"3617508982"}
 
-Set a configuration option:
+Fetching documents is just as simple.
 
-  server.set_config("mysection", "myoption", "myvalue")
-
-Restart the server:
-
-  server.restart
-
-Obtain server stats:
-
-  server.stats
-
-Replicate from a source database to a target database:
-
-  server.replicate("db1", "db2")
-  server.replicate("db1", "http://host2:5984/bar")
+  db.key?("mydoc")    # => true
+  db.fetch("mydoc")   # => {"_id"=>"mydoc", "_rev"=>"3617508982", "foo"=>"baz"}
+  db.fetch("bogusid") # => raises RestClient::ResourceNotFound
 
-Return a <tt>Cushion::Database</tt> without first creating it:
+  # Use etags to perform a conditional GET
+  db.fetch("mydoc", :etag => cur_rev)  # => raises RestClient::NotModified
 
-  server.db("mydb")
-  server[:mydb]
+Store attachments inline or via CouchDB's standalone attachment API. The standalone
+method accepts both IO objects and strings:
 
-Create a database and return a <tt>Cushion::Database</tt>:
-
-  server.db!("mydb")
-
-== Databases
-
-Create a database directly from a url, or just return the database instance if
-it already exists:
-
-  Cushion.db!('http://127.0.0.1:5984/mydb')
-
-Compact a database, eliminating old document revisions:
-
-  db.compact
-
-Create and delete a database from an instance of <tt>Cushion::Database</tt>
-
-  db.create
-  db.delete
-
-Open a document:
-
-  db.open_doc("mydoc")
+  # Inline
+  db.store("_id" => "hasfiles", ..., "_attachments" => {
+    "foo.txt" => {
+      "content_type" => "text/plain",
+      "data" => "Hello World!"
+    }})
 
-Fetch all documents from a database:
+  # Standalone
+  res = @db.store("_id" => "savemefirst", ...)
+  db.attach("savemefirst", "foo.txt", "Hello World!", :rev => res['rev'],
+    :content_type => "text/plain")
+  # => Foo now contains an attachment hash similar to the above example
 
-  db.all_docs
+  # Fetch attachment data
+  db.fetch("savemefirst", "foo.txt")  # => "Hello World!"
 
-Save a document. The +_id+ may be omitted on document creation:
+Cushion returns parsed JSON by default. In those cases where you need the raw
+JSON string, simply set an accept header:
 
-  db.save_doc("_id" => "abc", .. attributes ..)
-  db.save_doc(.. attributes ..)
-  ab.save_doc("_id" => "exists", "_rev" => "1234", .. attributes ..)
+  db.fetch("mydoc", :headers => { :accept => "text/plain" })
+  # => "{\"_id\":\"mydoc\",\"_rev\":\"3617508982\",\"foo\":\"baz\"}\n"
 
-Delete a document. Must include both an +id+ and a +rev+:
+The technique above works for nearly every <tt>Cushion</tt> request method.
 
-  db.delete_doc("mydoc", "1234")
+== Document Macros
 
-Perform a bulk save/update/delete operation:
+You can use CouchDB's bulk docs feature to create, update and delete many
+documents at once:
 
   docs = [
-    { "_id" => "0", "_rev" => "123456", "_deleted" => true }, #=> Delete this doc
-    { "_id" => "1", "_rev" => "32486671", "foo" => "bar" },   #=> Update this doc
-    { "_id" => "2", "baz" => "bat" }                          #=> Create this doc
+    { "_id" => "0", "_rev" => "123456", "_deleted" => true }, #=> Delete
+    { "_id" => "1", "_rev" => "32486671", "foo" => "bar" },   #=> Update
+    { "_id" => "2", "baz" => "bat" }                          #=> Create
   ]
 
-  db.bulk_docs(docs)
+  db.bulk(docs)                  # => returns a hash of updated documents
+  db.bulk(docs, :delete => true) # => deletes the selected docs
 
-Perform a bulk delete operation. This is a convenience method:
+Documents and attachments may also be copied or moved within the same database.
+Some useful examples:
 
-  db.bulk_delete(some_docs)
+  # Documents
+  db.copy("mydoc", "new_doc")
+  # => {"ok"=>true, "id"=>"new_doc", "rev"=> ...}
+  db.move("mydoc", "existing_doc", :rev => ..., :dest_rev => ...)
+  # => overwrites the existing doc
 
-Purge document revisions from the database, effectively erasing history:
+  # Attachments
+  db.copy_attachment("mydoc", "foo.txt", "bar.txt")
+  # => copies an attachment within the same doc
+  db.move_attachment("mydoc", "foo.txt", "bar.txt")
+  # => renames an attachment; aliased at #rename_attachment
 
-  doc_revs = {
-    "1" => ["12345", "42836"],
-    "2" => ["572654"],
-    "3" => ["34462"]
-  }
-
-  db.purge(doc_revs)
-
-Copy or move a document to a new +id+. Specify a +dest_rev+ to overwrite an existing
-document:
-
-  db.copy_doc("doc1", "doc2")
-  db.copy_doc("doc1", "doc2", :dest_rev => "36452")
-  db.move_doc("doc1", "1234", "doc2")
-  db.move_doc("doc1", "1234", "doc2", :dest_rev => "37462")
-
-CouchDB can attach multiple files directly to documents, either as inline Base64
-encoded data or via a standalone attachment API.
-
-Open a document attachment. This will return an <tt>IO</tt> object:
-
-  temp = db.open_attachment("mydoc", "foo.txt")
-  temp.read
-
-Save an inline attachment to a document:
-
-  db.save_doc("_id" => "mydoc", "_attachments" => {
-    "foo.txt" => {
-      "content_type" => "text/plain",
-      "data" => "Hello World!"
-    }
-  })
-
-Save a standalone attachment to a saved document. Content type defaults to
-"application/octet-stream":
-
-  db.save_attachment("mydoc", "1234", "bar.txt", "somedata", :content_type => "text/plain")
-
-Delete a document attachment:
-
-  db.delete_attachment("mydoc", "1234", "foo.txt")
-
-Rename an attachment:
-
-  db.rename_attachment("mydoc", "1234", "baz.txt", "bat.txt")
+See the database specs for more copy and move examples.
 
 == Views
 
-Create a temporary view and run a query against it:
+- creating (design docs)
+- querying
+- temp views
 
-  temp_view = { :map => "function(doc){emit(doc.status,null)}" }
-  db.temp_view(temp_view, :key => "verified")
+== Servers and Databases
 
-Run a query against a saved view:
-
-  db.view("people/by_first_name", :key => "gomer")
-
-Show and list functions:
-
-  db.show("examples", "people", "mydoc", :format => "xml")
-  db.list("examples", "browse-people", "people-by-name", :startkey => ["a"], :limit => 10)
+The server location defaults to http://127.0.0.1:5984, so you may omit the host
+when initializing a server if you are satisfied with the default.
 
-See http://wiki.apache.org/couchdb/Formatting_with_Show_and_List
+NOTE: Some cruft needs cleaning up. Use <tt>Cushion!(dbname, opts)</tt> for
+now.
 
-== External Processes
+Display various bits of server metadata as follows:
 
-Issue a request to a CouchDB external process, such as a full text indexing
-engine:
+  server.info          #=> welcome message
+  server.all_dbs       #=> all dbs available
+  server.active_tasks  #=> running tasks (e.g., replication or compaction)
+  server.config        #=> server config
+  server.restart       #=> restart the server
+  server.stats         #=> detailed runtime stats
 
-  db.external(:get, 'search/foo', :query => { 'foo' => 'bar' })
+<tt>Cushion::Server</tt> can also replicate local and remote databases:
 
-== Content Negotiation
+  server.replicate("db1", "db2")
+  server.replicate("db1", "http://host2:5984/bar")
 
-All commands except for +show+ and +list+ return parsed JSON by default, but in some
-cases it is useful to return the raw response from CouchDB. Simply set the correct
-HTTP headers to request an alternate format:
+Creating database instances:
 
-  db.all_docs :headers => { :accept => "text/plain" }
+- top level methods
+- options
 
-Some commands accept a headers hash as the last parameter, allowing you to omit
-the explicit headers key like so:
+DB Operations:
 
-  db.info :accept => "text/plain"
+  db.create
+  db.delete
+  db.compact
 
 == Cushion::Document
 
-<tt>Cushion::Document</tt> provides a light wrapper for working directly with
-individual documents.
-
-Create a document:
-
-  Cushion::Document.use_database(db)
-  doc = Cushion::Document.new("foo" => "bar")
-  doc.save
-
-Open a document and return an instance of <tt>Cushion::Document</tt>:
-
-  db.doc("mydoc")
-  doc["_foo"] = "bar"
-  doc.save
-
-Copy a document:
-
-  doc.copy("mydoc2")
+== Tricks
 
-Work with document attachments:
+Use the #headers method to obtain response headers on any request:
 
-  doc.open_attachment("foo.txt")
-  doc.save_attachment("bar.txt", "somedata", :content_type => "text/plain")
-  doc.delete_attachment("bar.txt")
-  doc.rename_attachment("foo.txt", "newfoo.txt")
+  db.fetch("mydoc").headers
+  # => {:server=>"CouchDB/0.9.0a (Erlang OTP/R12B)", :etag=>"\"3617508982\"",
+    :date=>"Fri, 06 Mar 2009 10:21:59 GMT", :content_type=>"application/json",
+    :content_length=>"48", :cache_control=>"must-revalidate"}

data/lib/cushion.rb

@@ -12,14 +12,22 @@ require dir + 'design'
 
 DEFAULT_COUCH_HOST = "http://127.0.0.1:5984"
 
+def Cushion(dbname, opts = {})
+  Cushion.server(opts).db(dbname)
+end
+
+def Cushion!(dbname, opts = {})
+  Cushion.server(opts).db!(dbname)
+end
+
 module Cushion
-  VERSION = '0.5.2'
+  VERSION = '0.6.0'
 
   class << self
 
     # Returns a Cushion::Server instance.
-    def server(*args)
-      Server.new(*args)
+    def server(options = {})
+      Server.new(options)
     end
     alias_method :new, :server
 
@@ -27,7 +35,7 @@ module Cushion
     # to create the database on the server.
     def db(url)
       parsed = parse(url)
-      server = Cushion.new(parsed[:host])
+      server = Cushion.new(:uri => parsed[:host])
       server.db(parsed[:db])
     end
     alias_method :database, :db
@@ -36,7 +44,7 @@ module Cushion
     # instance.
     def db!(url)
       parsed = parse(url)
-      server = Cushion.new(parsed[:host])
+      server = Cushion.new(:uri => parsed[:host])
       server.db!(parsed[:db])
     end
     alias_method :database!, :db!
@@ -45,7 +53,7 @@ module Cushion
     # instance.
     def recreate(url)
       parsed = parse(url)
-      server = Cushion.new(parsed[:host])
+      server = Cushion.new(:uri => parsed[:host])
       server.recreate(parsed[:db])
     end
 
@@ -61,9 +69,13 @@ module Cushion
       url
     end
 
-    # Handles document id escaping.
-    def escape_docid(id)
-      /^_design\/(.*)/ =~ id ? "_design/#{CGI.escape($1)}" : CGI.escape(id)
+    # Handles key escaping.
+    def escape_key(id, filename = nil)
+      if filename
+        "#{escape_docid(id)}/#{CGI.escape(filename)}"
+      else
+        escape_docid(id)
+      end
     end
 
     # Base64 encodes inline attachments.
@@ -78,7 +90,7 @@ module Cushion
     def base64(data)
       Base64.encode64(data).gsub(/\s/,'')
     end
-    
+
     # Sets the RestClient proxy.
     def proxy(url)
       RestClient.proxy = url
@@ -86,6 +98,10 @@ module Cushion
 
     private
 
+    def escape_docid(id)
+      /^_design\/(.*)/ =~ id ? "_design/#{CGI.escape($1)}" : CGI.escape(id)
+    end
+
     def parse(url)
       parsed = URI.parse(url)
       {
@@ -94,4 +110,32 @@ module Cushion
       }
     end
   end # class << self
+
+  # Provides a clean method of adding metadata (e.g., headers) to JSON parsed
+  # responses. Inspired by <tt>OpenURI::Meta</tt>.
+  module Meta
+    def Meta.init(obj, src=nil)
+      obj.extend Meta
+      obj.instance_eval {
+        @headers = {}
+      }
+      if src
+        src.headers.each {|name, value|
+          obj.add_header_field(name, value)
+        }
+      end
+      obj
+    end
+
+    attr_accessor :headers
+
+    def add_header_field(name, value)
+      #value.gsub!('"', '') if name == :etag  ==> CouchDB seems to require the xtra "'s
+      @headers[name] = value
+    end
+
+    def etag
+      @headers[:etag]
+    end
+  end
 end

data/lib/cushion/database.rb

@@ -4,92 +4,157 @@ require 'base64'
 module Cushion
   class Database
     attr_reader :server, :name
+    attr_accessor :use_tempfiles
 
-    def initialize(server, name)
-      raise ArgumentError, "server must be an a Cushion::Server" unless server.kind_of?(Cushion::Server)
+    # Initializes a Cushion::Database instance.
+    def initialize(name, options = {})
+      unless options[:server]
+        raise ArgumentError, "server option must be provided"
+      end
+      unless name
+        raise ArgumentError, "name must be provided"
+      end
       # TODO: CouchDB has strict db naming requirements. Should validate.
       @name = CGI.escape(name.to_s)
-      @server = server
-    end
-
-    # Retrieves information about this database.
-    def info(headers = {})
-      server.get(@name, headers)
-    end
-
-    # Compacts this database.
-    def compact(headers = {})
-      post("_compact", nil, headers)
-    end
-
-    # Creates this database on the server.
-    def create(headers = {})
-      server.put(@name, nil, headers)
+      @server = options[:server]
+      @use_tempfiles = options[:use_tempfiles]
     end
 
-    # Deletes this database from the server.
-    def drop(headers = {})
-      server.delete(@name, headers)
-    end
-
-    # Query the default +all_docs+ view. Set the +keys+ option to perform a
-    # key-based multi-document fetch. Set the +headers+ option to pass
-    # custom request headers.
+    # Retrieves a single document or attachment by key. Returns attachments as
+    # an <tt>OpenURI</tt> <tt>IO</tt> object if the +use_tempfiles+ database
+    # option has been set. Set the +headers+ option to pass custom request headers.
+    # Examples:
     #
-    def all_docs(params = {})
-      keys = params.delete(:keys)
-      opts = params.delete(:headers) || {}
-      path = Cushion.paramify_url("_all_docs", params)
-      if keys
-        post(path, {:keys => keys}, opts)
-      else
-        get(path, opts)
+    #   db.fetch("mydoc")
+    #   db.fetch("my/doc")      # Forward slashes are automatically escaped...
+    #   db.fetch("_design/foo") # ...except in the case of design docs
+    #
+    # Attachments can be fetched by supplying the id and filename as follows:
+    #
+    #   db.fetch("mydoc", "foo.txt")
+    #   db.fetch("mydoc", "path/to/foo.txt") # Virtual file path
+    #
+    # Cushion requests "application/json" by default, and response bodies will
+    # automatically be parsed as such. To request data from CouchDB in another
+    # (unparsed) format, simply set the +accept+ header:
+    #
+    #   db.fetch("mydoc", :headers => { :accept => "text/plain" })
+    #
+    # Set <code>:head => true</code> to return the headers rather than the
+    # content body. Set <code>:etag => some_value</code> to perform a
+    # simple if-none-match conditional GET.
+    #
+    def fetch(*args)
+      options = args.last.is_a?(Hash) ? args.pop : {}
+      id, file = args
+      slug = Cushion.escape_key(id, file)
+      headers = options.delete(:headers) || {}
+      if etag = options.delete(:etag)
+        headers.merge!(:if_none_match => "\"#{etag}\"")
       end
+      head = options.delete(:head)
+      path = Cushion.paramify_url("#{slug}", options)
+      if head
+        return head(path, headers)
+      elsif file && @use_tempfiles
+        return server.open_attachment("#{@name}/#{path}")
+      end
+      get(path, headers)
     end
 
-    # Retrieves a single document by +id+. Set the +headers+ option to pass
-    # custom request headers.
-    def open_doc(id, params = {})
-      opts = params.delete(:headers) || {}
-      slug = Cushion.escape_docid(id)
-      path = Cushion.paramify_url("#{slug}", params)
-      get(path, opts)
+    # Returns true if a document key exists in this database. See #fetch.
+    def key?(*args)
+      options = args.last.is_a?(Hash) ? args.pop : {}
+      id, file = args
+      !!fetch(id, file, options.merge(:head => true))
+    rescue RestClient::ResourceNotFound
+      false
     end
+    alias_method :has_key?, :key?
 
     # Retrieves a single document by +id+ and returns a <tt>Cushion::Document</tt>
     # linked to this database.
     #
-    def doc(id, params = {})
-      result = open_doc(id, params)
-      ndoc = Cushion::Document.new(result)
+    def doc(id, options = {})
+      result = fetch(id.to_s, options)
+
+      ndoc = if /^_design/ =~ result["_id"]
+        Design.new(result)
+      else
+        Document.new(result)
+      end
+
       ndoc.database = self
       ndoc
     end
     alias_method :document, :doc
 
-    # Saves the params hash to the database as a document, encoding inline
-    # attachments and generating a UUID if no +_id+ is supplied. A +_rev+ attribute
-    # must be supplied to update an existing document. Set the +headers+ option
-    # to pass custom request headers.
+    # Stores a document to the database. Pass a hash with the desired attributes.
+    # If an +_id+ attribute is not provided one will be generated automatically
+    # from the server UUID cache. Examples:
+    # 
+    #   db.store("foo" => "bar")  #=> Creates a doc with an auto-generated key
+    #   db.store("_id" => "def")  #=> Creates a doc with key "def"
+    #
+    # To update a document, set the +_rev+ attribute on the document hash:
     #
-    def save_doc(params = {})
-      opts = params.delete(:headers) || {}
-      if params['_attachments']
-        params['_attachments'] = Cushion.encode_attachments(params['_attachments'])
+    #   db.store("_id" => "ghi", "_rev" => "1234")
+    #
+    # Inline attachments are automatically encoded within the document.
+    #
+    def store(doc, options = {})
+      headers = options.delete(:headers) || {}
+      if doc['_attachments']
+        doc['_attachments'] = Cushion.encode_attachments(doc['_attachments'])
       end
-      if params['_id']
-        slug = Cushion.escape_docid(params['_id'])
-        put("#{slug}", params, opts)
+      res = if doc['_id']
+        slug = Cushion.escape_key(doc['_id'])
+        put("#{slug}", doc, headers)
       else
-        slug = params['_id'] = server.next_uuid
-        put("#{slug}", params, opts)
+        slug = doc['_id'] = server.next_uuid
+        put("#{slug}", doc, headers)
       end
+      if res['ok']
+        doc['_id'] = res['id']
+        doc['_rev'] = res['rev']
+      end
+      res
     end
 
-    # Deletes a single document by +id+ and +rev+.
-    def delete_doc(id, rev, headers = {})
-      slug = Cushion.escape_docid(id)
-      delete("#{slug}?rev=#{rev}", headers)
+    # Save a file attachment under an existing document, or create a new document
+    # containing an attachment. +id+ is the document id. +filename+ is the name
+    # of the attachment (extensions may be omitted). Set the +rev+ option to store
+    # the attachment under an existing document. Example:
+    #
+    #  db.attach("docid", "foo.txt", somedata, :rev => "1234")
+    #  #=> Stores an attachment under docid
+    #
+    #  db.attach("anotherid", "bar.jpg", :content_type => "image/jpeg")
+    #  #=> Creates a new document containing the attachment. Also sets the
+    #      content type.
+    #
+    #  +data+ may be a <tt>String</tt>, or any object that responds to read.
+    #
+    # Content type defaults to 'application/octet-stream'.
+    #
+    def attach(id, filename, data, options = {})
+      headers = options.delete(:headers) || {}
+      headers[:content_type] = options.delete(:content_type) || "application/octet-stream"
+      rev = options.delete(:rev)
+      slug = Cushion.escape_key(id, filename)
+      rev_slug = "?rev=#{rev}" if rev
+      data = data.respond_to?(:read) ? data.read : data
+      put("#{slug}#{rev_slug}", data, headers)
+    end
+
+    # Deletes a single document or attachment by key. The +rev+ option must be
+    # provided.
+    def destroy(*args)
+      options = args.last.is_a?(Hash) ? args.pop : {}
+      headers = options.delete(:headers) || {}
+      id, file = args
+      slug = Cushion.escape_key(id, file)
+      delete("#{slug}?rev=#{options[:rev]}", headers)
     end
 
     # Creates, updates and deletes multiple documents in this database according
@@ -102,10 +167,10 @@ module Cushion
     #     { "_id" => "1", "_rev" => "32486671", "foo" => "bar" },   #=> Update this doc
     #     { "_id" => "2", "baz" => "bat" }                          #=> Create this doc
     #   ]
-    #   
-    #   db.bulk_docs(docs)
     #
-    # +bulk_docs+ returns a hash of updated doc ids and revs, as follows:
+    #   db.bulk(docs)
+    #
+    # <tt>bulk</tt> returns a hash of updated doc ids and revs, as follows:
     #
     #   {
     #     "ok" => true,
@@ -117,12 +182,19 @@ module Cushion
     #   }
     #
     # Set the +use_uuids+ option to generate UUIDs from the server cache before
-    # saveing. Set the +headers+ option to pass custom request headers.
+    # saving. Set the +headers+ option to pass custom request headers.
     #
-    def bulk_docs(docs, params = {})
-      headers = params.delete(:headers) || {}
-      opts = { :use_uuids => true }.merge(params)
-      if (opts[:use_uuids])
+    def bulk(docs, options = {})
+      delete_all = options.delete(:delete)
+      headers = options.delete(:headers) || {}
+      use_uuids = options.delete(:use_uuids) || true
+      if delete_all
+        updates = docs.map { |doc|
+          { '_id' => doc['_id'], '_rev' => doc['_rev'], '_deleted' => true } }
+      else
+        updates = docs
+      end
+      if (use_uuids)
         ids, noids = docs.partition{|d|d['_id']}
         uuid_count = [noids.length, server.uuid_batch_count].max
         noids.each do |doc|
@@ -130,114 +202,144 @@ module Cushion
           doc['_id'] = nextid if nextid
         end
       end
-      post("_bulk_docs", {:docs => docs}, headers)
-    end
-
-    # A convenience method for deleting multiple documents at once. Just pass in
-    # an array of saved +docs+ and the correct deletion params are
-    # automatically set. (See #bulk_docs)
-    #
-    def bulk_delete(docs, params = {})
-      deletions = docs.map { |doc| { '_id' => doc['_id'], '_rev' => doc['_rev'], '_deleted' => true } }
-      bulk_docs(deletions, params.merge(:use_uuids => false))
+      post("_bulk_docs", {:docs => updates}, headers)
     end
 
-    # Completely purges the supplied document revisions from the database.
-    # +doc_revs+ is a hash of document ids, each containing an array of revisions
-    # to be deleted. Example:
-    # 
-    #   doc_revs = {
-    #     "1" => ["12345", "42836"],
-    #     "2" => ["572654"],
-    #     "3" => ["34462"]
-    #   }
+    # Copies the document at +source+ to a new or existing location at +destination+.
+    # Set the +dest_rev+ option to overwrite an existing document. Set the
+    # +headers+ option to pass custom request headers. Example:
     #
-    #  db.purge(doc_revs)
+    #   db.copy("doc1", "doc2")
+    #     #=> Copies to a new location
+    #   db.copy("doc1", "doc3", :dest_rev => "4567")
+    #     #=> Overwrites an existing doc
     #
-    def purge(doc_revs, headers = {})
-      post("_purge", doc_revs, headers)
+    def copy(source, destination, options = {})
+      headers = options.delete(:headers) || {}
+      dest_rev = options.delete(:dest_rev)
+      slug = Cushion.escape_key(source)
+      dest = if dest_rev
+        "#{destination}?rev=#{dest_rev}"
+      else
+        destination
+      end
+      server.copy("#{@name}/#{slug}", dest, headers)
+    end
+
+    # Copies an attachment to a new location. This is presently experimental.
+    def copy_attachment(id, old_filename, new_filename, options = {})
+      headers = options.delete(:headers) || {}
+      src = fetch(id, old_filename)
+      headers[:content_type] = src.headers[:content_type]
+      dest_id = options[:dest_id] || id
+      opts = options[:dest_rev] ? { :rev => options[:dest_rev] } : {}
+      if opts.empty? && (id == dest_id)
+        opts = { :rev => src.headers[:etag] }
+      end
+      res = attach(dest_id, new_filename, src, { :headers => headers }.merge(opts))
+      if id == dest_id
+        res.merge("src_rev" => res["rev"])
+      else
+        res.merge("src_rev" => src.headers[:etag])
+      end
     end
 
-    # Copies the document identified by +source_id+ to a new or existing document
-    # at +destination_id+. Set the +dest_rev+ option to overwrite an existing doc.
-    # Set the +headers+ option to pass custom request headers.
+    # Moves the document at +source+ to a new or existing location at +destination+.
+    # Set the +dest_rev+ option to overwrite an existing document. Set the
+    # +headers+ option to pass custom request headers. Example:
     #
-    def copy_doc(source_id, dest_id, params = {})
-      headers = params.delete(:headers) || {}
-      dest_rev = params[:dest_rev]
-      slug = Cushion.escape_docid(source_id)
-      destination = if dest_rev
-        "#{dest_id}?rev=#{dest_rev}"
+    #   db.move("doc1", "doc2", :rev => "1234")
+    #     #=> Moves to a new location
+    #   db.copy("doc1", "doc3", :rev => "1234", :dest_rev => "4567")
+    #     #=> Overwrites an existing doc
+    #
+    def move(source, destination, options = {})
+      headers = options.delete(:headers) || {}
+      dest_rev = options.delete(:dest_rev)
+      slug = Cushion.escape_key(source)
+      path = Cushion.paramify_url("#{slug}", options)
+      dest = if dest_rev
+        "#{destination}?rev=#{dest_rev}"
       else
-        dest_id
+        destination
       end
-      copy("#{slug}", destination, headers)
+      server.move("#{@name}/#{path}", dest, headers)
     end
 
-    # Moves the document identified by +source_id+ and +src_rev+ to a new or
-    # existing document at +destination_id+. Set the +dest_rev+ option to
-    # overwrite an existing doc. Set the +headers+ option to pass custom
-    # request headers.
-    #
-    def move_doc(source_id, dest_id, src_rev, params = {})
-      headers = params.delete(:headers) || {}
-      dest_rev = params[:dest_rev]
-      slug = Cushion.escape_docid(source_id)
-      destination = if dest_rev
-        "#{dest_id}?rev=#{dest_rev}"
+    # Moves an attachment to a new location. This is presently experimental.
+    def move_attachment(id, old_filename, new_filename, options = {})
+      res = copy_attachment(id, old_filename, new_filename, options)
+      if res["ok"]
+        destroy(id, old_filename, :rev => res["src_rev"])
       else
-        dest_id
+        res
       end
-      move("#{slug}?rev=#{src_rev}", destination, headers)
     end
+    alias_method :rename_attachment, :move_attachment
 
-    # Supply +funcs+ to create a temporary view and run a query against it. Set
-    # the +keys+ option to perform a key-based multi-document fetch against the
-    # temp view. Example:
+    # Query a named view. Set +name+ to :all to query CouchDB's all_docs view.
+    # Set +name+ to :temp to query a temp_view. Set the +keys+ option to perform
+    # a key-based multi-document fetch against any view. Examples
     #
     #   temp_view = { :map => "function(doc){emit(doc.status,null)}" }
-    #   db.temp_view(temp_view, :key => "verified")
+    #   db.view(:temp, :funcs => temp_view, :key => "verified")
+    #   db.view("people/by_first_name", :key => "gomer")
+    #   db.view("foo/bar", :keys => ["a", "b", "c"])
+    #   db.view(:all)
     #
-    # Set the +headers+ option to pass custom request headers.
+    # Set the +headers+ option to pass custom request headers. Set
+    # <code>:etag => some_value</code> to perform a simple if-none-match
+    # conditional GET.
     #
     # Temp view queries are slow, so they should only be used as a convenience
-    # during development.
-    #
-    def temp_view(funcs, params = {})
-      keys = params.delete(:keys)
-      headers = params.delete(:headers) || {}
-      funcs = funcs.merge({:keys => keys}) if keys
-      path = Cushion.paramify_url("_temp_view", params)
-      post(path, funcs, headers)
-    end
-
-    # Query a saved view identified by +view+. Set the +keys+ param to perform a
-    # key-based multi-document fetch. Example:
+    # during development. Whenever possible you should query against saved
+    # views.
     #
-    #   db.view("people/by_first_name", :key => "gomer")
-    #
-    # Set the +headers+ option to pass custom request headers.
-    #
-    def view(view, params = {})
-      keys = params.delete(:keys)
-      headers = params.delete(:headers) || {}
-      path = Cushion.paramify_url("_view/#{view}", params)
-      if keys
-        post(path, {:keys => keys}, headers)
+    def view(name, options = {})
+      keys = options.delete(:keys)
+      headers = options.delete(:headers) || {}
+      if etag = options.delete(:etag)
+        headers.merge!(:if_none_match => "\"#{etag}\"".squeeze("\""))
+      end
+      body = keys ? {:keys => keys} : {}
+      if name == :all
+        slug = "_all_docs"
+      elsif name == :temp
+        slug = "_temp_view"
+        body.merge!(options.delete(:funcs))
+      else
+        slug = "_view/#{name}"
+      end
+      path = Cushion.paramify_url(slug, options)
+
+      if body.any?
+        post(path, body, headers)
       else
         get(path, headers)
       end
     end
 
+    # Convenience method for querying the all_docs view. See #view for more
+    # information.
+    def all(options = {})
+      view(:all, options)
+    end
+
+    # Convenience method for querying temporary views. See #view for more
+    # information.
+    def temp(funcs, options = {})
+      view(:temp, options.merge(:funcs => funcs))
+    end
+
     # Query the show template identified by +design+, +show_template+ and +id+.
     # The results are not parsed by default. Set the +headers+ option to pass
     # custom request headers.
     #
-    def show(design, show_template, id, params = {})
+    def show(design, show_template, id, options = {})
       defaults = { :accept => "text/html;text/plain;*/*" }
-      headers = params.delete(:headers) || {}
-      slug = Cushion.escape_docid(id)
-      path = Cushion.paramify_url("_show/#{design}/#{show_template}/#{slug}", params)
+      headers = options.delete(:headers) || {}
+      slug = Cushion.escape_key(id)
+      path = Cushion.paramify_url("_show/#{design}/#{show_template}/#{slug}", options)
       get(path, defaults.merge(headers))
     end
 
@@ -245,65 +347,66 @@ module Cushion
     # The results are not parsed by default. Set the +headers+ option to pass
     # custom request headers.
     #
-    def list(design, list_template, view, params = {})
+    def list(design, list_template, view, options = {})
       defaults = { :accept => "text/html;text/plain;*/*" }
-      headers = params.delete(:headers) || {}
-      path = Cushion.paramify_url("_list/#{design}/#{list_template}/#{view}", params)
+      headers = options.delete(:headers) || {}
+      path = Cushion.paramify_url("_list/#{design}/#{list_template}/#{view}", options)
       get(path, defaults.merge(headers))
     end
 
-    # Issues a request to the CouchDB external server identified by +process+.
-    # Calls to external must include a request +verb+. Set the +headers+ option
-    # to pass custom request headers.
-    #
-    def external(verb, process_path, params = {})
-      path = Cushion.paramify_url("_#{process_path}", params[:query])
-      request(verb, path, :body => params[:body], :headers => params[:headers])
+    # Retrieves information about this database.
+    def info(headers = {})
+      server.get(@name, headers)
     end
 
-    # Uses open-uri to open the attachment identified by +id+ and +filename+.
-    # Returns a Tempfile.
-    #
-    def open_attachment(id, filename, params = {})
-      slug = Cushion.escape_docid(id)
-      fname = CGI.escape(filename)
-      path = Cushion.paramify_url("#{@name}/#{slug}/#{fname}", params)
-      server.open_attachment(path)
+    # Compacts this database.
+    def compact(headers = {})
+      post("_compact", nil, headers)
     end
 
-    # Saves an attachment under the document identified by +id+ and +rev+ with
-    # the supplied +filename+ and +data+. Content type defaults to
-    # 'application/octet-stream'. Change it by passing <code>:content_type => "foo/bar"</code>
-    # as the last param.
-    #
-    def save_attachment(id, rev, filename, data, headers = {})
-      defaults = { :content_type => "application/octet-stream" }
-      slug = Cushion.escape_docid(id)
-      fname = CGI.escape(filename)
-      put("#{slug}/#{fname}?rev=#{rev}", data, defaults.merge(headers))
+    # Creates this database on the server.
+    def create(headers = {})
+      server.put(@name, nil, headers)
     end
 
-    # Deletes an attachment under the document identified by +id+ and +rev+ with
-    # the supplied +filename+.
+    # Deletes this database from the server.
+    def drop(headers = {})
+      server.delete(@name, headers)
+    end
+
+    # Deletes and recreates this database.
+    def recreate
+      begin
+        drop
+      rescue RestClient::ResourceNotFound
+        nil
+      end
+      create
+    end
+
+    # Completely purges the supplied document revisions from the database.
+    # +doc_revs+ is a hash of document ids, each containing an array of revisions
+    # to be deleted. Example:
+    #
+    #   doc_revs = {
+    #     "1" => ["12345", "42836"],
+    #     "2" => ["572654"],
+    #     "3" => ["34462"]
+    #   }
     #
-    def delete_attachment(id, rev, filename, headers = {})
-      slug = Cushion.escape_docid(id)
-      fname = CGI.escape(filename)
-      delete("#{slug}/#{fname}?rev=#{rev}", headers)
+    #  db.purge(doc_revs)
+    #
+    def purge(doc_revs, options = {})
+      post("_purge", doc_revs, options)
     end
 
-    # Renames an attachment under the document identified by +id+ and +rev+.
-    # +oldname+ is the name of the existing attachment and +newname+ is the
-    # desired name.
+    # Issues a request to the CouchDB external server identified by +process+.
+    # Calls to external must include a request +verb+. Set the +headers+ option
+    # to pass custom request headers.
     #
-    def rename_attachment(id, rev, oldname, newname)
-      temp = open_attachment(id, oldname)
-      res = save_attachment(id, rev, newname, temp.read, :content_type => temp.content_type)
-      if res["ok"] == true
-        res = delete_attachment(id, res["rev"], oldname)
-      else
-        res
-      end
+    def external(verb, process_path, params = {})
+      path = Cushion.paramify_url("_#{process_path}", params[:query])
+      request(verb, path, :body => params[:body], :headers => params[:headers])
     end
 
     # Issues a HEAD request to this database. See Cushion::Server#head.
@@ -331,22 +434,10 @@ module Cushion
       server.delete("#{@name}/#{path}", headers)
     end
 
-    # Issues a COPY request to this database. See Cushion::Server#copy.
-    def copy(source, destination, headers = {})
-      server.copy("#{@name}/#{source}", destination, headers)
-    end
-
-    # Issues a MOVE request to this database. See Cushion::Server#move.
-    def move(source, destination, headers = {})
-      server.move("#{@name}/#{source}", destination, headers)
-    end
-
     # Issues a generic request to this database. See Cushion::Server#request.
     def request(verb, path, params)
       server.request(verb, "#{@name}/#{path}", params)
     end
 
-    ## EXPERIMENTAL ##
-
   end
 end