jaq

jaq（发音类似于 Jacques[^jacques]）是 JSON 数据处理工具 jq 的克隆。jaq 旨在支持 jq 的大多数语法和操作子集。

您可以在 jaq 演示场 上尝试 jaq。演示场的说明可以在这里找到 这里。

jaq 关注三个目标

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

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

  • nan > nan 是假的，而 nan < nan 是真的。
  • [[]] | 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的长时间启动时间感到困扰，在我的机器上大约需要50毫秒。这在处理大量小文件时尤其明显。jaq的启动速度比jq 1.6快约30倍，并且在许多其他基准测试中也优于jq。

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

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

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

安装

二进制文件

您可以在发布页面上下载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 的性能。空（empty）基准测试在空输入上运行 empty 过滤器 n 次，用于测量启动时间。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 .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]