Introduction to bson

ver 1.1.2

.. image:: https://raw.githubusercontent.com/yglukhov/nimble-tag/master/nimble.png :height: 34 :width: 131 :alt: nimble :target: https://nimble.directory/pkg/bson

.. image:: https://repo.support/img/rst-banner.png :height: 34 :width: 131 :alt: repo.support :target: https://repo.support/gh/JohnAD/bson

BSON

This is a Nim library for supporting BSON. BSON is short for Binary JSON -- a compact binary protocol similar to the JSON it is based on.

Most notably, MongoDB, a document-oriented database uses BSON for it's underlying storage, though there are other applications that use it as well.

More details about the protocol can be found at:

http://bsonspec.org/

More detail can also be found in the reference document linked at the bottom.

CREATING A BSON DOCUMENT USING BRACKETS

You can use a pair of '@@' symbols prefixing a pair of curly braces with json-like data in between to create a quick an easy BSON document.

For example:

.. code:: nim

var doc = @@{"name": "Joe", "age": 42, "siblings": ["Amy", "Jerry"]}

CREATING A BSON DOCUMENT MANUALLY

Start building a BSON document by declaring a new document with newBsonDocument and start building out items in that document as if were using a table.

.. code:: nim

var doc = newBsonDocument()
doc["name"] = "Joe"
doc["age"] = 42

You can also add sub elements such as lists (with newBsonArray) and other documents (with newBsonDocument):

.. code:: nim

doc["siblings"] = newBsonArray()
doc["siblings"].add "Amy"
doc["siblings"].add "Jerry"
doc["schedule"] = newBsonDocument()
doc["schedule"]["8am"] = "go to work"
doc["schedule"]["11am"] = "see dentist"

READING A BSON DOCUMENT

To read a BSON document, you can reference the field by string in either traditional square brackets ([]) or the forgiving curly brackets ({}).

.. code:: nim

var doc = @@{
  "name": "Joe",
  "address": {"city": "New Orleans", "state": "LA"},
  "pots": [9, 22, 16]
}

let personName = doc["name"]                 # set to "Joe"
let personState = doc["address"]["state"]    # set to "LA"
let secondPot = doc["pots"][1]               # set to 22

When using square brackets, if the key is missing a runtime error is generated. But when using curly brackets, a missing key simply results in a null. And, the keys can be separated by commas to easily transverse down the tree.

.. code:: nim

let personCity = doc{"address", "city"}      # set to "New Orleans"
let personCode = doc{"address", "postal"}    # set to null
let thirdPot = doc{"pots", "2"}              # set to 16
let fourthPot = doc{"pots", "3"}             # set to null

GENERATING THE BSON CODE

To generate the actual binary code, such as to stream to a file or a service, use the 'bytes' function:

.. code:: nim

var bString: string = doc.bytes()

Please keep in mind that this is a binary packed string and is not printable.

To convert a binary blob of data back into a Bson library document, pass the string into 'newBsonDocument' as a string parameter.

.. code:: nim

var newDoc = newBsonDocument(bString)

HANDLING TYPES

The BSON specification calls for 18 types of data (and a few subtypes).

Not all of them are fully supported by the libary yet.

=============================== ================= =========================== BSON Nim Equiv Notes =============================== ================= =========================== 64-bit binary floating point float Nim defaults to 64 bit UTF-8 string string Nim strings are UTF-8 ready by default Embedded document newBsonDocument from this library. for key/value pairs, the key must always be a string Array newBsonArray technically a list, not an array, because you can mix types Binary data string (binary) not always printable, but works, see binstr ObjectId Oid from standard oids library <https://nim-lang.org/docs/oids.html> Boolean "false" bool = false Boolean "true" bool = true UTC datetime Time from standard times library <https://nim-lang.org/docs/times.html> Null value null from this library Regular expression regex() from this library DBPointer (deprecated) dbref() from this library JavaScript code js() from this library JavaScript code w/ scope 32-bit integer int32 Timestamp BsonTimestamp from this library. Do not use to store dates or time. Meant for internal use by MongoDb only. 64-bit integer int64 128-bit decimal floating point would like to support ! Min key Max key =============================== ================= ===========================

Marshal

There is a submodule called marshal, that allows for the easy conversion of object types to/from BSON. It has a single macro: marshal which generates toBson and pull procedure for the object.

An example:

.. code:: nim

import bson
import bson/marshal

type
  User = object
    name: string
    height: Option[float]

marshal(User)

var u = User()

var someBson = @@{"name": "Bob", "height": 95.3}

u.pull(someBson)

assert u.name == "Bob"

See the bson/marshal Reference link in the Table of Contents below for more detail.

Credit

Large portions of this code were pulled from the nimongo project, a scalable pure-nim mongodb driver. See https://github.com/SSPkrolik/nimongo

However, this library is NOT compatilible with nimongo, as nimongo relies on an internal implementation of BSON.

Table Of Contents

1. Introduction to bson <https://github.com/JohnAD/bson>__

2. Appendices

   A. bson Reference <https://github.com/JohnAD/bson/blob/master/docs/bson-ref.rst> B. bson/marshal Reference <https://github.com/JohnAD/bson/blob/master/docs/bson-marshal-ref.rst>