leanback 0.2.8 → 0.3.0

data/README.rdoc

@@ -1,393 +0,0 @@
-= 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'.
-
-Let's update that document to change the email address
- data = {:email => "linda@mail.com" }
- doc = { :database => 'contacts', :doc_id => 'Linda', :data => data}   
- Document.update doc 
-
-Let's add gender and age 
- data = {:age => "32", :gender => "female" }
- doc = { :database => 'contacts', :doc_id => 'Linda', :data => data}   
- Document.update doc 
-
-
-To change phone# and add a fax number
- data = {:phone => "718-234-2904",:fax => "646-309-4049" }
- doc = { :database => 'contacts', :doc_id => 'Linda', :data => data}   
- Document.update doc
- 
-Let's add twitter account, facebook account and website url
-  data = { :twitter => "http://twitter.com/#!/linda", 
-            :faceboook => "http://facebook.com/linda", 
-             :website => "http://linda-blogs.com" }
-
-   doc = { :database => 'contacts', :doc_id => 'Linda', :data => data}   
-   Document.update doc 
-
-Retrieve/view the document 
- doc = {:database => 'contacts', :doc_id => 'Linda'}
- Couchdb.view doc
-
- #=> {"_id"=>"Linda", "_rev"=>"5-f99fd63f2c784b5e2f7b7d92b2df9a1e", "firstname"=>"Linda", "lastname"=>"smith", 
-   "phone"=>"718-234-2904", "email"=>"linda@mail.com", "age"=>"32", "gender"=>"female", 
-      "fax"=>"646-309-4049", "twitter"=>"http://twitter.com/#!/linda", 
-             "faceboook"=>"http://facebook.com/linda", "website"=>"http://linda-blogs.com"}
-
-To edit the document and replace it with a new one
- data = {:firstname => 'Linda', 
-         :lastname =>'smith', 
-         :email => 'linda@mail.com',
-         :gender=>'female',
-         :phone =>'718-245-5611',
-         :_rev=>'5-f99fd63f2c784b5e2f7b7d92b2df9a1e'}
-
- doc = {:database => 'contacts', :doc_id => 'Linda', :data => data}
- Document.edit doc
-
- # => {"ok"=>true, "id"=>"Linda", "rev"=>"6-211ebb68bdd4ba8799387214b4a3b445"}
-This replaces the existing document with a new one, the _rev number of the document must be included in the data.
-
-Retrieve/view the document 
- doc = {:database => 'contacts', :doc_id => 'Linda'}
- Couchdb.view doc
-
-  #=> {"_id"=>"Linda", "_rev"=>"6-211ebb68bdd4ba8799387214b4a3b445", "firstname"=>"Linda", 
-                  "lastname"=>"smith", "email"=>"linda@mail.com", "gender"=>"female", "phone"=>"718-245-5611"} 
-
-Delete the document
-  doc = {:database => 'contacts', :doc_id => 'Linda'}
-  Document.delete doc
-  
- #=> {"ok"=>true, "id"=>"Linda", "rev"=>"7-a2cfbbb607a668c26256bc19ff270ecf"}
-
-Delete the document using it's revision number (_rev):
- doc = {:database => 'contacts', :doc_id => 'Linda', :rev => '2-e813a0e902e3ac114400ff3959a2adde'}
- Document.delete_rev 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  
-
-
-===To Find documents by key
-To find documents by email key (example: to find all contacts with email = 'nancy@mail.com')
- Couchdb.find_by( :database => 'contacts', :email => 'nancy@mail.com')  
-
- # => [{"_id"=>"Nancy", "_rev"=>"1-d15a83d2a23b495c19df2595b636ecc8", "firstname"=>"Nancy", "lastname"=>"Lee",
-                   "phone"=>"347-808-3734", "email"=>"nancy@mail.com", "gender"=>"female"}]
-
-To find all contacts with lastname = 'Smith'
- Couchdb.find_by( :database => 'contacts', :lastname => 'Smith')  
-
- # => [{"_id"=>"john", "_rev"=>"5-642689e0a50843d6fa508159a01b4fd4", "firstname"=>"John", "lastname"=>"Smith",
-                   "email"=>"john@mail.com", "gender"=>"male"}]
-
-To find all female contacts 
- Couchdb.find_by( :database => 'contacts', :gender => 'female') 
-
- # => [{"_id"=>"Nancy", "_rev"=>"1-d15a83d2a23b495c19df2595b636ecc8", "firstname"=>"Nancy", "lastname"=>"Lee",
-                  "phone"=>"347-808-3734", "email"=>"nancy@mail.com", "gender"=>"female"}]
-
-
-====How it works
-The method
- Couchdb.find_by(:database => 'contacts', :email => 'nancy@mail.com')  
-sends a
- GET http://127.0.0.1:5984/contacts/_design/email_finder/_view/find_by_email?key="nancy@mail.com"
-This returns all contacts with email = 'nancy@mail.com'. Leanback will parse the native JSON results to return only the data values. If the design_document (_design/email_finder) and the view (find_by_email) doesn't exist, Leanback will create it in the database. See the source for the generated design_document;
- {
-   "_id": "_design/email_finder",
-   "_rev": "7-da7f3c0bf183f4a36a82013bd0ea6537",
-   "language": "javascript",
-   "views": {
-       "find_by_email": {
-           "map": "function(doc){
-              if(doc.email)          
-                  emit(doc.email,doc); 
-                 }"
-       }
-   }
- }
-
-If you ran 
- Couchdb.find_by( :database => 'contacts', :lastname => 'Smith')  
- Couchdb.find_by( :database => 'contacts', :gender => 'female') 
-you will notice the following design_documents have been added to the database 
- _design/lastname_finder
- _design/gender_finder
-
-====Usage
-You can do 
-  docs = Couchdb.find_by( :database => 'contacts', :email => 'nancy@mail.com')  
-     docs.each do |d| 
- 	puts d["_rev"]
- 	puts d["_id"]    
- 	puts d["firstname"]
- 	puts d["lastname"]
- 	puts d["email"] 
- 	puts d["phone"]
-    end
-
- # => rev1-d15a83d2a23b495c19df2595b636ecc8
-      Nancy
-      Nancy
-      Lee
-      nancy@mail.com
-      347-808-3734
-
-===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.
-
-===Query a view by key 
- view = { :database => "contacts", :design_doc => 'the_view', :view => 'age'}
- age = "36"
- Couchdb.find(view,key = age)
-
- # => [{"_id"=>"Nancy", "_rev"=>"2-4404d0a5a1a3dff103fd46faf1e46c30", "firstname"=>"Nancy", "lastname"=>"Lee", 
-                 "phone"=>"347-808-3734", "email"=>"nancy@mail.com", "gender"=>"female", "age"=>"36"}]
-
-The above example will return all contacts with age = 36.
-
-This is similar to sending a
- GET http://127.0.0.1:5984/[database]/_design/[design_doc]/_view/[view_name]?key="searchterm"
-For the above example
- GET http://127.0.0.1:5984/contacts/_design/the_view/_view/age?key="36"
-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' }
- 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"}]
-
-
-===Query a View and Create it on the fly if it doesn't already exist 
-Let's say we want to query a view, and create it on the fly if it doesn't already exist, and still return the values. In this example we will query a view called get_emails view (which returns emails of all contacts), if this view doesn't already exist it will be added to the database.
-
- 
- def get_emails
-    view = {:database => 'contacts',
-         :design_doc => 'my_views',
-          :view => 'get_emails',
-           :json_doc => '/path/to/my_views.json'}
-
-    Couchdb.find_on_fly(view)
-  end
-
-  email_list = get_emails()
-  puts email_list.inspect 
-
- # => [{"Name"=>"Nancy", "Email"=>"nancy@mail.com"}, {"Name"=>"John", "Email"=>"john@mail.com"}]
-
-In get_emails(), 
- Couchdb.find_on_fly(view)
-sends a request to the design_document (my_views) and view (get_emails). If this view is found in the database, it returns an Array with the name and email of all contacts:
-  [{"Name"=>"Nancy", "Email"=>"nancy@mail.com"}, {"Name"=>"John", "Email"=>"john@mail.com"}]
-if the design document and view doesn't already exist, it creates it and adds it to the database using the json document
-   :json_doc => '/path/to/my_views.json' 
-  
-next it sends a request for the view again and then it returns the email list.
-
-So the first time the get_emails() method is called, the view will be created on the fly and added to the database. Future calls to get_email would simply return the values from the view.
-
-Source for the get_emails view:
- #my_views.json
- {
-  "language" : "javascript",
-  "views" :{
-    "get_emails" : {
-      "map" : "function(doc){
-         if(doc.firstname && doc.email)
-           emit(doc.id,{Name: doc.firstname, Email: doc.email});
-        }"
-    }
-  }
- }
-
-You can also query a permanent view with a key and create it on the fly, if it doesn't already exist.
-Let's say we want to view all contacts with age = "36", and we already defined the view in a json file (view_age.json).
-  view = { :database => 'contacts', 
-           :design_doc => 'the_view', 
-            :view => 'age',
-             :json_doc => '/path/to/view_age.json'}
-
-  age = '36'
-  Couchdb.find_on_fly(view,key = age)
-
- #=> [{"_id"=>"Nancy", "_rev"=>"2-4404d0a5a1a3dff103fd46faf1e46c30", "firstname"=>"Nancy", "lastname"=>"Lee", 
-                  "phone"=>"347-808-3734", "email"=>"nancy@mail.com", "gender"=>"female", "age"=>"36"}]
-
-The above example will query the design_document (the_view) and view (age) in the database (contacts), using the key (age). If the view doesn't exist it will be created from the json document (view.age.json). And then return the values from the view.
-
-This is similar to sending a
- GET http://127.0.0.1:5984/contacts/_design/the_view/_view/age?key="36"
-
-The view is generated from the source code:
- #view_age.json
- {
-  "language" : "javascript",
-  "views" :{
-    "age" : {
-      "map" : "function(doc){
-         if(doc.age)
-           emit(doc.age,doc);
-        }"
-     }
-  }
- }
-
-===Error handling
-Every database operation raises a CouchdbException when things go wrong.
-
-Attempting to create a database that already exists
-  begin 	
-   Couchdb.create 'contacts'
-   #create static views
-  rescue CouchdbException => e
-   puts "Error message: " + e.to_s
-   puts "Error value: " + e.error
-  end 
-
- # => Error message: CouchDB: Error - file_exists. Reason - The database could not be created, the file already exists.
-      Error value: file_exists
-
-
-Attempting to delete a database that doesn't exist
-  begin
-   Couchdb.delete 'buildings'
-  rescue CouchdbException => e
-   puts "Error message: " + e.to_s
-   puts "Error value: " + e.error
-  end
-
- # => Error message: CouchDB: Error - not_found. Reason - missing
-      Error value: not_found
-
-Attempting to query a permanent view that doesn't exist
-  begin
-   view = { :database => "contacts", :design_doc => 'more_views', :view => 'get_user_email'}
-   Couchdb.find view 
-  rescue CouchdbException => e
-   puts "Error message: " + e.to_s
-   puts "Error value: " + e.error
-  end 
-
- # => Error message: CouchDB: Error - not_found. Reason - missing_named_view
-      Error value: not_found
-
-You can always check the information passed to the Exception. 
-  
-===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'
- ...
- Document.address = '192.168.2.16'
- Document.port = '6000'
- 
-
-To change it back to default bind address at anytime, simply set the values to nil
- Couchdb.address = nil
- Couchdb.port = nil
- ...
- Document.address = nil
- Document.port = nil
-
-
-== Copyright
-
-Copyright (c) 2011 Obi Akubue. See LICENSE.txt for
-further details.
-
-