cl-BSON ยป BSON Types

The BSON specification has a few more types than the built-in Common Lisp types. cl-bson defines classes for those types.

The cl-bson.readtable package defines the following BSON types/classes:

It exports all classes slot accessors symbols and classes symbols.

It also exports two custom types: octet and octets-array.

Classes and methods

<OBJECT-ID>

<object-id>

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

The structure of the array is:

  1. a 4-byte value representing the seconds since the Unix epoch.
  2. a 3-byte machine identifier.
  3. a 2-byte process id
  4. a 3-byte counter, starting with a random value.

Check the reference for more info.

  • octets
    Array of actual OCTETS-ARRAY that represent the MongoDB ObjectId. Value generated by #'generate-object-id.
str(object-id)
The hexadecimal string representation of the given object-id. Method from the reference.
* (str (make-instance '<object-id>))
; => "35F97455616E6477630600D3"
get-timestamp(object-id)
Returns the timestamp portion of object-id as a local-time:timestamp. The local-time:timestamp is used to represent the MongoDB Date.
string->object-id(string)
Utility for instanciating an <object-id> from a given string. Useful for fetching documents with parameters received from HTTP requests.
;; without the custom pprinter:
* (string->object-id "35F97455616E6477630600D3")
; => #<<OBJECT-ID> {1008C48CE3}>

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

Generates a fresh 12 bytes octets-array for an <object-id>.

A typical array looks like: 

* (generate-object-id)
; => #(34 250 116 85 97 110 100 119 99 7 0 211)

...where:

  • #(34 250 116 85) is the Unix timestamp of when it was generated. See it with: 
    * (get-timestamp (make-instance '<object-id> :octets *))
; => @2015-06-07T23:12:50.000000-03:00
  • #(97 110 100) is the machine identifier. See it with: 
    * (babel:octets-to-string (subseq (generate-object-id) 4 7))
; => "and" ;; three first letters of "andreh"
  • #c(119 99) is the PID. See it with: 
    * (intbytes:octets->int (subseq (generate-object-id) 7 9) 2)
; => 25463
  • #(10 0 211) is the counter. See it with: 
    * *object-id-counter*
; => 13828114
* (intbytes:octets->uint (subseq (generate-object-id) 9 12) 3)
; => 13828115
* *object-id-counter*
; => 13828115
*object-id-counter*
3-byte size integer counter, starting with a random value: (random (expt 2 24)) .
increment-id-counternil
Increments *OBJECT-ID-COUNTER* up to (1- (expt 2 24)). When pass that, it "overflows" back to 0.

<REGEX>

<regex>
This class is used to represent regexps in the BSON document.
  • pattern
    This slot holds the actual regex pattern as a string.
  • options
    This slot holds the options of the <regex> object as an alphabetically sorted 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
No node with name setf.
No node with name initialize-instance.

<BINARY-DATA>

<binary-data>
This class is used to represent custom array of bytes in BSON. <binary-data> values have a 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 :user-defined.
  • subtype
    This slot holds a keyword that represents one of the <binary-data> subtypes. A valid subtype is any of the following: :generic, :function, :binary-old(deprecated), :uuid-old(deprecated), :uuid, :md5 or :user-defined.
  • octets
    This slot holds the actual binary data.
No node with name setf.
No node with name initialize-instance.

<JAVASCRIPT>

<javascript>
This class puts together two BSON types: "JavaScript code" and "Code with scope". When the scope slot is nil(default), a <javascript> object gets encoded as "JavaScript code". When the scope slot is not nil, <javascript> gets encoded as "Code with scope".
  • code
    This slot holds JavaScript code as a string.
  • scope
    This slot holds a <document> that represents the scope in which the string should be evaluated. The <document> is a mapping from identifiers to values.

<MONGO-TIMESTAMP>

<mongo-timestamp>

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

The structure of the array is:

  1. 4 bytes are an increment, starting with a random value.
  2. 4 bytes are seconds since the Unix epoch.
generate-mongo-timestampnil
Generates a fresh 8 bytes octets-array for a <mongo-timestamp>.
increment-mongo-timestamp-counternil
Increments *MONGO-TIMESTAMP-COUNTER* up to (1- (expt 2 32)). When pass that, it "overflows" back to 0.
*mongo-timestamp-counter*
4-byte size integer counter, starting with a random value: (random (expt 2 32)).

<DOCUMENT>

<document>

Main class for interacting with MongoDB.

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

  • elements
    hash-table that holds all the the document data.
make-document(&key (_id (make-instance (quote <object-id>))))
Utility function to easily create <document>s already with an <object-id. To create an <document> with an _id from a string, use: 
(make-document :_id (string->object-id "my id string"))
.
add-element(document key value)
Properly adds a given key-value pair to the document. The key is coerced to string using the string function. The type of the value must be a valid BSON supported type.
get-element(document key)
Gets the elements identified by key. key is coerced to string using the string.
remove-element(document key)
Removes the elements identified by key. key is coerced to string using string.
keys(document)
Returns all keys of the document.