[clouchdb-cvs] CVS clouchdb/public_html
peddy
peddy at common-lisp.net
Sun Jul 12 18:59:04 UTC 2009
Update of /project/clouchdb/cvsroot/clouchdb/public_html
In directory cl-net:/tmp/cvs-serv23658/public_html
Modified Files:
index.html
Log Message:
Substantial documentation update, added attachment API and conditions
--- /project/clouchdb/cvsroot/clouchdb/public_html/index.html 2008/10/11 18:55:48 1.5
+++ /project/clouchdb/cvsroot/clouchdb/public_html/index.html 2009/07/12 18:59:04 1.6
@@ -15,89 +15,43 @@
CouchDb databases.
</div>
+<h2>Overview</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 database server. Clouchdb comes with
+a <a href="http://www.opensource.org/licenses/bsd-license.php">BSD
+Style License</a> for maximum agreeableness.
+</p>
+
<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="#examples">Examples</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="#attachment-api-reference">Atachment API</a></h4></li>
<li><h4><a href="#views-api-reference">Views API</a></h4></li>
+ <li><h4><a href="#conditions-reference">Conditions Defined by Clouchdb</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
@@ -116,67 +70,6 @@
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>
@@ -191,16 +84,9 @@
<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 version is 0.7 (in clouchdb pre-0.0.10 releases), the
- current release is compatible with CouchDb 0.8+.
- </li>
-</ul>
-
-<h3>Optional</h3>
-<ul>
- <li><a href="http://www.cliki.net/LIFT/">LIFT</a> testing
- framework. Required only to run the unit tests.</li>
+ minimum supported version is 0.7, now tested on 7.3a</li>
</ul>
<h3>ASDF Install</h3>
@@ -212,30 +98,35 @@
<pre class="code">
(asdf-install:install 'clouchdb)
-(asdf:oos 'asdf:load-op '#:clouchdb)
+(asdf:operate '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>
+ ASDF-INSTALL will install library dependencies, though you must of
+ course install the <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:
+ 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>
+<p>
+ Note that if the CouchDb server is not running on the same host you
+ will have to modify tests.lisp to point it to the appropriate host.
+</p>
+
<h3>Examples</h3>
<p>
@@ -264,34 +155,37 @@
<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:
+ 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>
+ <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>
+ The following clouchdb REPL sessions demonstrate various aspects of
+ the three major functional areas of the CouchDb API: Database API,
+ Document API and View API.
</p>
-<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.
+ CouchDb's bulit-in HTML UI at <a
+ href="http://localhost:5984/_utils/">http://localhost:5894/_utils/</a>.
+ Of course adjust the URL for the actual CouchDb server and port in
+ use.
</p>
<h4>Example 1</h4>
@@ -306,41 +200,62 @@
<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>(defpackage :clouchdb-user (:use :cl :clouchdb :parenscript))</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"))
+;; View the current (default) CouchDb connection configuration
+CLOUCHDB-USER> <b>*couchdb*</b>
+#S(CLOUCHDB::DB
+ :HOST "localhost"
+ :PORT "5984"
+ :NAME "default"
+ :PROTOCOL "http"
+ :USER NIL
+ :PASSWORD NIL
+ :DOCUMENT-FETCH-FN NIL
+ :DOCUMENT-UPDATE-FN NIL)
+
+;; The current database name is "default". Set appropriate values, for
+;; example, if the CouchDb server is running on host "odeon" set that
+;; value like so:
+CLOUCHDB-USER> <b>(set-connection :host "odeon")</b>
+#S(CLOUCHDB::DB
+ :HOST "odeon"
+ :PORT "5984"
+ :NAME "default"
+ :PROTOCOL "http"
+ :USER NIL
+ :PASSWORD NIL
+ :DOCUMENT-FETCH-FN NIL
+ :DOCUMENT-UPDATE-FN NIL)
+
+;; Get CouchDb Server Information. This is the first communication
+;; with the CouchDb server.
+CLOUCHDB-USER> <b>(get-couchdb-info)</b>
+((:|couchdb| . "Welcome") (:|version| . "0.10.0a788899"))
-;; Create database "test-db", which we named above
+;; Create database named "default", (as configured in *couchdb*)
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"))
+((:|ok| . T) (:|id| . "gjc") (:|rev| . "1-1009420200"))
;; Fetch the document we just created
CLOUCHDB-USER> <b>(get-document "gjc")</b>
-((:|_id| . "gjc") (:|_rev| . "1479031852") (:NAME . "Gaius Julius Caesar"))
+((:|_id| . "gjc") (:|_rev| . "1-1009420200") (:NAME . "Gaius Julius Caesar"))
-;; Add a field to "gjc"
+;; Add a field to this new document
CLOUCHDB-USER> <b>(put-document (cons '(:lover . "Servilia Caepionis") *))</b>
-((:|ok| . T) (:|id| . "gjc") (:|rev| . "1460552879"))
+((:|ok| . T) (:|id| . "gjc") (:|rev| . "2-3501332342"))
-;; Get the updated document
+;; Get the updated document to verify that the new field stuck
CLOUCHDB-USER> <b>(get-document "gjc")</b>
-((:|_id| . "gjc") (:|_rev| . "1460552879") (:LOVER . "Servilia Caepionis")
+((:|_id| . "gjc") (:|_rev| . "2-3501332342") (:LOVER . "Servilia Caepionis")
(:NAME . "Gaius Julius Caesar"))
</pre>
@@ -349,11 +264,8 @@
<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> Updating a the value of a document field</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">
@@ -363,37 +275,29 @@
;; 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"))
+((:|ok| . T) (:|id| . "37173e3a844a342414272daa733e1302")
+ (:|rev| . "1-3111744915"))
;; 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"))
[1964 lines skipped]
More information about the clouchdb-cvs
mailing list