前言
JSON 是什么
JSON(JavaScript Object Notation)是一个用于数据交换的文本格式,现时的标准为ECMA-404。
虽然 JSON 源至于 JavaScript 语言,但它只是一种数据格式,可用于任何编程语言。现时具类似功能的格式有 XML、YAML,当中以 JSON 的语法最为简单。
例如,一个动态网页想从服务器获得数据时,服务器从数据库查找数据,然后把数据转换成 JSON 文本格式
{
"title": "Design Patterns",
"subtitle": "Elements of Reusable Object-Oriented Software",
"author": [
"Erich Gamma",
"Richard Helm",
"Ralph Johnson",
"John Vlissides"
],
"year": 2009,
"weight": 1.8,
"hardcover": true,
"publisher": {
"Company": "Pearson Education",
"Country": "India"
},
"website": null
}
网页的脚本代码就可以把此 JSON 文本解析为内部的数据结构去使用。
从此例子可看出,JSON 是树状结构,而 JSON 只包含 6 种数据类型:
- null: 表示为 null
- boolean: 表示为 true 或 false
- number: 一般的浮点数表示方式,在下一单元详细说明
- string: 表示为 “…”
- array: 表示为 [ … ]
- object: 表示为 { … }
JSON库设计
我们要实现的 JSON 库,主要是完成 3 个需求:
1 把 JSON 文本解析为一个树状数据结构(parse)。
2 提供接口访问该数据结构(access)。
3 把数据结构转换成 JSON 文本(stringify)。
null 和 boolean 解析
如前所述,JSON 中有 6 种数据类型,如果把 true 和 false 当作两个类型就是 7 种,我们为此声明一个枚举类型(enumeration type):
typedef enum { LEPT_NULL, LEPT_FALSE, LEPT_TRUE, LEPT_NUMBER, LEPT_STRING, LEPT_ARRAY, LEPT_OBJECT } lept_type;
因为 C 语言没有 C++ 的命名空间(namespace)功能,一般会使用项目的简写作为标识符的前缀。通常枚举值用全大写(如 LEPT_NULL),而类型及函数则用小写(如 lept_type)。
接下来,我们声明 JSON 的数据结构。JSON 是一个树形结构,我们最终需要实现一个树的数据结构,每个节点使用 lept_value 结构体表示,我们会称它为一个 JSON 值(JSON value)。 在此单元中,我们只需要实现 null, true 和 false 的解析,因此该结构体只需要存储一个 lept_type。之后的单元会逐步加入其他数据。
typedef struct {
lept_type type;
}lept_value;
C 语言的结构体是以 struct X {} 形式声明的,定义变量时也要写成 struct X x;。为方便使用,上面的代码使用了 typedef。
然后,我们现在只需要两个 API 函数,一个是解析 JSON:
int lept_parse(lept_value* v, const char* json);
传入的 JSON 文本是一个 C 字符串(空结尾字符串/null-terminated string),由于我们不应该改动这个输入字符串,所以使用 const char* 类型。
另一注意点是,传入的根节点指针 v 是由使用方负责分配的,所以一般用法是:
lept_value v;
const char json[] = ...;
int ret = lept_parse(&v, json);
返回值是以下这些枚举值,无错误会返回 LEPT_PARSE_OK。
enum {
LEPT_PARSE_OK = 0,
LEPT_PARSE_EXPECT_VALUE,
LEPT_PARSE_INVALID_VALUE,
LEPT_PARSE_ROOT_NOT_SINGULAR
};
现时我们只需要一个访问结果的函数,就是获取其类型:
lept_type lept_get_type(const lept_value* v);
JSON 语法子集
下面是此单元的 JSON 语法子集,使用 RFC7159 中的 ABNF 表示:
JSON-text = ws value ws
ws = *(%x20 / %x09 / %x0A / %x0D)
value = null / false / true
null = "null"
false = "false"
true = "true"
当中 %xhh 表示以 16 进制表示的字符,/ 是多选一,* 是零或多个,( ) 用于分组。
那么第一行的意思是,JSON 文本由 3 部分组成,首先是空白(whitespace),接着是一个值,最后是空白。
第二行告诉我们,所谓空白,是由零或多个空格符(space U+0020)、制表符(tab U+0009)、换行符(LF U+000A)、回车符(CR U+000D)所组成。
第三行是说,我们现时的值只可以是 null、false 或 true,它们分别有对应的字面值(literal)。
我们的解析器应能判断输入是否一个合法的 JSON。如果输入的 JSON 不合符这个语法,我们要产生对应的错误码,方便使用者追查问题。
在这个 JSON 语法子集下,我们定义 3 种错误码:
1 若一个 JSON 只含有空白,传回 LEPT_PARSE_EXPECT_VALUE。
2 若一个值之后,在空白之后还有其他字符,传回 LEPT_PARSE_ROOT_NOT_SINGULAR。
3 若值不是那三种字面值,传回 LEPT_PARSE_INVALID_VALUE。
单元测试
在做练习或刷题时,都是以 printf/cout 打印结果,再用肉眼对比结果是否乎合预期。但当软件项目越来越复杂,这个做法会越来越低效。一般我们会采用自动的测试方式,例如单元测试(unit testing)。单元测试也能确保其他人修改代码后,原来的功能维持正确(这称为回归测试/regression testing)。
一般来说,软件开发是以周期进行的。例如,加入一个功能,再写关于该功能的单元测试。但也有另一种软件开发方法论,称为测试驱动开发(test-driven development, TDD),它的主要循环步骤是:
- 加入一个测试。
- 运行所有测试,新的测试应该会失败。
- 编写实现代码。
- 运行所有测试,若有测试失败回到3。
- 重构代码。
- 回到 1。
TDD 是先写测试,再实现功能。好处是实现只会刚好满足测试,而不会写了一些不需要的代码,或是没有被测试的代码。
leptjson 项目,test.c
包含了一个极简的单元测试框架:
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "leptjson.h"
static int main_ret = 0;
static int test_count = 0;
static int test_pass = 0;
#define EXPECT_EQ_BASE(equality, expect, actual, format) \
do {\
test_count++;\
if (equality)\
test_pass++;\
else {\
fprintf(stderr, "%s:%d: expect: " format " actual: " format "\n", __FILE__, __LINE__, expect, actual);\
main_ret = 1;\
}\
} while(0)
#define EXPECT_EQ_INT(expect, actual) EXPECT_EQ_BASE((expect) == (actual), expect, actual, "%d")
static void test_parse_null() {
lept_value v;
v.type = LEPT_TRUE;
EXPECT_EQ_INT(LEPT_PARSE_OK, lept_parse(&v, "null"));
EXPECT_EQ_INT(LEPT_NULL, lept_get_type(&v));
}
/* ... */
static void test_parse() {
test_parse_null();
/* ... */
}
int main() {
test_parse();
printf("%d/%d (%3.2f%%) passed\n", test_pass, test_count, test_pass * 100.0 / test_count);
return main_ret;
}
宏的编写技巧
不了解 EXPECT_EQ_BASE
宏的编写技巧,简单说明一下。反斜线代表该行未结束,会串接下一行。而如果宏里有多过一个语句(statement),就需要用 do { /*...*/ } while(0)
包裹成单个语句,否则会有如下的问题:
#define M() a(); b()
if (cond)
M();
else
c();
/* 预处理后 */
if (cond)
a(); b(); /* b(); 在 if 之外 */
else /* <- else 缺乏对应 if */
c();
只用 { }
也不行:
#define M() { a(); b(); }
/* 预处理后 */
if (cond)
{ a(); b(); }; /* 最后的分号代表 if 语句结束 */
else /* else 缺乏对应 if */
c();
用 do while 就行了:
#define M() do { a(); b(); } while(0)
/* 预处理后 */
if (cond)
do { a(); b(); } while(0);
else
c();
实现解析器
有了 API 的设计、单元测试,终于要实现解析器了。
首先为了减少解析函数之间传递多个参数,我们把这些数据都放进一个 lept_context
结构体:
typedef struct {
const char* json;
}lept_context;
/* ... */
/* 提示:这里应该是 JSON-text = ws value ws */
/* 以下实现没处理最后的 ws 和 LEPT_PARSE_ROOT_NOT_SINGULAR */
int lept_parse(lept_value* v, const char* json) {
lept_context c;
assert(v != NULL);
c.json = json;
v->type = LEPT_NULL;
lept_parse_whitespace(&c);
return lept_parse_value(&c, v);
}
暂时我们只储存 json 字符串当前位置,之后的单元我们需要加入更多内容。
若 lept_parse()
失败,会把 v
设为 null
类型,所以这里先把它设为 null
,让 lept_parse_value()
写入解析出来的根值。
leptjson 是一个手写的递归下降解析器(recursive descent parser)。由于 JSON 语法特别简单,我们不需要写分词器(tokenizer),只需检测下一个字符,便可以知道它是哪种类型的值,然后调用相关的分析函数。对于完整的 JSON 语法,跳过空白后,只需检测当前字符:
- n ➔ null
- t ➔ true
- f ➔ false
- " ➔ string
- 0-9/- ➔ number
- [ ➔ array
- { ➔ object
所以,我们可以按照 JSON 语法一节的 EBNF 简单翻译成解析函数:
#define EXPECT(c, ch) do { assert(*c->json == (ch)); c->json++; } while(0)
/* ws = *(%x20 / %x09 / %x0A / %x0D) */
static void lept_parse_whitespace(lept_context* c) {
const char *p = c->json;
while (*p == ' ' || *p == '\t' || *p == '\n' || *p == '\r')
p++;
c->json = p;
}
/* null = "null" */
static int lept_parse_null(lept_context* c, lept_value* v) {
EXPECT(c, 'n');
if (c->json[0] != 'u' || c->json[1] != 'l' || c->json[2] != 'l')
return LEPT_PARSE_INVALID_VALUE;
c->json += 3;
v->type = LEPT_NULL;
return LEPT_PARSE_OK;
}
/* value = null / false / true */
/* 提示:下面代码没处理 false / true,将会是练习之一 */
static int lept_parse_value(lept_context* c, lept_value* v) {
switch (*c->json) {
case 'n': return lept_parse_null(c, v);
case '\0': return LEPT_PARSE_EXPECT_VALUE;
default: return LEPT_PARSE_INVALID_VALUE;
}
}
由于 lept_parse_whitespace()
是不会出现错误的,返回类型为 void
。其它的解析函数会返回错误码,传递至顶层。
断言
断言(assertion)是 C 语言中常用的防御式编程方式,减少编程错误。最常用的是在函数开始的地方,检测所有参数。有时候也可以在调用函数后,检查上下文是否正确。
C 语言的标准库含有 assert()
这个宏(需 #include <assert.h>
),提供断言功能。当程序以 release 配置编译时(定义了 NDEBUG
宏),assert()
不会做检测;而当在 debug 配置时(没定义 NDEBUG
宏),则会在运行时检测 assert(cond)
中的条件是否为真(非 0),断言失败会直接令程序崩溃。
例如上面的 lept_parse_null()
开始时,当前字符应该是 'n'
,所以我们使用一个宏 EXPECT(c, ch)
进行断言,并跳到下一字符。
初使用断言的同学,可能会错误地把含副作用的代码放在 assert()
中:
assert(x++ == 0); /* 这是错误的! */
这样会导致 debug 和 release 版的行为不一样。
另一个问题是,初学者可能会难于分辨何时使用断言,何时处理运行时错误(如返回错误值或在 C++ 中抛出异常)。简单的答案是,如果那个错误是由于程序员错误编码所造成的(例如传入不合法的参数),那么应用断言;如果那个错误是程序员无法避免,而是由运行时的环境所造成的,就要处理运行时错误(例如开启文件失败)。
1. 修正 LEPT_PARSE_ROOT_NOT_SINGULAR
单元测试失败的是这一行:
EXPECT_EQ_INT(LEPT_PARSE_ROOT_NOT_SINGULAR, lept_parse(&v, "null x"));
我们从 JSON 语法发现,JSON 文本应该有 3 部分:
JSON-text = ws value ws
但原来的 lept_parse()
只处理了前两部分。我们只需要加入第三部分,解析空白,然后检查 JSON 文本是否完结:
int lept_parse(lept_value* v, const char* json) {
lept_context c;
int ret;
assert(v != NULL);
c.json = json;
v->type = LEPT_NULL;
lept_parse_whitespace(&c);
if ((ret = lept_parse_value(&c, v)) == LEPT_PARSE_OK) {
lept_parse_whitespace(&c);
if (*c.json != '\0')
ret = LEPT_PARSE_ROOT_NOT_SINGULAR;
}
return ret;
}
有一些 JSON 解析器完整解析一个值之后就会顺利返回,这是不符合标准的。但有时候也有另一种需求,文本中含多个 JSON 或其他文本串接在一起,希望当完整解析一个值之后就停下来。因此,有一些 JSON 解析器会提供这种选项,例如 RapidJSON 的 kParseStopWhenDoneFlag
。
2. true/false 单元测试
此问题很简单,只需参考 test_parse_null()
加入两个测试函数:
static void test_parse_true() {
lept_value v;
v.type = LEPT_FALSE;
EXPECT_EQ_INT(LEPT_PARSE_OK, lept_parse(&v, "true"));
EXPECT_EQ_INT(LEPT_TRUE, lept_get_type(&v));
}
static void test_parse_false() {
lept_value v;
v.type = LEPT_TRUE;
EXPECT_EQ_INT(LEPT_PARSE_OK, lept_parse(&v, "false"));
EXPECT_EQ_INT(LEPT_FALSE, lept_get_type(&v));
}
static void test_parse() {
test_parse_null();
test_parse_true();
test_parse_false();
test_parse_expect_value();
test_parse_invalid_value();
test_parse_root_not_singular();
}
但要记得在上一级的测试函数 test_parse()
调用这函数,否则会不起作用。还好如果我们记得用 static
修饰这两个函数,编译器会发出警告:
test.c:30:13: warning: unused function 'test_parse_true' [-Wunused-function]
static void test_parse_true() {
^
因为 static 函数的意思是指,该函数只作用于编译单元中,那么没有被调用时,编译器是能发现的。
3. true/false 解析
这部分很简单,只要参考 lept_parse_null()
,再写两个函数,然后在 lept_parse_value
按首字符分派。
static int lept_parse_true(lept_context* c, lept_value* v) {
EXPECT(c, 't');
if (c->json[0] != 'r' || c->json[1] != 'u' || c->json[2] != 'e')
return LEPT_PARSE_INVALID_VALUE;
c->json += 3;
v->type = LEPT_TRUE;
return LEPT_PARSE_OK;
}
static int lept_parse_false(lept_context* c, lept_value* v) {
EXPECT(c, 'f');
if (c->json[0] != 'a' || c->json[1] != 'l' || c->json[2] != 's' || c->json[3] != 'e')
return LEPT_PARSE_INVALID_VALUE;
c->json += 4;
v->type = LEPT_FALSE;
return LEPT_PARSE_OK;
}
static int lept_parse_value(lept_context* c, lept_value* v) {
switch (*c->json) {
case 't': return lept_parse_true(c, v);
case 'f': return lept_parse_false(c, v);
case 'n': return lept_parse_null(c, v);
case '\0': return LEPT_PARSE_EXPECT_VALUE;
default: return LEPT_PARSE_INVALID_VALUE;
}
}
其实这 3 种类型都是解析字面量,可以使用单一个函数实现,例如用这种方式调用:
case 'n': return lept_parse_literal(c, v, "null", LEPT_NULL);
这样可以减少一些重复代码,不过可能有少许额外性能开销。
为什么把例子命名为 leptjson?
来自于标准模型中的轻子(lepton),意为很轻量的 JSON 库。