jq語言

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

jq

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

jq與Icon和Haskell編程語言有關。它最初採用Haskell實現，隨即移植至C語言。

歷史

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

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

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

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

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

用法

命令行用法

jq典型的用於命令行，並可以協作於其他命令行實用工具，比如curl。下面的例子展示如何將curl命令的輸出通過管道接轉到jq過濾器，從而確定同這個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的進程間通信機制。

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

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

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

嵌入式用法

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

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

運算的模態

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

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

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

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

語法和語義

類型

所有JSON值自身是jq中的值，它們從而有在下列表格中展示的類型。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是一個值，就像任何其他JSON標量一樣；它不是指針或空指針。nan（對應於NaN）和infinite（參見IEEE 754），是僅有的兩個不是JSON值的jq標量。

形式

對於函數創建、條件、串流歸約和模塊系統，分別有特殊語法形式：def、if~then~else~end、reduce和import~as。

過濾器

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]

點號.可以被用來在右手端定義一個附着點（attachment point），例如：

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

下面例子是隱式編程風格生成斐波那契數列：

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

下面將其定義為新的命名過濾器：

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

下面的例子展示如何定義命名的參數化的過濾器，它格式化從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文件，接着使用這個函數：

$ jq 'include "./tobase"; tobase(16)'
16
"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;used): ([range(m;n+1)] - used)[];
    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;
    1 as $m | 0 as $o
    | choose(8;9;[]) as $s
    | choose(2;9;[$s]) as $e
    | choose(2;9;[$s,$e]) as $n
    | choose(2;9;[$s,$e,$n]) as $d
    | choose(2;9;[$s,$e,$n,$d]) as $r
    | choose(2;9;[$s,$e,$n,$d,$r]) as $y
    | 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）形式化之間有密切關聯。這種關聯源於下列表格中展示的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] == []);

移植和變體

gojq是「純Go」實現。還有Rust實現的jq方言叫做jaq，它規定了指稱語義。

參考書目

• 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 （英語）. 

外部連結

• 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