The cl-bson Reference Manual

Table of Contents

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

The cl-bson Reference Manual

This is the cl-bson Reference Manual, version 0.1.0, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 03:09:26 2018 GMT+0.


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

1 Introduction

cl-BSON

Quicklisp Build Status Circle CI Coverage Status

Inspired by cl-mongo and mongo-cl-driver.

API and documentation generated by the (awesome) Codex.

Usage

Setup

* (ql:quickload :cl-bson)
; => (:CL-BSON)
* (in-package :cl-bson)
; => #<PACKAGE "CL-BSON">
* (named-readtables:in-readtable bson-syntax)
; => big alist of readtables...
* (enable-printers)
; => NIL

;; Obs.: all read macros are just optional ;)

Main API

The main functions are encode and decode:

* (decode (encode (make-document)))
; => #d("_id" #i(057DCB554D4143C13A5FBB91))
* (encode #d(:a-key 'a-value))
; => #(24 0 0 0 2 65 45 75 69 89 0 7 0 0 0 65 45 86 65 76 85 69 0 0)
* (decode *)
; => #d("A-KEY" "A-VALUE")

* (encode #d(:keyword-key :keyword-value
             'symbol-key 'symbol-value
             "string-key" "string-value"
             "will be coerced to double" 1.5
             "will stay as double" 1.5d0
             "embedded document" #d("one more level" #d("i believe" "that's enough"))
             "one more" (let ((doc (make-document)))
                          (add-element doc "document" "example"))
             "sequence" #(1 2 3)
             "vector" #(1 2 3)
             "list" '(1 2 3)
             "regex" #/\d+\/$/li 
             "binary data" (make-instance '<binary-data>
                                          :octets (fast-io:make-octet-vector 10))
             "javascript code" (make-instance '<javascript> :code "var example = 1;")
             "javascript code with scope" (make-instance '<javascript>
                                                         :code "var example = inScope;"
                                                         :scope #d("inScope" 10))
             "object-id" (make-instance '<object-id>)
             "boolean true" t
             "boolean false" nil
             "null value" nil
             "32 bit integer" 123
             "64 bit integer" 1234567890987654321
             "local-time:timestamp" (local-time:now)))
; => #(174 2 0 0 2 75 69 89 87 79 82 68 45 75 69 89 0 14 0 0 0 75 69 89 87 79 82 68 45 86 65 76 85 69 0 2 83 89 77 66 79 76 45 75 69 89 0 13 0 0 0 83 89 77 66 79 76
       45 86 65 76 85 69 0 2 115 116 114 105 110 103 45 107 101 121 0 13 0 0 0 115 116 114 105 110 103 45 118 97 108 117 101 0 1 119 105 108 108 32 98 101 32 99 111
       101 114 99 101 100 32 116 111 32 100 111 117 98 108 101 0 0 0 0 0 0 0 248 63 1 119 105 108 108 32 115 116 97 121 32 97 115 32 100 111 117 98 108 101 0 0 0 0
       0 0 0 248 63 3 101 109 98 101 100 100 101 100 32 100 111 99 117 109 101 110 116 0 55 0 0 0 3 111 110 101 32 109 111 114 101 32 108 101 118 101 108 0 34 0 0 0
       2 105 32 98 101 108 105 101 118 101 0 14 0 0 0 116 104 97 116 39 115 32 101 110 111 117 103 104 0 0 0 3 111 110 101 32 109 111 114 101 0 44 0 0 0 7 95 105
       100 0 117 125 203 85 77 65 67 193 58 98 187 145 2 100 111 99 117 109 101 110 116 0 8 0 0 0 101 120 97 109 112 108 101 0 0 4 115 101 113 117 101 110 99 101 0
       26 0 0 0 16 48 0 1 0 0 0 16 49 0 2 0 0 0 16 50 0 3 0 0 0 0 4 118 101 99 116 111 114 0 26 0 0 0 16 48 0 1 0 0 0 16 49 0 2 0 0 0 16 50 0 3 0 0 0 0 4 108 105
       115 116 0 26 0 0 0 16 48 0 1 0 0 0 16 49 0 2 0 0 0 16 50 0 3 0 0 0 0 11 114 101 103 101 120 0 92 100 43 92 47 36 0 105 108 0 5 98 105 110 97 114 121 32 100
       97 116 97 0 10 0 0 0 0 0 0 0 0 0 0 0 0 0 0 13 106 97 118 97 115 99 114 105 112 116 32 99 111 100 101 0 17 0 0 0 118 97 114 32 101 120 97 109 112 108 101 32
       61 32 49 59 0 15 106 97 118 97 115 99 114 105 112 116 32 99 111 100 101 32 119 105 116 104 32 115 99 111 112 101 0 46 0 0 0 0 118 97 114 32 101 120 97 109
       112 108 101 32 61 32 105 110 83 99 111 112 101 59 0 18 0 0 0 16 105 110 83 99 111 112 101 0 10 0 0 0 0 7 111 98 106 101 99 116 45 105 100 0 117 125 203 85 77
       65 67 193 58 99 187 145 8 98 111 111 108 101 97 110 32 116 114 117 101 0 1 8 98 111 111 108 101 97 110 32 102 97 108 115 101 0 0 8 110 117 108 108 32 118 97
       108 117 101 0 0 16 51 50 32 98 105 116 32 105 110 116 101 103 101 114 0 123 0 0 0 18 54 52 32 98 105 116 32 105 110 116 101 103 101 114 0 177 28 108 177 244
       16 34 17 9 108 111 99 97 108 45 116 105 109 101 58 116 105 109 101 115 116 97 109 112 0 124 17 226 34 79 1 0 0 0)

* (decode *)
; => #d("KEYWORD-KEY" "KEYWORD-VALUE"
        "SYMBOL-KEY" "SYMBOL-VALUE"
        "string-key" "string-value"
        "will be coerced to double" 1.5d0
        "will stay as double" 1.5d0
        "embedded document" #d("one more level" #d("i believe" "that's enough"))
        "one more" #d("document" "example")
        "sequence" #(1 2 3)
        "vector" #(1 2 3)
        "list" #(1 2 3)
        "regex" #/\d+\/$/il
        "binary data" #<<BINARY-DATA> {100D002AF3}>
        "javascript code" #<<JAVASCRIPT> {100D074A43}>
        "javascript code with scope" #<<JAVASCRIPT> {100D0E5613}>
        "object-id" #i(C92F7555616E64776371F874)
        "boolean true" T
        "boolean false" NIL
        "null value" NIL
        "32 bit integer" 123
        "64 bit integer" 1234567890987654321
        "local-time:timestamp" @2015-06-08T09:43:14.232000-03:00)

Examples from the FAQ:

;; Original: {"hello": "world"}
* (encode #d("hello" "world"))
; => #(22 0 0 0 2 104 101 108 108 111 0 5 0 0 0 119 111 114 108 100 0 0)

;; Since the example is in hexadecimal base:
* (map 'vector (lambda (_)
                 (let ((*print-base* 16))
                   (princ-to-string _)))
       *)

;; Output:
#("16" "0" "0" "0"
  "2"
  "68" "65" "6C" "6C" "6F" "0"
  "6" "0" "0" "0" "77" "6F" "72" "6C" "64" "0"
  "0")

\x16\x00\x00\x00                   // total document size
\x02                               // 0x02 = type String
hello\x00                          // field name
\x06\x00\x00\x00world\x00          // field value
\x00                               // 0x00 = type EOO ('end of object')


;; Original: {"BSON": ["awesome", 5.05, 1986]}
* (encode #d("BSON" #("awesome" 5.05d0 1986)))
#(49 0 0 0 4 66 83 79 78 0 38 0 0 0 2 48 0 8 0 0 0 97 119 101 115 111 109 101 0 1 49 0 51 51 51 51 51 51 20 64 16 50 0 194 7 0 0 0 0)

;; To hexadecimal:
* (map 'vector (lambda (_)
                 (let ((*print-base* 16))
                   (princ-to-string _)))
       *)

;; Output:
#("31" "0" "0" "0"
  "4" "42" "53" "4F" "4E" "0"
  "26" "0" "0" "0"
  "2" "30" "0" "8" "0" "0" "0" "61" "77" "65" "73" "6F" "6D" "65" "0"
  "1" "31" "0" "33" "33" "33" "33" "33" "33" "14" "40"
  "10" "32" "0" "C2" "7" "0" "0"
  "0"
  "0")

\x31\x00\x00\x00
\x04BSON\x00
\x26\x00\x00\x00
\x02\x30\x00\x08\x00\x00\x00awesome\x00
\x01\x31\x00\x33\x33\x33\x33\x33\x33\x14\x40
\x10\x32\x00\xc2\x07\x00\x00
\x00
\x00

Check the detailed explanation of the last example.

Dependencies

This library depends on:

The test package uses the prove test library, and the documentation uses the Codex documentation library.

Installation

(ql:quickload :cl-bson)

Bugs

If you find any bug or inconsistency in the code, or if you find it too hard to use, please, feel free to open an issue.

Tests

This library is tested under SBCL and CCL Common Lisp implementations.

To run all the defined tests, use:

* (asdf:test-system :cl-bson)
; prints lots of (colorful) stuff...
; => T

Tests are ran with Travis CI and Circle CI using cl-travis, CIM, cl-coveralls and Roswell. Check it out!

Author

License

LLGPL.


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-bson

Maintainer

André Miranda

Author

André Miranda

Contact

andremiramor@gmail.com

Home Page

https://euandreh.github.io/cl-BSON

Source Control

(:git "git@github.com:euandreh/cl-bson.git")

Bug Tracker

https://github.com/EuAndreh/cl-bson/issues

License

LLGPL

Description

BSON encoder/decoder for Common Lisp.

Long Description

# cl-BSON
[![Quicklisp](http://quickdocs.org/badge/cl-bson.svg)](http://quickdocs.org/cl-bson/)
[![Build Status](https://travis-ci.org/EuAndreh/cl-BSON.svg?branch=master)](https://travis-ci.org/EuAndreh/cl-BSON)
[![Circle CI](https://circleci.com/gh/EuAndreh/cl-BSON.svg?style=svg)](https://circleci.com/gh/EuAndreh/cl-BSON/)
[![Coverage Status](https://coveralls.io/repos/EuAndreh/cl-bson/badge.svg?branch=master)](https://coveralls.io/r/EuAndreh/cl-bson?branch=master)

Inspired by [cl-mongo](https://github.com/fons/cl-mongo) and [mongo-cl-driver](https://github.com/archimag/mongo-cl-driver/tree/master/bson).

[API and documentation](https://euandreh.github.io/cl-BSON) generated by the (awesome) [Codex](https://github.com/CommonDoc/codex).

## Usage
### Setup
“‘lisp
* (ql:quickload :cl-bson)
; => (:CL-BSON)
* (in-package :cl-bson)
; => #<PACKAGE "CL-BSON">
* (named-readtables:in-readtable bson-syntax)
; => big alist of readtables...
* (enable-printers)
; => NIL

;; Obs.: all read macros are just optional ;)
“‘

### Main API
The main functions are ‘encode‘ and ‘decode‘:
“‘lisp
* (decode (encode (make-document)))
; => #d("_id" #i(057DCB554D4143C13A5FBB91))
* (encode #d(:a-key ’a-value))
; => #(24 0 0 0 2 65 45 75 69 89 0 7 0 0 0 65 45 86 65 76 85 69 0 0)
* (decode *)
; => #d("A-KEY" "A-VALUE")

* (encode #d(:keyword-key :keyword-value
’symbol-key ’symbol-value
"string-key" "string-value"
"will be coerced to double" 1.5
"will stay as double" 1.5d0
"embedded document" #d("one more level" #d("i believe" "that’s enough"))
"one more" (let ((doc (make-document)))
(add-element doc "document" "example"))
"sequence" #(1 2 3)
"vector" #(1 2 3)
"list" ’(1 2 3)
"regex" #/\d+\/$/li
"binary data" (make-instance ’<binary-data>
:octets (fast-io:make-octet-vector 10))
"javascript code" (make-instance ’<javascript> :code "var example = 1;")
"javascript code with scope" (make-instance ’<javascript>
:code "var example = inScope;"
:scope #d("inScope" 10))
"object-id" (make-instance ’<object-id>)
"boolean true" t
"boolean false" nil
"null value" nil
"32 bit integer" 123
"64 bit integer" 1234567890987654321
"local-time:timestamp" (local-time:now)))
; => #(174 2 0 0 2 75 69 89 87 79 82 68 45 75 69 89 0 14 0 0 0 75 69 89 87 79 82 68 45 86 65 76 85 69 0 2 83 89 77 66 79 76 45 75 69 89 0 13 0 0 0 83 89 77 66 79 76
45 86 65 76 85 69 0 2 115 116 114 105 110 103 45 107 101 121 0 13 0 0 0 115 116 114 105 110 103 45 118 97 108 117 101 0 1 119 105 108 108 32 98 101 32 99 111
101 114 99 101 100 32 116 111 32 100 111 117 98 108 101 0 0 0 0 0 0 0 248 63 1 119 105 108 108 32 115 116 97 121 32 97 115 32 100 111 117 98 108 101 0 0 0 0
0 0 0 248 63 3 101 109 98 101 100 100 101 100 32 100 111 99 117 109 101 110 116 0 55 0 0 0 3 111 110 101 32 109 111 114 101 32 108 101 118 101 108 0 34 0 0 0
2 105 32 98 101 108 105 101 118 101 0 14 0 0 0 116 104 97 116 39 115 32 101 110 111 117 103 104 0 0 0 3 111 110 101 32 109 111 114 101 0 44 0 0 0 7 95 105
100 0 117 125 203 85 77 65 67 193 58 98 187 145 2 100 111 99 117 109 101 110 116 0 8 0 0 0 101 120 97 109 112 108 101 0 0 4 115 101 113 117 101 110 99 101 0
26 0 0 0 16 48 0 1 0 0 0 16 49 0 2 0 0 0 16 50 0 3 0 0 0 0 4 118 101 99 116 111 114 0 26 0 0 0 16 48 0 1 0 0 0 16 49 0 2 0 0 0 16 50 0 3 0 0 0 0 4 108 105
115 116 0 26 0 0 0 16 48 0 1 0 0 0 16 49 0 2 0 0 0 16 50 0 3 0 0 0 0 11 114 101 103 101 120 0 92 100 43 92 47 36 0 105 108 0 5 98 105 110 97 114 121 32 100
97 116 97 0 10 0 0 0 0 0 0 0 0 0 0 0 0 0 0 13 106 97 118 97 115 99 114 105 112 116 32 99 111 100 101 0 17 0 0 0 118 97 114 32 101 120 97 109 112 108 101 32
61 32 49 59 0 15 106 97 118 97 115 99 114 105 112 116 32 99 111 100 101 32 119 105 116 104 32 115 99 111 112 101 0 46 0 0 0 0 118 97 114 32 101 120 97 109
112 108 101 32 61 32 105 110 83 99 111 112 101 59 0 18 0 0 0 16 105 110 83 99 111 112 101 0 10 0 0 0 0 7 111 98 106 101 99 116 45 105 100 0 117 125 203 85 77
65 67 193 58 99 187 145 8 98 111 111 108 101 97 110 32 116 114 117 101 0 1 8 98 111 111 108 101 97 110 32 102 97 108 115 101 0 0 8 110 117 108 108 32 118 97
108 117 101 0 0 16 51 50 32 98 105 116 32 105 110 116 101 103 101 114 0 123 0 0 0 18 54 52 32 98 105 116 32 105 110 116 101 103 101 114 0 177 28 108 177 244
16 34 17 9 108 111 99 97 108 45 116 105 109 101 58 116 105 109 101 115 116 97 109 112 0 124 17 226 34 79 1 0 0 0)

* (decode *)
; => #d("KEYWORD-KEY" "KEYWORD-VALUE"
"SYMBOL-KEY" "SYMBOL-VALUE"
"string-key" "string-value"
"will be coerced to double" 1.5d0
"will stay as double" 1.5d0
"embedded document" #d("one more level" #d("i believe" "that’s enough"))
"one more" #d("document" "example")
"sequence" #(1 2 3)
"vector" #(1 2 3)
"list" #(1 2 3)
"regex" #/\d+\/$/il
"binary data" #<<BINARY-DATA> {100D002AF3}>
"javascript code" #<<JAVASCRIPT> {100D074A43}>
"javascript code with scope" #<<JAVASCRIPT> {100D0E5613}>
"object-id" #i(C92F7555616E64776371F874)
"boolean true" T
"boolean false" NIL
"null value" NIL
"32 bit integer" 123
"64 bit integer" 1234567890987654321
"local-time:timestamp" @2015-06-08T09:43:14.232000-03:00)
“‘

Examples from the [FAQ](http://bsonspec.org/faq.html):
“‘lisp
;; Original: {"hello": "world"}
* (encode #d("hello" "world"))
; => #(22 0 0 0 2 104 101 108 108 111 0 5 0 0 0 119 111 114 108 100 0 0)

;; Since the example is in hexadecimal base:
* (map ’vector (lambda (_)
(let ((*print-base* 16))
(princ-to-string _)))
*)

;; Output:
#("16" "0" "0" "0"
"2"
"68" "65" "6C" "6C" "6F" "0"
"6" "0" "0" "0" "77" "6F" "72" "6C" "64" "0"
"0")

\x16\x00\x00\x00 // total document size
\x02 // 0x02 = type String
hello\x00 // field name
\x06\x00\x00\x00world\x00 // field value
\x00 // 0x00 = type EOO (’end of object’)

;; Original: {"BSON": ["awesome", 5.05, 1986]}
* (encode #d("BSON" #("awesome" 5.05d0 1986)))
#(49 0 0 0 4 66 83 79 78 0 38 0 0 0 2 48 0 8 0 0 0 97 119 101 115 111 109 101 0 1 49 0 51 51 51 51 51 51 20 64 16 50 0 194 7 0 0 0 0)

;; To hexadecimal:
* (map ’vector (lambda (_)
(let ((*print-base* 16))
(princ-to-string _)))
*)

;; Output:
#("31" "0" "0" "0"
"4" "42" "53" "4F" "4E" "0"
"26" "0" "0" "0"
"2" "30" "0" "8" "0" "0" "0" "61" "77" "65" "73" "6F" "6D" "65" "0"
"1" "31" "0" "33" "33" "33" "33" "33" "33" "14" "40"
"10" "32" "0" "C2" "7" "0" "0"
"0"
"0")

\x31\x00\x00\x00
\x04BSON\x00
\x26\x00\x00\x00
\x02\x30\x00\x08\x00\x00\x00awesome\x00
\x01\x31\x00\x33\x33\x33\x33\x33\x33\x14\x40
\x10\x32\x00\xc2\x07\x00\x00
\x00
\x00
“‘

Check the [detailed explanation](https://groups.google.com/d/msg/bson/8g76R0cb-CQ/DWdjQaS0tMMJ) of the last example.

## Dependencies
This library depends on:
+ [arrow-macros](https://github.com/hipeta/arrow-macros/)
+ [babel](https://common-lisp.net/project/babel/)
+ [cl-intbytes](https://github.com/EuAndreh/cl-intbytes)
+ [fast-io](https://github.com/rpav/fast-io)
+ [ieee-floats](https://github.com/marijnh/ieee-floats)
+ [let-over-lambda](https://github.com/thephoeron/let-over-lambda)
+ [local-time](https://common-lisp.net/project/local-time/)
+ [named-readtables](https://common-lisp.net/project/named-readtables/)
+ [rutils](https://github.com/vseloved/rutils)
+ [trivial-shell](https://github.com/gwkkwg/trivial-shell)

The test package uses the [prove](https://github.com/fukamachi/prove) test library, and the documentation uses the [Codex](https://github.com/CommonDoc/codex) documentation library.

## Installation
“‘lisp
(ql:quickload :cl-bson)
“‘

## Bugs
If you find any bug or inconsistency in the code, or if you find it too hard to use, please, feel free to open an issue.

## Tests
This library is tested under [SBCL](http://www.sbcl.org/) and [CCL](http://ccl.clozure.com/) Common Lisp implementations.

To run all the defined tests, use:
“‘lisp
* (asdf:test-system :cl-bson)
; prints lots of (colorful) stuff...
; => T
“‘
Tests are ran with [Travis CI](https://travis-ci.org/EuAndreh/cl-BSON) and [Circle CI](https://circleci.com/gh/EuAndreh/cl-BSON) using [cl-travis](https://github.com/luismbo/cl-travis), [CIM](https://github.com/KeenS/CIM), [cl-coveralls](https://github.com/fukamachi/cl-coveralls) and [Roswell](https://github.com/snmsts/roswell). Check it out!

## Author
+ [André Miranda](https://github.com/EuAndreh)

## License
[LLGPL](https://tldrlegal.com/license/lisp-lesser-general-public-license#fulltext).

Version

0.1.0

Dependencies
Source

cl-bson.asd (file)

Components

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

3 Modules

Modules are listed depth-first from the system components tree.


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

3.1 cl-bson/src

Parent

cl-bson (system)

Location

src/

Components

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

4 Files

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


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

4.1 Lisp


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

4.1.1 cl-bson.asd

Location

cl-bson.asd

Systems

cl-bson (system)


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

4.1.2 cl-bson/src/types.lisp

Parent

src (module)

Location

src/types.lisp

Packages

cl-bson.types

Exported Definitions
Internal Definitions

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

4.1.3 cl-bson/src/readtable.lisp

Parent

src (module)

Location

src/readtable.lisp

Packages

cl-bson.readtable

Exported Definitions
Internal Definitions

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

4.1.4 cl-bson/src/encode.lisp

Parent

src (module)

Location

src/encode.lisp

Packages

cl-bson.encode

Exported Definitions
Internal Definitions

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

4.1.5 cl-bson/src/decode.lisp

Parent

src (module)

Location

src/decode.lisp

Packages

cl-bson.decode

Exported Definitions
Internal Definitions

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

4.1.6 cl-bson/src/cl-bson.lisp

Parent

src (module)

Location

src/cl-bson.lisp

Packages

cl-bson


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

4.2 Other


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

4.2.1 cl-bson/README.md

Dependency

src (module)

Parent

cl-bson (system)

Location

README.md


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

5 Packages

Packages are listed by definition order.


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

5.1 cl-bson.types

The @link[uri="http://bsonspec.org/spec.html"](BSON specification) has a few more types than the built-in Common Lisp types. @c(cl-bson) defines classes for those types.

The @c(cl-bson.readtable) package defines the following BSON types/classes:
@begin(list)
@item(@c(<binary-data>) for representing any subtype of the BSON binary data. LINK)
@item(@c(<document>) main class for encoding/decoding. The @c(<document>) class is a wrapper around a @c(hash-table) with custom methods.)
@item(@c(<javascript>) for representing both "JavaScript code" (@c(#x??)) and "JavaScript code with scope" (@c(#x!!)). The @c(<javascript>) class has two slots, @c(code) and @c(scope), so the @c(<javascript>) object will behave differently if the @c(scope) slot is bound or not.) @item(@c(<mongo-timestamp>) for representing Timestamp LINK that MongoDB uses internally.)
@item(@c(<object-id>) for representing the MongoDB ObjectId. LINK)
@item(@c(<regex>) for representing a regular expression in the document. The @c(<regex>) class has two slots: the actual @c(pattern) and some @c(options).)
@end(list)

It exports all classes slot accessors symbols and classes symbols.

It also exports two custom types: @c(octet) and @c(octets-array).

Source

types.lisp (file)

Use List

common-lisp

Used By List

cl-bson

Exported Definitions
Internal Definitions

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

5.2 cl-bson.readtable

Package for optional BSON read-print functionality. Uses @link[uri="https://common-lisp.net/project/named-readtables/"](named-readtables) for @cl:spec(*readtable*) manipulation.

Defines read-macros for @c(#d()) (literal @c(<document>)) and for @c(#i()) (literal @c(<document>)).

Also defines @cl:spec(pprint)int behaviour (for consistent read-print equivalence) for @c(#d()) and @c(#i()) read-macros in the @c(bson-syntax) readtable.

All of them are just optional. If you don’t like, feel free to not use it =]

@begin(section)
@title(Usage)
@code[lang=lisp](* (make-instance ’<regex> :pattern "^abc$" :options "i")
; => #/^abc$/i
* (make-instance ’<object-id>)
; => #i(90E08055616E64726568310C67E3D1)
* (make-document)
; => #d("_id" #i(9CE08055616E64726568310C68E3D1))

* (enable-printers)
; => NIL
* (make-instance ’<regex> :pattern "^abc$" :options "i")
; => #/^abc$/i
* (make-instance ’<object-id>)
; => #i(B4E08055616E64726568310C69E3D1)
* (make-document)
; => #d("_id" #i(B8E08055616E64726568310C6AE3D1))

* (named-readtables:in-readtable bson-syntax)
; big alist of readtables
* #/asdf/li
; => #/asdf/il
* #i(B4E08055616E64726568310C69E3D1)
; => #i(B4E08055616E64726568310C69E3D1)
* #d("my" "doc")
; => #d("my" "doc")
)

Explicar sobre #d($lt 1)
@end(section)

Source

readtable.lisp (file)

Use List

common-lisp

Used By List

cl-bson

Exported Definitions
Internal Definitions

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

5.3 cl-bson.encode

This package defines the main function (@c(#’encode)) for actually converting a @c(<document>) object to @c(octets-array) and many helper functions for internal use. @c(*bson-out*) gets bound to a @c(fast-io:output-buffer) in the first to of @c(#’encode).

Source

encode.lisp (file)

Use List

common-lisp

Used By List

cl-bson

Exported Definitions
Internal Definitions

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

5.4 cl-bson.decode

This package defines the main function (@c(#’decode)) for converting an @c(octets-array) to BSON @c(<document>)s many helper functions for internal use.

Source

decode.lisp (file)

Use List

common-lisp

Used By List

cl-bson

Exported Definitions
Internal Definitions

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

5.5 cl-bson

Source

cl-bson.lisp (file)

Nickname

bson

Use List

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

6 Definitions

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


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

6.1 Exported definitions


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

6.1.1 Special variables

Special Variable: *allowed-regex-options*

List of charaters allowed in the @c(options) slot of a @c(<regex>) object.

Package

cl-bson.types

Source

types.lisp (file)

Special Variable: *bson-in*

Special var that gets bound to @c(fast-io:input-buffer) on every @c(#’decode) call. Many of the @c(#’decode-*) functions read from @c(*bson-in*) (destructively) and returns the value to be added to @c(*doc-out*).

Package

cl-bson.decode

Source

decode.lisp (file)

Special Variable: *bson-out*

Special var that gets bound to @c(fast-io:output-buffer) on every @c(#’encode) call.

Package

cl-bson.encode

Source

encode.lisp (file)

Special Variable: *bson-sequence-type*

Special variable that holds the kind of output to return when decoding a BSON array.

Package

cl-bson.decode

Source

decode.lisp (file)


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

6.1.2 Functions

Function: decode OCTETS-ARRAY

Main entry point to decode a given array. It performs the first binding of @c(*doc-out*) and call @c(#’decode-document).

Package

cl-bson.decode

Source

decode.lisp (file)

Function: decode-int32 ()

Decodes a 4 bytes integer from @c(*bson-in*).

Package

cl-bson.decode

Source

decode.lisp (file)

Function: decode-int64 ()

Decodes an 8 bytes integer from @c(*bson-in*).

Package

cl-bson.decode

Source

decode.lisp (file)

Function: disable-bson-document-printer ()

Disables the pprinter for @c(<document>) objects.

Package

cl-bson.readtable

Source

readtable.lisp (file)

Function: disable-object-id-printer ()

Disables the pprinter for @c(<object-id>) objects.

Package

cl-bson.readtable

Source

readtable.lisp (file)

Function: disable-printers ()

Disables pprinter for @c(<document>) and @c(<object-id>) objects.

Package

cl-bson.readtable

Source

readtable.lisp (file)

Function: enable-bson-document-printer ()

Enable pprinter for @c(<document>) objects.

Package

cl-bson.readtable

Source

readtable.lisp (file)

Function: enable-object-id-printer ()

Enable pprinter for @c(<object-id>) objects.

Package

cl-bson.readtable

Source

readtable.lisp (file)

Function: enable-printers ()

Enables pprinter for both @c(<document>) and @c(<object-id>) objects.

Package

cl-bson.readtable

Source

readtable.lisp (file)

Function: make-document &key _ID

Utility function to easily create @c(<document>)s already with an @c(<object-id). To create an @c(<document>) with an @cl:param(_id) from a string, use: @code[lang=lisp]((make-document :_id (string->object-id "my id string"))).

Package

cl-bson.types

Source

types.lisp (file)

Function: read-n-bytes N

Reads @cl:param(n) bytes from @c(*bson-in*).

Package

cl-bson.decode

Source

decode.lisp (file)

Function: repeated-keys-p PAIRS

Checks if any @c(key) as in @c((key value)) is repeated (tested with @cl:spec(equal) for @c(hash-table)-like string comparison) in the @cl:param(pairs) list. If @c(T), returns the repeated @c(key).

Package

cl-bson.readtable

Source

readtable.lisp (file)

Function: string->object-id STRING

Utility for instanciating an @c(<object-id>) from a given @cl:param(string). Useful for fetching documents with parameters received from HTTP requests.

@code[lang=lisp](;; without the custom pprinter:
* (string->object-id "35F97455616E6477630600D3")
; => #<<OBJECT-ID> {1008C48CE3}>

;; with the custom pprinter:
* (enable-printers)
; => NIL
* (string->object-id "35F97455616E6477630600D3")
; => #i(35F97455616E6477630600D3)
)

Package

cl-bson.types

Source

types.lisp (file)


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

6.1.3 Generic functions

Generic Function: add-element DOCUMENT KEY VALUE

Properly adds a given @cl:param(key)-@cl:param(value) pair to the @cl:param(document). The @cl:param(key) is coerced to string using the @cl:spec(string) function. The type of the @cl:param(value) must be a valid BSON supported type.

Package

cl-bson.types

Source

types.lisp (file)

Methods
Method: add-element (DOCUMENT <document>) KEY VALUE
Method: add-element (DOCUMENT <document>) KEY (VALUE symbol)
Method: add-element (DOCUMENT <document>) KEY (VALUE (eql nil))
Method: add-element (DOCUMENT <document>) KEY (VALUE (eql t))
Generic Function: code OBJECT
Generic Function: (setf code) NEW-VALUE OBJECT
Package

cl-bson.types

Methods
Method: code (<JAVASCRIPT> <javascript>)
Method: (setf code) NEW-VALUE (<JAVASCRIPT> <javascript>)

This slot holds JavaScript code as a @i(string).

Source

types.lisp (file)

Generic Function: elements OBJECT
Generic Function: (setf elements) NEW-VALUE OBJECT
Package

cl-bson.types

Methods
Method: elements (<DOCUMENT> <document>)
Method: (setf elements) NEW-VALUE (<DOCUMENT> <document>)

@c(hash-table) that holds all the the document data.

Source

types.lisp (file)

Generic Function: encode DOCUMENT

Encodes a given @cl:param(document) into an @c(octets-array) following the @link[uri="http://bsonspec.org/spec.html"](BSON specification).

Package

cl-bson.encode

Source

encode.lisp (file)

Methods
Method: encode (DOCUMENT <document>)
Generic Function: get-element DOCUMENT KEY

Gets the elements identified by @cl:param(key). @cl:param(key) is coerced to string using the @cl:spec(string).

Package

cl-bson.types

Source

types.lisp (file)

Methods
Method: get-element (DOCUMENT <document>) KEY
Generic Function: get-timestamp OBJECT-ID

Returns the timestamp portion of @cl:param(object-id) as a @c(local-time:timestamp). The @link[uri="https://common-lisp.net/project/local-time/manual.html#Types"](@c(local-time:timestamp)) is used to represent the MongoDB @link[uri="http://docs.mongodb.org/manual/reference/bson-types/#date"](Date).

Package

cl-bson.types

Source

types.lisp (file)

Methods
Method: get-timestamp (OBJECT-ID <object-id>)
Generic Function: keys DOCUMENT

Returns all keys of the @cl:param(document).

Package

cl-bson.types

Source

types.lisp (file)

Methods
Method: keys (DOCUMENT <document>)
Generic Function: mongo-time OBJECT
Generic Function: (setf mongo-time) NEW-VALUE OBJECT
Package

cl-bson.types

Methods
Method: mongo-time (<MONGO-TIMESTAMP> <mongo-timestamp>)
Method: (setf mongo-time) NEW-VALUE (<MONGO-TIMESTAMP> <mongo-timestamp>)

Array of actual @c(octets-array) that represent the @link[uri="http://docs.mongodb.org/manual/reference/bson-types/#timestamps"](Mongo Timestamp).

Source

types.lisp (file)

Generic Function: octets OBJECT
Generic Function: (setf octets) NEW-VALUE OBJECT
Package

cl-bson.types

Methods
Method: octets (<BINARY-DATA> <binary-data>)
Method: (setf octets) NEW-VALUE (<BINARY-DATA> <binary-data>)

This slot holds the actual binary data.

Source

types.lisp (file)

Method: octets (<OBJECT-ID> <object-id>)
Method: (setf octets) NEW-VALUE (<OBJECT-ID> <object-id>)

Array of actual OCTETS-ARRAY that represent the @link[uri="http://docs.mongodb.org/manual/reference/object-id/"](MongoDB ObjectId). Value generated by @c(#’generate-object-id).

Source

types.lisp (file)

Generic Function: options OBJECT
Package

cl-bson.types

Writer

(setf options) (generic function)

Methods
Method: options (<REGEX> <regex>)

This slot holds the options of the @c(<regex>) object as an alphabetically sorted @i(string). Options are identified by by characters. Valid options are: ’i’ for case insensitive matching, ’m’ for multiline matching, ’x’ for verbose mode, ’l’ to make \w, \W, etc. locale dependent, ’s’ for dotall mode (’.’ matches everything), and ’u’ to make \w, \W, etc. match unicode

Source

types.lisp (file)

Generic Function: (setf options) REGEX OPTIONS

Checks if the @cl:param(options) string contains any invalid characters and, if not, sorts them alphabetically before @c(setf)ing. Otherwise, throws an @cl:spec(error).

Package

cl-bson.types

Source

types.lisp (file)

Reader

options (generic function)

Methods
Method: (setf options) (OPTIONS string) (REGEX <regex>)
Method: (setf options) NEW-VALUE (<REGEX> <regex>)

This slot holds the options of the @c(<regex>) object as an alphabetically sorted @i(string). Options are identified by by characters. Valid options are: ’i’ for case insensitive matching, ’m’ for multiline matching, ’x’ for verbose mode, ’l’ to make \w, \W, etc. locale dependent, ’s’ for dotall mode (’.’ matches everything), and ’u’ to make \w, \W, etc. match unicode

Generic Function: pattern OBJECT
Generic Function: (setf pattern) NEW-VALUE OBJECT
Package

cl-bson.types

Methods
Method: pattern (<REGEX> <regex>)
Method: (setf pattern) NEW-VALUE (<REGEX> <regex>)

This slot holds the actual regex pattern as a @i(string).

Source

types.lisp (file)

Generic Function: remove-element DOCUMENT KEY

Removes the elements identified by @cl:param(key). @cl:param(key) is coerced to string using @cl:spec(string).

Package

cl-bson.types

Source

types.lisp (file)

Methods
Method: remove-element (DOCUMENT <document>) KEY
Generic Function: scope OBJECT
Generic Function: (setf scope) NEW-VALUE OBJECT
Package

cl-bson.types

Methods
Method: scope (<JAVASCRIPT> <javascript>)
Method: (setf scope) NEW-VALUE (<JAVASCRIPT> <javascript>)

This slot holds a @c(<document>) that represents the scope in which the string should be evaluated. The @c(<document>) is a mapping from identifiers to values.

Source

types.lisp (file)

Generic Function: str OBJECT-ID

The hexadecimal string representation of the given @cl:param(object-id). Method from the @link[uri="http://docs.mongodb.org/manual/reference/object-id/#core-object-id-class"](reference).

@code[lang=lisp](* (str (make-instance ’<object-id>))
; => "35F97455616E6477630600D3"
)

Package

cl-bson.types

Source

types.lisp (file)

Methods
Method: str (OBJECT-ID <object-id>)
Generic Function: subtype OBJECT
Generic Function: (setf subtype) NEW-VALUE OBJECT
Package

cl-bson.types

Methods
Method: subtype (<BINARY-DATA> <binary-data>)
Method: (setf subtype) NEW-VALUE (<BINARY-DATA> <binary-data>)

This slot holds a keyword that represents one of the @c(<binary-data>) subtypes. A valid @c(subtype) is any of the following: @c(:generic), @c(:function), @c(:binary-old) (@i(deprecated)), @c(:uuid-old) (@i(deprecated)), @c(:uuid), @c(:md5) or @c(:user-defined).

Source

types.lisp (file)


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

6.1.4 Classes

Class: <binary-data> ()

This class is used to represent custom array of bytes in BSON. @c(<binary-data>) values have a @cl:param(subtype). This is used to indicate what kind of data is in the byte array. Subtypes from zero to 127 are predefined or reserved. Subtypes from 128 to 255 are @c(:user-defined).

Package

cl-bson.types

Source

types.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: subtype

This slot holds a keyword that represents one of the @c(<binary-data>) subtypes. A valid @c(subtype) is any of the following: @c(:generic), @c(:function), @c(:binary-old) (@i(deprecated)), @c(:uuid-old) (@i(deprecated)), @c(:uuid), @c(:md5) or @c(:user-defined).

Type

keyword

Initargs

:subtype

Initform

:generic

Readers

subtype (generic function)

Writers

(setf subtype) (generic function)

Slot: octets

This slot holds the actual binary data.

Type

cl-bson.types:octets-array

Initargs

:octets

Initform

(make-array 0 :element-type (quote cl-bson.types:octet))

Readers

octets (generic function)

Writers

(setf octets) (generic function)

Class: <document> ()

Main class for interacting with MongoDB.

You can instanciate it with @c((make-instance ’<document>)), which yields a @c(<document>) with no @c("_id") field; or with @c(#’make-document), which instanciates a @c(<document>) for you with an @c(<object-id>) already.

Package

cl-bson.types

Source

types.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: elements

@c(hash-table) that holds all the the document data.

Type

hash-table

Initargs

:elements

Initform

(make-hash-table :test (function equal))

Readers

elements (generic function)

Writers

(setf elements) (generic function)

Class: <javascript> ()

This class puts together two BSON types: "JavaScript code" and "Code with scope". When the @cl:param(scope) slot is @c(nil) (default), a @c(<javascript>) object gets encoded as "JavaScript code". When the @cl:param(scope) slot is not @c(nil), @c(<javascript>) gets encoded as "Code with scope".

Package

cl-bson.types

Source

types.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: code

This slot holds JavaScript code as a @i(string).

Type

string

Initargs

:code

Readers

code (generic function)

Writers

(setf code) (generic function)

Slot: scope

This slot holds a @c(<document>) that represents the scope in which the string should be evaluated. The @c(<document>) is a mapping from identifiers to values.

Type

cl-bson.types:<document>

Initargs

:scope

Readers

scope (generic function)

Writers

(setf scope) (generic function)

Class: <mongo-timestamp> ()

Special @i(internal) type used by MongoDB for replication and sharding. Within a single @c(mongod) instance, @c(<mongo-timestamp>) are always unique.

The structure of the array is:
@begin(enum)
@item(4 bytes are an increment, starting with a random value.)
@item(4 bytes are seconds since the Unix epoch.)
@end(enum)

Package

cl-bson.types

Source

types.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: mongo-time

Array of actual @c(octets-array) that represent the @link[uri="http://docs.mongodb.org/manual/reference/bson-types/#timestamps"](Mongo Timestamp).

Type

cl-bson.types:octets-array

Initargs

:mongo-time

Initform

(cl-bson.types::generate-mongo-timestamp)

Readers

mongo-time (generic function)

Writers

(setf mongo-time) (generic function)

Class: <object-id> ()

This class is a container for the actual OCTETS-ARRAY that represent the MongoDB ObjectId.

The structure of the array is:
@begin(enum)
@item(a 4-byte value representing the seconds since the Unix epoch.)
@item(a 3-byte machine identifier.)
@item(a 2-byte process id)
@item(a 3-byte counter, starting with a random value.)
@end(enum)

Check the @link[uri="http://docs.mongodb.org/manual/reference/bson-types/#objectid"](reference) for more info.

Package

cl-bson.types

Source

types.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: octets

Array of actual OCTETS-ARRAY that represent the @link[uri="http://docs.mongodb.org/manual/reference/object-id/"](MongoDB ObjectId). Value generated by @c(#’generate-object-id).

Type

cl-bson.types:octets-array

Initargs

:octets

Initform

(cl-bson.types::generate-object-id)

Readers

octets (generic function)

Writers

(setf octets) (generic function)

Class: <regex> ()

This class is used to represent regexps in the BSON document.

Package

cl-bson.types

Source

types.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: pattern

This slot holds the actual regex pattern as a @i(string).

Type

string

Initargs

:pattern

Initform

""

Readers

pattern (generic function)

Writers

(setf pattern) (generic function)

Slot: options

This slot holds the options of the @c(<regex>) object as an alphabetically sorted @i(string). Options are identified by by characters. Valid options are: ’i’ for case insensitive matching, ’m’ for multiline matching, ’x’ for verbose mode, ’l’ to make \w, \W, etc. locale dependent, ’s’ for dotall mode (’.’ matches everything), and ’u’ to make \w, \W, etc. match unicode

Type

string

Initargs

:options

Initform

""

Readers

options (generic function)

Writers

(setf options) (generic function)


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

6.1.5 Types

Type: octet ()

Equivalent to @c’(UNSIGNED-BYTE 8)). A 8-bit byte.

Package

cl-bson.types

Source

types.lisp (file)

Type: octets-array &optional SIZE

A @c(SIMPLE-ARRAY) of @c(’(UNSIGNED-BYTE 8)).

Package

cl-bson.types

Source

types.lisp (file)


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

6.2 Internal definitions


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

6.2.1 Special variables

Special Variable: *doc-out*

Special variable that holds the current @c(<document>) on every @c(#’decode-document) call.

Package

cl-bson.decode

Source

decode.lisp (file)

Special Variable: *mongo-timestamp-counter*

4-byte size integer counter, starting with a random value: @c((random (expt 2 32))).

Package

cl-bson.types

Source

types.lisp (file)

Special Variable: *object-id-counter*

3-byte size integer counter, starting with a random value: @c((random (expt 2 24))) .

Package

cl-bson.types

Source

types.lisp (file)

Special Variable: *regex-literal-delimiter*

Limiter character used for @c(<regex>) objects literals.

Package

cl-bson.readtable

Source

readtable.lisp (file)


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

6.2.2 Macros

Macro: bson-document-literal &rest CONTENTS

Converts the @cl:param(contents) list into pairs of @c((key value)) and makes a @c(<document>) from it. Expands in the form that create such @c(<document>).

If any key is repeated (tested with @cl:spec(equal) in @c(#’repeated-keys-p)), or if @cl:param(contents) has an odd number of elements, or if @cl:param(contents) has non-string keys it throws an @cl:spec(error) at compile-time.

Package

cl-bson.readtable

Source

readtable.lisp (file)


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

6.2.3 Functions

Function: bson-document-reader STREAM CHAR NUMARG

@c(<document>) literal reader function. Reads in a form as a @c(#’bson-document-literal) form. Escapes any symbol that starts with @c($).

Package

cl-bson.readtable

Source

readtable.lisp (file)

Function: decode-binary ()

Reads an @c(octets-array) and instanciates a @c(<binary-data>) object with the read data.

Package

cl-bson.decode

Source

decode.lisp (file)

Function: decode-boolean ()

Decodes a byte from @c(*bson-in*) as boolean. Since Common Lisp doesn’t differenciate ’null’ values from ’false’ values, it can correctly decode a ’null value’, but it gets encoded back as a ’nil’ value.

Package

cl-bson.decode

Source

decode.lisp (file)

Function: decode-cstring ()

Decodes a null terminated UTF-8 encoded string from @c(*bson-in*).

Package

cl-bson.decode

Source

decode.lisp (file)

Function: decode-document ()

Binds @c(*doc-out*) to a new document and call @c(#’decode-key-value) to decode values withing the new bound @c(*doc-out*). Returns the decoded @c(*doc-out*) @c(<document>).

Package

cl-bson.decode

Source

decode.lisp (file)

Function: decode-double ()

Decodes an 8 bytes double from @c(*bson-in*).

Package

cl-bson.decode

Source

decode.lisp (file)

Function: decode-javascript ()

Decodes a string from @c(*bson-in*) and creates an instance of @c(<javascript>).

Package

cl-bson.decode

Source

decode.lisp (file)

Function: decode-javascript-w/scope ()

Decodes a string and a @c(<document>) from @c(*bson-in*) and creates an instance of @c(<javascript>) with the @c(scope) field bound to the decoded @c(<document>).

Package

cl-bson.decode

Source

decode.lisp (file)

Function: decode-key-value ()

Main function that dispatches to the correct @c(#’decode-*) function. It first decodes the element type, than dispatches to the function that decodes the value type and finally adds the decoded @c(key) @c(value) pair to @c(*doc-out*). If it finds an invalid element type, it throws an @cl:spec(error).

Package

cl-bson.decode

Source

decode.lisp (file)

Function: decode-mongo-timestamp ()

Decodes an 8 bytes @c(<mongo-timestamp>).

Package

cl-bson.decode

Source

decode.lisp (file)

Function: decode-object-id ()

Decodes a 12 bytes @c(<object-id>) from @c(*bson-in*).

Package

cl-bson.decode

Source

decode.lisp (file)

Function: decode-regex ()

Decodes 2 strings with @c(#’decode-cstring) and creates an instance of @c(<regex>).

Package

cl-bson.decode

Source

decode.lisp (file)

Function: decode-sequence ()

Decodes a @c(<document>) and extract only the values. Depending on the value of @c(*bson-sequence-type), returns the values as a list or as a vector.

Package

cl-bson.decode

Source

decode.lisp (file)

Function: decode-string ()

Decodes a null terminated UTF-8 encoded string from @c(*bson-in*).

Package

cl-bson.decode

Source

decode.lisp (file)

Function: decode-timestamp ()

Decodes a @link[uri="https://common-lisp.net/project/local-time/manual.html#Types"](@c(local-time:timestamp)) with milliseconds precision.

Package

cl-bson.decode

Source

decode.lisp (file)

Function: disable-regex-printer ()

Disable the pprinter for @c(<regex>) objects.

Package

cl-bson.readtable

Source

readtable.lisp (file)

Function: enable-regex-printer ()

Enable pprint for @c(<regex>) objects.

Package

cl-bson.readtable

Source

readtable.lisp (file)

Function: encode-boolean KEY VALUE

Encodes the given boolean @cl:param(value). Since Common Lisp doesn’t differenciate ’false’ values from ’null’ values, any null value gets ’encoded’ as a boolean @cl:spec(nil).

Package

cl-bson.encode

Source

encode.lisp (file)

Function: encode-cstring VALUE

Coerces @cl:param(value) to string using the @cl:spec(string) function and transforms it to an @c(octets-array) using @c((babel:string-to-octets (string value) :encoding :utf-8)).

Package

cl-bson.encode

Source

encode.lisp (file)

Function: encode-document ELEMENTS

Goes through all the elements of the @cl:param(elements) hash-table using @cl:spec(maphash) and encode the @c(key) @c(value) pairs with @c(#’encode-key-value), writing to the bound @c(*bson-out*).

Package

cl-bson.encode

Source

encode.lisp (file)

Function: encode-document-array KEY VALUE

Gets @cl:param(value) sequence and encodes it as a document. Each element gets a index as a key to create the document.

Package

cl-bson.encode

Source

encode.lisp (file)

Function: encode-int32 KEY VALUE

Encodes the given @cl:param(value) as a 4 bytes @c(octets-array) sequence.

Package

cl-bson.encode

Source

encode.lisp (file)

Function: encode-int64 KEY VALUE

Encodes the given value as a 8 bytes @c(octets-array) sequence.

Package

cl-bson.encode

Source

encode.lisp (file)

Function: encode-string VALUE

Encodes a given @cl:param(value) into an array with 4 bytes for length, the string @cl:param(value) encoded with @c((string-to-octets value :encoding :utf-8)) and a null byte (0) at the end.

Package

cl-bson.encode

Source

encode.lisp (file)

Function: generate-mongo-timestamp ()

Generates a fresh 8 bytes @c(octets-array) for a @c(<mongo-timestamp>).

Package

cl-bson.types

Source

types.lisp (file)

Function: generate-object-id ()

Generates a fresh 12 bytes @c(octets-array) for an @c(<object-id>).

A typical array looks like:
@code[lang=lisp](* (generate-object-id)
; => #(34 250 116 85 97 110 100 119 99 7 0 211)
)
...where:
@begin(list)
@item(@c(#(34 250 116 85)) is the Unix timestamp of when it was generated. See it with: @code[lang=lisp](* (get-timestamp (make-instance ’<object-id> :octets *))
; => @2015-06-07T23:12:50.000000-03:00
))
@item(@c(#(97 110 100)) is the machine identifier. See it with:
@code[lang=lisp](* (babel:octets-to-string (subseq (generate-object-id) 4 7))
; => "and" ;; three first letters of "andreh"
))
@item(@c(#c(119 99)) is the PID. See it with:
@code[lang=lisp](* (intbytes:octets->int (subseq (generate-object-id) 7 9) 2)
; => 25463
))
@item(@c(#(10 0 211)) is the counter. See it with:
@code[lang=lisp](* *object-id-counter*
; => 13828114
* (intbytes:octets->uint (subseq (generate-object-id) 9 12) 3)
; => 13828115
* *object-id-counter*
; => 13828115
))
@end(list)

Package

cl-bson.types

Source

types.lisp (file)

Function: increment-id-counter ()

Increments @c(*OBJECT-ID-COUNTER*) up to @c((1- (expt 2 24))). When pass that, it "overflows" back to 0.

Package

cl-bson.types

Source

types.lisp (file)

Function: increment-mongo-timestamp-counter ()

Increments *MONGO-TIMESTAMP-COUNTER* up to @c((1- (expt 2 32))). When pass that, it "overflows" back to 0.

Package

cl-bson.types

Source

types.lisp (file)

Function: object-id-reader STREAM CHAR NUMARG

@c(<object-id>) literal reader function. Converts the symbol inside the form into an @c(<object-id>) using @c(#’string->object-id).

Package

cl-bson.readtable

Source

readtable.lisp (file)

Function: pprint-bson-document *STANDARD-OUTPUT* DOCUMENT

Pprints a given @cl:param(document) in the @c(#d(key value)) format. Stablishes read-print-equivalence for @c(<document>) objects.

Package

cl-bson.readtable

Source

readtable.lisp (file)

Function: pprint-object-id *STANDARD-OUTPUT* OBJECT-ID

Pprints a given @cl:param(object-id) in the @c(#(hex-id)) format. Stablishes read-print-equivalence for @c(<object-id>) objects.

Package

cl-bson.readtable

Source

readtable.lisp (file)

Function: pprint-regex *STANDARD-OUTPUT* REGEX

Pprints a given @cl:param(regex>) int..

Package

cl-bson.readtable

Source

readtable.lisp (file)

Function: read-until-null ()

Reads from @c(*bson-in*) until it finds a null (0) byte.

Package

cl-bson.decode

Source

decode.lisp (file)

Function: regexp-reader STREAM CHAR NUMARG

@c(<regex>) literal reader function.

Package

cl-bson.readtable

Source

readtable.lisp (file)


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

6.2.4 Generic functions

Generic Function: encode-key-value KEY VALUE

Main helper generic function for doing the actual work of encoding @cl:param(key) @cl:param(value) pairs. Most of the method implementations have the following skeleton:

@code[lang=lisp]((defmethod encode-key-value (key (value SOME-TYPE))
;; Writes the BSON-BYTE-SPECIFIER
(fast-write-byte BSON-BYTE-SPECIFIER *bson-out*)
;; Encodes the key string in C-style
(encode-cstring key)
;; Encodes the value with a custom function
(encode-the-value-somehow value))
)

In general, the functions relative to @c(encode-the-value-somehow) converts the @cl:param(value) into an @c(octets-array) and then call @c(#’fast-io:fast-write-sequence).

Package

cl-bson.encode

Source

encode.lisp (file)

Methods
Method: encode-key-value KEY (VALUE <mongo-timestamp>)

Encodes the given @cl:param(value) (@c(<mongo-timestamp>) object) as an @c(octets-array).

Method: encode-key-value KEY (VALUE integer)

Checks the @cl:spec(integer-length) of the given @cl:param(value) and dispatches to the correct function (or it throws an @cl:spec(error)).

Method: encode-key-value KEY (VALUE <javascript>)

Encodes the given @c(<javascript>) @cl:param(value). If the @c(scope) attribute of @cl:param(value) is not nil, encodes @cl:param(value) as a "Code with scope" object; otherwise, enocodes it as a "JavaScript code" object.

Method: encode-key-value KEY (VALUE <regex>)

Encodes the given @cl:param(value) (@c(<regex>) object).

Method: encode-key-value KEY (VALUE timestamp)

Encodes the given @link[name="https://common-lisp.net/project/local-time/manual.html#Types"](@c(local-time:timestamp)) as a 8 bytes integer representing the milisseconds since the Unix epoch. Since the @(local-time:timestamp) stores up to nanoseconds, the given @cl:param(value) loses precision, getting coerced to milliseconds. When decoded and reencoded, the precision stay the same (milliseconds).

Method: encode-key-value KEY (VALUE (eql t))

Dispatches to @c(#’encode-boolean).

Method: encode-key-value KEY (VALUE (eql nil))

Dispatches to @c(#’encode-boolean).

Method: encode-key-value KEY (VALUE <object-id>)

Encodes the given @cl:param(value) (@c(<object-id>) object).

Method: encode-key-value KEY (VALUE <binary-data>)

Encodes the binary data @c(subtype) and @c(octets) of the given @cl:param(value) (@c(<binary-data>) object).

Method: encode-key-value KEY (VALUE vector)

Dispatches to @c(#’encode-document-array).

Method: encode-key-value KEY (VALUE list)

Dispatches to @c(#’encode-document-array).

Method: encode-key-value KEY (VALUE <document>)

Calls @c(#’encode-document) for encoding the embedded document.

Method: encode-key-value KEY (VALUE symbol)

Coerces @cl:param(value) to string using the @cl:param(string) and call @c(#’encode-key-value) for strings.

Method: encode-key-value KEY (VALUE string)

Encodes an UTF-8 string @cl:param(value).

Method: encode-key-value KEY (VALUE float)

Encode a given @c(single-float) or @c(double-float) @cl:param(value) and encodes it as an 8 bytes @c(double-float), even if it originally is a @c(single-float).


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   C   F   L   M   O  
Index Entry  Section

C
cl-bson.asd: The cl-bson<dot>asd file
cl-bson/README.md: The cl-bson/readme<dot>md file
cl-bson/src: The cl-bson/src module
cl-bson/src/cl-bson.lisp: The cl-bson/src/cl-bson<dot>lisp file
cl-bson/src/decode.lisp: The cl-bson/src/decode<dot>lisp file
cl-bson/src/encode.lisp: The cl-bson/src/encode<dot>lisp file
cl-bson/src/readtable.lisp: The cl-bson/src/readtable<dot>lisp file
cl-bson/src/types.lisp: The cl-bson/src/types<dot>lisp file

F
File, Lisp, cl-bson.asd: The cl-bson<dot>asd file
File, Lisp, cl-bson/src/cl-bson.lisp: The cl-bson/src/cl-bson<dot>lisp file
File, Lisp, cl-bson/src/decode.lisp: The cl-bson/src/decode<dot>lisp file
File, Lisp, cl-bson/src/encode.lisp: The cl-bson/src/encode<dot>lisp file
File, Lisp, cl-bson/src/readtable.lisp: The cl-bson/src/readtable<dot>lisp file
File, Lisp, cl-bson/src/types.lisp: The cl-bson/src/types<dot>lisp file
File, other, cl-bson/README.md: The cl-bson/readme<dot>md file

L
Lisp File, cl-bson.asd: The cl-bson<dot>asd file
Lisp File, cl-bson/src/cl-bson.lisp: The cl-bson/src/cl-bson<dot>lisp file
Lisp File, cl-bson/src/decode.lisp: The cl-bson/src/decode<dot>lisp file
Lisp File, cl-bson/src/encode.lisp: The cl-bson/src/encode<dot>lisp file
Lisp File, cl-bson/src/readtable.lisp: The cl-bson/src/readtable<dot>lisp file
Lisp File, cl-bson/src/types.lisp: The cl-bson/src/types<dot>lisp file

M
Module, cl-bson/src: The cl-bson/src module

O
Other File, cl-bson/README.md: The cl-bson/readme<dot>md file

Jump to:   C   F   L   M   O  

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

A.2 Functions

Jump to:   (  
A   B   C   D   E   F   G   I   K   M   O   P   R   S  
Index Entry  Section

(
(setf code): Exported generic functions
(setf code): Exported generic functions
(setf elements): Exported generic functions
(setf elements): Exported generic functions
(setf mongo-time): Exported generic functions
(setf mongo-time): Exported generic functions
(setf octets): Exported generic functions
(setf octets): Exported generic functions
(setf octets): Exported generic functions
(setf options): Exported generic functions
(setf options): Exported generic functions
(setf options): Exported generic functions
(setf pattern): Exported generic functions
(setf pattern): Exported generic functions
(setf scope): Exported generic functions
(setf scope): Exported generic functions
(setf subtype): Exported generic functions
(setf subtype): Exported generic functions

A
add-element: Exported generic functions
add-element: Exported generic functions
add-element: Exported generic functions
add-element: Exported generic functions
add-element: Exported generic functions

B
bson-document-literal: Internal macros
bson-document-reader: Internal functions

C
code: Exported generic functions
code: Exported generic functions

D
decode: Exported functions
decode-binary: Internal functions
decode-boolean: Internal functions
decode-cstring: Internal functions
decode-document: Internal functions
decode-double: Internal functions
decode-int32: Exported functions
decode-int64: Exported functions
decode-javascript: Internal functions
decode-javascript-w/scope: Internal functions
decode-key-value: Internal functions
decode-mongo-timestamp: Internal functions
decode-object-id: Internal functions
decode-regex: Internal functions
decode-sequence: Internal functions
decode-string: Internal functions
decode-timestamp: Internal functions
disable-bson-document-printer: Exported functions
disable-object-id-printer: Exported functions
disable-printers: Exported functions
disable-regex-printer: Internal functions

E
elements: Exported generic functions
elements: Exported generic functions
enable-bson-document-printer: Exported functions
enable-object-id-printer: Exported functions
enable-printers: Exported functions
enable-regex-printer: Internal functions
encode: Exported generic functions
encode: Exported generic functions
encode-boolean: Internal functions
encode-cstring: Internal functions
encode-document: Internal functions
encode-document-array: Internal functions
encode-int32: Internal functions
encode-int64: Internal functions
encode-key-value: Internal generic functions
encode-key-value: Internal generic functions
encode-key-value: Internal generic functions
encode-key-value: Internal generic functions
encode-key-value: Internal generic functions
encode-key-value: Internal generic functions
encode-key-value: Internal generic functions
encode-key-value: Internal generic functions
encode-key-value: Internal generic functions
encode-key-value: Internal generic functions
encode-key-value: Internal generic functions
encode-key-value: Internal generic functions
encode-key-value: Internal generic functions
encode-key-value: Internal generic functions
encode-key-value: Internal generic functions
encode-key-value: Internal generic functions
encode-string: Internal functions

F
Function, bson-document-reader: Internal functions
Function, decode: Exported functions
Function, decode-binary: Internal functions
Function, decode-boolean: Internal functions
Function, decode-cstring: Internal functions
Function, decode-document: Internal functions
Function, decode-double: Internal functions
Function, decode-int32: Exported functions
Function, decode-int64: Exported functions
Function, decode-javascript: Internal functions
Function, decode-javascript-w/scope: Internal functions
Function, decode-key-value: Internal functions
Function, decode-mongo-timestamp: Internal functions
Function, decode-object-id: Internal functions
Function, decode-regex: Internal functions
Function, decode-sequence: Internal functions
Function, decode-string: Internal functions
Function, decode-timestamp: Internal functions
Function, disable-bson-document-printer: Exported functions
Function, disable-object-id-printer: Exported functions
Function, disable-printers: Exported functions
Function, disable-regex-printer: Internal functions
Function, enable-bson-document-printer: Exported functions
Function, enable-object-id-printer: Exported functions
Function, enable-printers: Exported functions
Function, enable-regex-printer: Internal functions
Function, encode-boolean: Internal functions
Function, encode-cstring: Internal functions
Function, encode-document: Internal functions
Function, encode-document-array: Internal functions
Function, encode-int32: Internal functions
Function, encode-int64: Internal functions
Function, encode-string: Internal functions
Function, generate-mongo-timestamp: Internal functions
Function, generate-object-id: Internal functions
Function, increment-id-counter: Internal functions
Function, increment-mongo-timestamp-counter: Internal functions
Function, make-document: Exported functions
Function, object-id-reader: Internal functions
Function, pprint-bson-document: Internal functions
Function, pprint-object-id: Internal functions
Function, pprint-regex: Internal functions
Function, read-n-bytes: Exported functions
Function, read-until-null: Internal functions
Function, regexp-reader: Internal functions
Function, repeated-keys-p: Exported functions
Function, string->object-id: Exported functions

G
generate-mongo-timestamp: Internal functions
generate-object-id: Internal functions
Generic Function, (setf code): Exported generic functions
Generic Function, (setf elements): Exported generic functions
Generic Function, (setf mongo-time): Exported generic functions
Generic Function, (setf octets): Exported generic functions
Generic Function, (setf options): Exported generic functions
Generic Function, (setf pattern): Exported generic functions
Generic Function, (setf scope): Exported generic functions
Generic Function, (setf subtype): Exported generic functions
Generic Function, add-element: Exported generic functions
Generic Function, code: Exported generic functions
Generic Function, elements: Exported generic functions
Generic Function, encode: Exported generic functions
Generic Function, encode-key-value: Internal generic functions
Generic Function, get-element: Exported generic functions
Generic Function, get-timestamp: Exported generic functions
Generic Function, keys: Exported generic functions
Generic Function, mongo-time: Exported generic functions
Generic Function, octets: Exported generic functions
Generic Function, options: Exported generic functions
Generic Function, pattern: Exported generic functions
Generic Function, remove-element: Exported generic functions
Generic Function, scope: Exported generic functions
Generic Function, str: Exported generic functions
Generic Function, subtype: Exported generic functions
get-element: Exported generic functions
get-element: Exported generic functions
get-timestamp: Exported generic functions
get-timestamp: Exported generic functions

I
increment-id-counter: Internal functions
increment-mongo-timestamp-counter: Internal functions

K
keys: Exported generic functions
keys: Exported generic functions

M
Macro, bson-document-literal: Internal macros
make-document: Exported functions
Method, (setf code): Exported generic functions
Method, (setf elements): Exported generic functions
Method, (setf mongo-time): Exported generic functions
Method, (setf octets): Exported generic functions
Method, (setf octets): Exported generic functions
Method, (setf options): Exported generic functions
Method, (setf options): Exported generic functions
Method, (setf pattern): Exported generic functions
Method, (setf scope): Exported generic functions
Method, (setf subtype): Exported generic functions
Method, add-element: Exported generic functions
Method, add-element: Exported generic functions
Method, add-element: Exported generic functions
Method, add-element: Exported generic functions
Method, code: Exported generic functions
Method, elements: Exported generic functions
Method, encode: Exported generic functions
Method, encode-key-value: Internal generic functions
Method, encode-key-value: Internal generic functions
Method, encode-key-value: Internal generic functions
Method, encode-key-value: Internal generic functions
Method, encode-key-value: Internal generic functions
Method, encode-key-value: Internal generic functions
Method, encode-key-value: Internal generic functions
Method, encode-key-value: Internal generic functions
Method, encode-key-value: Internal generic functions
Method, encode-key-value: Internal generic functions
Method, encode-key-value: Internal generic functions
Method, encode-key-value: Internal generic functions
Method, encode-key-value: Internal generic functions
Method, encode-key-value: Internal generic functions
Method, encode-key-value: Internal generic functions
Method, get-element: Exported generic functions
Method, get-timestamp: Exported generic functions
Method, keys: Exported generic functions
Method, mongo-time: Exported generic functions
Method, octets: Exported generic functions
Method, octets: Exported generic functions
Method, options: Exported generic functions
Method, pattern: Exported generic functions
Method, remove-element: Exported generic functions
Method, scope: Exported generic functions
Method, str: Exported generic functions
Method, subtype: Exported generic functions
mongo-time: Exported generic functions
mongo-time: Exported generic functions

O
object-id-reader: Internal functions
octets: Exported generic functions
octets: Exported generic functions
octets: Exported generic functions
options: Exported generic functions
options: Exported generic functions

P
pattern: Exported generic functions
pattern: Exported generic functions
pprint-bson-document: Internal functions
pprint-object-id: Internal functions
pprint-regex: Internal functions

R
read-n-bytes: Exported functions
read-until-null: Internal functions
regexp-reader: Internal functions
remove-element: Exported generic functions
remove-element: Exported generic functions
repeated-keys-p: Exported functions

S
scope: Exported generic functions
scope: Exported generic functions
str: Exported generic functions
str: Exported generic functions
string->object-id: Exported functions
subtype: Exported generic functions
subtype: Exported generic functions

Jump to:   (  
A   B   C   D   E   F   G   I   K   M   O   P   R   S  

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

A.3 Variables

Jump to:   *  
C   E   M   O   P   S  
Index Entry  Section

*
*allowed-regex-options*: Exported special variables
*bson-in*: Exported special variables
*bson-out*: Exported special variables
*bson-sequence-type*: Exported special variables
*doc-out*: Internal special variables
*mongo-timestamp-counter*: Internal special variables
*object-id-counter*: Internal special variables
*regex-literal-delimiter*: Internal special variables

C
code: Exported classes

E
elements: Exported classes

M
mongo-time: Exported classes

O
octets: Exported classes
octets: Exported classes
options: Exported classes

P
pattern: Exported classes

S
scope: Exported classes
Slot, code: Exported classes
Slot, elements: Exported classes
Slot, mongo-time: Exported classes
Slot, octets: Exported classes
Slot, octets: Exported classes
Slot, options: Exported classes
Slot, pattern: Exported classes
Slot, scope: Exported classes
Slot, subtype: Exported classes
Special Variable, *allowed-regex-options*: Exported special variables
Special Variable, *bson-in*: Exported special variables
Special Variable, *bson-out*: Exported special variables
Special Variable, *bson-sequence-type*: Exported special variables
Special Variable, *doc-out*: Internal special variables
Special Variable, *mongo-timestamp-counter*: Internal special variables
Special Variable, *object-id-counter*: Internal special variables
Special Variable, *regex-literal-delimiter*: Internal special variables
subtype: Exported classes

Jump to:   *  
C   E   M   O   P   S  

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

A.4 Data types

Jump to:   <  
C   O   P   S   T  
Index Entry  Section

<
<binary-data>: Exported classes
<document>: Exported classes
<javascript>: Exported classes
<mongo-timestamp>: Exported classes
<object-id>: Exported classes
<regex>: Exported classes

C
cl-bson: The cl-bson system
cl-bson: The cl-bson package
cl-bson.decode: The cl-bson<dot>decode package
cl-bson.encode: The cl-bson<dot>encode package
cl-bson.readtable: The cl-bson<dot>readtable package
cl-bson.types: The cl-bson<dot>types package
Class, <binary-data>: Exported classes
Class, <document>: Exported classes
Class, <javascript>: Exported classes
Class, <mongo-timestamp>: Exported classes
Class, <object-id>: Exported classes
Class, <regex>: Exported classes

O
octet: Exported types
octets-array: Exported types

P
Package, cl-bson: The cl-bson package
Package, cl-bson.decode: The cl-bson<dot>decode package
Package, cl-bson.encode: The cl-bson<dot>encode package
Package, cl-bson.readtable: The cl-bson<dot>readtable package
Package, cl-bson.types: The cl-bson<dot>types package

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

T
Type, octet: Exported types
Type, octets-array: Exported types

Jump to:   <  
C   O   P   S   T