UBJSON

Reference

encode( data )

Serialize a data.

decode( str )

Deserialize a string.

decoder( src )

Accept a string or a ltn12.source and returns a iterator.

The iterator gives a couple of values, the interesting value is the second one.

set_string( str )

Configures the behaviour of encode. The valid options are 'binary', 'text' and 'check_utf8'. The default is 'text'.

set_array( str )

Configures the behaviour of encode. The valid options are 'without_hole', 'with_hole' and 'always_as_object'. The default is 'with_hole'.

set_float( str )

Configures the behaviour of encode. The valid options are 'float32', 'float64' and 'high-precision'. The default is 'float64' with a standard Lua interpreter.

encode_name( str )

Encodes a name or a key, ie. a string without the marker S (typically used for streaming of object).

open_array( [count [, type]] )

Encodes the start of an array with by an optional count and an optional type marker.

open_object( [count [, type]] )

Encodes the start of an object with by an optional count and an optional type marker.

close_array()

Returns the marker ].

close_object()

Returns the marker }.

no_op()

Returns the marker N.

Data Conversion

  • The following Lua types could be converted : nil, boolean, number, string and table.
  • A Lua number has one of two subtypes: integer and float. A Lua integer is converted into an UBJSON integer. A Lua float is converted into the UBJSON float32 or float64 or high-precision (see set_float).
  • When a Lua table is converted into UBJSON, some parts could be discarded (like JSON, the only permitted key or name of an UBJSON object are string).
  • A Lua table is converted into a UBJSON array only if all the keys are composed of strictly positive integers, without hole or with holes (see set_array). Otherwise it is converted into UBJSON object.
  • With set_array'without_hole', all values after a hole are discarded.
  • With set_array'always_as_object', all Lua table are converted into a UBJSON object (non-string keys are discarded).
  • LIMITATION : UBJSON cannot handle data with cyclic reference.

Examples

Basic usage

local u = require'ubjson'

u.set_float'float32'
u.set_array'with_hole'
u.set_string'text'

ubj = u.encode(data)
data = u.decode(ubj)

See other usages in Stream.

Advanced usage

The following Lua hack allows to have several instances of the module ubjson, each one with its own settings.

local u1 = require'ubjson'
package.loaded['ubjson'] = nil    -- the hack is here
local u2 = require'ubjson'

u1.set_array'without_hole'
u2.set_array'always_as_object'