= exegesis

by Matthew Lyon <matt@flowerpowered.com>
* http://github.com/mattly/exegesis

== Description:

A CouchDB ODM (Object/Document Mapper) in Ruby.

== Features:

Encourages per-"Account" databases. Actually, does not even currently provide a way to do a "singleton" or global database, however this is planned. Since a given class (say, "Article") cannot know what database it is supposed to get/search from you cannot do classical class-based finders such as "Article.find('value')". While it might be possible to pass in a database to use for some class-wide view, Exegesis takes the opinion that this is bad design for couchdb for the reasons that views may return multiple document types other than the desired class, and that views should be scoped to objects that mixin the database accessors.

CouchDB is table-less, and Exegesis's design reflects this. In CouchDB, Documents are retrieved by their unique id, or can be queried from a view function in a design document. Exegesis provides tools to aid this. Additionally, since view functions can be used for map/reduce computations against your documents, Exegesis helps you get non-document data out of your views.

== Examples:

    class Account
      include Exegesis::Database
      
      # declares the existence of a design document named 'articles'
      # view functions will be loaded from 'views/articles/:viewname/*.js
      design :articles do
        docs :by_author
        docs :at_path
        docs :tagged_with
        hash :tags_count, :view => :tagged_with
      end
    end
    
    @account.articles.by_author('user-mattly')
    # performs GET '/_design/articles/_view/by_author?key="user-mattly"&include_docs=true&reduce=false'
    @account.articles.at_path('blog/2009'..'blog/2009/04/04')
    # transforms the range into startkey/endkey
    # performs GET '/_design/articles/_view/at_path?startkey="blog/2009"&endkey="blog/2009/04/04"
    #               &include_docs=true&reduce=false'
    @account.articles.tags_count('couchdb')
    # performs GET '/_design/articles/_view/tagged_with?key="couchdb"&group=true'
    
    class Article
      include Exegesis::Document
      
      # defines readers, writers for given attributes
      expose :path, :title, :body, :tags
      expose :published_at, :writer => false, :as => Time
      timestamps!
      
      # will load the document at the id referenced by doc['author']; does not yet set writer.
      expose :author, :as => :reference
    end

== Requirements:

* RestClient 0.9 or later.

For running the tests:

* MiniTest
  MiniTest is the default testing framework for Ruby 1.9
  However, these tests require the trunk version, and my patches against the trunk version.
  The trunk version is here: http://github.com/seattlerb/minitest
  My patches are in my fork: http://github.com/mattly/minitest
  You will need to clone my repo and from its directory, do the following:
    `rake gem`
    `sudo gem install pkg/minitest-1.3.1`
  Once MiniTest 1.3.2 is released you should be able to use the standard gem.

The test suite creates and destroys a database for each test that requires access to the database. This is slow, and the test suite may take some time to run. However, I would rather the test suite be slow and accurate than quick and full of mocking or possibly error-prone deleting.