jaq

jaq（发音类似于 Jacques）是JSON数据处理工具jq的克隆版。jaq旨在支持jq的大部分语法和操作。

您可以在jaq游乐场上在线尝试jaq。游乐场的说明可以在这里找到。

jaq关注三个目标

• 正确性：jaq旨在提供比jq更正确和可预测的实现，同时在大多数情况下保持与jq的兼容性。

  一些令人惊讶的jq行为示例

  • nan > nan是false，而nan < nan是true。
  • [[]] | implode会导致jq崩溃，尽管这个问题已经存在五年了，但当时并未修复。
  • 《jq 手册》中声称，limit(n; exp) "从 exp 中提取最多 n 个输出"。这在 n > 1 的情况下成立，例如 jq -n '[limit(2; 1, 2, 3)]' 的结果是 [1, 2]，但当 n == 0 时，jq -n '[limit(0; 1, 2, 3)]' 的结果是 [1]，而不是 []。更糟糕的是，当 n < 0 时，limit 会产生 exp 的所有输出，但这在文档中并未提及。

• 性能：我最初创建 jaq 是因为我对 jq 的 长时间启动时间 感到烦恼，在我的机器上大约为 50ms。这在大文件处理中尤为明显。jaq 的启动速度比 jq 1.6 快约 30 倍，并在许多其他基准测试中也优于 jq。

• 简单性：jaq 旨在实现简单且体积小，以减少潜在的错误并便于贡献。

我从另一个 Rust 程序中获得了灵感，即 jql。然而，与 jql 不同，jaq 旨在尽可能模仿 jq 的语法和语义。这应该使用户能够轻松使用 jaq。

[^jacques]：我希望创建一个像好服务员一样低调而乐于助人的工具。当我想到一个典型的（法国）服务员的名字时，我的脑海中浮现出“Jacques”。后来，我了解到古老的法语单词 jacquet，意为“松鼠”，这为这个名字提供了一个很好的 ex post 启发。

安装

二进制文件

您可以在 发布页面 下载 Linux、Mac 和 Windows 的二进制文件。

您也可以在 macOS 或 Linux 上使用 homebrew 安装 jaq

$ brew install jaq
$ brew install --HEAD jaq # latest development version

或在 Windows 上使用 scoop

$ scoop install main/jaq

从源代码

要编译 jaq，您需要一个 Rust 工具链。有关说明，请参阅 https://rustup.rs/。（请注意，Linux 发行版中提供的 Rust 编译器可能过于陈旧，无法编译 jaq。）

以下任何命令都可以安装 jaq

$ cargo install --locked jaq
$ cargo install --locked --git https://github.com/01mf02/jaq # latest development version

在我的系统上，这两个命令都将可执行文件放置在 ~/.cargo/bin/jaq。

如果您已克隆此存储库，您还可以通过在克隆的存储库中执行其中一个命令来构建 jaq

$ cargo build --release # places binary into target/release/jaq
$ cargo install --locked --path jaq # installs binary

jaq 应该能在所有由 Rust 支持的系统中工作。如果不行，请提交一个问题。

示例

以下示例应给人留下 jaq 当前能做什么的印象。你应该通过将 jaq 替换为 jq 来获得相同的输出。如果不一致，提交问题会很有帮助。 :) 语法在 jq 手册 中有记录。

访问字段

$ echo '{"a": 1, "b": 2}' | jaq '.a'
1

添加值

$ echo '{"a": 1, "b": 2}' | jaq 'add'
3

以两种方式从一个对象构造一个数组并显示它们是相等的

$ echo '{"a": 1, "b": 2}' | jaq '[.a, .b] == [.[]]'
true

对数组的所有元素应用一个过滤器并过滤结果

$ echo '[0, 1, 2, 3]' | jaq 'map(.*2) | [.[] | select(. < 5)]'
[0, 2, 4]

将输入值读入数组并计算其元素的平均值

$ echo '1 2 3 4' | jaq -s 'add / length'
2.5

反复对一个过滤器本身应用过滤器并输出中间结果

$ echo '0' | jaq '[recurse(.+1; . < 3)]'
[0, 1, 2]

懒惰地折叠输入并输出中间结果

$ seq 1000 | jaq -n 'foreach inputs as $x (0; . + $x)'
1 3 6 10 15 [...]

性能

以下评估包括几个基准测试，可以比较 jaq、jq 和 gojq 的性能。空基准测试运行 n 次的空过滤器 empty 与空输入，用于测量启动时间。bf-fib 基准测试运行一个用 jq 编写的 Brainfuck 解释器，解释产生 n 个斐波那契数的 Brainfuck 脚本。其他基准测试使用 n 作为输入评估各种过滤器；有关详细信息，请参阅 bench.sh。

我在一个装有 AMD Ryzen 5 5500U 的 Linux 系统上使用 bench.sh target/release/jaq jq-1.7 gojq-0.1213 jq-1.6 | tee bench.json 生成基准测试数据。然后，我使用一个 "单行命令"（稍微扩展了这个术语和行）处理结果

jq -rs '.[] | "|`\(.name)`|\(.n)|" + ([.time[] | min | (.*1000|round)? // "N/A"] | min as $total_min | map(if . == $total_min then "**\(.)**" else "\(.)" end) | join("|"))' bench.json

（当然，你也可以在这里用 jaq 代替 jq。）最后，我将表头与输出连接起来，并通过 pandoc -t gfm 传递。

[^binaries]：从它们的 GitHub 发布页面获取了 jq-1.7.1 和 gojq-0.12.15 的二进制文件，jq-1.6 的二进制文件是从标准的 Ubuntu 仓库安装的。

表：以毫秒为单位的评估结果（如果超过 10 秒，则为 "N/A"）。

结果表明，jaq-1.4 在 15 个基准测试中速度最快，而 jq-1.7.1 在 2 个基准测试中速度最快，gojq-0.12.15 也在 2 个基准测试中速度最快。gojq 在 tree-flatten 上速度很快，因为它以原生化方式实现过滤器 flatten 而不是通过定义。

特性

以下是一个概述，总结了

• 已实现的功能，
• 尚未实现的功能。

欢迎为扩展 jaq 做出贡献。

基础

• 恒等（.）
• 递归（..）
• 基本数据类型（null，布尔值，数字，字符串，数组，对象）
• 条件分支（if .a < .b then .a else .b end）
• 折叠（reduce .[] as $x (0; . + $x)，foreach .[] as $x (0; . + $x; . + .)）
• 错误处理（try ... catch ...）（参见与jq的差异）
• 字符串插值（"The successor of \(.) is \(.+1)."）
• 格式化字符串（@json，@text，@csv，@tsv，@html，@sh，@base64，@base64d）

$ jq  -n '[0, 1, 2] | .[1.0000000000000001]'
1
$ jaq -n '[0, 1, 2] | .[1.0000000000000001]'
Error: cannot use 1.0 as integer
$ jaq -n '[0, 1, 2] | .[1]'
1

$ jaq -n '1 + 2'
3
$ jaq -n '10 / 2'
5.0
$ jaq -n '1.0 + 2'
3.0

$ jaq -n '1.2 | [floor, round, ceil]'
[1, 1, 2]

$ echo '1e500' | jq '.'
1.7976931348623157e+308
$ echo '1e500' | jaq '.'
1e500

def map(f): [.[] | f];

def cartesian($f; $g): [$f, $g];

def recurse(f): def r: ., (f | r); r;

def f(a): a, f(1+a);

$ jaq -n --arg x 1 --arg y 2 '$x, $y, $ARGS.named'
"1"
"2"
{
  "x": "1",
  "y": "2"
}

init
| x0 as $x | f
| ...
| xn as $x | f

init
| x0 as $x | f | (.,
| ...
| xn as $x | f | (.,
empty)...)

init
| ., (x0 as $x | f
| ...
| ., (xn as $x | f
)...)

[try (1, error(2), 3, error(4)) catch .] == [1, 2]

[try (1, error(2), 3, error(4)) catch .] == [1, 2, 3, 4]