cl-bson

API Reference

cl-bson

BSON encoder/decoder for Common Lisp.

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).
  • Type OCTET
    Equivalent to @c'(UNSIGNED-BYTE 8)). A 8-bit byte.
  • Type OCTETS-ARRAY (&optional (size '*))
    A @c(SIMPLE-ARRAY) of @c('(UNSIGNED-BYTE 8)).
  • 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.
    OCTETS   Accessor: 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).
  • 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" )
  • Method STR ((object-id <object-id>))
  • Method STR ((object-id <object-id>))
  • Method STR ((object-id <object-id>))
  • 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) )
  • 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).
  • Method GET-TIMESTAMP ((object-id <object-id>))
  • Method GET-TIMESTAMP ((object-id <object-id>))
  • Method GET-TIMESTAMP ((object-id <object-id>))
  • Class <REGEX>
    This class is used to represent regexps in the BSON document.
    PATTERN   Accessor: PATTERN
    This slot holds the actual regex pattern as a @i(string).
    OPTIONS   Accessor: 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
  • Variable *ALLOWED-REGEX-OPTIONS*
    '(#\i #\l #\m #\s #\u #\w #\x)
    List of charaters allowed in the @c(options) slot of a @c(<regex>) object.
  • 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).
  • Method (setf OPTIONS) ((options string) (regex <regex>))
  • Method (setf OPTIONS) ((options string) (regex <regex>))
  • Method (setf OPTIONS) ((options string) (regex <regex>))
  • 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).
    SUBTYPE   Accessor: 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).
    OCTETS   Accessor: OCTETS
    This slot holds the actual binary data.
  • Method (setf SUBTYPE) ((subtype symbol) (binary-data <binary-data>))
  • 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".
    CODE   Accessor: CODE
    This slot holds JavaScript code as a @i(string).
    SCOPE   Accessor: 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.
  • 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)
    MONGO-TIME   Accessor: MONGO-TIME
    Array of actual @c(octets-array) that represent the @link[uri="http://docs.mongodb.org/manual/reference/bson-types/#timestamps"](Mongo Timestamp).
  • 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.
    ELEMENTS   Accessor: ELEMENTS
    @c(hash-table) that holds all the the document data.
  • 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.
  • Function MAKE-DOCUMENT (&key (_id (make-instance '<object-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"))).
  • Method ADD-ELEMENT ((document <document>) key (value symbol))
  • 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).
  • Method GET-ELEMENT ((document <document>) key)
  • Method GET-ELEMENT ((document <document>) key)
  • Method GET-ELEMENT ((document <document>) key)
  • 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).
  • Generic-Function KEYS (document)
    Returns all keys of the @cl:param(document).
  • Method KEYS ((document <document>))
  • Method KEYS ((document <document>))
  • Method KEYS ((document <document>))

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)
  • 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).
  • Function ENABLE-BSON-DOCUMENT-PRINTER
    Enable pprinter for @c(<document>) objects.
  • Function ENABLE-OBJECT-ID-PRINTER
    Enable pprinter for @c(<object-id>) objects.
  • Function ENABLE-PRINTERS
    Enables pprinter for both @c(<document>) and @c(<object-id>) objects.
  • Function DISABLE-BSON-DOCUMENT-PRINTER
    Disables the pprinter for @c(<document>) objects.
  • Function DISABLE-OBJECT-ID-PRINTER
    Disables the pprinter for @c(<object-id>) objects.
  • Function DISABLE-PRINTERS
    Disables pprinter for @c(<document>) and @c(<object-id>) objects.

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).
  • Variable *BSON-OUT*
    nil
    Special var that gets bound to @c(fast-io:output-buffer) on every @c(#'encode) call.
  • 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).
  • Method ENCODE ((document <document>))
  • Method ENCODE ((document <document>))
  • Method ENCODE ((document <document>))

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.
  • Variable *BSON-IN*
    nil
    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*).
  • Function READ-N-BYTES (n)
    Reads @cl:param(n) bytes from @c(*bson-in*).
  • Function DECODE-INT32
    Decodes a 4 bytes integer from @c(*bson-in*).
  • Function DECODE-INT64
    Decodes an 8 bytes integer from @c(*bson-in*).
  • Variable *BSON-SEQUENCE-TYPE*
    'vector
    Special variable that holds the kind of output to return when decoding a BSON array.
  • 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).

CL-BSON

No exported symbols.

Also exports

  • CL-BSON.READTABLE:ENABLE-BSON-DOCUMENT-PRINTER
  • CL-BSON.TYPES:STRING->OBJECT-ID
  • CL-BSON.TYPES:OCTETS
  • CL-BSON.TYPES:<DOCUMENT>
  • CL-BSON.TYPES:OCTET
  • CL-BSON.TYPES:PATTERN
  • CL-BSON.TYPES:REMOVE-ELEMENT
  • CL-BSON.READTABLE:DISABLE-BSON-DOCUMENT-PRINTER
  • CL-BSON.ENCODE:ENCODE
  • CL-BSON.TYPES:SUBTYPE
  • CL-BSON.READTABLE:BSON-SYNTAX
  • CL-BSON.TYPES:GET-ELEMENT
  • CL-BSON.TYPES:OPTIONS
  • CL-BSON.TYPES:KEYS
  • CL-BSON.TYPES:STR
  • CL-BSON.TYPES:ELEMENTS
  • CL-BSON.DECODE:DECODE
  • CL-BSON.READTABLE:ENABLE-OBJECT-ID-PRINTER
  • CL-BSON.TYPES:MAKE-DOCUMENT
  • CL-BSON.READTABLE:ENABLE-PRINTERS
  • CL-BSON.READTABLE:DISABLE-PRINTERS
  • CL-BSON.TYPES:SCOPE
  • CL-BSON.TYPES:GET-TIMESTAMP
  • CL-BSON.TYPES:<REGEX>
  • CL-BSON.TYPES:OCTETS-ARRAY
  • CL-BSON.DECODE:*BSON-SEQUENCE-TYPE*
  • CL-BSON.TYPES:<BINARY-DATA>
  • CL-BSON.TYPES:<JAVASCRIPT>
  • CL-BSON.TYPES:<OBJECT-ID>
  • CL-BSON.TYPES:<MONGO-TIMESTAMP>
  • CL-BSON.READTABLE:DISABLE-OBJECT-ID-PRINTER
  • CL-BSON.TYPES:CODE
  • CL-BSON.TYPES:ADD-ELEMENT
  • CL-BSON.TYPES:MONGO-TIME

cl-bson-test

Test system for cl-BSON.

No packages.