BSON 1.0版本规范(翻译)

BSON 1.0版本规范

本文翻译自 http://bsonspec.org/spec.html

BSON是用于存储零个或多个键/值对为一个单一的实体的一个二进制格式。我们称这个实体为文档(Document)。

以下语法用于指定BSON标准的1.0版本。我们使用伪BNF语法来(编写)描述。有效数据BSON数据是由非终端显示的文档表示的。

基本类型

以下基本类型用作终端中其余的语法。每种类型必须序列化为小端字节序。

类型	内存宽度	描述
byte	1 byte	(8-bits)
int32	4 bytes	(32-bit 有符号整数，补码表示)
int64	8 bytes	(64-bit 有符号整数，补码表示)
double	8 bytes	(64-bit IEEE 754-2008 二进制浮点数)

非终端

下面指定BSON的其他语法。注意，终端引用字符的表示，应该用C语言的语义来理解(例如："\x01"代表的一个字节，二进制表示为0000 0001)。

同时，我们使用操作法*来速记重复的部分(例如：("\x01"*2)表示的是"\x01\x01")。当作为一元运算符，*表示重复出现0次或以上。

document    ::=	int32 e_list "\x00"	BSON 文档. int32表示的是组成这个文档的总字节数.
e_list      ::=	element e_list
            |	""
element     ::= "\x01" e_name double    64-bit二进制浮点数
            |	"\x02" e_name string    UTF-8 字符串
            |	"\x03" e_name document  内嵌文档
            |	"\x04" e_name document  数组
            |	"\x05" e_name binary    二进制数据
            |	"\x06" e_name           未定义(value) — 不推荐使用
            |	"\x07" e_name (byte*12)	对象Id
            |	"\x08" e_name "\x00"	布尔值 "false"
            |	"\x08" e_name "\x01"	布尔值 "true"
            |	"\x09" e_name int64     UTC 时间数据
            |	"\x0A" e_name           Null value(空值)
            |	"\x0B" e_name           cstring cstring	正则表达式 - 第一个 cstring 是正则表达式模式,
                                         第二个是正则表达式选项字符串. 选项是一个标记字符, 必须按照字母顺
                                         序存储. 有效的选项是：'i' 不区分大小写匹配, 'm'多行匹配, 'x'详
                                         细模式, 'l'去创建\w, \W,等区域(本地化)依赖设置, 's'dotall匹配
                                         ('.' 可以匹配所有字符),以及 'u'去创建 \w, \W 配置.匹配unicode.
            |	"\x0C" e_name string    (byte*12)	DB指针 — 不推荐使用
            |	"\x0D" e_name string    JavaScript代码
            |	"\x0E" e_name string    不推荐使用
            |	"\x0F" e_name code_w_s  JavaScript code w/ scope
            |	"\x10" e_name int32	    32-bit 整数
            |	"\x11" e_name int64     时间戳
            |	"\x12" e_name int64	    64-bit整数
            |	"\xFF" e_name           Min key
            |	"\x7F" e_name           Max key
e_name	    ::=	cstring	Key name
string	    ::=	int32 (byte*) "\x00"	String - Int32是总字节数 (byte*) + 1(结尾\x00)。(byte*)是零个
                                        或更多的 utf-8 编码字符。
cstring	    ::=	(byte*) "\x00"          零个或更多修改 UTF-8 编码字符后,以\x00结尾。(byte*)中必须不
                                        包含'\x00'，因此它不是完全UTF-8。
binary	    ::=	int32 subtype (byte*)	Binary - int32 是(byte*)字节数.
subtype	    ::=	"\x00"	Generic binary  子类型
            |	"\x01"	Function
            |	"\x02"	Binary (Old)
            |	"\x03"	UUID (Old)
            |	"\x04"	UUID
            |	"\x05"	MD5
            |	"\x80"	User defined
code_w_s	::=	int32 string document	Code w/ scope

笔记

• Array - 数组文档是一个正常的BSON文档。keys是从0开始顺序编号的整数.例如,一个数组['red', 'blue']编码为document表示{'0': 'red', '1': 'blue'}。keys必须是升序的。

• UTC datetime - int64是以毫秒为单位的Unix时间.

• Timestamp - 使用 MongoDB 复制和分片的特别内部类型。前4字节是增量,后4字节时间戳.

• Min key - 与其他可能的 BSON 元素值进行小于比较的特殊类型。

• Max key - 与其他可能的 BSON 元素值进行大于比较的特殊类型。

• Generic binary subtype - 这是最常用的二进制子类型，应该是默认的驱动程序和工具。

• BSON "binary"或"BinData"的数据类型用来表示的字节数组。它是有些类似于Java的ByteArray的概念。BSON 二进制值有一种亚型。这用于指示什么样的数据是在字节数组中。从0到127的子类型是预定义或保留的。从128-255 的子类型是用户定义的。

  \x02 Binary （旧版本）-这曾经是默认的子类型，但是为了支持 \x00 被否决。驱动程序和工具应务必妥善处理 \x02。二进制数据 （byte* 中的数组的二进制非终端） 的结构必须是int32后紧接着(byte*)。Int32是重复中的字节数。

  \x03 UUID （旧版本）-这曾经是 UUID 亚型，但为了支持 \x04 被否决。驱动程序和工具的语言与本机的 UUID 类型应适当地处理 \x03。

  \x80-\xFF是用户定义的子类型。二进制数据可以是任何数据。code_w_s带一个int32范围，表示代码以字节为单位的长度。该字符串是 JavaScript 代码。该文件是从标识符映射到值，表示应在其中计算字符串的范围。