= CouchObject

CouchObject is a set of classes to help you talk to CouchDb (http://couchdbwiki.com/) with Ruby.

* Author: Johan Sørensen
* Contact: johan (at) johansorensen DOT com
* Home: http://rubyforge.org/projects/couchobject/
* Source (Git): http://repo.or.cz/w/couchobject.git
 
== Creating, opening and deleting databases

CouchObject::Database is the first interaction point to your CouchDb. Creating a CouchDb database:

	>> CouchObject::Database.create!("http://localhost:8888", "mydb")
	=> {"ok"=>true}
	>> CouchObject::Database.all_databases("http://localhost:8888")
	=> ["couchobject", "couchobject_test", "foo", "mydb"]
	>> db = CouchObject::Database.open("http://localhost:8888/mydb")
	=> #<CouchObject::Database:0x642fa8 @server=#<CouchObject::Server:0x642ef4 @connection=#<Net::HTTP localhost:8888 open=false>, @port=8888, @uri=#<URI::HTTP:0x321612 URL:http://localhost:8888>, @host="localhost">, @uri="http://localhost:8888", @dbname="mydb">
	>> db.name
	=> "mydb"
	>> CouchObject::Database.delete!("http://localhost:8888", "mydb")
	=> {"ok"=>true}
	>> CouchObject::Database.all_databases("http://localhost:8888").include?("mydb")
	=> false
		
=== Interacting with the database

	>> db.get("_all_docs")
	=> #<CouchObject::Response:0x14ed364 @response=#<Net::HTTPOK 200 OK readbody=true>, @parsed_body={"rows"=>[], "view"=>"_all_docs"}>
		
Issueing CouchObject::Database#get, CouchObject::Database#post, CouchObject::Database#put and CouchObject::Database#delete requests will return a CouchObject::Response object
		
	>> db.get("_all_docs").body
	=> "{\"view\":\"_all_docs\", \"rows\":[\n\n]}"
	>> db.get("_all_docs").parsed_body
	=> {"rows"=>[], "view"=>"_all_docs"}
	>> db.post("", JSON.unparse({"foo" => "bar"}))
	=> #<CouchObject::Response:0x14d7780 @response=#<Net::HTTPCreated 201 Created readbody=true>, @parsed_body={"_rev"=>-992681820, "_id"=>"1206189E4496409DAD3818D241F5478F", "ok"=>true}>
	>> db.get("_all_docs").parsed_body
	=> {"rows"=>[{"_rev"=>-992681820, "_id"=>"1206189E4496409DAD3818D241F5478F"}], "view"=>"_all_docs"}
	>> db.get("1206189E4496409DAD3818D241F5478F").parsed_body
	=> {"_rev"=>-992681820, "_id"=>"1206189E4496409DAD3818D241F5478F", "foo"=>"bar"}
	>> db.delete("1206189E4496409DAD3818D241F5478F").parsed_body
	=> {"_rev"=>548318611, "ok"=>true}
	>> db.get("_all_docs").parsed_body
	=> {"rows"=>[], "view"=>"_all_docs"}
		
== The Document object

CouchObject::Document wraps a few things in a nice api. In particular you can use it if you don't want to deal with hashes all the time (similar to ActiveRecord and so on):

	>> doc = CouchObject::Document.new({ "foo" => [1,2], "bar" => true  })
	=> #<CouchObject::Document:0x14a7224 @id=nil, @attributes={"foo"=>[1, 2], "bar"=>true}, @revision=nil>
	>> doc["foo"]
	=> [1, 2]
	>> doc.foo
	=> [1, 2]
	>> doc.bar
	=> true
	>> doc.bar?
	=> true
		
You can also save a document to the database:

	>> doc.new?
	=> true
	>> doc.save(db)
	=> #<CouchObject::Response:0x149f358 @response=#<Net::HTTPCreated 201 Created readbody=true>, @parsed_body={"_rev"=>2030456697, "_id"=>"CAEADDC895AC4D506542A3796CCA355D", "ok"=>true}>
	>> doc.id
	=> "CAEADDC895AC4D506542A3796CCA355D"
		
Since CouchObject::Database#get returns a CouchObject::Response object we can convert it into a Document instance easily with CouchObject::Database#to_document:

	>> response = db.get(doc.id)
	=> #<CouchObject::Response:0x1498b98 @response=#<Net::HTTPOK 200 OK readbody=true>, @parsed_body={"_rev"=>2030456697, "_id"=>"CAEADDC895AC4D506542A3796CCA355D", "foo"=>[1, 2], "bar"=>true}>
	>> the_doc_we_just_saved = response.to_document
	=> #<CouchObject::Document:0x148415c @id="CAEADDC895AC4D506542A3796CCA355D", @attributes={"foo"=>[1, 2], "bar"=>true}, @revision=2030456697>
	>> the_doc_we_just_saved.foo
	=> [1, 2]
	>> doc.foo = "quux"
	=> "quux"
	>> doc.save(db)
	=> #<CouchObject::Response:0x4b0adc @response=#<Net::HTTPCreated 201 Created readbody=true>, @parsed_body={"_rev"=>1670064786, "_id"=>"B4077269D2DF8433D145DC0702B9791C", "ok"=>true}>


== CouchObject::Persistable

It all started with this module, it maps ruby objects to CouchDb documents, using two mapping methods. It's highly experimental and may go away n future releases

    gem "couchobject"
    require "couch_object"
    class Bike
      include CouchObject::Persistable

      def initialize(wheels)
        @wheels = wheels
      end
      attr_accessor :wheels

      def to_couch
        {:wheels => @wheels}
      end

      def self.from_couch(attributes)
        new(attributes["wheels"])
      end
    end

By including the CouchObject::Persistable and defining two methods on our class we specify how we should serialize and deserialize our object to and from a CouchDb:

    >> bike_4wd = Bike.new(4)
    => #<Bike:0x6a0a68 @wheels=4>
    >> bike_4wd.save("http://localhost:8888/couchobject")
    => {"_rev"=>1745167971, "_id"=>"6FA2AFB623A93E0E77DEAAF59BB02565", "ok"=>true}
    >> bike = Bike.get_by_id("http://localhost:8888/couchobject", bike_4wd.id)
    => #<Bike:0x64846c @wheels=4>