= 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/view the document 
 doc = {:database => 'contacts', :doc_id => 'Linda'}
 Couchdb.view 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  

===Query a permanent view
 view = { :database => "contacts", :design_doc => 'my_views', :view => 'get_female_contacts'}
 Couchdb.find view 
 # => [{"_id"=>"Mary", "_rev"=>"5-bfcd67fd17dbb6a875af8f6dc497b15f", "firstname"=>"Mary", "lastname"=>"smith", 
                                         "phone"=>"212-234-1234", "email"=>"mary@mail.com", "gender"=>"female"}, 
 {"_id"=>"Nancy", "_rev"=>"1-d15a83d2a23b495c19df2595b636ecc8", "firstname"=>"Nancy", "lastname"=>"Lee", 
                                    "phone"=>"347-808-3734", "email"=>"nancy@mail.com", "gender"=>"female"}]

This is similar to sending a
 GET http://127.0.0.1:5984/[database]/_design/[design_doc]/_view/[view_name] 
For the above example
 GET http://127.0.0.1:5984/contacts/_design/my_views/_view/get_female_contacts
Leanback parses the native JSON results to return only the data values.

===Create a design document with permanent views:
First define the views in a JSON file 
 //my_views.json
 {
  "language" : "javascript",
  "views" :{
     "get_email" : {
       "map" : "function(doc){
          if(doc.lastname && doc.email)
            emit(doc.id,{Firstname: doc.firstname, Lastname: doc.lastname, Email: doc.email});
         }"
     }
  }
 }

Now create the design document and add the json file
 doc = { :database => 'contacts', :design_doc => 'more_views', :json_doc => '/path/to/my_views.json' }
 hash = Couchdb.create_design doc 
 # => {"ok"=>true, "id"=>"_design/more_views", "rev"=>"1-d67ae97ff03a98f68ddc300bf9ae5048"}

To query the view
 view = { :database => "contacts", :design_doc => 'more_views', :view => 'get_email'}
 Couchdb.find view 
 # => [{"Firstname"=>"Nancy", "Lastname"=>"Lee", "Email"=>"nancy@mail.com"}, 
         {"Firstname"=>"john", "Lastname"=>"smith", "Email"=>"john@mail.com"}]


===Error handling
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 {"ok" => true ...} and when something goes wrong it returns a hash {"error" => ...}

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

===Bind Address
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.