[clouchdb-cvs] CVS clouchdb/public_html
peddy
peddy at common-lisp.net
Sun Jun 29 17:13:38 UTC 2008
Update of /project/clouchdb/cvsroot/clouchdb/public_html
In directory clnet:/tmp/cvs-serv26809
Added Files:
index.html
Log Message:
trying re-add again
--- /project/clouchdb/cvsroot/clouchdb/public_html/index.html 2008/06/29 17:13:38 NONE
+++ /project/clouchdb/cvsroot/clouchdb/public_html/index.html 2008/06/29 17:13:38 1.1
<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>clouchdb
</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"/>
</head>
<body>
<div class="header">
<h1>clouchdb</h1> A Common Lisp library for interacting with
CouchDb databases.
</div>
<p>
Author: Peter Eddy (peter.eddy at gmail.com)
</p>
<h2>Contents</h2>
<ul>
<li><h3><a href="#overview">Overview</a></h3></li>
<li><h3><a href="#news">News</a></h3></li>
<li><h3><a href="#download">Download and Installation</a></h3></li>
<li><h3><a href="#examples">Examples</a></h3></li>
<li><h3><a href="#support">Support and mailing lists</a></h3></li>
<li><h3><a href="#reference">API Reference</a></h3>
<ul>
<li><h4><a href="#db-api-reference">Connection and Database API</a></h4></li>
<li><h4><a href="#doc-api-reference">Document API</a></h4></li>
<li><h4><a href="#views-api-reference">Views API</a></h4></li>
</ul>
</li>
<li><h3><a href="#symbols">Symbol Index</a></h3></li>
<li><h3><a href="#issues-and-bugs">Issues and Bugs</a></h3></li>
</ul>
<h2><a name="overview">Overview</a></h2>
<p>
Clouchdb is a Common Lisp library for interacting
with <a href="http://couchdb.org">CouchDb</a>
databases. <a href="http://couchdb.org">CouchDb</a> is a document
based, schema-less database server.
</p>
<h3>Design Goals</h3>
<p> The library was written with the goals that it be: </p>
<ul>
<li><strong>Lightweight</strong> This library is designed to be an
as lightweight as possible wrapper of the CouchDb REST API while
still providing a resonable level of comfort for to the Lisp
developer. In support of the latter goal, the library
automatically translates between CouchDb's native Json
(JavaScript) data representation language and simple Lisp data
structures.
</li>
<li><strong>Interoperable</strong> CouchDb is a schema-less,
document-oriented database in which no two documents need share a
common structure. Clouchdb does not currently provide structure or
object database mapping functionality in order not to negate the
unique nature of the CouchDb database and also in order not to
impose any library-specific requirements on database documents. In
other words, documents created with the Clouchdb library should be
fully interoperable with database documents created via other
means.
</li>
<li><strong>Simple</strong> Clouchdb is intended to be used easily
from the Lisp REPL in order to facilitate experimentation and
prototyping. Towards this end the API is designed to be as
expressive and economical as possible. Simple document inspection
and modification functions have been provided in substitution for
an object database mapping scheme. These simple tools might serve
as the basis for more elaborate custom mapping schemes.
</li>
</ul>
<h3>License</h3>
<p>
Clouchdb, comes with
a <a href="http://www.opensource.org/licenses/bsd-license.php">BSD
Style License</a> for maximum agreeableness.
</p>
<h2><a name="news">News</a></h2>
<ul>
<li><b>Jun 28, 2008</b> Released version 0.0.10 to support CouchDb
version 0.8+ and updated this documentation to reflect those
changes. This new release is compatible only with CouchDb
0.8.0-incubating (and hopefully later releases). For CouchDb
releases prior to 0.8 please use clouchdb release 0.0.9.
</li>
<li><b>Jun 15, 2008</b> Added function create-ps-view and macro
ps-view to support the new CouchDb 8.0 style views (which use
map/reduce and emit). This code is checked into source control but
not yet in a release. See examples.lisp and test.lisp for usage
examples.
</li>
<li><b>Jun 7, 2008</b> Note: CouchDb's views API has changed in
source control, breaking this library. If you want to use CouchDb
and this library, you'll have better luck sticking to the 7.2
pre-release version of CouchDb.
</li>
<li><b>Mar 1, 2008</b> Released version 0.0.9 with proper support
for complex keys in views. The functions ad-hoc-view and
invoke-view's :key, :start-end and :end-key parameters now accept
s-exprs in addtion to string
values. See <a href="#views-api-reference">Views API</a>
documentaion and <a href="#example-3">Example 3</a> for details.
</li>
<li><b>Feb 16, 2008</b> Released version 0.0.8 with the following
significant changes. Please read if you're updating from prior
versions.
<ul>
<li>Changed document field name encoding to get rid of
cl-json/parenscript style * and - case encoding. Now using the
less irritating CL symbol quoting, i.e.: <b>:|MixedCase|</b>
instead of <b>:-mixed-case</b> (or whatever it was, I could
never get it right on the first try). <strong>Note:</strong>
This will break existing code wherever there is this case
sensitivity, especially in standard CouchDb property names
like :ID, :_ID, :REV, and :_REV, which are now :|id|, :|_id|,
:|rev| and :|_rev|. Sorry about this. On the bright side you
should never have to deal with field names like
:*A-L-L-U-P-P-E-R-C-A-S-E again.
</li>
<li> Changed (set-document-property) so that it no longer
modifies its document, but instead returns a copy with
specified changes. Also now allows multiple properties to be
set in one invocation. Be sure any existing code uses the
return value from this function.
</li>
<li>Added <a href="#sym-query-document">query-document</a>
function to make it easier to extract data from complex
documents.
</li>
<li>
Removed dependence on cl-json.
</li>
</ul>
</li>
<li><b>Dec 20, 2007</b> Released version 0.0.7 with fixes for what
had been cl-json's inability to distinguish certain database field
value types in the document associative list.
</li>
<li><b>Dec 19, 2007</b> Released version 0.0.6 with full support for
utf-8 character encoding. This change includes support for
non-Latin characters in document IDs and in document
content. Additionally the encoding of spaces in document IDs has
been changed from "+" to "%20", this fixes a problem where the "+"
characters were not removed from document IDs when they were
decoded.
</li>
<li><b>Dec 17, 2007</b> Released version 0.0.5 with fixes for
encoding of URL parameters. This fix allows use of legal CouchDb
characters for database names and document IDs which must be
escaped in urls.
</li>
<li><b>Dec 9, 2007</b> - Version 0.0.4: Updated
(<a href="#sym-invoke-view">invoke-view</a>) and
(<a href="#sym-ad-hoc-view">ad-hoc-view</a>) to use all options
supported by corresponding CouchDb API. Somehow I'd missed these
before.
</li>
<li><b>Nov 28, 2007</b> -
CouchDb 7.2 now uses IANA assigned port 5984 instead of 8888.
As of release 0.0.4, clouchdb's default has been changed to
reflect this fact. If you're using pre-7.2 CouchDb versions with
clouchdb 0.0.4, be sure to set your port to 8888. There should
be no other compatibility issues.
</li>
</ul>
<h2><a name="download">Download and Installation</a></h2>
<p>
The current download link for clouchdb can be found at
<a href="http://www.cliki.net/clouchdb">Clicki.net</a>. Clouchdb may
also be installed <a href="http://www.cliki.net/asdf">ASDF</a>.
</p>
<h3>Requirements:</h3>
<ul>
<li><a href="http://www.weitz.de/drakma/">Drakma</a></li>
<li><a href="http://www.cliki.net/Parenscript/">Parenscript</a></li>
<li><a href="http://www.cliki.net/LIFT/">LIFT</a> testing framework</li>
<li>An available <a href="http://couchdb.org">CouchDb</a> server,
minimum supported version is 0.7 (in pre-0.0.10 releases),
the current release is compatible with CouchDb 0.8+ only.
</li>
</ul>
<h3>ASDF Install</h3>
<p>
Something like the following should be all that's necessary to install
and load clouchdb using ASDF-INSTALL:
</p>
<pre class="code">
(asdf-install:install 'clouchdb)
(asdf:oos 'asdf:load-op '#:clouchdb)
</pre>
<p> ASDF-INSTALL will install library dependencies, though you must
install
a <a href="http://couchdb.org/CouchDB/CouchDBWeb.nsf/direct/Downloads">CouchDb
server</a> separately.
</p>
<h3>Unit tests</h3>
<p>
The clouchdb distribution comes with a unit test suite which uses
the LIFT testing framework. To run the tests, follow the following steps:
</p>
<pre class="code">
(asdf:oos 'asdf:load-op '#:clouchdb-tests)
(in-package :clouchdb-tests)
;; If CouchDb is running on a different host
(set-connection :host "db-host")
(run-all-tests)
</pre>
<h3>Examples</h3>
<p>
The distribution also includes an examples package:
</p>
<pre class="code">
(asdf:oos 'asdf:load-op '#:clouchdb-examples)
(in-package :clouchdb-examples)
</pre>
<p>
The file examples.lisp contains comments describing each example in detail.
</p>
<h3>CVS Access</h3>
<p>
Clouchdb project hosting is graciously provided by common-lisp.net,
the CVS repository may be checked out anonymously as follows:
</p>
<pre class="code">
cvs -z3 -d :pserver:anonymous:anonymous at common-lisp.net:/project/clouchdb/cvsroot co clouchdb
</pre>
<h2><a name="support">Support and mailing lists</a></h2>
<p>
The following email lists have been provided
by the <a href="http://common-lisp.net">common-lisp.net</a> for
clouchdb development and information:
</p>
<ul>
<li> <a href="http://common-lisp.net/cgi-bin/mailman/listinfo/clouchdb-announce">
clouchdb-announce
</a>
</li>
<li> <a href="http://common-lisp.net/cgi-bin/mailman/listinfo/clouchdb-devel">
clouchdb-devel
</a>
</li>
</ul>
<h2><a name="examples">Examples</a></h2>
<p> The following
clouchdb <a href="http://common-lisp.net/project/slime/">SLIME</a>
sessions demonstrate various aspects of the three major functional
areas of the CouchDb API: Database API, Document API and View API.
</p>
<p>
NB: If you try these examples I suggest also viewing the results via
CouchDb's bulit-in HTML UI
at <a href="http://localhost:5984/_utils/browse/index.html">http://localhost:5894/_utils/browse/index.html</a>,
adjust the URL host and port for the actual CouchDb server and port
in use.
</p>
<h4>Example 1</h4>
<p>The following example session demonstrates:</p>
<ul>
<li> Setting the CouchDb host and database name</li>
<li> Finding CouchDb server version</li>
<li> Creation of a database</li>
<li> Creation of a document in that database</li>
<li> Fetching a document and adding a new field</li>
</ul>
<pre class="code">
;; Create a package to try out clouchdb
CL-USER> <b>(defpackage :clouchdb-user (:use :cl :clouchdb))</b>
#<Package "CLOUCHDB-USER">
CL-USER> <b>(in-package :clouchdb-user)</b>
#<Package "CLOUCHDB-USER">
;; If CouchDb is running on a different host set that host
;; name (default is "localhost"), also set the database name
;; to be used in this session (default database name is "default")
CLOUCHDB-USER> <b>(set-connection :host "odeon" :db-name "test-db")</b>
; No value
;; Get CouchDb Server Information by specifying a nil DB name
CLOUCHDB-USER> <b>(get-db-info :db-name nil)</b>
((:|couchdb| . "Welcome") (:|version| . "0.8.0-incubating"))
;; Create database "test-db", which we named above
CLOUCHDB-USER> <b>(create-db)</b>
((:|ok| . T))
;; Create a document with one field, and give it an ID of "gjc"
CLOUCHDB-USER> <b>(create-document '((:name . "Gaius Julius Caesar")) :id "gjc")</b>
((:|ok| . T) (:|id| . "gjc") (:|rev| . "1479031852"))
;; Fetch the document we just created
CLOUCHDB-USER> <b>(get-document "gjc")</b>
((:|_id| . "gjc") (:|_rev| . "1479031852") (:NAME . "Gaius Julius Caesar"))
;; Add a field to "gjc"
CLOUCHDB-USER> <b>(put-document (cons '(:lover . "Servilia Caepionis") *))</b>
((:|ok| . T) (:|id| . "gjc") (:|rev| . "1460552879"))
;; Get the updated document
CLOUCHDB-USER> <b>(get-document "gjc")</b>
((:|_id| . "gjc") (:|_rev| . "1460552879") (:LOVER . "Servilia Caepionis")
(:NAME . "Gaius Julius Caesar"))
</pre>
<h4>Example 2</h4>
<p>Demonstrating:</p>
<ul>
<li> Recreating a database</li>
<li> Creating a document that uses a CouchDb generated ID</li>
<li> Updating a document value using set-document-property</li>
<li> Viewing document revision information</li>
<li> Fetching an old document revision</li>
<li> Creating a document with array and map field values</li>
<li> Getting a list of all documents, and filtering that list</li>
</ul>
<pre class="code">
;; Create, or drop and recreate, the current database
CLOUCHDB-USER> <b>(create-db :if-exists :recreate)</b>
((:|ok| . T))
;; Create a document that will have it's ID assigned by the CouchDb server
CLOUCHDB-USER> <b>(create-document '((:size . "medium") (:color . "blue")))</b>
((:|ok| . T) (:|id| . "C731D3A3698DA144FB35EDA9737917F2") (:|rev| . "3363852140"))
;; CouchDb generated IDs are too large to use easily in an
;; interactive example like this, so create another document
;; with a shorter ID to demonstrate property value updates
CLOUCHDB-USER> <b>(create-document '((:size . "large") (:color . "blue"))
:id "someid")</b>
((:|ok| . T) (:|id| . "someid") (:|rev| . "3181950830"))
;; Change :color property
CLOUCHDB-USER> <b>(put-document
(set-document-property (get-document "someid")
:color "green")</b>
((:|ok| . T) (:|id| . "someid") (:|rev| . "4275808446"))
;; Show that the new property stuck
CLOUCHDB-USER> <b>(get-document "someid")</b>
((:|_id| . "someid") (:|_rev| . "4275808446") (:SIZE . "large") (:COLOR . "green"))
;; Get revision information for this document
CLOUCHDB-USER> <b>(get-document "someid" :revision-info t)</b>
((:|_id| . "someid") (:|_rev| . "4275808446") (:SIZE . "large") (:COLOR . "green")
(:|_revs_info|
((:|rev| . "4275808446") (:|status| . "available"))
((:|rev| . "3181950830") (:|status| . "available"))))
;; Since the first revision is still available we can still retrieve it:
CLOUCHDB-USER> <b>(get-document "someid" :revision "3181950830")</b>
((:|_id| . "someid") (:|_rev| . "3181950830") (:SIZE . "large") (:COLOR . "blue"))
;; In the following document, the :tags field has an array value,
;; the :demographics field has a map value, and the :religion map
;; key also has an associated map value.
CLOUCHDB-USER> <b>(create-document '((:name . "Czech Republic")
(:tags . ("country" "European"))
;; Field using map property value:
(:demographics . ((:population . 10230000)
;; A nested map property:
(:religion . ((:agnostic . 0.59)
(:roman-catholic . 0.26)
[1286 lines skipped]
More information about the clouchdb-cvs
mailing list