6. 诊断记法

CBOR 是一种二进制交换格式. 为了方便编写文档和调试, 特别是为了方便协作调试的各个实体之间交流, 本节定义一种简单的人类可读的诊断记法. 所有实际的交换始终以二进制格式进行.

请注意, 这确实只是一种诊断格式; 它并不是为了被解析而设计的. 因此, 本文档不给出形式化定义 (如 ABNF). (正在为配置文件寻找表示 CBOR 数据项的基于文本的格式的实现者, 也可以考虑 YAML [YAML].)

诊断记法大致基于 RFC 4627 中定义的 JSON, 并在需要的地方对其加以扩展.

该记法借用了 JSON 对数值 (整数和浮点数)、True (>true<)、False (>false<)、Null (>null<)、UTF-8 串、数组和映射的语法 (映射在 JSON 中称为对象; 诊断记法在此对 JSON 加以扩展, 允许在键的位置上出现任意数据项). Undefined 按 JavaScript 的写法写成 >undefined<. 非有限浮点数 Infinity、-Infinity 和 NaN 的写法与这句话中完全相同 (这也是它们在 JavaScript 中的写法之一, 尽管 JSON 不允许它们). 带标签的数据项写成标签的整数值后跟括号中的数据项; 例如, 一个 RFC 3339 (ISO 8601) 日期可以记为:

0("2013-03-21T20:04:00Z")

或等价的相对时间:

1(1363896240)

字节串用某种基数编码表示, 不带填充, 包在单引号中, 并以 >h< 作为 base16 的前缀、>b32< 作为 base32 的前缀、>h32< 作为 base32hex 的前缀、>b64< 作为 base64 或 base64url 的前缀 (这些编码本身并不重叠, 因此字符串仍然是无歧义的). 例如, 字节串 0x12345678 可以写成 h'12345678'、b32'CI2FM6A' 或 b64'EjRWeA'.

未分配的简单值写成 "simple()", 括号中填入相应的整数. 例如, "simple(42)" 表示主类型 7、值 42.

6.1. 编码指示符

有时需要在诊断记法中指明实际使用的是若干种可选表示中的哪一种; 例如, 被诊断解码器写成 >1.5< 的数据项, 可能被编码为半精度、单精度或双精度浮点数.

编码指示符的约定是: 任何以下划线开头、其后所有字符均为字母数字或下划线的部分, 都是一个编码指示符, 对此信息不感兴趣的任何人都可以忽略它. 编码指示符始终是可选的.

可以在映射的左花括号或数组的左方括号之后写一个单独的下划线, 以表示该数据项是用不定长格式表示的. 例如, [_ 1, 2] 包含一个指示符, 表明数据项 [1, 2] 是用不定长表示法表示的.

下划线后跟一个十进制数字 n, 表示前一项 (对于数组和映射, 则是以前一个方括号或花括号开始的项) 是用附加信息值 24+n 编码的. 例如, 1.5_1 是一个半精度浮点数, 而 1.5_3 被编码为双精度. 该编码指示符在附录 A 中没有显示. (注意, 编码指示符 "_" 因此是完整形式 "_7" 的缩写, 后者并不使用.)

作为一种特殊情况, 不定长的字节串和文本串可以记为 (_ h'0123', h'4567') 和 (_ "foo", "bar") 的形式.