Differences between revisions 2 and 3
Revision 2 as of 2011-11-23 14:45:33
Size: 3430
Editor: 62
Comment: add ContributorGroup link
Revision 3 as of 2013-09-02 08:22:50
Size: 0
Editor: 88
Comment: out of data, available via github source anyway.
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:

Project page for Chillax: http://github.com/sykopomp/chillax

= Introduction =

Chillax is a CouchDB abstraction layer for Common Lisp.

Chillax also includes a CouchDB view server, which can be used to write CouchDB views in full, native Common Lisp.

Chillax includes several systems:

    * chillax.asd - This is a 'DWIM' system. It uses Yason to parse/encode JSON data. If you don't know what you want, '''this is probably what you want'''.
    * chillax.core.asd - Core API and protocols for servers, databases, documents, and design-docs.
    * chillax.yason.asd - Implementation of the server protocol using Yason's JSON parser.
    * chillax.utils.asd - Some handy utilities.
    * chillax.view-server.asd - The Chillax view server. This only depends on chillax.utils.

= Features =

 * Lispy, thin abstraction over the CouchDB API. Chillax is not magical, but it tries to be convenient.
 * Chillax's server and database protocols allow easy overriding and extension of core behavior. Writing your own server and database objects, or integrating existing ones is trivial (Server protocol is 8 generic functions, 5 of them simply readers. Database protocol is a mere 2 genfuns, both readers). You can even make Chillax use your favorite JSON library!
 * Native Lisp view server. No need to use parenscript! Write your views in Common Lisp. Include your own libraries for convenience. See [[https://github.com/sykopomp/chillax/blob/master/doc/chillax-server.png|this screenshot]].

= Quickstart example =

Chillax is [[http://quicklisp.org|Quicklisp]]-installable, allowing for super-quick, painless installation of Chillax and all its dependencies.

Make sure CouchDB is installed, and currently running. This example assumes that the server is running in localhost, using the default 5984 port. Yason's alist encoder/decoder is used below to make replies readable (by default, it uses hash tables as JSON objects, instead of alists).

CL-USER> (ql:quickload 'chillax)
CL-USER> (in-package :chillax)
CHILLAX> (defparameter *server* (make-instance 'yason-server :object-as-alist-p t
                                               (lambda (string) (intern string *package*))))
CHILLAX> (defparameter *db* (ensure-db *server* "test"))
CHILLAX> (all-documents *db*)
((|rows|) (|offset| . 0) (|total_rows| . 0))
CHILLAX> (put-document *db* "my_test_doc" '((name . "Josh") (favorite-language . "common-lisp")))
((|rev| . "1-3c964cc898c03c48903a91d90b24a269")
 (|id| . "my_test_doc") (|ok| . T))
CHILLAX> (get-document *db* "my_test_doc")
((FAVORITE-LANGUAGE . "common-lisp")
 (NAME . "Josh")
 (|_rev| . "1-3c964cc898c03c48903a91d90b24a269")
 (|_id| . "my_test_doc"))
CHILLAX> (delete-document *db* (cdr (assoc '|_id| *)) (cdr (assoc '|_rev| *)))
((|rev| . "2-2221fc2b97c1fac1a82ba07d2835ac80")
 (|id| . "my_test_doc")
 (|ok| . T))

By implementing a couple of generic functions, you can hook your own JSON encoding/decoding mechanism into Chillax -- including encoding and decoding instances of your own classes. The protocol for doing so is very straightforward and well-documented.

= Using it =

Chillax is licensed under the MIT license. For API documentation and more details, please visit the [[http://github.com/sykopomp/chillax|project page]].