JSON5 - 更人性化的 JSON

13,941 阅读3分钟
原文链接: blog.hopsken.com

json5-logo

JSON5 是 JSON 的一个超集,通过引入部分 ECMAScript 5.1 的特性来扩展 JSON 的语法,以减少 JSON 格式的某些限制。同时,保持兼容现有的 JSON 格式。

JSON5 更像是 JavaScript 中的对象,但是它并不是 JSON 官方的扩展,所以需要 json5 作为文件扩展名。

与 JSON 的区别

对象 Objects

  • 对象的键名可以是任何 ES5.1 的标识符。
  • 对象可以以一个逗号结尾。

数组 Arrays

  • 数组可以以一个逗号结尾。

字符串 Strings

  • 字符串可以使用单引号表示。
  • 字符串可以占据多行文本,以 '' 换行。
  • 字符串可以包括转义字符。

数字 Numbers

  • 可以使用十六进制数字。
  • 数字可以以小数点开头/结尾。
  • 数字可以取 Infinity / -Infinity / NaN。参见 IEEE754
  • 数字可以以一个明确的加号"+"开头。

注释 Comments

  • 允许单行/多行注释

空白符 White Space

  • 允许多余的空白符

举个栗子🌰

{
  // comments
  unquoted: 'and you can quote me on that',
  singleQuotes: 'I can use "double quotes" here',
  lineBreaks: "Look, Mom! \
No \\n's!",
  hexadecimal: 0xdecaf,
  leadingDecimalPoint: .8675309, andTrailing: 8675309.,
  positiveSign: +1,
  trailingComma: 'in objects', andIn: ['arrays',],
  "backwardsCompatible": "with JSON",
}

安装

Node.js

npm install json5
const JSON5 = require('json5')

浏览器环境

<script src="https://unpkg.com/json5@^1.0.0"></script>

这会生成一个全局的 JSON5 变量。

API

JSON5 的 API 是与 JSON 的兼容的。

JSON5.parse()

解析一个 JSON5 字符串,通过字符串构建一个 JavaScript 值或者对象。如果指定了 reviver 函数,则解析出的 JavaScript 值(解析值)会经过一次转换后才将被最终返回(返回值)。

语法

JSON5.parse(text[, reviver])

参数

text: 要解析的字符串。

reviver: 如果指定为一个函数,则解析出的 JavaScript 值(解析值)会经过一次转换后才将被最终返回(返回值)。

返回值

对应 JavaScript 值或者对象。

JSON5.stringify()

将一个 JavaScript 值转为 JSON5 字符串,提供可选的替换函数,也可指定要导出部分属性。

语法

JSON5.stringify(value[, replacer[, space]])
JSON5.stringify(value[, options])

参数

value: 待转换的 JavaScript 值

replacer: 若为函数,则会替换默认的转换函数。若为一个字符串/数字组成的数组,则结果中只会包含数组指定的属性。若为 null 或者未提供,则结果中会包含所有的属性。

space: 可以是一个字符串或者数字,长度最高不超过 10。若为数字,则表示用多少个空格来表示空白符。若为字符串,则会用该字符串替换空白符。

options: 一个包含以下属性的对象:

  • replacer: 与 replacer 参数一致。
  • space: 与 space 参数一致。
  • quote: 指示序列号字符串时所使用的引用字符。

返回值

JSON5 字符串。

Node.js require() JSON5 files

Node.js 中,可以通过添加以下语句来支持导入 json5 文件。

require('json5/lib/register')

然后在通过 Node.js 的 require 语句导入 json5 文件。

const config = require('./config.json5')

命令行 CLI

JSON5 提供了一个命令行工具来将 JSON5 文件转换为 JSON 格式,以及验证 JSON5 文件的语法。

安装

npm install --global json5

使用

json5 [options] <file>

如果没有提供 file 参数,则会使用标准输入(STDIN)。

选项:
-s, --space: 缩进使用的空格数。t表示使用 tab 缩进。
-o, --out-file [file]: 指定输出文件。若为空,则使用标准输出(STDOUT)。
-v, --validate: 检验 JSON5 语法。
-V, --version: 版本号。
-h, --help: 帮助信息。