jq語言

jq
	jq官方圖標
編程範型	純函數式, 面向JSON處理, 隱式
設計者	Stephen Dolan
釋出時間	2012年8月21日，12年前
當前版本	1.7.1（2023年12月13日；穩定版本）;
實作語言	jq：C; gojq：Go; jaq：Rust; jqjq：jq
系統平台	跨平台
作業系統	跨平台
許可證	MIT
網站	jqlang.github.io/jq
啟發語言
	Haskell, Icon, JSON, Unix shell, sed

jq是高級領域特定的詞法作用域的純函數式編程語言，在其中所有JSON值都是常量。jq支持回溯並可管理JSON數據的無限長字串流。jq支持基於名字空間的模塊系統，並對閉包有一定支持，尤其是它的函數和泛函表達式可以用作其他函數的參數。

jq與Icon和Haskell程式語言有關。它最初採用Haskell實現^[3]，隨即移植至C語言。gojq是jq的「純Go」實現。jq還有用Rust實現的叫做jaq的方言^[4]，它規定了指稱語義^[5]。

歷史

jq由Stephen Dolan創建並在2012年10月發行^[6]^[7] 。它被設計為「針對JSON數據的sed類似者」^[8]。在jq版本1.5中增加支持了正則表達式。

針對jq的叫做yq的「包裝器」^[9]，增加支持了YAML、XML和TOML。它首次發行於2017年^[10]。

用Go實現的gojq最初發行於2019年^[11]，gojq顯著的擴展jq包括了支持YAML。

用Rust實現的jaq，其項目目標是更快速和更準確的jq實現，仍保持與jq在大多數情況下的兼容性。在2024年3月於其目標中排除了jq的特定高級特徵，比如模塊、SQL風格算子和給非常大JSON文檔的串流解析器^[4]。

用jq實現的jqjq，最初發行於2022年。jqjq顯著的可以運行自身，擁有REPL並支持eval。

用法

命令行用法

jq典型的用於命令行，並可以協作於其他命令行實用工具，比如curl。下面的例子展示如何將curl命令的輸出通過管道接轉到jq過濾器（英語：Filter (software)），從而確定同這個Wikipedia頁面關聯的範疇名字：

$ URL='https://zh.wikipedia.org/w/api.php?action=parse&page=Jq%E8%AF%AD%E8%A8%80&format=json'
$ curl -s ${URL} | jq '.parse.categories[]."*"'

這裏的流水線產生的輸出，由JSON字符串的串流組成，它們是：

"小寫標題"
"CS1英语来源_(en)"
"动态类型编程语言"
"函数式编程语言"
"面向文本编程语言"
"2012年建立的程式語言"
"数据查询语言"
"2012年软件"

上述curl命令對這個頁面使用了MediaWiki API來產生JSON響應。管道（pipe）符號|允許curl的輸出由jq來訪問，它是標準的Unix shell的進程間通信機制^[12]。

這裏展示的jq過濾器的方法鏈是如下流水線（pipeline）的簡寫：

.["parse"] | .["categories"] | .[] | .["*"]

這對應於curl調用所產生的嵌套JSON結構。jq流水線的構造方式，同Unix風格流水線一樣，採用管道符號|。

嵌入式用法

C語言和Go實現二者都提供函數庫，使得jq功能可以嵌入到其他應用和編程環境之中。

例如，gojq已經集成於SQLite，故而jq函數可以在其SQL語句中獲得到^[13]。這些函數被標記為「確定性的」^[14]，故而可以被用在CREATE INDEX命令中^[15]。

運算的模態

jq缺省的充當針對JSON輸入的「串流編輯器」，非常像被當作多行文本的「串流編輯器」的sed實用工具。但是jq有一些其他運算模態：

它可以將來自一個或多個來源的輸入當作文本的諸行；
它可以將來自特定來源的輸入的串流收集到一個JSON陣列之中；
它可以使用所謂的「串流解析器」解析其輸入，產生針對所有「葉子」路徑的[path, value]陣列的串流。

「串流解析器」（streaming parser），在一個或多個JSON輸入太大無法載入內存之時特別有用，因為它需求的內存典型的相當小。例如，對於任意大的JSON對象的陣列，峰值內存需求不比處理最大頂層對象所需要的多出很多。

這些運算模態可以在特定限制下組合起來。

語法和語義

類型

所有JSON值自身是jq中的值，它們從而有在下列表格中展示的類型^[16]。gojq和jaq實現將數區分為整數和浮點數。gojq實現支持無界精度整數算術，同於jq採用Haskell的最初實現。

jq支持的類型總結
類型	例子
"number"	`3` `3.2` `1e6` `nan` `infinite`
"string"	`"Hello"` `"😐"`
"boolean"	`true` `false`
"array"	`[1, "2", {"mixed": "type"}, [3,4]]`
"object"	`{"one": 1, "two": "2", "three": [3]}`
"null"	`null`

null是一個值^[17]，就像任何其他JSON純量一樣；它不是指針或空指針。nan（對應於NaN）和infinite（參見IEEE 754），是僅有的兩個不是JSON值的jq純量。

形式

jq有特殊語法形式，比如：

EXP as $var | ……：變量綁定；
def ……: ……;：函數創建；
if …… then …… elif …… then …… else …… end：條件；
reduce EXP as $var (INIT; UPDATE)：串流歸約；
include ……;和import …… as $NAME;：模塊導入。

過濾器

jq是面向JSON的程式語言，使用|符號來連接過濾器形成流水線。例如：

$ echo '[1,2]' | jq 'add'
3
$ jq -n '[1,2] | add'
3

這裏jq內的JSON陣列[1,2]是求值為陣列的一個jq過濾器。

儘管類似於Unix流水線，jq流水線允許將到來數據，如同並行的發送到在|右手端的多於一個接收者。例如，程序add/length將計算陣列中數的平均，故而：

$ jq -n '[1,2] | add/length'
1.5
$ jq -nc '[1,2] | [length, add, add/length]'
[2,3,1.5]

單獨的點號.可以充任佔位符（placeholder）或通配符，例如：

$ jq -nc '1 | [., .]'
[1,1]
$ jq -n '2 | pow(.; .)'
4

在jq中可以用隱式編程風格將斐波那契數列定義為[0,1] | recurse([last, add]) | first，下面是其使用例子：

$ echo '0 1 2 6' | jq -c '[limit(.+1; [0,1] | recurse([last, add]) | first)]'
[0]
[0,1]
[0,1,1]
[0,1,1,2,3,5,8]
$ echo '0 1 2 6' | jq -c '[limit(.; [0,1] | recurse([last, add]) | last)]'
[]
[1]
[1,1]
[1,1,2,3,5,8]
$ jq -n 'first([0,1] | recurse([last, add]) | first)'
0
$ jq -n '[0,1,2,6][] | nth(.; [0,1] | recurse([last, add]) | first)'
0
1
1
8
$ jq -nc '[0,1,2,6] | map(nth(.; [0,1] | recurse([last, add]) | first))'
[0,1,1,8]

這種無限列表不可以不加限定的使用，也不可以對其進行取最後一個元素的運算last()。下面將其定義為新的命名過濾器：

def fib: nth(.; [0,1] | recurse([last, add]) | first);

下面的例子展示如何定義參數化的命名過濾器，它格式化從2到36含二者的任何底數的整數：

def tobase($b):
    def digit: "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"[.:.+1];
    def mod: . % $b;
    def div: ((. - mod) / $b);
    def place_values: recurse(select(. >= $b) | div) | mod;
    select(2 <= $b and $b <= 36)
    | [place_values | digit] | reverse | add;

將其保存入tobase.jq文件，接着使用這個函數：

$ echo '15 16' | jq 'include "./tobase"; tobase(16)'
"F"
"10"

下一個例子求解經典的覆面算數學遊戲：

{\begin{matrix}&&{\text{S}}&{\text{E}}&{\text{N}}&{\text{D}}\\+&&{\text{M}}&{\text{O}}&{\text{R}}&{\text{E}}\\\hline =&{\text{M}}&{\text{O}}&{\text{N}}&{\text{E}}&{\text{Y}}\\\end{matrix}}

從M是在最高位的進位可知：M為1，S為8或9，O為0，代碼展示了基於range()和.[]的生成器：

def send_more_money:
    def choose(m; n; $k; used):
        ([range(m; n+1)] - [used[]])[]
        | used + {$k: .};
    def num(a; b; c; d): 1000*a + 100*b + 10*c + d;
    def num(a; b; c; d; e): 10*num(a; b; c; d) + e;
    choose(8; 9; "s"; {"m":1,"o":0}) as $t0
    | choose(2; 9; "e"; $t0) as $t1
    | choose(2; 9; "n"; $t1) as $t2
    | choose(2; 9; "d"; $t2) as $t3
    | choose(2; 9; "r"; $t3) as $t4
    | choose(2; 9; "y"; $t4) 
    | select(  num(.s; .e; .n; .d) 
        +      num(.m; .o; .r; .e)
        == num(.m; .o; .n; .e; .y))
    | [.s,.e,.n,.d,"+",.m,.o,.r,.e,"=",.m,.o,.n,.e,.y];
send_more_money

將上述代碼保存入send_more_money.jq文件，接着使用這個函數得到這個謎題僅有的一個解：

$ jq -nc -f ./send_more_money.jq
[9,5,6,7,"+",1,0,8,5,"=",1,0,6,5,2]

解析表達式文法

在jq和解析表達式文法（PEG）形式化之間有密切關聯^[18]。這種關聯源於下列表格中展示的PEG七個基本運算與jq構造之間的等價性。

PEG運算與對應的jq等價者
PEG運算名字	PEG表示法	jq運算或def
序列	`e1 e2`	`e1 \| e2`
有序選擇	`e1 / e2`	`e1 // e2`
零或多個	`e*`	`def star(E): (E \| star(E)) // .;`
一或多個	`e+`	`def plus(E): E \| (plus(E) // .);`
可選	`e?`	`def optional(E): E // .;`
與斷言	`&e`	`def amp(E): . as $in \| E \| $in;`
非斷言	`!e`	`def neg(E): select([E] == []);`

八皇后問題例子

採用回溯法求解八皇后問題的例子代碼：

def queens:
    def place(r; $c; pl):
        all(pl[0][]; . != $c)
        and all(pl[1][]; . != r+$c)
        and all(pl[2][]; . != r-$c);
    def q(r; pl):
        [range(0; 8)][] 
        | select(place(r; .; pl))
        | [pl[0]+[.], pl[1]+[r+.], pl[2]+[r-.]]; 
    q(0; [[],[],[]]) as $t0
    | q(1; $t0) as $t1
    | q(2; $t1) as $t2
    | q(3; $t2) as $t3
    | q(4; $t3) as $t4
    | q(5; $t4) as $t5
    | q(6; $t5) as $t6
    | q(7; $t6)[0]
    | map("abcdefgh"[.:.+1]) as $s
    | [$s[0]+"1", $s[1]+"2", $s[2]+"3", $s[3]+"4",
       $s[4]+"5", $s[5]+"6", $s[6]+"7", $s[7]+"8"]
    | sort;
queens

	a	b	c	d	e	f	g	h
8									8
7									7
6									6
5									5
4									4
3									3
2									2
1									1
	a	b	c	d	e	f	g	h

解1

	a	b	c	d	e	f	g	h
8									8
7									7
6									6
5									5
4									4
3									3
2									2
1									1
	a	b	c	d	e	f	g	h

解2

將這段代碼保存入queens.jq文件中，下面演示其執行結果並提取其92個解中的前兩個解：

$ jq -nc -f ./queens.jq | wc -l
92
$ jq -nc -f ./queens.jq | sed -n '1,2p'
["a1","b7","c5","d8","e2","f4","g6","h3"]
["a1","b7","c4","d6","e8","f2","g5","h3"]

這個存儲傳遞風格實現的3種位置列表，共有3*9 = 27個列表和3*9*(0+8)/2 = 108個元素，而在能採用可逆（reversible）賦值和靜態變量的語言比如Icon的實現中，其3個位置列表共有8+15+15 = 38個元素。

註釋

^ jq的C或Go實現都沒有任何運行時間依賴^[2]。
^ 包括Windows、Linux和macOS。Go實現可以在Go所支持的任何平台上編譯^[2]。
^ jq的C實現，使用了叫做decNumber的十進制浮點數庫，它採用了ICU許可證；和Oniguruma正則表達式庫，它採用了BSD許可證^[2]。

參考書目

Janssens, Jeroen. Data Science at the Command Line. O'Reilly Media. 2021. ISBN 9781492087885 （英語）.
Janssens, Jeroen. Data Science at the Command Line: Facing the Future with Time-Tested Tools. O'Reilly Media. 2014. ISBN 9781491947807 （英語）.
Marrs, Tom. JSON at Work: Practical Data Integration for the Web. O'Reilly Media. 2017. ISBN 9781491982419 （英語）.

引用

^ Release jq 1.7.1.
^ ^2.0 ^2.1 ^2.2 Download jq. jq. [January 6, 2023].
^ Initial · jqlang/Jq@eca89ac. GitHub.
^ ^4.0 ^4.1 01mf02/jaq: A jq clone focussed on correctness, speed, and simplicity. GitHub. [March 6, 2024].
^ Färber, Michael. Denotational Semantics and a fast interpreter for jq. 2023. arXiv:2302.10576  [cs.LO].
^ Janssens 2014.
^ jq. jq. [January 6, 2023].
^ like sed. （原始內容存檔於2013-04-14）.
^ yq
^ Release v2.0.0 · kislyuk/yq. GitHub.
^ Release v0.0.1 · itchyny/gojq. GitHub.
^ Tutorial. jq. [January 6, 2023].
^ sqlite_jq. GitHub.
^ "deterministic"
^ FAQ. GitHub.
^ Manual. jq. [January 6, 2023].
^ [https://www.json.org/json-en.html null
^ PEG. PEG.

外部連結

jq homepage
gojq - the Pure Go implementation
jaq - the Rust implementation
jqjq - the jq implementation
jq FAQ
Awesome jq - curated listing of jq-related resources
The jq Programming Language page on the Rosetta Code comparative programming tasks project site

[3] q的C或Go實現都沒有任何運行時間依賴^[2]。

[4] 包括Windows、Linux和macOS。Go實現可以在Go所支持的任何平台上編譯^[2]。

[5] q的C實現，使用了叫做decNumber的十進制浮點數庫，它採用了ICU許可證；和Oniguruma正則表達式庫，它採用了BSD許可證^[2]。

[wikidata-5ed9338ed4b21e53d443283c93be1a1d1f775995-v3-1] Release jq 1.7.1.

[Download-2] 2.0 ^2.1 ^2.2 Download jq. jq. [January 6, 2023].

[6] Initial · jqlang/Jq@eca89ac. GitHub.

[jaq-7] 4.0 ^4.1 01mf02/jaq: A jq clone focussed on correctness, speed, and simplicity. GitHub. [March 6, 2024].

[Denotational_Semantics-8] Färber, Michael. Denotational Semantics and a fast interpreter for jq. 2023. arXiv:2302.10576  [cs.LO].

[FOOTNOTEJanssens2014-9] Janssens 2014.

[News-10] q. jq. [January 6, 2023].

[archived-11] sed. （原始內容存檔於2013-04-14）.

[12] yq

[xq_versions-13] Release v2.0.0 · kislyuk/yq. GitHub.

[gojq-14] Release v0.0.1 · itchyny/gojq. GitHub.

[Tutorial-15] Tutorial. jq. [January 6, 2023].

[Maclean-16] sqlite_jq. GitHub.

[17] "deterministic"

[FAQ-18] FAQ. GitHub.

[Manual-19] Manual. jq. [January 6, 2023].

[20] [https://www.json.org/json-en.html null

[21] PEG. PEG.

[1]

[a]

[b]

[c]

[3]

[4]

[5]

[6]

[7]

[8]

[9]

[10]

[11]

[12]

[13]

[14]

[15]

[16]

[17]

[18]

[2]