[clouchdb-cvs] CVS clouchdb/public_html
peddy
peddy at common-lisp.net
Sat Feb 16 19:36:07 UTC 2008
Update of /project/clouchdb/cvsroot/clouchdb/public_html
In directory clnet:/tmp/cvs-serv13173/public_html
Modified Files:
index.html
Log Message:
- Updated docs to reflect 0.0.8 release
- Remove some junk code
- Updated example to demonstrate use of query-document
--- /project/clouchdb/cvsroot/clouchdb/public_html/index.html 2008/01/19 20:18:57 1.13
+++ /project/clouchdb/cvsroot/clouchdb/public_html/index.html 2008/02/16 19:36:06 1.14
@@ -27,7 +27,7 @@
</p>
<p>
- Author: Peter Eddy (peter.eddy at the gmail.com)
+ Author: Peter Eddy (peter.eddy at gmail.com)
</p>
<h2>Contents</h2>
@@ -50,6 +50,34 @@
<h2><a name="news">News</a></h2>
<ul>
+ <li><b>Feb 16, 2008</b> Released version 0.0.8 with the following
+ significant changes:
+ <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, :_REV, which are now :|id|, :|_id|,
+ :|rev| and :|_rev|. Sorry about that.
+ </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, making 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.
@@ -93,7 +121,6 @@
<ul>
<li><a href="http://www.weitz.de/drakma/">Drakma</a></li>
- <li><a href="http://www.cliki.net/cl-json/">cl-json</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,
@@ -145,11 +172,9 @@
<pre class="code">
(asdf:oos 'asdf:load-op '#:clouchdb-examples)
(in-package :clouchdb-examples)
-(example1)
-(example2)
</pre>
<p>
- Be sure to look at examples.lisp to understand what each example is doing.
+ The file examples.lisp contains comments describing each example in detail.
</p>
<h3>CVS Access</h3>
@@ -190,11 +215,12 @@
</p>
<p>
NB: If you try these examples I suggest also viewing the results via
- CouchDb's HTML UI
- at <a href="http://localhost:8888/_utils/browse/index.html">http://localhost:8888/_utils/browse/index.html</a>,
- (or <a href="http://localhost:5984/_utils/browse/index.html">http://localhost:5984/_utils/browse/index.html</a>
- if you're using ClouchDb version 7.2 or later), of course you'll need to
- adjust the URL for the actual CouchDb server and port in use.
+ CouchDb's bulit-in HTML UI
+ at <a href="http://localhost:5894/_utils/browse/index.html">http://localhost:8888/_utils/browse/index.html</a>,
+ (or <a href="http://localhost:8888/_utils/browse/index.html">http://localhost:5984/_utils/browse/index.html</a>
+ if you're using ClouchDb versions prior to 7.2), of course you'll
+ need to adjust the URL for the actual CouchDb server and port in
+ use.
</p>
<h4>Example 1</h4>
@@ -219,22 +245,22 @@
; 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.0a575"))
+((:|couchdb| . "Welcome") (:|version| . "0.7.3a"))
;; Create database "test-db", which we named above
CLOUCHDB-USER> <b>(create-db)</b>
-((:OK . T))
+((:|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| . "1479031852"))
;; Fetch the document we just created
CLOUCHDB-USER> <b>(get-document "gjc")</b>
-((:_ID . "gjc") (:_REV . "1479031852") (:NAME . "Gaius Julius Caesar"))
+((:|_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"))
+((:|ok| . T) (:|id| . "gjc") (:|rev| . "1460552879"))
;; Get the updated document
CLOUCHDB-USER> <b>(get-document "gjc")</b>
-((:_ID . "gjc") (:_REV . "1460552879") (:LOVER . "Servilia Caepionis")
+((:|_id| . "gjc") (:|_rev| . "1460552879") (:LOVER . "Servilia Caepionis")
(:NAME . "Gaius Julius Caesar"))
</pre>
@@ -252,34 +278,34 @@
<pre class="code">
;; Create, or drop and recreate, the current database
CLOUCHDB-USER> <b>(create-db :if-exists :recreate)</b>
-((:OK . T))
+((:|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"))
+((:|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"))
+((:|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"))
+((:|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"))
+((:|_id| . "someid") (:|_rev| . "4275808446") (:SIZE . "large") (:COLOR . "green"))
;; Get revision information for this document (formatted for legibility)
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"))))
+((:|_id| . "someid") (:|_rev| . "4275808446") (:SIZE . "large") (:COLOR . "green")
+ (:|_rev|S_INFO
+ ((:|rev| . "4275808446") (:STATUS . "disk"))
+ ((:|rev| . "3181950830") (:STATUS . "disk"))))
;; Since the first revision is still available (:status . "disk") we
;; can still retrieve it
CLOUCHDB-USER> <b>(get-document "someid" :revision "3181950830")</b>
-((:_ID . "someid") (:_REV . "3181950830") (:SIZE . "large") (:COLOR . "blue"))
+((:|_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
@@ -294,10 +320,10 @@
(:protestant . 2.5)))
(:political-system . "democracy"))))
:id "czechrepublic")</b>
-((:OK . T) (:ID . "czechrepublic") (:REV . "4272625130"))
+((:|ok| . T) (:|id| . "czechrepublic") (:|rev| . "4272625130"))
;; Let's see what this document looks like (formatted for legibility)
CLOUCHDB-USER> <b>(get-document "czechrepublic")</b>
-((:_ID . "czechrepublic") (:_REV . "3929202819")
+((:|_id| . "czechrepublic") (:|_rev| . "3929202819")
(:NAME . "Czech Republic") (:TAGS "country" "european")
(:DEMOGRAPHICS (:POPULATION . 10230000)
(:RELIGION (:AGNOSTIC . 0.59) (:ROMAN-CATHOLIC . 0.26) (:PROTESTANT . 2.5))
@@ -306,17 +332,17 @@
CLOUCHDB-USER> <b>(get-all-documents)</b>
((:TOTAL_ROWS . 3) (:OFFSET . 0)
(:ROWS
- ((:ID . "C731D3A3698DA144FB35EDA9737917F2") (:KEY . "C731D3A3698DA144FB35EDA9737917F2")
- (:VALUE (:REV . "3363852140")))
- ((:ID . "czechrepublic") (:KEY . "czechrepublic") (:VALUE (:REV . "4272625130")))
- ((:ID . "someid") (:KEY . "someid") (:VALUE (:REV . "4275808446")))))
+ ((:|id| . "C731D3A3698DA144FB35EDA9737917F2") (:KEY . "C731D3A3698DA144FB35EDA9737917F2")
+ (:VALUE (:|rev| . "3363852140")))
+ ((:|id| . "czechrepublic") (:KEY . "czechrepublic") (:VALUE (:|rev| . "4272625130")))
+ ((:|id| . "someid") (:KEY . "someid") (:VALUE (:|rev| . "4275808446")))))
</pre>
<h4>Example 3</h4>
<p>Demonstrating:</p>
<ul>
- <li> Conditionally creating a database if it does not exist</li>
+ <li> Conditionally creating a database if one does not already exist</li>
<li> The use
of <a href="http://www.cliki.net/Parenscript/">Parenscript</a> in
defining a view</li>
@@ -328,22 +354,22 @@
;; An (:IGNORED . T) result indicates that the create
;; was ignored because the database already existed.
CLOUCHDB-USER> <b>(create-db :if-exists :ignore)</b>
-((:OK . T) (:IGNORED . T))
+((:|ok| . T) (:IGNORED . T))
;; Create some documents representing various cities and their
;; associated countries.
CLOUCHDB-USER> <b>(create-document '((:city . "New York City")
(:country . "US"))
:id "nyc")</b>
-((:OK . T) (:ID . "nyc") (:REV . "1023292373"))
+((:|ok| . T) (:|id| . "nyc") (:|rev| . "1023292373"))
CLOUCHDB-USER> <b>(create-document '((:city . "Amsterdam")
(:country . "NL"))
:id "amst") </b>
-((:OK . T) (:ID . "amst") (:REV . "3679905075"))
+((:|ok| . T) (:|id| . "amst") (:|rev| . "3679905075"))
CLOUCHDB-USER> <b>(create-document '((:city . "Chicago")
(:country . "US"))
:id "chi") </b>
-((:OK . T) (:ID . "chi") (:REV . "1627558845"))
+((:|ok| . T) (:|id| . "chi") (:|rev| . "1627558845"))
;; Create a persistent view document to find cities in the
;; Netherlands and also to find cities by country key.
@@ -359,23 +385,23 @@
(with-slots (country) doc
(if (eql "NL" country)
(map country doc)))))))</b>
-((:OK . T) (:ID . "_design/cities") (:REV . "3690565831"))
+((:|ok| . T) (:|id| . "_design/cities") (:|rev| . "3690565831"))
;; Invoke "nl" view to find cities in the Netherlands
CLOUCHDB-USER> <b>(invoke-view "cities" "nl")</b>
((:TOTAL_ROWS . 1) (:OFFSET . 0)
(:ROWS
- ((:ID . "amst") (:KEY . "NL") (:VALUE (:_ID . "amst")
- (:_REV . "3679905075") (:CITY . "Amsterdam") (:COUNTRY . "NL")))))
+ ((:|id| . "amst") (:KEY . "NL") (:VALUE (:|_id| . "amst")
+ (:|_rev| . "3679905075") (:CITY . "Amsterdam") (:COUNTRY . "NL")))))
;; Invoke "country" view created above and search for US cities
CLOUCHDB-USER> <b>(invoke-view "cities" "country" :key "US")</b>
((:TOTAL_ROWS . 3) (:OFFSET . 1)
(:ROWS
- ((:ID . "chi") (:KEY . "US") (:VALUE (:_ID . "chi")
- (:_REV . "1627558845") (:CITY . "Chicago") (:COUNTRY . "US")))
- ((:ID . "nyc") (:KEY . "US") (:VALUE (:_ID . "nyc")
- (:_REV . "1023292373") (:CITY . "New York City") (:COUNTRY . "US")))))
+ ((:|id| . "chi") (:KEY . "US") (:VALUE (:|_id| . "chi")
+ (:|_rev| . "1627558845") (:CITY . "Chicago") (:COUNTRY . "US")))
+ ((:|id| . "nyc") (:KEY . "US") (:VALUE (:|_id| . "nyc")
+ (:|_rev| . "1023292373") (:CITY . "New York City") (:COUNTRY . "US")))))
;; Note: the two responses above have been formatted for legibility. Also,
;; see CouchDb documentation for why 3 is returned for TOTAL_ROWS when
@@ -415,14 +441,19 @@
;; Create the database named in the current connection settings
(set-connection :db-name "tvland")
(create-db)
-<b>=></b> ((:OK . T))
+<b>=></b> ((:|ok| . T))
;; Specify name of database to create, if it already exists
;; then ignore the request (don't generate error, don't
;; recreate database), return (:ignored . T) if database did
;; exist
-(create-db :db-name "tvland")
-<b>=></b> ((:OK . T) (:IGNORED . T))
+(create-db :db-name "tvland" :if-exists :ignore)
+<b>=></b> ((:|ok| . T) (:IGNORED . T))
+
+;; Create named db, if it already exists, drop it and
+;; recreate it
+(create-db :db-name "tvland" :if-exists :recreate)
+<b>=></b> ((:|ok| . T))
</pre>
</blockquote>
@@ -448,7 +479,7 @@
;; Create the database named in the current connection settings
(set-connection :db-name "tvland")
(delete-db)
-<b>=></b> ((:OK . T))
+<b>=></b> ((:|ok| . T))
;; Specify name of database to delete, if it doesn't exist
;; then ignore the request (don't generate error), return
@@ -558,7 +589,7 @@
<pre class="code">
(create-document '((<b>:name</b> . "Max") (<b>:agent</b> . 86)) :id "agent86")
(get-document "agent86")
-<b>=></b> ((:_ID . "agent86") (:_REV . "3674093994") (<b>:NAME</b> . "Max") (<b>:AGENT</b> . 86))
+<b>=></b> ((:|_id| . "agent86") (:|_rev| . "3674093994") (<b>:NAME</b> . "Max") (<b>:AGENT</b> . 86))
</pre>
<p>
@@ -572,35 +603,30 @@
<p>
Field names in CouchDb are case sensitive. Field names specified
- with keyword symbols are normally converted to or from lower case
- in communication with the CouchDb server, however it is possible
- to specify case in field names like so:
+ with unquoted keyword symbols are normally to upper case, and
+ result in upper case field names in the CouchDb server. Use symbol
+ name quotes to specify mixed or lower case field names like so:
</p>
<pre class="code">
;; Create a document with a mixed case field name. This document
-;; will appear in the database as, "fieldName"
-(create-document '((<b>:field-name</b> . "Value")) :id "mixed-case1")
+;; will appear in the database as, "MixedCaseName"
+(create-document '((<b>:|MixedCaseName|</b> . "Value")) :id "mixed-case1")
(get-document "mixed-case1")
-<b>=></b> ((:_ID . "mixed-case1") (:_REV . "2016717365") (<b>:*FIELD-NAME</b> . "Value"))
+<b>=></b> ((:|_id| . "mixed-case1") (:|_rev| . "2016717365") (<b>:|MixedCaseName|</b> . "Value"))
</pre>
<p>
- But see <a href="#issues-and-bugs">Issues and Bugs</a>
- </p>
-
- <p>
The native document representation in the CouchDb protocol is
- a <a href="http://json.org/">JSON</a> object. Using
- <a href="http://common-lisp.net/project/cl-json/">cl-json</a>,
- clouchdb automatically translates documents between JSON and Lisp
- associative lists.
+ a <a href="http://json.org/">JSON</a> object. Clouchdb
+ automatically translates documents between JSON and Lisp
+ associative lists.
</p>
<p>
The value of a document field may be a string, a number, a list,
or an associative list. Document field values may be nested to
- create very complex document structures.
+ create arbitrarily complex document structures.
</p>
<pre class="code">
@@ -630,10 +656,10 @@
<pre class="code">
(create-document '((:name . "Maxwell Smart") (:agent . 86)) :id "max")
-<b>=></b> ((:OK . T) (:ID . "max") (:REV . "3789799231"))
+<b>=></b> ((:|ok| . T) (:|id| . "max") (:|rev| . "3789799231"))
(get-document "max")
-<b>=></b> ((:_ID . "max") (:_REV . "3789799231") (:NAME . "Maxwell Smart") (:AGENT . 86))
+<b>=></b> ((:|_id| . "max") (:|_rev| . "3789799231") (:NAME . "Maxwell Smart") (:AGENT . 86))
</pre>
</blockquote>
@@ -656,21 +682,20 @@
Example:
</p>
<pre class="code">
- ;; No case encoding
- (as-keyword-symbol "normal")
- <b>=></b> :NORMAL
+ ;; Lower case
+ (as-keyword-symbol "lowercase")
+ <b>=></b> :|lowercase|
;; Upper case
(as-keyword-symbol "UPPER-CASE")
- <b>=></b> :-U-P-P-E-R--C-A-S-E
+ <b>=></b> :UPPER-CASE
;; Mixed case
(as-keyword-symbol "MixedCase")
- <b>=></b>:-MIXED-CASE
+ <b>=></b>:|MixedCase|
</pre>
<p>
See (<a href="#sym-as-field-name-string">as-field-name-string</a>)
- and <a href="#issues-and-bugs">Issues and Bugs</a>
</p>
</blockquote>
@@ -688,21 +713,20 @@
Example:
</p>
<pre class="code">
- ;; No case encoding
- (as-field-name-string :normal)
- <b>=></b> "normal"
-
;; Upper case
- (as-field-name-string :-u-p-p-e-r--c-a-s-e)
- <b>=></b> "UPPER-CASE"
+ (as-field-name-string :case)
+ <b>=></b> "CASE"
+
+ ;; Lower case
+ (as-field-name-string :|case|)
+ <b>=></b> "case"
;; Mixed case
- (as-field-name-string :-Mixed-Case)
[190 lines skipped]
More information about the clouchdb-cvs
mailing list