[clouchdb-cvs] CVS clouchdb/public_html
peddy
peddy at common-lisp.net
Sat Jun 28 22:55:08 UTC 2008
Update of /project/clouchdb/cvsroot/clouchdb/public_html
In directory clnet:/tmp/cvs-serv20169/public_html
Modified Files:
index.html
Log Message:
Release 0.0.10 checkin
--- /project/clouchdb/cvsroot/clouchdb/public_html/index.html 2008/06/17 01:13:20 1.23
+++ /project/clouchdb/cvsroot/clouchdb/public_html/index.html 2008/06/28 22:55:07 1.24
@@ -50,6 +50,12 @@
<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
@@ -256,29 +262,37 @@
<pre class="code">
;; Create a package to try out clouchdb
-CL-USER> <b>(defpackage :clouchdb-user (:use :cl :clouchdb :parenscript))</b>
+CL-USER> <b>(defpackage :clouchdb-user (:use :cl :clouchdb))</b>
#<Package "CLOUCHDB-USER">
+
CL-USER> <b>(in-package :clouchdb-user)</b>
#<Package "CLOUCHDB-USER">
-;; Set our CouchDb host (default is "localhost"), and the database name for
-;; the examples
-CLOUCHDB-USER> <b>(set-connection :host "odeon" :db-name "test-db")</b>
+
+;; If necessary, set the CouchDb host name (default is "localhost"),
+;; and the database name (default is "default") for the examples
+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.7.3a"))
+((:|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")
@@ -300,29 +314,35 @@
;; 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>(let ((doc (get-document "someid")))
(setf (document-property :color doc) "green")
(put-document doc))</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 (formatted for legibility)
+
+;; 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| . "disk"))
((:|rev| . "3181950830") (:|status| . "disk"))))
+
;; Since the first revision is still available (i.e., :|status| == "disk")
;; we can still retrieve it:
CLOUCHDB-USER> <b>(get-document "someid" :revision "3181950830")</b>
@@ -342,14 +362,16 @@
(:political-system . "democracy"))))
:id "czechrepublic")</b>
((:|ok| . T) (:|id| . "czechrepublic") (:|rev| . "4272625130"))
-;; Let's see what this document looks like (formatted for legibility)
+
+;; Let's see what this document looks like
CLOUCHDB-USER> <b>(get-document "czechrepublic")</b>
((:|_id| . "czechrepublic") (:|_rev| . "3929202819")
(:NAME . "Czech Republic") (:TAGS "country" "european")
(:DEMOGRAPHICS (:POPULATION . 10230000)
(:RELIGION (:AGNOSTIC . 0.59) (:ROMAN-CATHOLIC . 0.26) (:PROTESTANT . 2.5))
(:POLITICAL-SYSTEM . "democracy")))
-;; Get all documents, results again formatted for legibility
+
+;; Get all documents in current database
CLOUCHDB-USER> <b>(get-all-documents)</b>
((:TOTAL_ROWS . 3) (:OFFSET . 0)
(:ROWS
@@ -400,7 +422,7 @@
;; Netherlands, cities by country key, and cities by country
;; and city.
-;; Note: Expressions within the (ps) expressions are <a href="http://www.cliki.net/Parenscript/">Parenscript</a>,
+;; Note: Expressions within the (ps-view) macro are <a href="http://www.cliki.net/Parenscript/">Parenscript</a>,
;; a lispy way to generate JavaScript. Unquoted keyword symbols in Lisp
;; field names should be referenced in Parenscript with the double
;; asterix names, as in the examples below. This is because JavaScript
@@ -408,23 +430,23 @@
;; case. The double asterix syntax causes Parenscript to generate
;; upper case JavaScript property names.
-CLOUCHDB-USER> <b>(create-view "cities"
- ;; Index of cities in the Netherlands
- (cons "nl"
- (ps (lambda (doc)
- (with-slots (*country* *city*) doc
- (if (eql "NL" *country*)
- (map *city* doc))))))
- ;; Index by country
- (cons "country"
- (ps (lambda (doc)
- (with-slots (*country*) doc
- (map *country* doc)))))
- ;; Index by country and city
- (cons "multi"
- (ps (lambda (doc)
- (with-slots (*country* *city*) doc
- (map (list *country* *city*) doc))))))</b>
+CLOUCHDB-USER> <b>(create-ps-view "cities"
+ ;; Index of cities in the Netherlands
+ (ps-view ("nl")
+ (defun map (doc)
+ (with-slots (*country* *city*) doc
+ (if (eql "NL" *country*)
+ (emit *city* doc)))))
+ ;; Index by country
+ (ps-view ("country")
+ (defun map (doc)
+ (with-slots (*country*) doc
+ (emit *country* doc)))))
+ ;; Index by country and city
+ (ps-view ("multi")
+ (defun map (doc)
+ (with-slots (*country* *city*) doc
+ (emit (list *country* *city*) doc))))))</b>
((:|ok| . T) (:|id| . "_design/cities") (:|rev| . "3690565831"))
;; Invoke "nl" view to find cities in the Netherlands
@@ -520,6 +542,16 @@
</blockquote>
<p>[Function]<br />
+<a name="sym-compact-db"><b>compact-db</b></a> &key db-name
+</p>
+<blockquote>
+<p>
+ Force a manual compaction of a database. If db-name is specified,
+ compacts that database, otherwise compacts the current database.
+</p>
+</blockquote>
+
+<p>[Function]<br />
<a name="sym-delete-db"><b>delete-db</b></a> &key db-name if-missing
</p>
<blockquote>
@@ -551,6 +583,51 @@
</pre>
</blockquote>
+<p>[Special Variable]<br />
+<a name="sym-document-fetch-fn"><b>*document-fetch-fn*</b></a>
+<blockquote>
+<p>
+ A function which is called whenever a document is fetched from the
+ database. The function takes one argument, the document, and returns
+ the potentially modified document.
+</p>
+<p> See <a href="#sym-document-update-fn">*document-update-fn*</a></p>
+</blockquote>
+
+<p>[Special Variable]<br />
+<a name="sym-document-update-fn"><b>*document-update-fn*</b></a>
+<blockquote>
+<p>
+ A function which is called whenver a document is sent to the
+ database via put-document, create-document or post-document
+ functions. The function should take one parameter, which will be the
+ document, and it should return one value, which should be the
+ potentially modified document.
+</p>
+<p>
+<pre class="code">
+;; Create a function that adds or updates a timestamp field in a
+;; document and returns the modified document
+(defun time-stamper (doc)
+ (set-document-property doc :timestamp (get-universal-time)))
+
+;; Cause time-stamper to be invoked with each document as
+;; it's updated or created
+(setf *document-fetch-fn* #'time-stamper)
+
+;; Test the new time stamping feature
+(create-document '((:hello . "there")) :id "test")
+<b>=></b> ((:|ok| . T) (:|id| . "test") (:|rev| . "3721228336"))
+
+;; The new document should have been created with a timestamp,
+;; let's see if it worked:
+(get-document "test")
+<b>=></b> ((:|_id| . "test") (:|_rev| . "3721228336") (:TIMESTAMP . 3422649324)
+ (:HELLO . "there"))
+</pre>
+<p> See <a href="#sym-document-fetch-fn">*document-fetch-fn*</a></p>
+</blockquote>
+
<p>[Function]<br />
<a name="sym-get-db-info"><b>get-db-info</b></a> &key db-name
</p>
@@ -596,37 +673,12 @@
protocol="http", port="5984" and database="default".
</p>
<p>
- Functions may be specified that should invoked automatically each
+ Functions may be specified that will be invoked automatically each
time a document is created or updated (document-update-fn) and each
time a document is fetched (document-fetch-fn). These functions must
take one argument, the document, and return the potentially modified
document.
</p>
-
-<p>
-Example:
-</p>
-<pre class="code">
-;; Create a function that adds or updates a timestamp field in a
-;; document and returns the modified document
-(defun time-stamper (doc)
- (set-document-property doc :timestamp (get-universal-time)))
-
-;; Cause time-stamper to be invoked with each document as
-;; it's updated or created
-(set-connection :document-update-fn #'time-stamper)
-
-;; Test the new time stamping feature
-(create-document '((:hello . "there")) :id "test")
-<b>=></b> ((:|ok| . T) (:|id| . "test") (:|rev| . "3721228336"))
-
-;; The new document should have been created with a timestamp,
-;; let's see if it worked:
-(get-document "test")
-<b>=></b> ((:|_id| . "test") (:|_rev| . "3721228336") (:TIMESTAMP . 3422649324)
- (:HELLO . "there"))
-</pre>
-
<p> See (<a href="#sym-with-connection">with-connection</a>)</p>
</blockquote>
@@ -1004,7 +1056,7 @@
</p>
<pre class="code">
;; Create document "A"
-(put-document '((:name . "Laraby")) :id "A")
+(put-document '((:name . "Larrabee")) :id "A")
;; Copy to new document "B"
(put-document (get-document "A") :id "B")
@@ -1076,7 +1128,7 @@
((:agent . 44))
((:agent . 13))
((:name . "Hymie"))
- ((:name . "Larrabee"))
+ ((:name . " Larrabee"))
((:name . "Fang") (:agent . "K-9"))))
(:kaos
(((:name . "Siegfried"))
@@ -1171,8 +1223,8 @@
views are expressed in JavaScript. While it is possible to use
JavaScript with the Clouchdb API, it may be more natural to use the
<a href="http://www.cliki.net/Parenscript/">Parenscript</a> library
- instead. Parenscript is library for generating JavaScript using Lisp
- syntax.
+ instead. Parenscript is a library for generating JavaScript using
+ a Lisp syntax.
</p>
<p>
Note that CouchDb and JavaScript are case sensitivie. Field names in
@@ -1268,43 +1320,52 @@
Example:
</p>
<pre class="code">
-(create-document '((:name . "Laraby")))
-(ad-hoc-view "function(doc) { if (doc.NAME == 'Laraby') { map(null,doc.NAME) } }")
+(create-document '((:name . "Larrabee")))
+
+(ad-hoc-view "{'map': function(doc) {
+ if (doc.NAME == 'Larrabee') {
+ map(null,doc.NAME)
+ }
+ };
+ }")
</pre>
<p>
- Ok, but this is Lisp and JavaScript looks exotic and scary. To
- solve this problem we use Parenscript. The following expression
- generates the same view with a more familiar syntax:
+ Ok, but JavaScript looks exotic and scary. To solve this problem we
+ use Parenscript. The following expression generates the same ad-hoc
+ view as above, but with a more comfortable syntax:
</p>
<pre class="code">
-(create-document '((:name . "Laraby")))
-(ad-hoc-view (ps (lambda (doc)
- (with-slots (*name*) doc
- (if (eql *name* "Laraby")
- (map nil doc))))))
+(create-document '((:name . "Larrabee")))
+
+(ad-hoc-view (ps-view ()
+ (defun map (doc)
+ (with-slots (*name*) doc
+ (if (eql *name* "Larrabee")
+ (map nil doc))))))
</pre>
<p>
- Note that it is not necessary for every document in the database to
- have a field called 'name'. This view will return only those
- documents that have a name field and where the value of that name
- field is "Laraby". No errors result from documents with no name
- field.
+ Note that views may be defined which refer to document properties
+ which may not exist in all documents in the database. For example,
+ given the view above CouchDb will simply ignore documents that do not
+ contain a NAME property.
</p>
<p>
- The (with-slots) expression above can be eliminated, if desired, like so:
+ Because ParenScript also supports Object-Oriented style "dot"
+ notation, the (with-slots) expression can be replaced with the
+ following:
</p>
<pre class="code">
-(ad-hoc-view (ps (lambda (doc)
- (if (eql doc.*name* "Laraby")
- (map nil doc))))))
+(ad-hoc-view (ps-view (lambda (doc)
+ (if (eql doc.*name* "Larrabee")
+ (map nil doc))))))
</pre>
-<p>See (<a href="#sym-create-view">create-view</a>) and <a href="#example-3">Example 3</a></p>
+<p>See (<a href="#sym-create-ps-view">create-ps-view</a>) and <a href="#example-3">Example 3</a></p>
</blockquote>
<p>[Function]<br />
-<a name="sym-create-view"><b>create-view</b></a> {view-definition}*</p>
+<a name="sym-create-ps-view"><b>create-ps-view</b></a> {view-definition}*</p>
<blockquote>
<p>
Creates a view document containing one or more view definitions. The
@@ -1313,23 +1374,66 @@
s-expresions.
</p>
<p>
-Example:
-</p>
-<pre class="code">
-;; Views defined with <a href="http://www.cliki.net/Parenscript/">Parenscript</a>
-(create-view "names"
- (cons "laraby"
- (ps (lambda (doc)
- (with-slots (name) doc
- (if (eql "Laraby" name)
- (map name doc))))))
- (cons "name"
- (ps (lambda (doc)
- (with-slots (name) doc
- (map name doc))))))
-</pre>
-<p>
-See (<a href="#sym-invoke-view">invoke-view</a>)
+The following example document, taken from the
+<a href="http://wiki.apache.org/couchdb/HttpViewApi">CouchDb
+HttpViewAPI Wiki</a>, represents a native JavaScript CouchDb View document
+</a>:
[200 lines skipped]
More information about the clouchdb-cvs
mailing list