定义

• 基本定义 (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）

数字过滤器

jaq 从 libm 导入了许多过滤器，并遵循它们的类型签名。

高级功能

jaq 目前并不旨在支持 jq 的几个功能，例如

• 模块
• SQL 风格的运算符
• 流式处理

jq 和 jaq 之间的差异

数字

jq 使用 64 位浮点数（floats）表示任何数字。相比之下，jaq 将数字 0 或 -42 解释为机器大小的整数，将数字 0.0 或 3e8 解释为 64 位浮点数。jaq 中的许多操作，如数组索引，都会检查传递的数字是否确实是整数。背后的动机是避免可能无声地导致错误结果的舍入误差。例如

$ 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 的规则是

• 两个整数的和、差、积和余数是整数。
• 两个数字之间的任何其他操作都产生浮点数。

示例

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

您可以通过添加0.0、乘以1.0或除以1将整数转换为浮点数，例如。您可以通过round、floor或ceil将浮点数转换为整数。

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

NaN和无穷大

在jq中，除以0有一些令人惊讶的特性；例如，0 / 0会产生nan，而0 as $n | $n / 0会产生一个错误。在jaq中，n / 0如果n == 0则产生nan，如果n > 0则产生infinite，如果n < 0则产生-infinite。jaq的行为更接近浮点数算术的IEEE标准（IEEE 754）。

jaq在浮点数上实现了一个全序，以便对值进行排序。因此，它不幸地必须强制执行nan == nan。 （jq通过强制执行nan < nan来解决这个问题，这违反了全序的基本定律。）

与jq一样，jaq将nan和infinite打印为null，因为JSON不支持将这些值作为数字进行编码。

分数数的保留

jaq完美地保留了来自JSON数据的分数数（只要它们不用于某些算术运算），而jq 1.6可能静默地转换为64位浮点数

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

因此，与jq 1.6不同，jaq满足jq手册中的以下段落

关于身份过滤器的一个重要观点是，它保证了保留值的字面十进制表示。当处理不能无损转换为IEEE754双精度表示的数字时，这一点尤为重要。

请注意，jq的新版本，例如1.7，似乎也保留了字面十进制表示。

赋值

与jq一样，jaq允许以下形式的赋值：p |= f。然而，jaq对这些赋值的解释不同。幸运的是，在大多数情况下，结果是一样的。

在jq中，赋值p |= f首先构造匹配p的所有值的路径。 然后，它将这些值应用于过滤器f。

在jaq中，赋值p |= f立即将f应用于任何匹配p的值。与jq不同，赋值不会显式构造路径。

jaq的赋值实现可能产生更高的性能，因为它不构造路径。此外，这也防止了jq中“设计”的几个错误。例如，给定过滤器[0, 1, 2, 3] | .[] |= empty，jq产生[1, 3]，而jaq产生[]。这里发生了什么？

jq首先构建与.[]对应的路径，它们是.0, .1, .2, .3。然后，它会移除这些路径中的每个元素。然而，这些移除都会改变剩余路径所引用的值。也就是说，在移除.0（值0）后，.1不再指向值1，而是值2！这也是为什么值1（以及随之而来的值3）没有被移除的原因。

在jq中还有更多奇怪的情况；例如，0 | 0 |= .+1在jq中产生1的结果，尽管0不是一个有效的路径表达式。然而，1 | 0 |= .+1会产生一个错误。在jaq中，任何这样的赋值都会产生错误。

jaq尝试使用右侧表达式的多个输出，而jq只使用第一个。例如，0 | (., .) |= (., .+1)在jaq中产生0 1 1 2的结果，而在jq中只产生0。然而，{a: 1} | .a |= (2, 3)在jaq和jq中都产生{"a": 2}的结果，因为一个对象只能将单个值与任何给定的键关联起来，所以我们不能在这里以有意义的方式使用多个输出。

由于jaq不构建路径，它不允许在赋值左侧使用某些过滤器，例如 first、last、limit 等：例如，[1, 2, 3] | first(.[]) |= .-1 在jq中会得到 [0, 2, 3]，但在jaq中是无效的。同样，[1, 2, 3] | limit(2; .[]) |= .-1 在jq中会得到 [0, 1, 3]，但在jaq中是无效的。（顺便一提，jq也不允许使用 last。）

定义

与jq类似，jaq允许定义过滤器，例如

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

参数也可以通过值传递，例如

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

过滤器定义可以是嵌套和递归的，即引用自身。也就是说，可以在jaq中定义一个如 recurse 的过滤器

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

从jaq 1.2开始，jaq像jq一样优化尾调用。从jaq 1.1开始，递归过滤器也可以有非变量参数，就像在jq中一样。例如

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

具有非变量参数的递归过滤器会产生令人惊讶的效果；例如，一个调用 f(0) 会构建形如 f(1+(..(1+0)...)) 的调用，这会导致指数级执行时间。

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