jaq

jaq（发音类似于 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的语法和语义。这应该使用户能够轻松地使用jaq。

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

安装

二进制文件

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

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

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

或在Windows上使用scoop安装jaq

$ 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）运行n次带有null输入的过滤器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）

路径

• 数组/对象的索引（.[0]，.a，.["a"]）
• 遍历数组/对象（.[]）
• 可选索引/迭代（.a?，.[]?）
• 数组切片（.[3:7]，.[0:-1]）
• 字符串切片

运算符

• 组合（|）
• 绑定（. as $x | $x）
• 连接（,）
• 普通赋值（=）
• 更新赋值（|=，+=，-=）
• 交替（//）
• 逻辑运算（or，and）
• 等式与比较（.a == .b，.a < .b）
• 算术（+，-，*，/，%）
• 取反（-）
• 错误抑制（?）

定义

• 基本定义（def map(f): [.[] | f];）
• 递归定义（def r: r; r）

核心过滤器

• 空（empty）
• 错误（error）
• 输入（inputs）
• 长度（length，utf8bytelength）
• 四舍五入（floor，round，ceil）
• 字符串与JSON之间的转换（fromjson，tojson）
• 字符串与整数之间的转换（explode，implode）
• 字符串规范化（ascii_downcase，ascii_upcase）
• 字符串前缀/后缀（startswith，endswith，ltrimstr，rtrimstr）
• 字符串分割（split("foo")）
• 数组过滤器（reverse，sort，sort_by(-.)，group_by，min_by，max_by）
• 流消费者（first，last，range，fold）
• 流生成器（range，recurse）
• 时间（now，fromdateiso8601，todateiso8601）
• 更多数值过滤器（sqrt，sin，log，pow，...）（数值过滤器列表）
• 更多时间过滤器（strptime，strftime，strflocaltime，mktime，gmtime，和 localtime）

$ 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]