[clouchdb-cvs] CVS clouchdb/public_html
peddy
peddy at common-lisp.net
Mon Feb 18 03:16:02 UTC 2008
Update of /project/clouchdb/cvsroot/clouchdb/public_html
In directory clnet:/tmp/cvs-serv13099
Modified Files:
index.html
Log Message:
Lots of minor fixes and corrections
--- /project/clouchdb/cvsroot/clouchdb/public_html/index.html 2008/02/16 19:53:49 1.15
+++ /project/clouchdb/cvsroot/clouchdb/public_html/index.html 2008/02/18 03:16:01 1.16
@@ -51,7 +51,8 @@
<ul>
<li><b>Feb 16, 2008</b> Released version 0.0.8 with the following
- significant changes:
+ 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
@@ -60,8 +61,10 @@
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.
+ 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
@@ -70,7 +73,7 @@
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
+ function to make it easier to extract data from complex
documents.
</li>
<li>
@@ -603,24 +606,24 @@
<p>
Field names in CouchDb are case sensitive. Field names specified
- 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:
+ with unquoted keyword symbols are normally converted to upper case
+ by Lisp and this results in upper case field names in the CouchDb
+ server. Use quotes in symbol names 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, "MixedCaseName"
-(create-document '((<b>:|MixedCaseName|</b> . "Value")) :id "mixed-case1")
-(get-document "mixed-case1")
-<b>=></b> ((:|_id| . "mixed-case1") (:|_rev| . "2016717365") (<b>:|MixedCaseName|</b> . "Value"))
+(create-document '((<b>:|MixedCaseName|</b> . "Value")) :id "mixed-case")
+(get-document "mixed-case")
+<b>=></b> ((:|_id| . "mixed-case") (:|_rev| . "2016717365") (<b>:|MixedCaseName|</b> . "Value"))
</pre>
<p>
The native document representation in the CouchDb protocol is
- a <a href="http://json.org/">JSON</a> object. Clouchdb
- automatically translates documents between JSON and Lisp
- associative lists.
+ a <a href="http://json.org/">JSON</a> object. Clouchdb translates
+ documents to and from JSON as necessary.
</p>
<p>
@@ -647,11 +650,13 @@
<blockquote>
<p>
- When a document is created CouchDb assigns special properties to that
- document, these properties cannot be modified by clients. The special
- properties include the document's ID (:_id) and the document revision
- number (:_rev). All special properties begin with an underscore (_)
- symbol.
+ When a document is created CouchDb assigns special properties to
+ that document, these properties cannot be modified by clients. The
+ special properties include the document's ID (:|_id|) and the
+ document revision number (:|_rev|). All special properties begin
+ with an underscore (_) symbol. CouchDb uses lower case for these
+ special properties therefore, as of Clouchdb version 0.0.8, they
+ will always appear as quoted keyword symbols.
</p>
<pre class="code">
@@ -762,12 +767,12 @@
id revision</p>
<blockquote>
<p>
-Delete the specified document, which must include the standard CouchDb
-special variables :|_id| and :|_rev|. The document may also identified by
-ID. If revision is specified, delete the specific revision of
-identified document, otherwise, delete the most current revision by
-fetching the document by ID and using its :_rev value for the
-deletion.
+ Delete the specified document, which must include the standard
+ CouchDb special variables :|_id| and :|_rev|. The document may also
+ identified by ID. If revision is specified, deletes the specific
+ revision of identified document. If no revision is specified,
+ deletes the most current revision by fetching the document by ID and
+ using its :|_rev| value for the deletion.
</p>
</blockquote>
@@ -786,6 +791,10 @@
(document-property :name (get-document "max"))
<b>=></b> "Maxwell Smart"
</pre>
+<p>
+See
+(<a href="#sym-set-document-property">set-document-property</a>)
+</p>
</blockquote>
<p>[Function]<br />
@@ -844,11 +853,11 @@
<blockquote>
<p>
Create a new document or update an existing one. If the document is
-new, the ID must be specified. If the document has been fetched from
-the server (and still retains its :_* CouchDb special properties) then
-no ID need be specified. If an ID is specified and it differs from the
-existing :_id value, then a new document is created with the specified
-ID and any non-special properties of the document.
+new an ID must be specified. If the document has been fetched from the
+server (and still retains its :|_*| CouchDb special properties) then
+no ID need be specified. If an parameter ID is provided and it differs
+from the :|_id| value in the document, then a new document is created
+with the provided ID and any non-special properties of the document.
</p>
<p>
Example:
@@ -871,19 +880,21 @@
</p>
<blockquote>
<p>
- This function can be used to easily extract data from complex
- documents or other CouchDb data such as results returned from
- queries. The query parameter is a list containing zero or more query
- expressions to match in the specified document.
+ This function can be used to extract data from complex documents or
+ other CouchDb data such as results returned from views. The query
+ parameter is a list containing zero or more query expressions. A
+ query expression can be either a keyword symbol, which simply
+ matches the keyword field name in the document, wild card symbols,
+ or a function.
</p>
-<table summary="query operator values">
- <caption><em>Query Operator Values</em></caption>
+<table summary="query operators">
+ <caption><em>Query Operators</em></caption>
<tr>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
- <td>Symbol</td>
+ <td>keyword symbol</td>
<td>Matches field name in document</td>
</tr>
<tr>
@@ -899,10 +910,13 @@
<tr>
<td>function</td>
<td>
- Invokes function with a single parameter, which is the value of
- the previous match or the document if the function is the first
- element in the query list. The return value of function is
- applied to any subsequent query parameters.
+ The function should accept a single parameter, which will
+ contain the value of the previous match or the initial document
+ if the function is the first element in the query list. Query
+ operators following the function are applied to the result of
+ the function or, if the function is the last operator in the
+ query, the function return value is collected in the
+ query-document results list.
</td>
</tr>
</table>
@@ -910,31 +924,29 @@
Examples:
</p>
<pre class="code">
-;; Get all values for :agent under :agents
-(query-document '(:agents :agent)
- '((:agents
- (((:name . "Max") (:agent . 86))
- ((:name . "Ninety Nine") (:agent . 99))
- ((:name . "Fang") (:agent "K-9"))))))
-<b>=></b> (("K-9") 99 86)
-
-;; Get names of agents that work for Control or Kaos, where those agents have names
-(query-document '(:* :name)
- '(((:control-agents
+;; Secret Agent document to query
+(setf *agents* '((:control
(((:name . "Max") (:agent . 86))
((:name . "Ninety Nine") (:agent . 99))
((:agent . 44))
((:agent . 13))
((:name . "Hymie"))
((:name . "Larrabee"))
- ((:name . "Fang") (:agent "K-9")))))
- ((:kaos-agents
- (((:name . "Siegfried"))
- ((:name . "Shtarker"))
- ((:name . "The Claw"))
- ((:name . "Colonel vol Klaus")))))))
-
-<b>=></b> ("Colonel vol Klaus" "The Claw" "Shtarker" "Siegfried" "Fang" "Larrabee" "Hymie" "Ninety Nine" "Max")
+ ((:name . "Fang") (:agent . "K-9"))))
+ (:kaos
+ (((:name . "Siegfried"))
+ ((:name . "Shtarker"))
+ ((:name . "The Claw"))
+ ((:name . "Colonel von Klaus"))))))
+
+;; Get the agent values for all Control agents that have these values
+(query-document '(:control :agent) *agents*)
+<b>=></b> ("K-9" 13 44 99 86)
+
+;; Get names of agents that work for Control or Kaos, for agents who have names
+(query-document '(:* :name) *agents*)
+<b>=></b> ("Colonel von Klaus" "The Claw" "Shtarker" "Siegfried" "Fang" "Larrabee"
+ "Hymie" "Ninety Nine" "Max")
;; Get a value from a deeply nested position
(query-document '(:** :value) '((:a .
@@ -950,18 +962,23 @@
((:very .
((:deeply .
((:nested .
- ((:value . "Deep Value 1")))))))))
+ ((:value . "Deep Value")))))))))
(:this .
((:value .
((:is .
- ((:different . "Deep Value 2")))))))))
+ ((:different . "Different Deep Value")))))))))
-<b>=></b> (((:IS (:DIFFERENT . "Deep Value 2"))) "Deep Value 1")
+<b>=></b> (((:IS (:DIFFERENT . "Different Deep Value"))) "Deep Value")
-;; Use the clouchdb function (<a href="#sym-get-document">get-document</a>)
-;; to look up documents by ID as found by the previous query element,
-;; :|id|. The form below will return the value for :name for all
-;; documents in the current database that have one or more :name properties
+;; Query using a function
+;;
+;; Query the results of (<a href="#sym-get-all-documents">get-all-documents</a>), extracting all
+;; document :|id| values in the :|rows| property.
+;;
+;; Use the clouchdb function (<a href="#sym-get-document">get-document</a>) to look up the
+;; corresponding document for each value of :|id|. The form below will
+;; return the value of the :name property for all documents in the
+;; current database that have one or more :name properties
(query-document `(:|rows| :|id| ,#'get-document :** :name) (get-all-documents))
@@ -975,9 +992,12 @@
<a name="sym-set-document-property"><b>set-document-property</b></a> doc &rest args</p>
<blockquote>
<p>
-Modify or add property values to a document. This function returns a
-new copy of the specified document, it does not modify its
-parameter. Be sure to use the return value.
+Modify existing named property or add property names and values to a
+document. This function returns a new copy of the specified document,
+it does not modify its document parameter.
+</p>
+<p>
+Example:
</p>
<pre class="code">
(create-document '((:name . "Maxwell Smart") (:agent . 86)) :id "max")
@@ -985,7 +1005,7 @@
(document-property :name (get-document "max"))
<b>=></b> "Maxwell Smart"
-;; Modify :name and add :employer properties
+;; Modify existing :name value and add :employer property
(put-document
(set-document-property (get-document "max")
:name "Maxwell Smart, Secret Agent"
@@ -1275,7 +1295,7 @@
</ul>
-<p>Back to <a href="http://common-net.lisp/">Common-lisp.net</a>.</p>
+<p>Back to <a href="http://common-lisp.net/">Common-lisp.net</a>.</p>
<div class="check">
<a href="http://validator.w3.org/check/referer">Valid XHTML 1.0 Strict</a>
More information about the clouchdb-cvs
mailing list