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 的长时间启动时间所困扰，在我的机器上约为 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目前能做什么的印象。您应该用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次带有null输入的过滤器，以测量启动时间。bf-fib基准测试运行一个用jq编写的Brainfuck解释器，解释产生n个斐波那契数的Brainfuck脚本。其他基准测试使用n作为输入评估各种过滤器；有关详细信息，请参阅bench.sh。

我在Linux系统上使用AMD Ryzen 5 5500U，使用bench.sh target/release/jaq jq-1.7.1 gojq-0.12.15 jq-1.6 | tee bench.json生成了基准测试数据。[^binaries]。然后，我使用一个“单行命令”（稍微拉伸了这个术语和行）处理了结果

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）

标准过滤器

这些过滤器是通过更基本的过滤器定义的。它们的定义在std.jq。

• 未定义（null）
• 布尔值（true、false、not）
• 特殊数值（nan、infinite、isnan、isinfinite、isfinite、isnormal）
• 类型（type）
• 过滤（select(. >= 0)）
• 选择（values、nulls、booleans、numbers、strings、arrays、objects、iterables、scalars）
• 转换（tostring、tonumber）
• 可迭代过滤器（map(.+1)、map_values(.+1)、add、join("a")）
• 数组过滤器（transpose、first、last、nth(10)、flatten、min、max）
• 对象-数组转换（to_entries、from_entries、with_entries）
• 全/存在性（all、any）
• 递归（walk）
• I/O（input）
• 正则表达式（test、scan、match、capture、splits、sub、gsub）
• 时间（fromdate、todate）

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