The cl-mango Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-mango Reference Manual

This is the cl-mango Reference Manual, generated automatically by Declt version 2.4 patchlevel 1 "Will Decker" on Mon Jul 29 15:00:52 2019 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction


[[mango2.jpg]]


Mango is a client library for CouchDB 2.x
(it also happens to be the name of CouchDB's alternate query language)


* Configuration

#+BEGIN_SRC lisp -n +i
(eval-when (:compile-toplevel :load-toplevel :execute)
  (setf cl-mango:*host* "127.0.0.1")
  (setf cl-mango:*port* 5984)
  (setf cl-mango:*scheme* :http) ;; or :https
  (setf cl-mango:*username* "user")
  (setf cl-mango:*password* "password"))
#+END_SRC


* (defmango ...)

  (defmango) macro that generates an orm-ish interface to a class.


#+BEGIN_SRC lisp -n +i

(defmango person people
  ((name :json-type :string
         :json-key "name"
         :initarg :name
         :accessor person-name)
   (role :json-type :string
         :json-key "role"
         :initform "pleb"
         :initarg :role
         :accessor person-role))
=>

(progn
  (defclass person ()
    ((cl-mango::-id :initarg :-id
                    :json-type :string
                    :json-key "_id"
                    :accessor person--id)
     (cl-mango::-rev :initarg :-rev
                     :json-type :string
                     :json-key "_rev"
                     :accessor person-rev)
     (type :initarg :type
           :json-type :string
           :json-key "type"
           :initform (string-downcase "person"))
     (name :json-type :string
           :json-key "name"
           :initarg :name
           :accessor person-name)
     (role :json-type :string
           :json-key "role"
           :initform "pleb"
           :accessor person-role))
    (:metaclass json-mop:json-serializable-class))

  ;;
  ;; Important notes about this defclass expansion:
  ;;
  ;; - type is special as it tells defmodel what class query results
  ;;   are supposed to be.  It's filled in automatically.  Unless you
  ;;   want to see things explode spectacularly, don't change it.
  ;;
  ;; - person--id and person-rev are special to CouchDB.  When
  ;;   creating a new record, *don't* fill in "_rev" as CouchDB
  ;;   assigns it a new revision tag on insert and update.  The only
  ;;   time I ever find myself reading the rev slot in practice is
  ;;   when I need to delete a record, in which you provide an _id and
  ;;   _rev.
  ;;

  (defun person-get-all ())
  
  ;; 
  ;; Doesn't actually get all, only the first 100 as it uses
  ;; couchdb/database/_all_docs?include_docs=true if you truly want
  ;; all, I would suggest fetching only the "_id" of all with
  ;; (person-find) and then iterating over that list.  ie.
  ;; 
  ;; (person-find (list (cons "name" (alist-hash-table ;; this selector can b
  ;;                                  (list (cons "$exists" 't)))))
  ;;              :limit 1000000 ;; or some similarly large number.
  ;;              :fields (list "_id"))
  
  (defun person-get (id))

  ;; Fetch a single person record from the database with the given id.
  ;; CouchDB enforces that all "_id" values are unique, so there will
  ;; only ever be a single result from this call.
  
  (defun person-put (cl-mango::object))
  (defun person-update (cl-mango::object))

  ;; These two calls are identical in their implementation, however
  ;; there are two to help with the differences in adding a record and
  ;; updating a record in CouchDB.
  ;; - Adding a record without a value for "_rev" adds a new record to
  ;;   the database.
  ;; - Adding a record with a value in "_rev" means, in CouchDB terms,
  ;;   "This is a new revision of that document."  Note that if you
  ;;   update a record (ie. you have a value for "_rev") and it's not
  ;;   the latest and greatest version in the database at that time,
  ;;   you'll get a document update conflict and cl-mango will throw
  ;;   the dreaded "unexpected-http-response" condition.  So, yes,
  ;;   it's a bit redundant, but it helps me, so it's staying.
  ;;
  
  (defmacro person-find (cl-mango::query &rest cl-mango::query-args))

  ;;
  ;; This is the main interface for querying objects of your class.
  ;; It takes the same arguments as (make-selector) above and
  ;; transparently adds (cons "type" "") to all queries.
  ;;
  ;; Notes:
  ;; - (defmango) does *not* add an index for "type" in the database.
  ;;   You'll have to go in to the Mango query interface in Fauxton
  ;;   and add one.  You can also turn on cl-mango:*explain* and it
  ;;   will complain to you when you've queried against a field that
  ;;   has no index.
  ;; - If you plan to sort by a given field, you'll need to add a
  ;;   Mango index for that as well or cl-mango will throw an
  ;;   "unexpected-http-response" condition.  It's CouchDB, man, not
  ;;   me.
  ;;
  
  (person-find (list (cons "name" "bob")))
  (person-find (list (cons "role" "admin"))
               :limit 1
               :skip 100
               :stable t
               :update t
               :use-index "index-name"
               :r 2
               :fields (list "_id" "_rev")
               :sort (list (alexandria:alist-hash-table
                            (list (cons "name" "desc")))))

  ;;
  
  (defun person-delete (cl-mango::object))

  ;;
  ;; Removes the object from the database.
  ;;

  (defmacro person-create (&rest cl-mango::args))

  ;; Make a new object and add it to the database.
  ;; There's nothing special about this, and there's nothing preventing you from
  ;; using (make-instance).

  (person-put (make-instance 'person :name "bob"))

#+END_SRC



* Lower level api

  (defmango) is defined in terms of the following functions.

- make-selector selector &key limit fields sort skip

  Builds a selector for doc-find.

  [[https://docs.couchdb.org/en/2.2.0/api/database/find.html#find-selectors][Docs]]


#+BEGIN_SRC lisp -n +i
  (make-selector (list (cons "name" "mango"))
                 :limit 10
                 :fields (list "_id" "_rev")
                 :sort '(cons "name" "desc")
                 :skip 100)
#+END_SRC


- doc-find database selector

  [[https://docs.couchdb.org/en/2.2.0/api/database/find.html][Docs]]

  Execute a query against .

#+BEGIN_SRC lisp -n +i
  (doc-find "test" (make-selector (list (cons "name" "me")))
#+END_SRC

- doc-get database document-id

  Get a single document by the ~_id~.

#+BEGIN_SRC lisp -n +i
  (doc-get "test" "")
#+END_SRC

- doc-delete database document-id document-rev

  Delete a single document.

- doc-put database json-string

  Insert a single document.

#+BEGIN_SRC lisp -n +i
;; Assuming you use yason, but as long as the
;; string is well formed JSON, you can use
;; whatever library you want.
(doc-put "test" (with-output-to-string (sink)
                  (yason:encode
                    (list (cons "name" "me")
                          (cons "something" "something else"))
                    sink)))
#+END_SRC


- query-view database view index &key parameters

[[https://docs.couchdb.org/en/2.2.0/ddocs/views/index.html?highlight=views][Docs]]

#+BEGIN_SRC lisp
(query-view "test" "reports" "by-person" (list (cons "uid" 12")))
#+END_SRC


* Issues, Project Page, etc.

[[https://github.com/cmoore/cl-mango][See github]]



Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 cl-mango

Author

Clint Moore <clint@ivy.io>

License

BSD3

Description

A minimalist CouchDB 2.x database client.

Dependencies
Source

cl-mango.asd (file)

Component

cl-mango.lisp (file)


Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 cl-mango.asd

Location

cl-mango.asd

Systems

cl-mango (system)


Previous: , Up: Lisp files   [Contents][Index]

3.1.2 cl-mango/cl-mango.lisp

Parent

cl-mango (system)

Location

cl-mango.lisp

Packages

cl-mango

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 cl-mango

Source

cl-mango.lisp (file)

Nicknames
Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Special variables

Special Variable: *explain*
Package

cl-mango

Source

cl-mango.lisp (file)

Special Variable: *host*
Package

cl-mango

Source

cl-mango.lisp (file)

Special Variable: *password*
Package

cl-mango

Source

cl-mango.lisp (file)

Special Variable: *port*
Package

cl-mango

Source

cl-mango.lisp (file)

Special Variable: *scheme*
Package

cl-mango

Source

cl-mango.lisp (file)

Special Variable: *username*
Package

cl-mango

Source

cl-mango.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Macros

Macro: couch-query DATABASE SELECTOR &rest ARGS
Package

cl-mango

Source

cl-mango.lisp (file)

Macro: defmango NAME DATABASE SLOT-DEFINITIONS
Package

cl-mango

Source

cl-mango.lisp (file)

Macro: make-selector SELECTOR &key LIMIT FIELDS SORT SKIP STALE USE-INDEX R BOOKMARK UPDATE STABLE EXECUTION-STATS
Package

cl-mango

Source

cl-mango.lisp (file)

Macro: query-view DB VIEW INDEX PARAMETERS
Package

cl-mango

Source

cl-mango.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Functions

Function: bulk-docs DB BUNDLE
Package

cl-mango

Source

cl-mango.lisp (file)

Function: doc-batch-put DB BUNDLE
Package

cl-mango

Source

cl-mango.lisp (file)

Function: doc-delete DB DOCID REVISION
Package

cl-mango

Source

cl-mango.lisp (file)

Function: doc-find DB QUERY
Package

cl-mango

Source

cl-mango.lisp (file)

Function: doc-get DB DOCID
Package

cl-mango

Source

cl-mango.lisp (file)

Function: doc-get-all DB &key ALL-DOCS
Package

cl-mango

Source

cl-mango.lisp (file)

Function: doc-put DB BUNDLE
Package

cl-mango

Source

cl-mango.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.4 Conditions

Condition: unexpected-http-response ()
Package

cl-mango

Source

cl-mango.lisp (file)

Direct superclasses

condition (condition)

Direct methods
Direct slots
Slot: status-code
Initargs

:status-code

Initform

(quote nil)

Readers

status-code (generic function)

Slot: status-body
Initargs

:body

Initform

(quote nil)

Readers

status-body (generic function)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Macros

Macro: couchdb-request PATH &key PARAMETERS CONTENT METHOD CONTENT-TYPE ACCEPT PRESERVE-URI
Package

cl-mango

Source

cl-mango.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: %json-to-clos BUNDLE CLASS &key DOC-NAME
Package

cl-mango

Source

cl-mango.lisp (file)

Function: allowed-slot-p CLASS NAME
Package

cl-mango

Source

cl-mango.lisp (file)

Function: make-request-uri REQ-PATH
Package

cl-mango

Source

cl-mango.lisp (file)

Function: mango-find DB CLASS QUERY
Package

cl-mango

Source

cl-mango.lisp (file)

Function: mango-get-all DB CLASS
Package

cl-mango

Source

cl-mango.lisp (file)

Function: mango-update DB OBJECT
Package

cl-mango

Source

cl-mango.lisp (file)

Function: symb A B
Package

cl-mango

Source

cl-mango.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Generic functions

Generic Function: status-body CONDITION
Package

cl-mango

Methods
Method: status-body (CONDITION unexpected-http-response)
Source

cl-mango.lisp (file)

Generic Function: status-code CONDITION
Package

cl-mango

Methods
Method: status-code (CONDITION unexpected-http-response)
Source

cl-mango.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
cl-mango.asd: The cl-mango<dot>asd file
cl-mango/cl-mango.lisp: The cl-mango/cl-mango<dot>lisp file

F
File, Lisp, cl-mango.asd: The cl-mango<dot>asd file
File, Lisp, cl-mango/cl-mango.lisp: The cl-mango/cl-mango<dot>lisp file

L
Lisp File, cl-mango.asd: The cl-mango<dot>asd file
Lisp File, cl-mango/cl-mango.lisp: The cl-mango/cl-mango<dot>lisp file

Jump to:   C   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   %  
A   B   C   D   F   G   M   Q   S  
Index Entry  Section

%
%json-to-clos: Internal functions

A
allowed-slot-p: Internal functions

B
bulk-docs: Exported functions

C
couch-query: Exported macros
couchdb-request: Internal macros

D
defmango: Exported macros
doc-batch-put: Exported functions
doc-delete: Exported functions
doc-find: Exported functions
doc-get: Exported functions
doc-get-all: Exported functions
doc-put: Exported functions

F
Function, %json-to-clos: Internal functions
Function, allowed-slot-p: Internal functions
Function, bulk-docs: Exported functions
Function, doc-batch-put: Exported functions
Function, doc-delete: Exported functions
Function, doc-find: Exported functions
Function, doc-get: Exported functions
Function, doc-get-all: Exported functions
Function, doc-put: Exported functions
Function, make-request-uri: Internal functions
Function, mango-find: Internal functions
Function, mango-get-all: Internal functions
Function, mango-update: Internal functions
Function, symb: Internal functions

G
Generic Function, status-body: Internal generic functions
Generic Function, status-code: Internal generic functions

M
Macro, couch-query: Exported macros
Macro, couchdb-request: Internal macros
Macro, defmango: Exported macros
Macro, make-selector: Exported macros
Macro, query-view: Exported macros
make-request-uri: Internal functions
make-selector: Exported macros
mango-find: Internal functions
mango-get-all: Internal functions
mango-update: Internal functions
Method, status-body: Internal generic functions
Method, status-code: Internal generic functions

Q
query-view: Exported macros

S
status-body: Internal generic functions
status-body: Internal generic functions
status-code: Internal generic functions
status-code: Internal generic functions
symb: Internal functions

Jump to:   %  
A   B   C   D   F   G   M   Q   S  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*explain*: Exported special variables
*host*: Exported special variables
*password*: Exported special variables
*port*: Exported special variables
*scheme*: Exported special variables
*username*: Exported special variables

S
Slot, status-body: Exported conditions
Slot, status-code: Exported conditions
Special Variable, *explain*: Exported special variables
Special Variable, *host*: Exported special variables
Special Variable, *password*: Exported special variables
Special Variable, *port*: Exported special variables
Special Variable, *scheme*: Exported special variables
Special Variable, *username*: Exported special variables
status-body: Exported conditions
status-code: Exported conditions

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   P   S   U  
Index Entry  Section

C
cl-mango: The cl-mango system
cl-mango: The cl-mango package
Condition, unexpected-http-response: Exported conditions

P
Package, cl-mango: The cl-mango package

S
System, cl-mango: The cl-mango system

U
unexpected-http-response: Exported conditions

Jump to:   C   P   S   U