couchrest_model/README.md

99 lines
3.4 KiB
Markdown
Raw Normal View History

2009-01-11 11:27:22 +01:00
# CouchRest: CouchDB, close to the metal
2008-09-07 21:54:22 +02:00
2008-10-02 19:57:13 +02:00
CouchRest is based on [CouchDB's couch.js test
library](http://svn.apache.org/repos/asf/couchdb/trunk/share/www/script/couch.js),
2008-10-02 19:57:13 +02:00
which I find to be concise, clear, and well designed. CouchRest lightly wraps
CouchDB's HTTP API, managing JSON serialization, and remembering the URI-paths
to CouchDB's API endpoints so you don't have to.
2008-09-07 21:54:22 +02:00
2009-01-16 00:05:55 +01:00
CouchRest is designed to make a simple base for application and framework-specific object oriented APIs. CouchRest is Object-Mapper agnostic, the parsed JSON it returns from CouchDB shows up as subclasses of Ruby's Hash. Naked JSON, just as it was mean to be.
2008-09-07 21:54:22 +02:00
2009-04-16 21:20:17 +02:00
Note: CouchRest only support CouchDB 0.9.0 or newer.
2009-01-11 11:27:22 +01:00
## Easy Install
2008-09-07 21:54:22 +02:00
2009-01-11 11:27:22 +01:00
Easy Install is moving to RubyForge, heads up for the gem.
2008-09-07 21:54:22 +02:00
2009-01-11 11:27:22 +01:00
### Relax, it's RESTful
2008-09-07 21:54:22 +02:00
2008-10-02 19:57:13 +02:00
The core of Couchrest is Herokus excellent REST Client Ruby HTTP wrapper.
REST Client takes all the nastyness of Net::HTTP and gives is a pretty face,
while still giving you more control than Open-URI. I recommend it anytime
youre interfacing with a well-defined web service.
2008-09-07 21:54:22 +02:00
2009-01-11 11:27:22 +01:00
### Running the Specs
2008-09-07 21:54:22 +02:00
2008-10-02 19:57:13 +02:00
The most complete documentation is the spec/ directory. To validate your
CouchRest install, from the project root directory run `rake`, or `autotest`
(requires RSpec and optionally ZenTest for autotest support).
2008-09-07 21:54:22 +02:00
2009-01-11 11:27:22 +01:00
## Examples
2008-09-07 21:54:22 +02:00
Quick Start:
# with !, it creates the database if it doesn't already exist
2008-12-14 12:05:02 +01:00
@db = CouchRest.database!("http://127.0.0.1:5984/couchrest-test")
2009-01-29 08:04:22 +01:00
response = @db.save_doc({:key => 'value', 'another key' => 'another value'})
2008-09-07 21:54:22 +02:00
doc = @db.get(response['id'])
puts doc.inspect
Bulk Save:
@db.bulk_save([
{"wild" => "and random"},
{"mild" => "yet local"},
{"another" => ["set","of","keys"]}
])
# returns ids and revs of the current docs
puts @db.documents.inspect
Creating and Querying Views:
2009-01-29 08:04:22 +01:00
@db.save_doc({
2008-09-07 21:54:22 +02:00
"_id" => "_design/first",
:views => {
:test => {
:map => "function(doc){for(var w in doc){ if(!w.match(/^_/))emit(w,doc[w])}}"
}
}
})
puts @db.view('first/test')['rows'].inspect
2009-01-11 11:27:22 +01:00
## CouchRest::Model
2008-09-07 21:54:22 +02:00
CouchRest::Model has been deprecated and replaced by CouchRest::ExtendedDocument
## CouchRest::ExtendedDocument
### Callbacks
`CouchRest::ExtendedDocuments` instances have 4 callbacks already defined for you:
`validate_callback`, `create_callback`, `save_callback`, `update_callback` and `destroy_callback`
`CouchRest::CastedModel` instances have 1 callback already defined for you:
`validate_callback`
Define your callback as follows:
save_callback :before, :generate_slug_from_name
CouchRest uses a mixin you can find in lib/mixins/callbacks which is extracted from Rails 3, here are some simple usage examples:
save_callback :before, :before_method
save_callback :after, :after_method, :if => :condition
save_callback :around {|r| stuff; yield; stuff }
Check the mixin or the ExtendedDocument class to see how to implement your own callbacks.
### Casting
Often, you will want to store multiple objects within a document, to be able to retrieve your objects when you load the document,
you can define some casting rules.
property :casted_attribute, :cast_as => 'WithCastedModelMixin'
property :keywords, :cast_as => ["String"]
If you want to cast an array of instances from a specific Class, use the trick shown above ["ClassName"]