lua-cbson
lua-cbson copied to clipboard
Lua bindings for libbson
Lua-cbson
Lua bindings to MongoDB's libbson
Table of Contents
- FAQ
- Requirements
- Installation
- Usage
- Authors
- Copyright and License
FAQ
- Q: Is it compatible with cjson?
A: Hell no. All bson subtypes are defined as userdata. Use cbson.to_json and cbson.from_json - Q: What about integers?
A: Lua, prior to 5.3 stores all numbers as double. So, cbson.encode({foo = 10}) will yield double bson type.
Use cbson.int datatype. It will automaticaly yield int32 or int64 depending on value.
Requirements
- Lua (5.1/5.2) or LuaJit
- Cmake 2.8.12 or later
- Working C compiler
- libbson 1.7 or later
Installation
Manual
As easy as
mkdir build
cd build
cmake ..
make
make install
You can also use make unittest
after make to run tests.
By default module compiles with support for luajit
For other Lua interpreters see cmake options.
LuaRocks
Via rockspec-file:
luarocks install https://raw.githubusercontent.com/isage/lua-cbson/master/rockspec/lua-cbson-git-1.rockspec
use specific lua version or luajit
luarocks --lua-dir=/usr/local/opt/openresty/luajit install https://raw.githubusercontent.com/isage/lua-cbson/master/rockspec/lua-cbson-git-1.rockspec
See all available versions of lua-bson in [./rockspec](rockspec directory).
Usage
Synopsis
local cbson = require "cbson"
local table_data = cbson.decode(bson_data)
local bson_data = cbson.encode(table_data)
local json_string = cbson.to_json(bson_data)
local json_string = cbson.to_relaxed_json(bson_data)
local bson_data = cbson.from_json(json_string)
Compatibility with cjson array metatables
cjson
(2.1.0.5 and higher) uses metatable for set table (especially empty) as arrays, so this library can use this (or other)
metatable for encoding and decoding arrays. See usage array metatables example
CBSON Functions
<table>decoded = cbson.decode(<binary>bson_data)
Decodes binary BSON data to lua table.
<binary>bson_data = cbson.encode(<table>data)
Encodes lua table to binary BSON data.
local cbson = require "cbson"
-- Encodes lua table
local bson_data = cbson.encode({foobar = {bar = "hello", foo = "world"}})
print(cbson.to_json(bson_data)) -- { "foobar" : { "foo" : "world", "bar" : "hello" } }
-- Encodes lua table containing bson data
local bson_data = cbson.encode({foobar = cbson.from_json('{"bar":"hello","foo":"world"}')})
print(cbson.to_json(bson_data)) -- { "foobar" : { "bar" : "hello", "foo" : "world" } }
<binary>bson_data = cbson.encode_first(<string>first_key, <table>data)
Encodes lua table to binary BSON data, putting first_key value at start of bson.
(required for mongodb commands)
Make sure, that given key exists, otherwise it'll add this key with NULL value.
<binary>bson_data = cbson.from_json(<string>json)
Encodes json string as binary BSON data.
<string>json_data = cbson.to_json(<binary>bson_data)
Encodes binary BSON data as json string.
<string>json_data = cbson.to_relaxed_json(<binary>bson_data)
Encodes binary BSON data as relaxed json string.
Embed datatypes
cbson.regex(<string>regex, <string>options)
local regex = cbson.regex("foo|bar","ism")
print( regex:regex() )
regex:regex("bar|foo")
regex:options("im")
print( regex:options() )
cbson.oid(<string>oid) or cbson.oid(<oid>oid)
Unique object id with 24 hex numbers.
local oid = cbson.oid("1234567890ABCDEF01234567")
local oid2 = cbson.oid(oid)
Get time from oid
(first 8 hex numbers):
local timestamp = oid:timestamp()
print(timestamp) -- 305419896
cbson.binary(<string>base64_encoded_data[, <int> type])
local binary = cbson.binary("ZGVhZGJlZWY=")
print( binary:raw() ) -- returns raw binary data "deadbeef"
binary:set_raw("hello") -- binary:raw("hello") works fine
print( binary:data() ) -- returns base64 encoded data "aGVsbG8="
binary:set_data("ZGVhZGJlZWY=")
Maximum size of binary string is 4,294,967,295
bytes.
cbson.symbol(<string>symbol)
local symbol = cbson.symbol("something")
cbson.code(<string>code)
local code = cbson.code("code")
cbson.codewscope(<string>code)
Scopes are not supported yet.
local code = cbson.codewcope("code")
cbson.undefined()
local undef = cbson.undefined()
cbson.null()
local null = cbson.null()
cbson.array()
local empty_array = cbson.array()
cbson.minkey()
local minkey = cbson.minkey()
cbson.maxkey()
local maxkey = cbson.maxkey()
cbson.ref(<string>ref, <string>id)
local ref = cbson.ref("foo", "123456789012345678901234")
print( ref:ref() )
ref:ref("bar")
ref:id("432109876543210987654321")
cbson.timestamp(<number>timestamp, <number>increment)
BSON has a special timestamp
type for internal
MongoDB use and is not associated with the regular date
type.
local timestamp = cbson.timestamp(100,1000)
timestamp:timestamp(500)
print( timestamp:timestamp() ) -- 500
timestamp:increment(100500)
print( timestamp:increment() ) -- 100500
cbson.int(<number>value) or cbson.int(<int>value) or cbson.int(<string>value)
That's basically int64. It supports all arithmetic operations.
Due to nature of lua numbers, you can pass big (> 2^53) numbers only as string.
It also have __tostring metamethod for opposite operation.
There's also helper methods int_to_raw/uint_to_raw(<int>value, <number>bytes, <bool>big_endian)
and raw_to_int/raw_to_uint(<string>data, <bool>big_endian)
for converting between number and in-memory representation.
local int = cbson.int(10)
print(int) -- 10
local int = cbson.int("100")
print(int) -- 100
local int = cbson.int("100")
print(int:number() + 20) -- 120
local int = cbson.int(10)
local int2 = cbson.int(int)
print(int2) -- 10
cbson.uint(<number>value) or cbson.uint(<uint>value) or cbson.uint(<string>value)
See cbson.int. They are same (except sign), and you can init one from another.
cbson.date(<number>value) or cbson.date(<date>value) or cbson.date(<string>value)
BSON Date is a 64-bit integer that represents the number of milliseconds since the Unix epoch (Jan 1, 1970). This results in a representable date range of about 290 million years into the past and future.
cbson.decimal(<string>value)
Since version 1.1
.
It's decimal128.
The Decimal128 supports 34 decimal digits of precision,
a max value of approximately 10^6145
, and min value of approximately -10^6145
local dec = cbson.decimal("1.0")
print(dec) -- 1.0
local dec = cbson.decimal("0.0005")
print(dec) -- 0.0005
Authors
Epifanov Ivan [email protected]
Back to TOC
Copyright and License
This module is licensed under the WTFPL license.
(See LICENSE)