You can edit this page using wiki syntax for markup.

Article contents:== Outdated egg! This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for [[/eggref/5/couchdb|the CHICKEN 5 version of this egg]], if it exists. If it does not exist, there may be equivalent functionality provided by another egg; have a look at the [[https://wiki.call-cc.org/chicken-projects/egg-index-5.html|egg index]]. Otherwise, please consider porting this egg to the current version of CHICKEN. [[tags: egg]] [[toc:]] == couchdb === Introduction [[http://couchdb.apache.org/|Apache CouchDB]] is a document-oriented database that can be queried and indexed in a MapReduce fashion using JavaScript. CouchDB also offers incremental replication with bi-directional conflict detection and resolution. The couchdb egg provides a scheme interface to couchdb's RESTful JSON API. If you are looking for a method of writing couchdb views, i.e server side code in scheme see the [[couchdb-view-server]] egg. === Requirements [[http-client]] [[intarweb]] [[json]] [[uri-common]] [[defstruct]] === Documentation As said above a CouchDB server will use the [[http://json.org|JSON]] format for encoding responses. The [[json]] egg manages the marshalling and unmarshalling. See there for the correct type conversions. As a convenience function ''json-ref'' is provided by this egg. Querys to the database are encoded in URIs. Depending on the setup of the CouchDB server username and password may have to be encoded in the URI. This applys to database creation / deletion mostly. ==== Error handling All procedures return ''#f'' on error. The last error is provided with the utility procedure ''last-error''. ==== CouchDB connection procedures For identifying connections a connection record has to be created first. ===== make-connection <procedure>(make-connection database: DATABASE-STRING server: URI-REFERENCE)</procedure> Creates a connection record for the desired ''DATABASE-STRING'' on the CouchDB located at the specified URI reference. Note: You will need uri-common's uri-reference. Example: <enscript higlight="scheme"> (define conn (make-connection server: (uri-reference "http://localhost:5984/") database: "chicken-test-couchdb")) </enscript> ===== Connection accessors / setters <procedure>(connection-uri connection)</procedure> <procedure>(connection-database connection)</procedure> Accessors for the CouchDB egg connection record. <procedure>(update-connection connection #!key database connection)</procedure> Update function for the connection record. ===== get-server-info <procedure>(get-server-info connection)</procedure> Returns the couchdb version information as the json egg parses the response. <enscript hilight="scheme> CSI> (get-server-info (make-connection server: (uri-reference "http://localhost:5984/"))) #(("couchdb" . "Welcome") ("version" . "0.11.0")) </enscript> ==== Database handling <procedure>(create-database connection)</procedure> Creates a database as specified in the connection record ''connection''. Use ''(make-connection database-string couchdb-uri-string)'' to create a connection object. Returns #t or #f. Verbose error message can be retrieved with ''last-error'. <procedure>(delete-database connection)</procedure> Deletes the database as specified in the connection record ''connection''. Use ''(make-connection database-string couchdb-uri-string)'' to create a connection object. Returns #t or #f. Verbose error message can be retrieved with ''last-error'. <procedure>(get-database-info connection)</procedure> Returns the database information for a given connection record. Use ''(make-connection database-string couchdb-uri-string)'' to create a connection record. ==== Document handling The central entity in a CouchDB is a so called document. A CouchDB document is an object that consists of named fields. Field values may be strings, numbers, dates, or even ordered lists and associative maps, all encoded in JSON. However there are at least two mandatory fields in each document: ; ''id'' : unique id within the database ; ''rev'' : revision of that document ===== Document datatype <procedure>(make-document id revision #!optional (body '#()))</procedure> The couchdb uses a record to represent the contents of a document. The mandatory elements have distinct slots whereas the rest of the fiels is accessible in a vector called ''body''. <procedure>(document? doc)</procedure> Type checking predicate for a document record. <procedure>(document-id doc)</procedure> <procedure>(document-rev doc)</procedure> <procedure>(document-body doc)</procedure> <procedure>(update-document doc #!key id rev body)</procedure> Accessors for the ''id'' ''rev'' and ''body'' slots of a document record. <procedure>(document-attribute? document name)</procedure> Predicate indicating wether ''document'' does contain a attribute ''name''. <procedure>(document-attribute document name)</procedure> Returns the value for ''name'' if it is contained in ''document''. ===== Document retrieval / storage <procedure>(get-document connection id)</procedure> Requests the document with id ''id'' and returns that or #f. <procedure>(save-document connection document)</procedure> Stores the document in the database and returns it with updated id and revision attributes. If the document does not exist in the database it is created. <procedure>(delete-document connection document)</procedure> Deletes the document form the database. <procedure>(get-all-documents connection #!optional (query '()))</procedure> Returns all documents in the database. The output can be quite large! You can pass any valid query URI part for the optional ''query'' parameter. ==== View Handling <procedure>(get-view connection view-string #!optional (query '()))</procedure> Returns the results of the requested ''view''. View can be either a string depicting an explicit path or a list of strings which in the latter case is treated as ''(list design-document view-name)''. The query parameter is an alist containing ''(parameter-name . value)'' pairs. <Procedure>(send-temp-view-request connection view method #!key query)</procedure> ==== Utility functions <procedure>(json-ref name object)</procedure> Retrieves a field ''name'' from a JSON object ''object''. This is a convenience function to ease the access of the vector / hash-table mix the json egg generates. <parameter>(last-error #f)</parameter> Will be set on errors. Returns a descriptive error string. === Author [[/users/Moritz-Heidkamp|Moritz Heidkamp]] === License Apache CouchDB client library Copyright (C) 2009 Moritz Heidkamp This program is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You can find a copy of the GNU Lesser General Public License at http://www.gnu.org/licenses/ === Version History ; 0.1 : initial release Description of your changes:

I would like to authenticate

Spam control

What do you get when you add 17 to 16?