jaq

jaq（发音类似于 Jacques[^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 的二进制文件。

您还可以使用 homebrew 在 macOS 或 Linux 上安装 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当前可以做什么的印象。您应该通过用jq替换jaq来获得相同的输出。如果不是，您提交问题将受到赞赏。 :) 语法在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的性能。空基准empty运行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]：jq-1.7.1和gojq-0.12.15的二进制文件是从它们的GitHub发布页面检索的，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-then-else (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]