購物清單

基礎

我們假設你已經熟悉 JSON 的語法和資料型態。

jq 的運作方式，是把傳入的 JSON 資料通過_單一運算式_（寫成_過濾器管線_），以得到想要的轉換後資料。

過濾器與管線

過濾器也稱為運算式。

一個_過濾器_接受輸入並產生輸出。 就像你在 unix shell 裡工作的方式一樣，你可以用管線|串接_過濾器_，把一個_過濾器_的輸出接到另一個的輸入。

恆等過濾器：.

這是最簡單的_過濾器_。 它只是把輸入直接傳到輸出。

$ echo '[1, 2, 3]' | jq '.'
[
  1,
  2,
  3
]

陣列

這裡會快速介紹如何處理陣列。 我們之後會更詳細地探討這個主題。

_陣列_元素用方括號存取，索引從 0 開始。

$ echo '[10, 20, 30]' | jq '.[1]'
20

一個_過濾器_可以把運算式包在[和]裡來建構_陣列_

• 搭配一份已知的元素清單：

  jq -n '[1, 2, 3]'
  

• 收集一串元素：舉例來說，range是一個會輸出數字串流的函式

  $ jq -n 'range(10; 70; 15)'
  10
  25
  40
  55
  

  用[]會把運算式的結果收集成一個陣列

  $ jq -c -n '[range(10; 70; 15)]'
  [10,25,40,55]
  

逗號是運算子

_逗號_不只是分隔_陣列_元素的語法。 逗號是一個串接資料流的運算子。

舉例來說，[1, 2, 3]是一個_過濾器_，它用_陣列_建構子[]來收集串接三個運算式1、2和3的結果。

你注意到上面range(10; 70; 15)裡的分號了嗎？ 因為_逗號_在jq語言中有特定的用途，所以接受多個引數的函式會用分號來分隔引數。

物件

快速介紹物件。

和許多程式語言類似，用點來存取_物件_的屬性

$ echo '{"foo": {"bar": "qux"}}' | jq '.foo.bar'
"qux"

$ echo '{"foo bar": "qux"}' | jq '.["foo bar"]'
"qux"

你可以用{}和key: value配對來建構_物件_。 「簡單」的字串不需要用引號把_鍵_括起來。

jq -n '{question: (6 * 9), answer: 42}'

輸出

{
  "question": 54,
  "answer": 42
}

若要把_鍵_當成_運算式_處理，你必須用括號把它包起來（下面這段也會輸出和上面相同的結果）。

echo '[{"key":"question", "value":54}, {"key":"answer", "value":42}]' \
| jq '{(.[0].key): .[0].value, (.[1].key): .[1].value}'

管線

舉例來說，假設file.json的內容是

{
  "key1": "value1",
  "key2": [5, 15, 25]
}

讓我們來算算 key2 _陣列_的長度：

$ jq '.key2 | length' file.json
3

我們把.key2運算式的輸出_用管線接到_length的輸入，毫不意外地，它會輸出_陣列_中的元素個數。

過濾器可以忽略它的輸入

在這個範例中，輸入的 JSON 資料會被忽略，對輸出沒有任何影響：

$ echo '{"answer": 42}' | jq '6 * 9'
54

過濾器可以輸出資料流

一個_過濾器_可以輸出多個值。 舉例來說，.[]這個_過濾器_會把_陣列_的每個元素當成獨立的值輸出：

$ jq -n -c '[1, 2, 3]'
[1,2,3]

$ jq -n -c '[1, 2, 3] | .[]'
1
2
3

把這樣的_過濾器_用管線接到另一個過濾器時，第二個_過濾器_會**針對每個值**各執行一次：

$ jq -n -c '[1, 2, 3] | .[] | . * 2'
2
4
6

這就像是隱含的疊代。 一旦你懂了這個技巧，就會發現非常強大的jq_過濾器_可以寫得非常簡潔。

括號

括號用來把子運算式群組在一起，以強制運算的順序，就像其他語言一樣。 在jq中，需要用到它們的時機有時會讓人覺得有點意外。

舉例來說，假設我們想建構一個有 2 個元素的_陣列_：9 的平方根，以及_e_的 1 次方。 這兩個獨立的運算式是9 | sqrt和1 | exp。 我們預期輸出會是_陣列_[3, 2.7...]

$ jq -n '[ 9|sqrt, 1|exp ]'
[
  20.085536923187668,
  2.718281828459045
]

為什麼我們沒有得到預期的結果？ jq把它解讀成這樣：

[ ((9|sqrt), 1) | exp ]

jq會建立一個有兩個元素（3和1）的資料流，兩者都分別被送給exp。

我們必須確保exp只會收到一個數字當作輸入。 換句話說，我們必須強制管線在逗號之前先被求值。

$ jq -n '[ 9|sqrt, (1|exp) ]'
[
  3,
  2.718281828459045
]

函式與運算子

這裡不深入探討（函式會是另一個練習的主題），以下是一些實用的內建函式：

• length

  以陣列為輸入時，輸出陣列中的元素個數。

  $ jq -n '[10, 20, 30, 40] | length'
  4
  

• +

  這個運算子的行為取決於運算元的型態： 它會相加數字、 串接字串、 附加陣列、 合併物件。

  $ jq -c -n '
      3 + 4,
      "foo" + "bar",
      ["a", "b"] + ["c"],
      {"m": 10} + {"n": 20}
  '
  7
  "foobar"
  ["a","b","c"]
  {"m":10,"n":20}
  

  add是一個函式，它接受一個陣列，並依照+的規則把所有元素加總後回傳一個結果。 [1, 2, 3] | add會輸出6。

• map

  以陣列為輸入、以過濾器為引數時，輸出一個把該過濾器套用到每個元素後所得的陣列

  $ jq -c -n '[10, 20, 30, 40] | map(. / 5)'
  [2,4,6,8]
  

• select

  給定_某個_輸入和一個過濾器作為引數：

  • 如果套用到該引數的過濾器產生_true_值，就原封不動地輸出輸入
  • 否則輸出_空無_（不是null值，是真的沒有任何輸出）

  舉例來說，給定一些數字，挑出其中能被 3 整除的

  $ jq -n 'range(10) | select(. % 3 == 0)'
  0
  3
  6
  9
  

  回想一下，range會輸出一個數字的_資料流_。 select會針對每個數字各被呼叫一次。 只有「通過」該運算式的數字才會被輸出。

  你經常需要挑選陣列中的元素。 這裡有幾種做法。

  以["Anne", "Bob", "Cathy", "Dave"]為輸入時，挑出長度為 4 的名字。

  • 把map和select一起使用

    map(select(length == 4))
    

  • 把陣列拆解成個別元素，對該資料流使用select，再收集結果

    [ .[] | select(length == 4) ]
    

註解

註解以#字元開頭，一直持續到該行的結尾。