README.txt

   1 = CouchObject
   2
   3 CouchObject is a set of classes to help you talk to CouchDb (http://couchdbwiki.com/) with Ruby.
   4
   5 * Author: Johan Sørensen
   6 * Contact: johan (at) johansorensen DOT com
   7 * Home: http://rubyforge.org/projects/couchobject/
   8 * Source (Git): http://repo.or.cz/w/couchobject.git
   9
  10 == Creating, opening and deleting databases
  11
  12 CouchObject::Database is the first interaction point to your CouchDb. Creating a CouchDb database:
  13
  14         >> CouchObject::Database.create!("http://localhost:8888", "mydb")
  15         => {"ok"=>true}
  16         >> CouchObject::Database.all_databases("http://localhost:8888")
  17         => ["couchobject", "couchobject_test", "foo", "mydb"]
  18         >> db = CouchObject::Database.open("http://localhost:8888/mydb")
  19         => #<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">
  20         >> db.name
  21         => "mydb"
  22         >> CouchObject::Database.delete!("http://localhost:8888", "mydb")
  23         => {"ok"=>true}
  24         >> CouchObject::Database.all_databases("http://localhost:8888").include?("mydb")
  25         => false
  26
  27 === Interacting with the database
  28
  29         >> db.get("_all_docs")
  30         => #<CouchObject::Response:0x14ed364 @response=#<Net::HTTPOK 200 OK readbody=true>, @parsed_body={"rows"=>[], "view"=>"_all_docs"}>
  31
  32 Issueing CouchObject::Database#get, CouchObject::Database#post, CouchObject::Database#put and CouchObject::Database#delete requests will return a CouchObject::Response object
  33
  34         >> db.get("_all_docs").body
  35         => "{\"view\":\"_all_docs\", \"rows\":[\n\n]}"
  36         >> db.get("_all_docs").parsed_body
  37         => {"rows"=>[], "view"=>"_all_docs"}
  38         >> db.post("", JSON.unparse({"foo" => "bar"}))
  39         => #<CouchObject::Response:0x14d7780 @response=#<Net::HTTPCreated 201 Created readbody=true>, @parsed_body={"_rev"=>-992681820, "_id"=>"1206189E4496409DAD3818D241F5478F", "ok"=>true}>
  40         >> db.get("_all_docs").parsed_body
  41         => {"rows"=>[{"_rev"=>-992681820, "_id"=>"1206189E4496409DAD3818D241F5478F"}], "view"=>"_all_docs"}
  42         >> db.get("1206189E4496409DAD3818D241F5478F").parsed_body
  43         => {"_rev"=>-992681820, "_id"=>"1206189E4496409DAD3818D241F5478F", "foo"=>"bar"}
  44         >> db.delete("1206189E4496409DAD3818D241F5478F").parsed_body
  45         => {"_rev"=>548318611, "ok"=>true}
  46         >> db.get("_all_docs").parsed_body
  47         => {"rows"=>[], "view"=>"_all_docs"}
  48
  49 == The Couch View Requestor
  50
  51 couch_ruby_view_requestor is a JsServer client for CouchDb, allowing you to query documents with Ruby instead of Javascript! All you need to do is pass in a string with something that reponds to #call with one argument (the document):
  52
  53   >> db.post("_temp_view", "proc { |doc| doc[\"foo\"] =~ /ba/ }").parsed_body["rows"]
  54   => [{"_rev"=>928806717, "_id"=>"28D568C5992CBD2B4711F57225A19517", "value"=>0}, {"_rev"=>-1696868121, "_id"=>"601D858DB2E298EFC4BBA92A11760D1E", "value"=>0}, {"_rev"=>-2093091288, "_id"=>"CABCEB3F2C8B70B3FE24A03FF6AB7A1E", "value"=>0}]
  55   >> pp db.post("_temp_view", "proc { |doc| doc[\"foo\"] =~ /ba/ }").parsed_body["rows"]
  56   [{"_rev"=>928806717, "_id"=>"28D568C5992CBD2B4711F57225A19517", "value"=>0},
  57    {"_rev"=>-1696868121, "_id"=>"601D858DB2E298EFC4BBA92A11760D1E", "value"=>0},
  58    {"_rev"=>-2093091288, "_id"=>"CABCEB3F2C8B70B3FE24A03FF6AB7A1E", "value"=>0}]
  59
  60 But you can even do it in plain Ruby, as opposed to a string, with Database#filter:
  61
  62   >> db.filter do |doc|
  63   ?>    if doc["foo"] == "bar"
  64   >>      return doc
  65   >>    end
  66   >> end
  67   => [{"_rev"=>-1696868121, "_id"=>"601D858DB2E298EFC4BBA92A11760D1E", "value"=>{"_id"=>"601D858DB2E298EFC4BBA92A11760D1E", "_rev"=>-1696868121, "foo"=>"bar"}}, {"_rev"=>-2093091288, "_id"=>"CABCEB3F2C8B70B3FE24A03FF6AB7A1E", "value"=>{"_id"=>"CABCEB3F2C8B70B3FE24A03FF6AB7A1E", "_rev"=>-2093091288, "foo"=>"bar"}}]
  68
  69 It requires that you set JsServer in your couch.ini to the path of the couch_ruby_view_requestor executable
  70
  71 == The Document object
  72
  73 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):
  74
  75         >> doc = CouchObject::Document.new({ "foo" => [1,2], "bar" => true  })
  76         => #<CouchObject::Document:0x14a7224 @id=nil, @attributes={"foo"=>[1, 2], "bar"=>true}, @revision=nil>
  77         >> doc["foo"]
  78         => [1, 2]
  79         >> doc.foo
  80         => [1, 2]
  81         >> doc.bar
  82         => true
  83         >> doc.bar?
  84         => true
  85
  86 You can also save a document to the database:
  87
  88         >> doc.new?
  89         => true
  90         >> doc.save(db)
  91         => #<CouchObject::Response:0x149f358 @response=#<Net::HTTPCreated 201 Created readbody=true>, @parsed_body={"_rev"=>2030456697, "_id"=>"CAEADDC895AC4D506542A3796CCA355D", "ok"=>true}>
  92         >> doc.id
  93         => "CAEADDC895AC4D506542A3796CCA355D"
  94
  95 Since CouchObject::Database#get returns a CouchObject::Response object we can convert it into a Document instance easily with CouchObject::Database#to_document:
  96
  97         >> response = db.get(doc.id)
  98         => #<CouchObject::Response:0x1498b98 @response=#<Net::HTTPOK 200 OK readbody=true>, @parsed_body={"_rev"=>2030456697, "_id"=>"CAEADDC895AC4D506542A3796CCA355D", "foo"=>[1, 2], "bar"=>true}>
  99         >> the_doc_we_just_saved = response.to_document
 100         => #<CouchObject::Document:0x148415c @id="CAEADDC895AC4D506542A3796CCA355D", @attributes={"foo"=>[1, 2], "bar"=>true}, @revision=2030456697>
 101         >> the_doc_we_just_saved.foo
 102         => [1, 2]
 103         >> doc.foo = "quux"
 104         => "quux"
 105         >> doc.save(db)
 106         => #<CouchObject::Response:0x4b0adc @response=#<Net::HTTPCreated 201 Created readbody=true>, @parsed_body={"_rev"=>1670064786, "_id"=>"B4077269D2DF8433D145DC0702B9791C", "ok"=>true}>
 107
 108
 109 == CouchObject::Persistable
 110
 111 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
 112
 113     gem "couchobject"
 114     require "couch_object"
 115     class Bike
 116       include CouchObject::Persistable
 117
 118       def initialize(wheels)
 119         @wheels = wheels
 120       end
 121       attr_accessor :wheels
 122
 123       def to_couch
 124         {:wheels => @wheels}
 125       end
 126
 127       def self.from_couch(attributes)
 128         new(attributes["wheels"])
 129       end
 130     end
 131
 132 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:
 133
 134     >> bike_4wd = Bike.new(4)
 135     => #<Bike:0x6a0a68 @wheels=4>
 136     >> bike_4wd.save("http://localhost:8888/couchobject")
 137     => {"_rev"=>1745167971, "_id"=>"6FA2AFB623A93E0E77DEAAF59BB02565", "ok"=>true}
 138     >> bike = Bike.get_by_id("http://localhost:8888/couchobject", bike_4wd.id)
 139     => #<Bike:0x64846c @wheels=4>
 140
 141