Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
BSON documents in Erlang, see bsonspec.org
Erlang Shell
branch: master

This branch is 29 commits behind comtihon:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
doc
ebin
include
src
README.md

README.md

This is the Bson implementation for Erlang. Bson is a record-like data type with a standard binary representation defined at http://www.bsonspec.org. This implements version 1.0 of that spec. The standard binary form allows for easy data interchange between systems. In particular, MongoDB uses it for exchanging data between the MongoDB server and its clients.

The root Bson data type is bson:document(). Conceptually, it is a list of name-value pairs, analogous to an associative array, dictionary, or record. However, in this implementation, for writability and readability, the list of pairs is flattened, (ie. the tuples for each pair are elided), and the list is actually a tuple to distinguish it from list (array) of values. So a document is a tuple with alternating name and value elements, where a name is an atom() and a value is a bson:value(), which includes basic types like boolean(), number(), atom(), bson:utf8() (string), and compound types like [bson:value()] and bson:document(). For example,

> Doc = {x,<<"abc">>, y,[1,2,3], z,{a,'Foo', b,4.2}}.

is a document with three fields: {x,<<"abc">>} and {y,[1,2,3]}, and {z,{a,'Foo', b,4.2}}. There is a function bson:fields that converts a document to a list of fields but normally you don't need it. Instead you should use the following operations on documents: bson:lookup, bson:at, bson:include, bson:exclude, bson:update, bson:merge, and bson:append.

> {[1,2,3]} = bson:lookup (y, Doc).
> {} = bson:lookup (w, Doc).
> [1,2,3] = bson:at (y, Doc). % error if missing
> {x,<<"abc">>, y,[1,2,3]} = bson:include ([x, y], Doc).
> {z,{a,'Foo', b,4.2}} = bson:exclude ([x, y], Doc).
> {x,<<"abc">>, y,[1,2,3], z,null} = bson:update (z, null, Doc).
> {x,<<"abc">>, y,[1,2,3], z,null, w,1} = bson:merge ({w,1, z,null}, Doc).
> {w,1, x,<<"abc">>, y,[1,2,3], z,{a,'Foo', b,4.2}} = bson:append ({w,1}, Doc).

For the full list of bson:value() types see the bson module. Notice that an Erlang string() will be interpreted as a list of integers, so remember to alway delimit string literals with binary brackets (eg. <<"abc">>) and convert string variables using bson:utf8. You may be tempted to use atoms instead of strings, but you should only use atoms for enumerated types.

There are some special bson:value() types like bson:javascript() that are tagged tuples, eg. {javascript, {x,1}, <<"function (y) {return y + x}">>}. But embedded documents are also tuples, so how do we distinguish between the two? The answer is the bson:value() types that are tagged tuples are purposely defined to have an odd number of elements to distinguish them from documents which have an even number of elements.

API Docs - Documentation generated from source code comments

Something went wrong with that request. Please try again.