ver 1.1.2
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.
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:
var doc = @@{"name": "Joe", "age": 42, "siblings": ["Amy", "Jerry"]}
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.
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):
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"
To read a BSON document, you can reference the field by string in either
traditional square brackets ([]
) or the forgiving curly brackets ({}
).
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.
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
To generate the actual binary code, such as to stream to a file or a service, use the 'bytes' function:
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.
var newDoc = newBsonDocument(bString)
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 |
Boolean "false" | bool = false | |
Boolean "true" | bool = true | |
UTC datetime | Time | from standard times library |
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 |
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:
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.
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.