从零开始的 JSON 库教程（七）：生成器

  • Milo Yip
  • 2016/12/20

本文是《从零开始的 JSON 库教程》的第七个单元。代码位于 json-tutorial/tutorial07。

1. JSON 生成器

我们在前 6 个单元实现了一个合乎标准的 JSON 解析器，它把 JSON 文本解析成一个树形数据结构，整个结构以 lept_value 的节点组成。

JSON 生成器（generator）负责相反的事情，就是把树形数据结构转换成 JSON 文本。这个过程又称为「字符串化（stringify）」。

JSON 的解析与生成

相对于解析器，通常生成器更容易实现，而且生成器几乎不会造成运行时错误。因此，生成器的 API 设计为以下形式，直接返回 JSON 的字符串：

  1. char* lept_stringify(const lept_value* v, size_t* length);

length 参数是可选的，它会存储 JSON 的长度，传入 NULL 可忽略此参数。使用方需负责用 free() 释放内存。

为了简单起见，我们不做换行、缩进等美化（prettify）处理，因此它生成的 JSON 会是单行、无空白字符的最紧凑形式。

2. 再利用 lept_context 做动态数组

在实现 JSON 解析时，我们加入了一个动态变长的堆栈，用于存储临时的解析结果。而现在，我们也需要存储生成的结果，所以最简单是再利用该数据结构，作为输出缓冲区。

  1. #ifndef LEPT_PARSE_STRINGIFY_INIT_SIZE
  2. #define LEPT_PARSE_STRINGIFY_INIT_SIZE 256
  3. #endif
  5. int lept_stringify(const lept_value* v, char** json, size_t* length) {
  6.     lept_context c;
  7.     int ret;
  8.     assert(v != NULL);
  9.     assert(json != NULL);
  10.     c.stack = (char*)malloc(c.size = LEPT_PARSE_STRINGIFY_INIT_SIZE);
  11.     c.top = 0;
  12.     if ((ret = lept_stringify_value(&c, v)) != LEPT_STRINGIFY_OK) {
  13.         free(c.stack);
  14.         *json = NULL;
  15.         return ret;
  16.     }
  17.     if (length)
  18.         *length = c.top;
  19.     PUTC(&c, '\0');
  20.     *json = c.stack;
  21.     return LEPT_STRINGIFY_OK;
  22. }

生成根节点的值之后，我需还需要加入一个空字符作结尾。

如前所述，此 API 还提供了 length 可选参数，当传入非空指针时，就能获得生成 JSON 的长度。或许读者会疑问，为什么需要获得长度，我们不是可以用 strlen() 获得么？是的，因为 JSON 不会含有空字符（若 JSON 字符串中含空字符，必须转义为 \u0000），用 strlen() 是没有问题的。但这样做会带来不必要的性能消耗，理想地是避免调用方有额外消耗。

3. 生成 null、false 和 true

接下来，我们生成最简单的 JSON 类型，就是 3 种 JSON 字面值。为贯彻 TDD，先写测试：

  1. #define TEST_ROUNDTRIP(json)\
  2.     do {\
  3.         lept_value v;\
  4.         char* json2;\
  5.         size_t length;\
  6.         lept_init(&v);\
  7.         EXPECT_EQ_INT(LEPT_PARSE_OK, lept_parse(&v, json));\
  8.         EXPECT_EQ_INT(LEPT_STRINGIFY_OK, lept_stringify(&v, &json2, &length));\
  9.         EXPECT_EQ_STRING(json, json2, length);\
  10.         lept_free(&v);\
  11.         free(json2);\
  12.     } while(0)
  14. static void test_stringify() {
  15.     TEST_ROUNDTRIP("null");
  16.     TEST_ROUNDTRIP("false");
  17.     TEST_ROUNDTRIP("true");
  18.     /* ... */
  19. }

这里我们采用一个最简单的测试方式，把一个 JSON 解析，然后再生成另一 JSON，逐字符比较两个 JSON 是否一模一样。这种测试可称为往返（roundtrip）测试。但需要注意，同一个 JSON 的内容可以有多种不同的表示方式，例如可以插入不定数量的空白字符，数字 1.0 和 1 也是等价的。所以另一种测试方式，是比较两次解析的结果（lept_value 的树）是否相同，此功能将会在下一单元讲解。

然后，我们实现 lept_stringify_value，加入一个 PUTS() 宏去输出字符串：

  1. #define PUTS(c, s, len)     memcpy(lept_context_push(c, len), s, len)
  3. static int lept_stringify_value(lept_context* c, const lept_value* v) {
  4.     size_t i;
  5.     int ret;
  6.     switch (v->type) {
  7.         case LEPT_NULL:   PUTS(c, "null",  4); break;
  8.         case LEPT_FALSE:  PUTS(c, "false", 5); break;
  9.         case LEPT_TRUE:   PUTS(c, "true",  4); break;
  10.         /* ... */
  11.     }
  12.     return LEPT_STRINGIFY_OK;
  13. }

4. 生成数字

为了简单起见，我们使用 sprintf("%.17g", ...) 来把浮点数转换成文本。"%.17g" 是足够把双精度浮点转换成可还原的文本。

最简单的实现方式可能是这样的：

  1.         case LEPT_NUMBER:
  2.             {
  3.                 char buffer[32];
  4.                 int length = sprintf(buffer, "%.17g", v->u.n);
  5.                 PUTS(c, buffer, length);
  6.             }
  7.             break;

但这样需要在 PUTS() 中做一次 memcpy()，实际上我们可以避免这次复制，只需要生成的时候直接写进 c 里的推栈，然后再按实际长度调查 c->top：

  1.         case LEPT_NUMBER:
  2.             {
  3.                 char* buffer = lept_context_push(c, 32);
  4.                 int length = sprintf(buffer, "%.17g", v->u.n);
  5.                 c->top -= 32 - length;
  6.             }
  7.             break;

因每个临时变量只用了一次，我们可以把代码压缩成一行：

  1.         case LEPT_NUMBER:
  2.             c->top -= 32 - sprintf(lept_context_push(c, 32), "%.17g", v->u.n);
  3.             break;

5. 总结与练习

我们在此单元中简介了 JSON 的生成功能和 leptjson 中的实现方式。

leptjson 重复利用了 lept_context 中的数据结构作为输出缓冲，可以节省代码量。

生成通常比解析简单（一个例外是 RapidJSON 自行实现了浮点数至字符串的算法），余下的 3 种 JSON 类型就当作练习吧：

  1. 由于有两个地方需要生成字符串（JSON 字符串和对象类型），所以先实现 lept_stringify_string()。注意，字符串的语法比较复杂，一些字符必须转义，其他少于 0x20 的字符需要转义为 \u00xx 形式。

  2. 直接在 lept_stringify_value() 的 switch 内实现 JSON 数组和对象类型的生成。这些实现里都会递归调用 lept_stringify_value() 。

  3. 在你的 lept_stringify_string() 是否使用了多次 PUTC()？如果是，它每次输出一个字符时，都要检测缓冲区是否有足够空间（不够时需扩展）。能否优化这部分的性能？这种优化有什么代价么？

如果你遇到问题，有不理解的地方，或是有建议，都欢迎在评论或 issue 中提出，让所有人一起讨论。