= leanback

Simple Ruby Interface to CouchDB. 

--This project is still under development. Not complete by any means. I made this Gem to use in my projects. I will expose more CouchDB features soon.

==Goals
* To create a simple Ruby Interface to CouchDB
* Expose the features of CouchDB to the Ruby Lang., 
* Use a minimalist Ruby DSL to access CouchDB
* provide a very easy way to persist and retrieve data

==Install

 gem install leanback


==Usage

Require the leanback Gem
 require 'leanback'
 
Create a CouchDB database
 Couchdb.create 'contacts'
 # => {"ok"=>true}

Delete a database
 Couchdb.delete 'contacts'
 # => {"ok"=>true} 

Return a list of all Databases
 Couchdb.all
 # => ["maps", "inventory", "monitors", "contacts", "books"]

Create a new document
 data = {:firstname => 'Linda', 
         :lastname =>'smith', 
         :phone => '212-234-1234',
         :email =>'john@mail.com'}

 doc = {:database => 'contacts', :doc_id => 'Linda', :data => data}
 Document.create doc
 # => {"ok"=>true, "id"=>"Linda", "rev"=>"1-6f16274513f51e922ff1f745452a92b6"} 
This will create a new document in the 'contacts' database, with document id 'Linda'.

Lets edit that document to change the email address, phone number, and add a gender
 data = {:firstname => 'Linda', 
         :lastname =>'smith', 
         :email => 'linda@mail.com',
         :gender=>'female',
         :phone =>'718-245-5611',
         :_rev=>'1-6f16274513f51e922ff1f745452a92b6'}

 doc = {:database => 'contacts', :doc_id => 'Linda', :data => data}
 Document.edit doc
 # => {"ok"=>true, "id"=>"Linda", "rev"=>"2-e813a0e902e3ac114400ff3959a2adde"}

Retrieve the document by id
 doc = {:database => 'contacts', :doc_id => 'Linda'}
 Couchdb.find doc
  #=> {"_id"=>"Linda", "_rev"=>"2-e813a0e902e3ac114400ff3959a2adde", "firstname"=>"Linda", 
                  "lastname"=>"smith", "email"=>"linda@mail.com", "gender"=>"female", "phone"=>"718-245-5611"} 

Delete the document
 doc = {:database => 'contacts', :doc_id => 'Linda', :rev => '2-e813a0e902e3ac114400ff3959a2adde'}
 Document.delete doc
 # => {"ok"=>true, "id"=>"Linda", "rev"=>"3-48580d1806983b32cb03f114efb064e3"} 

Retrieve all documents in a database
 docs = Couchdb.docs_from 'contacts'  
 docs.each do |d| 
  puts d["_rev"]
  puts d["_id"]    
  puts d["firstname"]
  puts d["lastname"]
  puts d["email"] 
  puts d["phone"]
 end  

Attempting to create a database that already exists
 Couchdb.create 'contacts'
 # => {"error"=>"file_exists", "reason"=>"The database could not be created, the file already exists."} 

Attempting to delete a database that no longer exists
 Couchdb.delete 'more_books'
 # => {"error"=>"not_found", "reason"=>"missing"} 

Most methods return a hash value unless otherwise specified. When a database transaction goes through successfully most methods will return a hash value # => {"ok" => true ...} and when something goes wrong it returns a hash value # => {"error" => ...}

You can always check this value 
 hash = Couchdb.delete 'schools'
 puts hash.inspect

Leanback uses the default Couchdb bind address http://127.0.0.1:5984. To use a different bind address;
 Couchdb.address = '192.168.2.16'
 Couchdb.port = '6000'
 Couchdb.all
 ...
 Document.address = '192.168.2.16'
 Document.port = '6000'
 docs = Couchdb.docs_from 'contacts'  

To change it back to default bind address at anytime, simply set the values to nil
 Couchdb.address = nil
 Couchdb.port = nil
 Couchdb.all
 ...
 Document.address = nil
 Document.port = nil
 docs = Couchdb.docs_from 'contacts'  


== Copyright

Copyright (c) 2011 Obi Akubue. See LICENSE.txt for
further details.