couch-client 0.0.1

data/CHANGELOG

@@ -0,0 +1 @@
+v0.0.1. first release

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2010 Robert Sosinski (http://www.robertsosinski.com)
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/Manifest

@@ -0,0 +1,33 @@
+CHANGELOG
+LICENSE
+Manifest
+README.markdown
+Rakefile
+TODO
+lib/couch-client.rb
+lib/couch-client/attachment.rb
+lib/couch-client/attachment_list.rb
+lib/couch-client/collection.rb
+lib/couch-client/connection.rb
+lib/couch-client/connection_handler.rb
+lib/couch-client/consistent_hash.rb
+lib/couch-client/database.rb
+lib/couch-client/design.rb
+lib/couch-client/document.rb
+lib/couch-client/hookup.rb
+lib/couch-client/row.rb
+spec/attachment_list_spec.rb
+spec/attachment_spec.rb
+spec/collection_spec.rb
+spec/conection_handler_spec.rb
+spec/connection_spec.rb
+spec/consistent_hash_spec.rb
+spec/couch-client_spec.rb
+spec/database_spec.rb
+spec/design_spec.rb
+spec/document_spec.rb
+spec/files/image.png
+spec/files/plain.txt
+spec/hookup_spec.rb
+spec/row_spec.rb
+spec/spec_helper.rb

data/README.markdown

@@ -0,0 +1,176 @@
+Introduction
+============
+
+CouchClient is Ruby library that can be used to interact with CouchDB.  The goal of CouchClient is to make documents feel as much as possible as what they already represent, a Hash of primitives, Arrays and other Hashes.  As such, the interface for documents closely represents that of Hash and Array, but also includes additional methods and state in order to manage documents and interface with the CouchDB Server.
+
+Installation
+------------
+
+    gem install couch-client
+    
+    # In your ruby application
+    require 'couch-client'
+
+Connecting to CouchDB
+---------------------
+    
+    # Using hash syntax
+    Couch = CouchClient::Conection.new({
+      :scheme   => "http",
+      :host     => "localhost",
+      :port     => 5984,
+      :database => "sandbox",
+      :username => "admin",
+      :password => "nimda"
+    })
+    
+    # Using block syntax
+    Couch = CouchClient::Connection.new do |c| 
+      c.scheme   = "http"
+      c.host     = "localhost"
+      c.port     = 5984
+      c.database = "sandbox"
+      c.username = "admin"
+      c.password = "nimda"
+    end
+    
+    # Using both hash and block syntax
+    # NOTE: Hash parameters take precedence over block parameters
+    Couch = CouchClient::Connection.new(:username => "admin", :password => "nidma") do |c| 
+      c.scheme   = "http"
+      c.host     = "localhost"
+      c.port     = 5984
+      c.database = "sandbox"
+    end
+
+Fetching a Document
+-------------------
+    
+    # Using Hash syntax
+    person = Couch["a3b556796203eab59c31fa21b00043e3"]
+    
+    # You can also pass options if desired
+    person = Couch["a3b556796203eab59c31fa21b00043e3", :include_docs => true]
+
+Getting a Document's id, rev and attachments
+--------------------------------------------
+    # A document's id
+    person.id # => "a3b556796203eab59c31fa21b00043e3"
+
+    # A document's rev
+    person.rev # => "1-6665e6330ba75e757ce1f6d793305d67"
+
+    # A document's attachments
+    # NOTE: This will be an CouchClient::AttachmentList, and attachments will be CouchClient::Attachment objects
+    person.attachments # => {"plain.txt"=>{"content_type"=>"text/plain", "revpos"=>2, "length"=>406, "stub"=>true}}
+    
+
+Working with a Document
+-----------------------
+
+    # Building new documents
+    # Couch.build({:name => "alice"})
+
+    # Getting and setting fields (with indifferent access and value "stringification")
+    # person[:name] # => "alice"
+    # person[:city] = :nyc
+    # person["city"] # => "nyc"
+
+    # Fetching the same document on the server
+    person.saved_doc # => {"_id" => "7f22af967b04d1b88212d3d26b017ff6", "_rev" => "1-f867d6b9aa0a5c31d647d57110fa7d36", "name" => "alice"}
+
+    # Saving a document
+    person.save # => true
+    person.rev # => "2-1734c07abaf18db573706bc1db59e09d"
+
+    # Deleting a field
+    person.delete(:city) # => true
+    person[:city] # => nil
+
+    # Attaching a file (documents must be refreshed for attachments to be available)
+    person.attach("plain.txt", "Hello World", "plain/text") # => true
+    person = person.saved_doc
+    person.attachments # => {"plain.txt"=>{"content_type"=>"text/plain", "revpos"=>2, "length"=>406, "stub"=>true}}
+
+    # Getting attached files
+    attachment = person.attachments["plain.txt"]
+    attachment.uri # => http://localhost:5984/sandbox/7f22af967b04d1b88212d3d26b017ff6/plain.txt
+    attachment.path # => /sandbox/7f22af967b04d1b88212d3d26b017ff6/plain.txt
+    attachment.data # => "Hello World"
+
+    # Deleting a document
+    person.delete!
+    person.deleted? # => true
+
+    # Identifying a design document
+    person.design? # => false
+    c["_design/people"].design? # => true
+
+    # Identifying errors and conflicts
+    person.error # => {"conflict"=>"Document update conflict."}
+    person.error? # => true
+    person.conflict? # => true
+    person.invalid? # => false
+
+Working with Collections
+------------------------
+
+    # Getting all documents
+    Couch.all_docs # => [{"id"=>"7f22af967b04d1b88212d3d26b017ff6", "key"=>"7f22af967b04d1b88212d3d26b017ff6", "value"=>{"rev"=>"1-f867d6b9aa0a5c31d647d57110fa7d36"}},
+                   #     {"id"=>"7f22af967b04d1b88212d3d26b018e89", "key"=>"7f22af967b04d1b88212d3d26b018e89", "value"=>{"rev"=>"3-3a635c1a2b5a8ff94bb5d63eee3cd6ef"}}]
+    
+    # Getting all documents with document fields
+    Couch.all_docs(:include_docs => true)
+
+    # Specifying a `key`, `start_key` or `end_key`
+    couch.all_docs(:key => "7f22af967b04d1b88212d3d26b018e89")
+    couch.all_docs(:start_key => 200)
+    couch.all_docs(:end_key => [2010, 01, 01])
+
+    # Getting additional collection information
+    Couch.all_docs.info # => {"total_rows" => 2, "offset" => 0}
+
+Using Design Documents
+----------------------
+
+    # Map Views
+    Couch.design(:people).view(:all) # => [{"id"=>"7f22af967b04d1b88212d3d26b017ff6", "key"=>"7f22af967b04d1b88212d3d26b017ff6", "value"=>{"name" => "alice"}},
+                                     #     {"id"=>"7f22af967b04d1b88212d3d26b018e89", "key"=>"7f22af967b04d1b88212d3d26b018e89", "value"=>{"name" => "bob"}}]
+
+    # MapReduce Views
+    Couch.design(:people).view(:sum) # => [{"key" => "male", "value" => 1}, {"key" => "female", "value" => 1}]
+
+Using FullText Searching (Must Have CouchDB-Lucene Installed)
+-------------------------------------------------------------
+
+    # Getting search results
+    Couch.design(:people).fulltext(:by_name, :q => "alice") # => [{"id"=>"a6c92090bbee241e892be1ac4464b9d9", "score"=>4.505526065826416, "fields"=>{"default"=>"alice"}}]
+
+    # Getting additional search results information
+    Couch.design(:people).fulltext(:by_name, :q => "alice").info # => {"q"=>"default:alice", "etag"=>"11e1541e20d9b860", "skip"=>0, "limit"=>25, 
+                                                                 #     "total_rows"=>7, "search_duration"=>0, "fetch_duration"=>1}
+
+    # Getting search index information
+    Couch.design(:people).fulltext(:by_name) # => {"current"=>true, "disk_size"=>3759, "doc_count"=>25, "doc_del_count"=>3, "fields"=>["default"], 
+                                             #     "last_modified"=>"1288403429000", "optimized"=>false, "ref_count"=>2}
+
+Database Administration
+-----------------------
+
+    # Create a database
+    Couch.database.create
+
+    # See if a database exists
+    Couch.database.exists
+
+    # Get database stats
+    Couch.database.stats
+
+    # Compact the database
+    Couch.database.compact!
+
+    # Delete the database
+    Couch.databse.delete!
+
+
+

data/Rakefile

@@ -0,0 +1,17 @@
+require 'rake'
+require 'rspec/core/rake_task'
+require 'echoe'
+
+desc  "Run all specs"
+RSpec::Core::RakeTask.new do |t|
+  t.rspec_opts = %w[--colour --format progress]
+end
+
+Echoe.new("couch-client") do |p|
+  p.author = "Robert Sosinski"
+  p.email = "email@robertsosinski.com"
+  p.url = "http://github.com/robertsosinski/couch-client"
+  p.description = "CouchClient is Ruby library that can be used to interact with CouchDB"
+  p.summary = "The goal of CouchClient is to make documents feel as much as possible as what they already represent, a Hash of primitives, Arrays and other Hashes."
+  p.runtime_dependencies = ["json"]
+end

data/TODO

@@ -0,0 +1,11 @@
+Need
+* design save rake task
+
+Next
+* batch insert
+* batch update
+* batch delete
+* batch upload
+* show design
+* list design
+* replication

data/couch-client.gemspec

@@ -0,0 +1,33 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{couch-client}
+  s.version = "0.0.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Robert Sosinski"]
+  s.date = %q{2010-10-29}
+  s.description = %q{CouchClient is Ruby library that can be used to interact with CouchDB}
+  s.email = %q{email@robertsosinski.com}
+  s.extra_rdoc_files = ["CHANGELOG", "LICENSE", "README.markdown", "TODO", "lib/couch-client.rb", "lib/couch-client/attachment.rb", "lib/couch-client/attachment_list.rb", "lib/couch-client/collection.rb", "lib/couch-client/connection.rb", "lib/couch-client/connection_handler.rb", "lib/couch-client/consistent_hash.rb", "lib/couch-client/database.rb", "lib/couch-client/design.rb", "lib/couch-client/document.rb", "lib/couch-client/hookup.rb", "lib/couch-client/row.rb"]
+  s.files = ["CHANGELOG", "LICENSE", "Manifest", "README.markdown", "Rakefile", "TODO", "lib/couch-client.rb", "lib/couch-client/attachment.rb", "lib/couch-client/attachment_list.rb", "lib/couch-client/collection.rb", "lib/couch-client/connection.rb", "lib/couch-client/connection_handler.rb", "lib/couch-client/consistent_hash.rb", "lib/couch-client/database.rb", "lib/couch-client/design.rb", "lib/couch-client/document.rb", "lib/couch-client/hookup.rb", "lib/couch-client/row.rb", "spec/attachment_list_spec.rb", "spec/attachment_spec.rb", "spec/collection_spec.rb", "spec/conection_handler_spec.rb", "spec/connection_spec.rb", "spec/consistent_hash_spec.rb", "spec/couch-client_spec.rb", "spec/database_spec.rb", "spec/design_spec.rb", "spec/document_spec.rb", "spec/files/image.png", "spec/files/plain.txt", "spec/hookup_spec.rb", "spec/row_spec.rb", "spec/spec_helper.rb", "couch-client.gemspec"]
+  s.homepage = %q{http://github.com/robertsosinski/couch-client}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Couch-client", "--main", "README.markdown"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{couch-client}
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{The goal of CouchClient is to make documents feel as much as possible as what they already represent, a Hash of primitives, Arrays and other Hashes.}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<json>, [">= 0"])
+    else
+      s.add_dependency(%q<json>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<json>, [">= 0"])
+  end
+end

data/lib/couch-client.rb

@@ -0,0 +1,50 @@
+$:.unshift(File.dirname(File.expand_path(__FILE__)))
+
+# require '../core_ext/hash'
+
+require 'couch-client/consistent_hash'
+require 'couch-client/connection'
+require 'couch-client/connection_handler'
+require 'couch-client/hookup'
+require 'couch-client/database'
+require 'couch-client/document'
+require 'couch-client/attachment_list'
+require 'couch-client/attachment'
+require 'couch-client/design'
+require 'couch-client/collection'
+require 'couch-client/row'
+
+# The CouchClient module is the overall container of all CouchClient logic.
+module CouchClient
+  VERSION = "0.0.1"
+  
+  class Error < Exception; end
+  
+  # Start using CouchClient by constructing a new CouchClient::Connection object with a Hash:
+  #
+  #   CouchClient.connect(:database => "db_name")
+  #
+  # with a block:
+  #
+  #   CouchClient.connect do |c|
+  #     c.database = "db_name"
+  #   end
+  #
+  # or with both:
+  #
+  #   CouchClient.connect(:username => "user", :password => "pass") do |c|
+  #     c.database = "db_name"
+  #   end
+  #
+  # CouchClient.connect takes the following options.
+  #
+  #  scheme: Protocol used (e.g. http or https), default being "http".
+  #  username: Username used by HTTP Basic authentication.
+  #  password: Password used by HTTP Basic authentication.
+  #  host: The domain for your CouchDB erver, default being "localhost".
+  #  port: The port for your CouchDB server, default being 5984.
+  #  database: The database you wish to connect to.
+  def self.connect(args = {}, &block)
+    Connection.new(args, &block)
+  end
+end

data/lib/couch-client/attachment.rb

@@ -0,0 +1,32 @@
+module CouchClient
+  # The Attachment is an extended Hash that provides additional methods to
+  # interact with attached files saved within a document.
+  class Attachment < ConsistentHash
+    attr_reader :name
+
+    # Attachment is constructed the id of the document it is attached to,
+    # the filename, file stub and connection object.
+    def initialize(id, name, stub, connection)
+      self.merge!(stub)
+
+      @id = id
+      @name = name
+      @connection = connection
+    end
+    
+    # Returns the path for the attachment
+    def path
+      @connection.hookup.handler.path([@id, @name])
+    end
+
+    # Returns the uri for the attachment
+    def uri
+      @connection.hookup.handler.uri([@id, @name])
+    end
+
+    # Returns a string that contains file data
+    def data
+      @connection.hookup.get([@id, @name], nil, self["content_type"]).last
+    end
+  end
+end

data/lib/couch-client/attachment_list.rb

@@ -0,0 +1,10 @@
+module CouchClient
+  # The AttachmentList prevents ConsistentHash from absorbing
+  # instances of Attachment and making them a ConsistentHash.
+  class AttachmentList < ConsistentHash
+    # AttachmentList is constructed with a hash of attachments.
+    def initialize(attachments)
+      self.merge!(attachments)
+    end
+  end
+end

data/lib/couch-client/collection.rb

@@ -0,0 +1,20 @@
+module CouchClient
+  # The Document is an extended Array that provides additional methods
+  # and state to get status codes, info and connect documents to the server.
+  class Collection < Array
+    attr_reader :code, :info
+    
+    # Collection is constructed with a status code, response body,
+    # and connection object.
+    def initialize(code, body, connection)
+      # Iterate over each row to set them a CouchClient::Row object.
+      body.delete("rows").each.with_index do |row, idx|
+        self[idx] = Row.new(code, row, connection)
+      end
+
+      @code = code
+      @info = body
+      @connection = connection
+    end
+  end
+end

data/lib/couch-client/connection.rb

@@ -0,0 +1,104 @@
+module CouchClient
+  class DatabaseNotGiven < Exception; end
+  class DocumentNotValid < Exception; end
+  class DocumentNotFound < Exception; end
+
+  # The Connection is the high-level interface used to interact with the CouchDB Server.
+  class Connection
+    attr_reader :hookup, :database
+
+    # Connection is constructed with a Hash or with a block specifying connection parameters.
+    # An error will be raised if a database is not specified.
+    def initialize(args = {})
+      handler = ConnectionHandler.new
+      
+      # Set ConnectionHandler settings via a block
+      if block_given?
+        yield(handler)
+      end
+      
+      # Set remaining ConnectionHandler settings via a Hash
+      args.each_pair do |key, value|
+        handler.send("#{key}=", value)
+      end
+      
+      # Ensure a database is provided
+      unless handler.database
+        raise DatabaseNotGiven.new("specify a database to connect to")
+      end
+      
+      # `@hookup` is used as the HTTP interface and `@database` is a namespace for all
+      # database specific commands such as creation, deletion, compaction and replication.
+      @hookup = Hookup.new(handler)
+      @database = Database.new(self)
+    end
+
+    # Fetches documents from the CouchDB server. Although `[]` makes get requests and therefore
+    # could fetch design views and more, anything received that is not a valid document will
+    # raise an error.  As such, fetching designs can only be done through the `design` method.
+    def [](id, options = {})
+      code, body = @hookup.get([id], options)
+
+      case code
+      # If something was found
+      when 200
+        # And that something is a document
+        if body["_id"] && body["_rev"]
+          # Make a new document object
+          Document.new(code, body, self)
+        else
+          # Else raise an error as `[]` should only return document objects
+          raise DocumentNotValid.new("the id '#{id}' does not correspond to a document")
+        end
+      # If nothing was found
+      when 404
+        case body["reason"]
+        # Because the document was deleted
+        when "deleted"
+          # Tell the user it was deleted
+          raise DocumentNotFound.new("the document with id '#{id}' has been deleted")
+        else
+          # Else tell the user it was never there to begin with
+          raise DocumentNotFound.new("a document could not be found with id '#{id}'")
+        end
+      # If something else happened
+      else
+        # Raise an error
+        raise Error.new("code: #{code}, error: #{body["error"]}, reason: #{body["reason"]}")
+      end
+    end
+
+    # Constructs a new design factory that manages `views`, `shows`, `lists` and `fulltext` searches.
+    def design(id)
+      Design.new(id, self)
+    end
+    
+    # Acts as the interface to CouchDB's `_all_docs` map view.
+    def all_docs(options = {})
+      # key, startkey and endkey must be JSON encoded
+      ["key", "startkey", "endkey"].each do |key|
+        options[key] &&= options[key].to_json
+      end
+      
+      # Create a new Collection with the response code, body and connection.
+      Collection.new(*@hookup.get(["_all_docs"], options), self)
+    end
+    
+    # The interface used to construct new CouchDB documents.  Once constructed
+    # these documents can be saved, updated, validated and deleted.
+    def build(body = {})
+      Document.new(nil, body, self)
+    end
+
+    def inspect
+      head = "#<#{self.class}: "
+      body = []
+      body << "username: #{@hookup.handler.username}" if @hookup.handler.username
+      body << "password: #{@hookup.handler.password}" if @hookup.handler.password
+      body << "uri: #{@hookup.handler.uri}"
+      tail = ">"
+
+      head + body.join(", ") + tail
+    end
+  end
+end