This is the cl-bson Reference Manual, version 0.1.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon May 15 03:40:59 2023 GMT+0.
The main system appears first, followed by any subsystem dependency.
cl-bsonBSON encoder/decoder for Common Lisp.
André Miranda
André Miranda
(GIT git@github.com:EuAndreh/cl-bson.git)
LLGPL
# cl-BSON
[](http://quickdocs.org/cl-bson/)
[](https://travis-ci.org/EuAndreh/cl-BSON)
[](https://circleci.com/gh/EuAndreh/cl-BSON/)
[](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).
0.1.0
arrow-macros (system).
babel (system).
cl-intbytes (system).
fast-io (system).
ieee-floats (system).
let-over-lambda (system).
local-time (system).
named-readtables (system).
rutils (system).
trivial-shell (system).
Modules are listed depth-first from the system components tree.
cl-bson/srccl-bson (system).
types.lisp (file).
readtable.lisp (file).
encode.lisp (file).
decode.lisp (file).
cl-bson.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
cl-bson/cl-bson.asdcl-bson/src/types.lispcl-bson/src/readtable.lispcl-bson/src/encode.lispcl-bson/src/decode.lispcl-bson/src/cl-bson.lispcl-bson/src/types.lispsrc (module).
*allowed-regex-options* (special variable).
<binary-data> (class).
<document> (class).
<javascript> (class).
<mongo-timestamp> (class).
<object-id> (class).
<regex> (class).
add-element (generic function).
code (reader method).
(setf code) (writer method).
elements (reader method).
(setf elements) (writer method).
get-element (generic function).
get-timestamp (generic function).
initialize-instance (method).
initialize-instance (method).
keys (generic function).
make-document (function).
mongo-time (reader method).
(setf mongo-time) (writer method).
octet (type).
octets (reader method).
octets (reader method).
(setf octets) (writer method).
(setf octets) (writer method).
octets-array (type).
options (reader method).
(setf options) (generic function).
pattern (reader method).
(setf pattern) (writer method).
remove-element (generic function).
scope (reader method).
(setf scope) (writer method).
str (generic function).
string->object-id (function).
subtype (reader method).
(setf subtype) (writer method).
(setf subtype) (method).
*mongo-timestamp-counter* (special variable).
*object-id-counter* (special variable).
generate-mongo-timestamp (function).
generate-object-id (function).
increment-id-counter (function).
increment-mongo-timestamp-counter (function).
cl-bson/src/readtable.lispsrc (module).
disable-bson-document-printer (function).
disable-object-id-printer (function).
disable-printers (function).
enable-bson-document-printer (function).
enable-object-id-printer (function).
enable-printers (function).
repeated-keys-p (function).
*regex-literal-delimiter* (special variable).
bson-document-literal (macro).
bson-document-reader (function).
disable-regex-printer (function).
enable-regex-printer (function).
object-id-reader (function).
pprint-bson-document (function).
pprint-object-id (function).
pprint-regex (function).
regexp-reader (function).
cl-bson/src/encode.lispsrc (module).
*bson-out* (special variable).
encode (generic function).
encode-boolean (function).
encode-cstring (function).
encode-document (function).
encode-document-array (function).
encode-int32 (function).
encode-int64 (function).
encode-key-value (generic function).
encode-string (function).
cl-bson/src/decode.lispsrc (module).
*bson-in* (special variable).
*bson-sequence-type* (special variable).
decode (function).
decode-int32 (function).
decode-int64 (function).
read-n-bytes (function).
*doc-out* (special variable).
decode-binary (function).
decode-boolean (function).
decode-cstring (function).
decode-document (function).
decode-double (function).
decode-javascript (function).
decode-javascript-w/scope (function).
decode-key-value (function).
decode-mongo-timestamp (function).
decode-object-id (function).
decode-regex (function).
decode-sequence (function).
decode-string (function).
decode-timestamp (function).
read-until-null (function).
Packages are listed by definition order.
cl-bson.decodeThis package defines the main function (@c(#’decode)) for converting an @c(octets-array) to BSON @c(<document>)s many helper functions for internal use.
common-lisp.
*bson-in* (special variable).
*bson-sequence-type* (special variable).
decode (function).
decode-int32 (function).
decode-int64 (function).
read-n-bytes (function).
*doc-out* (special variable).
decode-binary (function).
decode-boolean (function).
decode-cstring (function).
decode-document (function).
decode-double (function).
decode-javascript (function).
decode-javascript-w/scope (function).
decode-key-value (function).
decode-mongo-timestamp (function).
decode-object-id (function).
decode-regex (function).
decode-sequence (function).
decode-string (function).
decode-timestamp (function).
read-until-null (function).
cl-bson.typesThe @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).
common-lisp.
*allowed-regex-options* (special variable).
<binary-data> (class).
<document> (class).
<javascript> (class).
<mongo-timestamp> (class).
<object-id> (class).
<regex> (class).
add-element (generic function).
code (generic reader).
(setf code) (generic writer).
elements (generic reader).
(setf elements) (generic writer).
get-element (generic function).
get-timestamp (generic function).
keys (generic function).
make-document (function).
mongo-time (generic reader).
(setf mongo-time) (generic writer).
octet (type).
octets (generic reader).
(setf octets) (generic writer).
octets-array (type).
options (generic reader).
(setf options) (generic function).
pattern (generic reader).
(setf pattern) (generic writer).
remove-element (generic function).
scope (generic reader).
(setf scope) (generic writer).
str (generic function).
string->object-id (function).
subtype (generic reader).
(setf subtype) (generic function).
*mongo-timestamp-counter* (special variable).
*object-id-counter* (special variable).
generate-mongo-timestamp (function).
generate-object-id (function).
increment-id-counter (function).
increment-mongo-timestamp-counter (function).
cl-bson.readtablePackage 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)
common-lisp.
disable-bson-document-printer (function).
disable-object-id-printer (function).
disable-printers (function).
enable-bson-document-printer (function).
enable-object-id-printer (function).
enable-printers (function).
repeated-keys-p (function).
*regex-literal-delimiter* (special variable).
bson-document-literal (macro).
bson-document-reader (function).
disable-regex-printer (function).
enable-regex-printer (function).
object-id-reader (function).
pprint-bson-document (function).
pprint-object-id (function).
pprint-regex (function).
regexp-reader (function).
cl-bsonbson
cl-bson.decode.
cl-bson.encode.
cl-bson.readtable.
cl-bson.types.
common-lisp.
cl-bson.encodeThis 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).
common-lisp.
*bson-out* (special variable).
encode (generic function).
encode-boolean (function).
encode-cstring (function).
encode-document (function).
encode-document-array (function).
encode-int32 (function).
encode-int64 (function).
encode-key-value (generic function).
encode-string (function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
List of charaters allowed in the @c(options) slot of a @c(<regex>) object.
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*).
Special var that gets bound to @c(fast-io:output-buffer) on every @c(#’encode) call.
Special variable that holds the kind of output to return when decoding a BSON array.
Main entry point to decode a given array. It performs the first binding of @c(*doc-out*) and call @c(#’decode-document).
Decodes a 4 bytes integer from @c(*bson-in*).
Decodes an 8 bytes integer from @c(*bson-in*).
Disables the pprinter for @c(<document>) objects.
Disables the pprinter for @c(<object-id>) objects.
Disables pprinter for @c(<document>) and @c(<object-id>) objects.
Enable pprinter for @c(<document>) objects.
Enable pprinter for @c(<object-id>) objects.
Enables pprinter for both @c(<document>) and @c(<object-id>) objects.
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"))).
Reads @cl:param(n) bytes from @c(*bson-in*).
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).
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)
)
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.
<document>) key value) ¶<document>) key (value symbol)) ¶<document>) key (value (eql nil))) ¶<document>) key (value (eql t))) ¶<javascript>)) ¶<javascript>)) ¶This slot holds JavaScript code as a @i(string).
code.
<document>)) ¶<document>)) ¶@c(hash-table) that holds all the the document data.
Encodes a given @cl:param(document) into an @c(octets-array) following the @link[uri="http://bsonspec.org/spec.html"](BSON specification).
<document>)) ¶Gets the elements identified by @cl:param(key). @cl:param(key) is coerced to string using the @cl:spec(string).
<document>) key) ¶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).
<object-id>)) ¶Returns all keys of the @cl:param(document).
<document>)) ¶<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).
<binary-data>)) ¶<binary-data>)) ¶This slot holds the actual binary data.
<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).
<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
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).
<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
Removes the elements identified by @cl:param(key). @cl:param(key) is coerced to string using @cl:spec(string).
<document>) key) ¶<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.
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"
)
<object-id>)) ¶<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).
<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).
<binary-data>) &key) ¶Checks if @cl:param(binary-data) has a valid @cl:param(subtype).
<regex>) &key) ¶@spec(sort) the @cl:param(option) of the @cl:param(regex) through @c((setf (options regex) ...)).
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).
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).
keyword
:generic
:subtype
This slot holds the actual binary data.
cl-bson.types:octets-array
(make-array 0 :element-type (quote cl-bson.types:octet))
:octets
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.
@c(hash-table) that holds all the the document data.
hash-table
(make-hash-table :test (function equal))
:elements
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".
This slot holds JavaScript code as a @i(string).
string
:code
code.
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.
cl-bson.types:<document>
:scope
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)
Array of actual @c(octets-array) that represent the @link[uri="http://docs.mongodb.org/manual/reference/bson-types/#timestamps"](Mongo Timestamp).
cl-bson.types:octets-array
(cl-bson.types::generate-mongo-timestamp)
:mongo-time
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.
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).
cl-bson.types:octets-array
(cl-bson.types::generate-object-id)
:octets
This class is used to represent regexps in the BSON document.
This slot holds the actual regex pattern as a @i(string).
string
""
:pattern
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
string
""
:options
Special variable that holds the current @c(<document>) on every @c(#’decode-document) call.
4-byte size integer counter, starting with a random value: @c((random (expt 2 32))).
3-byte size integer counter, starting with a random value: @c((random (expt 2 24))) .
Limiter character used for @c(<regex>) objects literals.
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.
@c(<document>) literal reader function. Reads in a form as a @c(#’bson-document-literal) form. Escapes any symbol that starts with @c($).
Reads an @c(octets-array) and instanciates a @c(<binary-data>) object with the read data.
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.
Decodes a null terminated UTF-8 encoded string from @c(*bson-in*).
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>).
Decodes an 8 bytes double from @c(*bson-in*).
Decodes a string from @c(*bson-in*) and creates an instance of @c(<javascript>).
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>).
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).
Decodes an 8 bytes @c(<mongo-timestamp>).
Decodes a 12 bytes @c(<object-id>) from @c(*bson-in*).
Decodes 2 strings with @c(#’decode-cstring) and creates an instance of @c(<regex>).
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.
Decodes a null terminated UTF-8 encoded string from @c(*bson-in*).
Decodes a @link[uri="https://common-lisp.net/project/local-time/manual.html#Types"](@c(local-time:timestamp)) with milliseconds precision.
Disable the pprinter for @c(<regex>) objects.
Enable pprint for @c(<regex>) objects.
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).
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)).
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*).
Gets @cl:param(value) sequence and encodes it as a document. Each element gets a index as a key to create the document.
Encodes the given @cl:param(value) as a 4 bytes @c(octets-array) sequence.
Encodes the given value as a 8 bytes @c(octets-array) sequence.
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.
Generates a fresh 8 bytes @c(octets-array) for a @c(<mongo-timestamp>).
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)
Increments @c(*OBJECT-ID-COUNTER*) up to @c((1- (expt 2 24))). When pass that, it "overflows" back to 0.
Increments *MONGO-TIMESTAMP-COUNTER* up to @c((1- (expt 2 32))). When pass that, it "overflows" back to 0.
@c(<object-id>) literal reader function. Converts the symbol inside the form into an @c(<object-id>) using @c(#’string->object-id).
Pprints a given @cl:param(document) in the @c(#d(key value)) format. Stablishes read-print-equivalence for @c(<document>) objects.
Pprints a given @cl:param(object-id) in the @c(#(hex-id)) format. Stablishes read-print-equivalence for @c(<object-id>) objects.
Pprints a given @cl:param(regex>) int..
Reads from @c(*bson-in*) until it finds a null (0) byte.
@c(<regex>) literal reader function.
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).
<mongo-timestamp>)) ¶Encodes the given @cl:param(value) (@c(<mongo-timestamp>) object) as an @c(octets-array).
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)).
<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.
<regex>)) ¶Encodes the given @cl:param(value) (@c(<regex>) object).
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).
(eql t))) ¶Dispatches to @c(#’encode-boolean).
(eql nil))) ¶Dispatches to @c(#’encode-boolean).
<object-id>)) ¶Encodes the given @cl:param(value) (@c(<object-id>) object).
<binary-data>)) ¶Encodes the binary data @c(subtype) and @c(octets) of the given @cl:param(value) (@c(<binary-data>) object).
vector)) ¶Dispatches to @c(#’encode-document-array).
list)) ¶Dispatches to @c(#’encode-document-array).
<document>)) ¶Calls @c(#’encode-document) for encoding the embedded document.
symbol)) ¶Coerces @cl:param(value) to string using the @cl:param(string) and call @c(#’encode-key-value) for strings.
string)) ¶Encodes an UTF-8 string @cl:param(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).
| Jump to: | (
A B C D E F G I K M O P R S |
|---|
| Jump to: | (
A B C D E F G I K M O P R S |
|---|
| Jump to: | *
C E M O P S |
|---|
| Jump to: | *
C E M O P S |
|---|
| Jump to: | <
C D E F M O P R S T |
|---|
| Jump to: | <
C D E F M O P R S T |
|---|