jq 1.7 Руководство

Identity: .

Абсолютно простейший фильтр — это . . Этот фильтр принимает свой вход и выдает то же самое значение на выходе. То есть это оператор тождества.

Поскольку jq по умолчанию форматирует весь вывод, тривиальная программа, состоящая только из ., может использоваться для форматирования JSON-вывода, например, из curl.

Хотя фильтр тождества никогда не изменяет значение своего входа, обработка jq иногда может создавать видимость того, что он это делает. Например, используя текущую реализацию jq, мы увидим, что выражение:

1E1234567890 | .

выдает 1.7976931348623157e+308 по крайней мере на одной платформе. Это происходит потому, что в процессе анализа числа эта конкретная версия jq преобразует его в представление с двойной точностью IEEE754, теряя точность.

Способ обработки чисел в jq со временем менялся, и дальнейшие изменения, вероятно, находятся в рамках параметров, установленных соответствующими стандартами JSON. Поэтому следующие замечания предлагаются с пониманием того, что они предназначены для описания текущей версии jq и не должны интерпретироваться как предписывающие:

(1) Любая арифметическая операция над числом, которое еще не было преобразовано в представление с двойной точностью IEEE754, вызовет преобразование в представление IEEE754.

(2) jq будет пытаться сохранить исходную десятичную точность числовых литералов, но в выражениях типа 1E1234567890, точность будет потеряна, если показатель степени слишком велик.

(3) В программах jq ведущий знак минус вызовет преобразование числа в представление IEEE754.

(4) Сравнения выполняются с использованием не усеченного представления чисел с большой точностью, если оно доступно, как показано в одном из следующих примеров.

Индекс идентификатора объекта: .foo, .foo.bar

Простейший полезный фильтр имеет вид .foo. При получении в качестве входных данных объекта JSON (также известного как словарь или хеш), .foo выдает значение по ключу "foo", если ключ присутствует, или null в противном случае.

Фильтр вида .foo.bar эквивалентен .foo | .bar.

Синтаксис .foo работает только для простых ключей, похожих на идентификаторы, то есть ключей, которые состоят только из буквенно-цифровых символов и символа подчеркивания, и которые не начинаются с цифры.

Если ключ содержит специальные символы или начинается с цифры, необходимо заключить его в двойные кавычки, например: ."foo$", иначе .["foo$"].

Например, .["foo::bar"] и .["foo.bar"] работают, а .foo::bar — нет.

Необязательный индекс идентификатора объекта: .foo?

То же самое, что и .foo, но не выдает ошибку, когда . не является объектом.

Индекс объекта: .[<string>]

Вы также можете искать поля объекта, используя синтаксис, подобный .["foo"] (.foo выше является сокращенной версией этого, но только для строк, подобных идентификаторам).

Индекс массива: .[<number>]

Когда значение индекса является целым числом, .[<number>] может индексировать массивы. Массивы нумеруются с нуля, поэтому .[2] возвращает третий элемент.

Допускаются отрицательные индексы, при этом -1 относится к последнему элементу, -2 — к предпоследнему и так далее.

Вырезка массива/строки: .[<number>:<number>]

Синтаксис .[<number>:<number>] может использоваться для возвращения подмассива массива или подстроки строки. Массив, возвращаемый .[10:15], будет иметь длину 5 и будет содержать элементы с индекса 10 (включительно) до индекса 15 (исключительно). Любой из индексов может быть отрицательным (в этом случае он отсчитывается от конца массива) или пропущен (в этом случае он относится к началу или концу массива). Индексы нумеруются с нуля.

Итератор значений массива/объекта: .[]

Если вы используете синтаксис .[index], но полностью опускаете индекс, он вернет все элементы массива. Выполнение .[] с входными данными [1,2,3] приведет к тому, что числа будут выведены как три отдельных результата, а не как один массив. Фильтр вида .foo[] эквивалентен .foo | .[].

Вы также можете использовать это для объекта, и он вернет все значения объекта.

Обратите внимание, что оператор итератора является генератором значений.

.[]?

Как .[], но никаких ошибок не будет выведено, если . не является массивом или объектом. Фильтр вида .foo[]? эквивалентен .foo | .[]?.

Запятая: ,

Если два фильтра разделены запятой, то на оба подаются одни и те же входные данные, и потоки выходных значений двух фильтров конкатенируются по порядку: сначала все выходные данные, полученные левым выражением, а затем все выходные данные, полученные правым. Например, фильтр .foo, .bar выдает поля "foo" и "bar" как отдельные результаты.

Оператор , — это один из способов построения генераторов.

Труба: |

Оператор | объединяет два фильтра, передавая вывод левого фильтра на вход правого. Он похож на конвейер в оболочке Unix, если вам знакома эта концепция.

Если левый фильтр производит несколько результатов, правый фильтр будет выполняться для каждого из этих результатов. Таким образом, выражение .[] | .foo извлекает поле "foo" каждого элемента входного массива. Это декартово произведение, что может быть неожиданным.

Обратите внимание, что .a.b.c эквивалентно .a | .b | .c.

Также обратите внимание, что . — это значение входных данных на определенной стадии "конвейера", конкретно: там, где появляется выражение .. Таким образом, .a | . | .b эквивалентно .a.b, так как . в середине относится к значению, которое вывело .a.

Скобки

Скобки работают как операторы группировки, как и в любом типичном языке программирования.

Создание массивов: []

Как и в JSON, [] используется для создания массивов, как в [1,2,3]. Элементы массивов могут быть любыми выражениями jq, включая конвейер. Все результаты, произведённые всеми выражениями, собираются в один большой массив. Можно использовать его для создания массива из известного количества значений (как в [.foo, .bar, .baz]) или для «собирания» всех результатов фильтра в массив (как в [.items[].name])

Поняв оператор «,» можно взглянуть на синтаксис массивов jq под другим углом: выражение [1,2,3] не использует встроенный синтаксис для массивов, разделенных запятыми, а вместо этого применяет оператор [] (собрать результаты) к выражению 1,2,3 (которое производит три разных результата).

Если у вас есть фильтр X, который производит четыре результата, то выражение [X] произведёт один результат — массив из четырёх элементов.

Создание объектов: {}

Как и в JSON, {} используется для создания объектов (также известных как словари или хэши), как в {"a": 42, "b": 17}.

Если ключи похожи на идентификаторы, кавычки можно опустить, как в {a:42, b:17}. Ссылок на переменные в качестве выражений ключей используют значение переменной как ключ. Выражения ключей, отличные от константных литералов, идентификаторов или ссылок на переменные, необходимо заключать в скобки, например, {("a"+"b"):59}.

Значение может быть любым выражением (хотя, возможно, его нужно заключить в скобки, если, например, оно содержит двоеточия), которое применяется к входным данным выражения {} (помните, у всех фильтров есть вход и выход).

{foo: .bar}

произведёт JSON-объект {"foo": 42} при вводе JSON-объекта {"bar":42, "baz":43}. Можно использовать это для выбора определённых полей объекта: если входной объект содержит поля "user", "title", "id" и "content", и вам нужны только "user" и "title", можно написать

{user: .user, title: .title}

Так как это очень распространённо, существует сокращённый синтаксис: {user, title}.

Если одно из выражений производит несколько результатов, будет произведено несколько словарей. Если у входных

{"user":"stedolan","titles":["JQ Primer", "More JQ"]}

то выражение

{user, title: .titles[]}

произведёт два вывода:

{"user":"stedolan", "title": "JQ Primer"}
{"user":"stedolan", "title": "More JQ"}

Заключение ключа в скобки означает, что он будет оценён как выражение. С тем же входным объектом, что и выше,

{(.user): .titles}

производит

{"stedolan": ["JQ Primer", "More JQ"]}

Ссылок на переменные в качестве ключей используют значение переменной как ключ. Без значения имя переменной становится ключом, а её значение — значением,

"f o o" as $foo | "b a r" as $bar | {$foo, $bar:$foo}

производит

{"foo":"f o o","b a r":"f o o"}

Рекурсивный спуск: ..

Рекурсивно спускается ., производя каждое значение. Это то же самое, что и встроенная функция recurse без аргументов (см. ниже). Это призвано имитировать оператор XPath //. Обратите внимание, что ..a не работает; используйте .. | .a вместо него. В примере ниже мы используем .. | .a? для поиска всех значений ключей "a" в любом объекте, найденном "ниже" ..

Это особенно полезно в сочетании с path(EXP) (также см. ниже) и оператором ?.

Сложение: +

Оператор + принимает два фильтра, применяет их оба к одному и тому же входному значению и складывает результаты. То, что означает «сложение», зависит от типов, участвующих в операции:

• Числа складываются с помощью обычной арифметики.

• Массивы складываются путем конкатенации в более крупный массив.

• Строки складываются путем объединения в более длинную строку.

• Объекты складываются путем слияния, то есть вставки всех пар ключ-значение из обоих объектов в один объединенный объект. Если оба объекта содержат значение для одного и того же ключа, выигрывает объект справа от +. (Для рекурсивного слияния используйте оператор *).

null можно добавить к любому значению, и он вернет другое значение без изменений.

Вычитание: -

Помимо обычного арифметического вычитания чисел, оператор - может использоваться для массивов, чтобы удалить все вхождения элементов второго массива из первого массива.

Умножение, деление, остаток от деления: *, /, %

Эти инфиксные операторы ведут себя так, как и ожидается, когда им даны два числа. Деление на ноль вызывает ошибку. x % y вычисляет x по модулю y.

Умножение строки на число приводит к конкатенации этой строки столько раз. "x" * 0 производит "".

Деление одной строки на другую разделяет первую, используя вторую в качестве разделителей.

Умножение двух объектов приведет к их рекурсивному слиянию: это работает как сложение, но если оба объекта содержат значение для одного и того же ключа, и значения являются объектами, то два объекта сливаются с той же стратегией.

abs

Встроенная функция abs определена наивно как: if . < 0 then - . else . end.

Для числового входного значения это абсолютное значение. См. раздел о фильтре идентичности для последствий этого определения для числового входного значения.

Для вычисления абсолютного значения числа как числа с плавающей точкой, вы можете использовать fabs.

length

Встроенная функция length получает длину различных типов значений:

• Длина строки — это количество символов Юникода, которые она содержит (что будет совпадать с длиной в байтах её JSON-представления, если это чистый ASCII).

• Длина числа — это его абсолютное значение.

• Длина массива — это количество элементов.

• Длина объекта — это количество пар ключ-значение.

• Длина null равна нулю.

• Использование length для булевого значения является ошибкой.

utf8bytelength

Встроенная функция utf8bytelength выводит количество байтов, используемых для кодирования строки в UTF-8.

keys, keys_unsorted

Встроенная функция keys, применимая к объекту, возвращает его ключи в виде массива.

Ключи отсортированы «алфавитно» в порядке кодов Юникода. Такой порядок не имеет особого смысла для конкретного языка, но вы можете рассчитывать на его сохранение для двух объектов с одинаковым набором ключей, независимо от настроек локали.

Когда keys применяется к массиву, она возвращает допустимые индексы этого массива: целые числа от 0 до длины-1.

Функция keys_unsorted аналогична keys, но если вход — объект, то ключи не сортируются, а примерно сохраняют порядок добавления.

has(key)

Встроенная функция has возвращает, существует ли у входного объекта заданный ключ или у входного массива элемент с заданным индексом.

has($key) имеет тот же эффект, что и проверка, является ли $key членом массива, возвращаемого keys, хотя has будет быстрее.

in

Встроенная функция in возвращает истину, если заданный ключ существует в объекте, или заданный индекс соответствует элементу в массиве. По сути, это обратная функция has.

map(f), map_values(f)

Для любого фильтра f, map(f) и map_values(f) применяется f к каждому из значений в входном массиве или объекте, то есть к значениям .[].

В отсутствие ошибок, map(f) всегда выводит массив, тогда как map_values(f) выводит массив, если задан массив, или объект, если задан объект.

Когда вход map_values(f) — объект, выходной объект имеет те же ключи, что и входной объект, за исключением тех ключей, значения которых, когда они передаются в f, не производят никаких значений.

Ключевое различие между map(f) и map_values(f) заключается в том, что первый просто формирует массив из всех значений ($x|f) для каждого значения, $x, во входном массиве или объекте, но map_values(f) использует только first($x|f).

Конкретно, для входных объектов map_value(f) строит выходной объект, последовательно рассматривая значение first(.[$k]|f) для каждого ключа $k$ входного объекта. Если это выражение не производит никаких значений, соответствующий ключ будет опущен; в противном случае, выходной объект будет иметь это значение в качестве ключа $k$.

Вот несколько примеров, чтобы прояснить поведение map и map_values при применении к массивам. Эти примеры предполагают, что вход [1] во всех случаях:

map(.+1)          #=>  [2]
map(., .)         #=>  [1,1]
map(empty)        #=>  []

map_values(.+1)   #=>  [2]
map_values(., .)  #=>  [1]
map_values(empty) #=>  []

map(f) эквивалентно [.[] | f], а map_values(f) эквивалентно .[] |= f.

На самом деле, это их реализации.

pick(pathexps)

Выводит проекцию входного объекта или массива, определённую заданной последовательностью выражений пути, таким образом, если p — одно из этих спецификаций, то (. | p) будет иметь такое же значение, что и (. | pick(pathexps) | p). Для массивов не следует использовать отрицательные индексы и спецификации .[m:n].

path(path_expression)

Выводит строковые представления заданного выражения пути в .. Выводы — массивы строк (ключи объектов) и/или чисел (индексы массивов).

Выражения пути — jq-выражения, такие как .a, но также и .[]. Существует два типа выражений пути: те, которые могут точно соответствовать, и те, которые не могут. Например, .a.b.c — это выражение пути точного соответствия, а .a[].b — нет.

path(exact_path_expression) будет генерировать строковое представление выражения пути, даже если оно не существует в ., если . — null или массив или объект.

path(pattern) будет генерировать строковые представления путей, соответствующих pattern, если пути существуют в ..

Обратите внимание, что выражения пути не отличаются от обычных выражений. Выражение path(..|select(type=="boolean")) выводит все пути к булевым значениям в ., и только эти пути.

del(path_expression)

Встроенная функция del удаляет ключ и его соответствующее значение из объекта.

getpath(PATHS)

Функция getpath выводит значения, находящиеся по каждому пути в заданном PATHS.

setpath(PATHS; VALUE)

Функция setpath устанавливает значение в . по указанному пути PATHS.

delpaths(PATHS)

Функция delpaths удаляет значения по указанным путям в .. PATHS должен быть массивом путей, где каждый путь — массив строк и чисел.

to_entries, from_entries, with_entries(f)

Эти функции преобразуют объект в массив пар «ключ-значение» и обратно. Если to_entries получает объект, то для каждой k: v записи входных данных выходной массив содержит {"key": k, "value": v}.

from_entries выполняет обратное преобразование, а with_entries(f) — это сокращение для to_entries | map(f) | from_entries, полезное для выполнения некоторых операций со всеми ключами и значениями объекта. from_entries принимает "key", "Key", "name", "Name", "value", и "Value" в качестве ключей.

select(boolean_expression)

Функция select(f) возвращает входные данные без изменений, если f возвращает true для этих данных, и не возвращает ничего в противном случае.

Она полезна для фильтрации списков: [1,2,3] | map(select(. >= 2)) даст вам [2,3].

arrays, objects, iterables, booleans, numbers, normals, finites, strings, nulls, values, scalars

Эти встроенные функции выбирают только входы, которые являются массивами, объектами, итерируемыми (массивы или объекты), булевыми значениями, числами, нормальными числами, конечными числами, строками, null, не-null значениями и не-итерируемыми, соответственно.

empty

empty возвращает нулевые результаты. Совсем никаких. Даже null.

Иногда это полезно. Вы поймёте, если вам это понадобится :)

error, error(message)

Возвращает ошибку со значением входных данных или с указанным в качестве аргумента сообщением. Ошибки можно перехватить с помощью try/catch; см. ниже.

halt

Останавливает программу jq без дальнейших выводов. jq завершит работу со статусом выхода 0.

halt_error, halt_error(exit_code)

Останавливает программу jq без дальнейших выводов. Входные данные будут напечатаны в stderr как сырой вывод (т.е. строки не будут иметь двойных кавычек) без оформления, даже без новой строки.

Указанное exit_code (по умолчанию 5) будет статусом выхода jq.

Например, "Error: something went wrong\n"|halt_error(1).

$__loc__

Возвращает объект с ключами "file" и "line", содержащими имя файла и номер строки, где $__loc__ возникает, как значения.

paths, paths(node_filter)

paths выводит пути ко всем элементам ввода (кроме пустого списка, представляющего . самого по себе).

paths(f) выводит пути к любым значениям, для которых f равно true. То есть, paths(type == "number") выводит пути ко всем числовым значениям.

add

Фильтр add принимает на вход массив и возвращает сумму элементов массива. Это может означать суммирование, конкатенацию или слияние, в зависимости от типов элементов входного массива - правила такие же, как для оператора + (описанного выше).

Если входной массив пустой, add возвращает null.

any, any(condition), any(generator; condition)

Фильтр any принимает на вход массив булевых значений и возвращает true в качестве результата, если любой из элементов массива является true.

Если входной массив пустой, any возвращает false.

Форма any(condition) применяет заданное условие к элементам входного массива.

Форма any(generator; condition) применяет заданное условие ко всем результатам данного генератора.

all, all(condition), all(generator; condition)

Фильтр all принимает на вход массив булевых значений и выдает true в качестве результата, если все элементы массива являются true.

Форма all(condition) применяет заданное условие к элементам входного массива.

Форма all(generator; condition) применяет заданное условие ко всем результатам заданного генератора.

Если входной массив пуст, all возвращает true.

flatten, flatten(depth)

Фильтр flatten принимает на вход массив вложенных массивов и выдает плоский массив, в котором все массивы внутри исходного массива рекурсивно заменены их значениями. Вы можете передать ему аргумент, чтобы указать, сколько уровней вложенности нужно выровнять.

flatten(2) похож на flatten, но работает только до двух уровней вложенности.

range(upto), range(from; upto), range(from; upto; by)

Функция range создает диапазон чисел. range(4; 10) создает 6 чисел, от 4 (включительно) до 10 (исключительно). Числа генерируются как отдельные результаты. Используйте [range(4; 10)], чтобы получить диапазон в виде массива.

Форма с одним аргументом генерирует числа от 0 до заданного числа с шагом 1.

Форма с двумя аргументами генерирует числа от from до upto с шагом 1.

Форма с тремя аргументами генерирует числа from до upto с шагом by.

floor

Функция floor возвращает целую часть своего числового входа.

sqrt

Функция sqrt возвращает квадратный корень из своего числового входа.

tonumber

Функция tonumber разбирает свой входной параметр как число. Она будет правильно преобразовывать отформатированные строки в их числовые эквиваленты, оставлять числа без изменений и выдавать ошибку на всех остальных входных данных.

tostring

Функция tostring выводит свой входной параметр как строку. Строки остаются без изменений, а все остальные значения кодируются в формате JSON.

type

Функция type возвращает тип своего аргумента в виде строки, который является одним из null, boolean, number, string, array или object.

infinite, nan, isinfinite, isnan, isfinite, isnormal

Некоторые арифметические операции могут давать бесконечности и значения "не число" (NaN). Встроенная функция isinfinite возвращает true, если её входной параметр является бесконечностью. Встроенная функция isnan возвращает true, если её входной параметр является NaN. Встроенная функция infinite возвращает положительное бесконечное значение. Встроенная функция nan возвращает NaN. Встроенная функция isnormal возвращает true, если её входной параметр является нормальным числом.

Обратите внимание, что деление на ноль вызывает ошибку.

В настоящее время большинство арифметических операций, выполняемых над бесконечностями, NaN и субнормальными числами, не вызывают ошибок.

sort, sort_by(path_expression)

Функции sort сортируют свой входной параметр, который должен быть массивом. Значения сортируются в следующем порядке:

• null
• false
• true
• числа
• строки, в алфавитном порядке (по значению кодовой точки Unicode)
• массивы, в лексикографическом порядке
• объекты

Порядок сортировки объектов немного сложен: сначала они сравниваются путем сравнения их наборов ключей (как отсортированных массивов), и если их ключи равны, то значения сравниваются ключ за ключом.

sort_by может использоваться для сортировки по определенному полю объекта или путем применения любого фильтра jq. sort_by(f) сравнивает два элемента, сравнивая результат f для каждого элемента. Когда f производит несколько значений, он сначала сравнивает первые значения, а затем вторые значения, если первые значения равны, и так далее.

group_by(path_expression)

group_by(.foo) принимает на вход массив, группирует элементы, имеющие одинаковое поле .foo, в отдельные массивы и выдает все эти массивы как элементы большего массива, отсортированного по значению поля .foo.

Вместо .foo может использоваться любое выражение jq, а не только доступ к полю. Порядок сортировки такой же, как описано в функции sort выше.

min, max, min_by(path_exp), max_by(path_exp)

Найти минимальный или максимальный элемент входного массива.

Функции min_by(path_exp) и max_by(path_exp) позволяют указать конкретное поле или свойство для проверки, например, min_by(.foo) находит объект с наименьшим полем foo.

unique, unique_by(path_exp)

Функция unique принимает на вход массив и выдает массив тех же элементов, отсортированных по порядку, без дубликатов.

Функция unique_by(path_exp) будет хранить только один элемент для каждого значения, полученного путем применения аргумента. Можно представить это как создание массива, взяв один элемент из каждой группы, полученной с помощью group.

reverse

Эта функция переворачивает массив.

contains(element)

Фильтр contains(b) вернет true, если b полностью содержится во входных данных. Строка B содержится в строке A, если B является подстрокой A. Массив B содержится в массиве A, если все элементы в B содержатся в любом элементе A. Объект B содержится в объекте A, если все значения в B содержатся в значении A с тем же ключом. Предполагается, что все остальные типы содержатся друг в друге, если они равны.

indices(s)

Выводит массив, содержащий индексы в ., где встречается s. Входные данные могут быть массивом, и в этом случае, если s является массивом, то выходные индексы будут теми, где все элементы в . совпадают с элементами s.

index(s), rindex(s)

Выводит индекс первого (index) или последнего (rindex) вхождения s во входных данных.

inside

Фильтр inside(b) вернет true, если входные данные полностью содержатся в b. По сути, это обратная версия contains.

startswith(str)

Выводит true, если . начинается с указанной строковой аргумента.

endswith(str)

Выводит true, если . заканчивается указанной строковой аргумента.

combinations, combinations(n)

Выводит все комбинации элементов массивов во входном массиве. Если задан аргумент n, он выводит все комбинации n повторений входного массива.

ltrimstr(str)

Выводит свой входной параметр со строкой-префиксом, удалённой, если она начинается с неё.

rtrimstr(str)

Выводит свой входной параметр со строкой-суффиксом, удалённой, если она заканчивается ею.

explode

Преобразует входную строку в массив числовых кодов символов строки.

implode

Обратное преобразование к explode.

split(str)

Разделяет входную строку по разделителю.

split также может разделять по совпадениям с регулярным выражением, если вызвана с двумя аргументами (см. раздел регулярных выражений ниже).

join(str)

Объединяет массив элементов, заданных в качестве входных данных, используя аргумент в качестве разделителя. Это обратное преобразование к split: выполнение split("foo") | join("foo") над любой входной строкой возвращает эту строку.

Числа и булевы значения во входных данных преобразуются в строки. Нулевые значения обрабатываются как пустые строки. Массивы и объекты во входных данных не поддерживаются.

ascii_downcase, ascii_upcase

Выводит копию входной строки с алфавитными символами (a-z и A-Z) в указанном регистре.

while(cond; update)

Функция while(cond; update) позволяет многократно применять обновление к . до тех пор, пока cond не станет ложным.

Обратите внимание, что while(cond; update) внутренне определена как рекурсивная функция jq. Рекурсивные вызовы внутри while не будут потреблять дополнительной памяти, если update производит не более одного результата для каждого входа. См. расширенные темы ниже.

repeat(exp)

Функция repeat(exp) позволяет многократно применять выражение exp к . до тех пор, пока не возникнет ошибка.

Обратите внимание, что repeat(exp) внутренне определена как рекурсивная функция jq. Рекурсивные вызовы внутри repeat не будут потреблять дополнительной памяти, если exp производит не более одного результата для каждого входа. См. расширенные темы ниже.

until(cond; next)

Функция until(cond; next) позволяет вам многократно применять выражение next, сначала к ., а затем к своему собственному результату, пока cond не станет истинным. Например, это может быть использовано для реализации факториальной функции (см. ниже).

Обратите внимание, что until(cond; next) внутренне определяется как рекурсивная функция jq. Рекурсивные вызовы внутри until() не будут потреблять дополнительную память, если next производит не более одного результата для каждого входного значения. См. дополнительные разделы ниже.

recurse(f), recurse, recurse(f; condition)

Функция recurse(f) позволяет вам искать в рекурсивной структуре и извлекать интересные данные со всех уровней. Предположим, ваш вход представляет собой файловую систему:

{"name": "/", "children": [
  {"name": "/bin", "children": [
    {"name": "/bin/ls", "children": []},
    {"name": "/bin/sh", "children": []}]},
  {"name": "/home", "children": [
    {"name": "/home/stephen", "children": [
      {"name": "/home/stephen/jq", "children": []}]}]}]}

Теперь предположим, что вы хотите извлечь все имеющиеся имена файлов. Вам нужно получить .name, .children[].name, .children[].children[].name и так далее. Вы можете сделать это с помощью:

recurse(.children[]) | .name

При вызове без аргумента recurse эквивалентно recurse(.[]?).

recurse(f) идентична recurse(f; true) и может использоваться без опасений по поводу глубины рекурсии.

recurse(f; condition) — это генератор, который начинает с вывода . и затем по очереди выводит .|f, .|f|f, .|f|f|f, ... до тех пор, пока вычисленное значение удовлетворяет условию. Например, чтобы сгенерировать все целые числа, по крайней мере в принципе, можно написать recurse(.+1; true).

Рекурсивные вызовы в recurse не будут потреблять дополнительную память, если f производит не более одного результата для каждого входного значения.

walk(f)

Функция walk(f) рекурсивно применяет f к каждому компоненту входной сущности. Когда встречается массив, f сначала применяется к его элементам, а затем к самому массиву; когда встречается объект, f сначала применяется ко всем значениям, а затем к объекту. На практике f обычно будет проверять тип своего входного значения, как показано в следующих примерах. Первый пример показывает полезность обработки элементов массива массивов перед обработкой самого массива. Второй пример показывает, как все ключи всех объектов во входных данных могут быть рассмотрены для изменения.

$JQ_BUILD_CONFIGURATION

Это встроенное связывание показывает конфигурацию сборки исполняемого файла jq. Его значение не имеет определенного формата, но можно ожидать, что это будут по крайней мере аргументы командной строки ./configure, и в будущем оно может быть расширено, чтобы включать версии используемых инструментов сборки.

Обратите внимание, что это можно переопределить в командной строке с помощью --arg и связанных параметров.

$ENV, env

$ENV — это объект, представляющий переменные среды, установленные при запуске программы jq.

env выводит объект, представляющий текущую среду jq.

На данный момент нет встроенного механизма для установки переменных среды.

transpose

Транспонировать возможно неровную матрицу (массив массивов). Строки дополняются значениями null, поэтому результат всегда прямоугольный.

bsearch(x)

bsearch(x) выполняет бинарный поиск x в входном массиве. Если входной массив отсортирован и содержит x, то bsearch(x) вернёт его индекс в массиве; в противном случае, если массив отсортирован, он вернёт (-1 - ix), где ix — позиция вставки, такая, что массив останется отсортированным после вставки x в ix. Если массив не отсортирован, bsearch(x) вернёт целое число, которое, вероятно, не представляет интереса.

Интерполяция строк: \(exp)

Внутри строки вы можете поместить выражение в скобки после обратной косой черты. То, что вернёт выражение, будет интерполировано в строку.

Преобразование в/из JSON

Встроенные функции tojson и fromjson выгружают значения как тексты JSON или соответственно парсят тексты JSON в значения. Функция tojson отличается от tostring тем, что tostring возвращает строки без изменений, в то время как tojson кодирует строки как строки JSON.

Форматирование строк и экранирование

Синтаксис @foo используется для форматирования и экранирования строк, что полезно для построения URL-адресов, документов на языках типа HTML или XML и так далее. @foo может использоваться как отдельный фильтр, возможные экранирования:

• @text:

Вызывает tostring, см. эту функцию для получения подробностей.

• @json:

Сериализует входные данные как JSON.

• @html:

Применяет экранирование HTML/XML, сопоставляя символы <>&'" с их эквивалентами сущностей <, >, &, ', ".

• @uri:

Применяет кодировку процентов, сопоставляя все зарезервированные символы URI с последовательностью %XX.

• @csv:

Входные данные должны быть массивом, и он отображается как CSV с двойными кавычками для строк, а кавычки экранируются повтором.

• @tsv:

Входные данные должны быть массивом, и он отображается как TSV (табулированные значения). Каждый массив входных данных будет напечатан в отдельной строке. Поля разделяются одной табуляцией (ascii 0x09). Символы переноса строки (ascii 0x0a), возврата каретки (ascii 0x0d), табуляции (ascii 0x09 ) и обратной косой черты (ascii 0x5c) будут выводиться как escape-последовательности \n, \r, \t, \\ соответственно.

• @sh:

Входные данные экранируются подходящим образом для использования в командной строке для оболочки POSIX. Если входные данные являются массивом, вывод будет представлять собой серию строк, разделённых пробелами.

• @base64:

Входные данные преобразуются в base64 в соответствии со спецификацией RFC 4648.

• @base64d:

Обратная функция к @base64, входные данные декодируются в соответствии со спецификацией RFC 4648. Примечание: Если декодированная строка не является UTF-8, результаты не определены.

Этот синтаксис может быть полезно комбинирован с интерполяцией строк. Вы можете после маркера @foo следовать строковой литералом. Содержимое строковой литерала не будет экранироваться. Однако все интерполяции внутри этой строковой литерала будут экранированы. Например,

@uri "https://www.google.com/search?q=\(.search)"

выведет следующий вывод для входных данных {"search":"what is jq?"}:

"https://www.google.com/search?q=what%20is%20jq%3F"

Обратите внимание, что слеши, вопросительный знак и т.д. в URL не экранированы, так как они были частью строковой литерала.

Даты

jq предоставляет некоторые базовые функции обработки дат с некоторыми высокоуровневыми и низкоуровневыми встроенными функциями. Во всех случаях эти встроенные функции работают исключительно со временем в UTC.

Встроенная функция fromdateiso8601 анализирует даты и время в формате ISO 8601 и преобразует их в количество секунд с момента эпохи Unix (1970-01-01T00:00:00Z). Встроенная функция todateiso8601 выполняет обратную операцию.

Встроенная функция fromdate анализирует строки даты и времени. В настоящее время fromdate поддерживает только строки даты и времени в формате ISO 8601, но в будущем она будет пытаться анализировать строки даты и времени в большем количестве форматов.

Встроенная функция todate является псевдонимом для todateiso8601.

Встроенная функция now выводит текущее время в секундах с момента эпохи Unix.

Также предоставляются низкоуровневые jq-интерфейсы к функциям времени C-библиотеки: strptime, strftime, strflocaltime, mktime, gmtime, и localtime. Обратитесь к документации вашей операционной системы для получения информации о форматах строк, используемых в strptime и strftime. Примечание: эти интерфейсы не обязательно являются стабильными в jq, особенно в отношении их функциональности локализации.

Встроенная функция gmtime принимает количество секунд с момента эпохи Unix и выводит представление "разложенного времени" по Гринвичу в виде массива чисел, представляющих (в этом порядке): год, месяц (нулевое основание), день месяца (единичное основание), час, минуту, секунду, день недели и день года - все единичные, если не указано иное. Номер дня недели может быть неправильным на некоторых системах для дат до 1 марта 1900 года или после 31 декабря 2099 года.

Встроенная функция localtime работает как встроенная функция gmtime , но использует локальную временную зону.

Встроенная функция mktime принимает представления "разложенного времени" времени, выводимые функциями gmtime и strptime.

Встроенная функция strptime(fmt) анализирует входные строки, соответствующие аргументу fmt. Результат представлен в виде "разложенного времени", используемого функцией gmtime и выводимого функцией mktime.

Встроенная функция strftime(fmt) форматирует время (GMT) в соответствии с заданным форматом. Встроенная функция strflocaltime делает то же самое, но использует локальную временную зону.

Форматы строк для strptime и strftime описаны в типичной документации C-библиотеки. Строка формата ISO 8601 для даты и времени - "%Y-%m-%dT%H:%M:%SZ".

jq может не поддерживать некоторые или все функции работы с датой на некоторых системах. В частности, спецификаторы %u и %j для strptime(fmt) не поддерживаются на macOS.

Операторы в стиле SQL

jq предоставляет несколько операторов в стиле SQL.

• INDEX(stream; index_expression):

Эта встроенная функция создаёт объект, ключи которого вычисляются с помощью данного выражения индексации, применённого к каждому значению из заданного потока.

• JOIN($idx; stream; idx_expr; join_expr):

Эта встроенная функция объединяет значения из заданного потока со значениями заданного индекса. Ключи индекса вычисляются путём применения данного выражения индексации к каждому значению из заданного потока. Массив значения из потока и соответствующего значения из индекса подаётся в данное выражение объединения для создания каждого результата.

• JOIN($idx; stream; idx_expr):

То же самое, что и JOIN($idx; stream; idx_expr; .).

• JOIN($idx; idx_expr):

Эта встроенная функция объединяет входные данные . с данным индексом, применяя данное выражение индексации к . для вычисления ключа индекса. Операция объединения выполняется, как описано выше.

• IN(s):

Эта встроенная функция выводит true , если . встречается в заданном потоке, иначе выводит false.

• IN(source; s):

Эта встроенная функция выводит true , если какое-либо значение из потока source встречается во втором потоке, иначе выводит false.

builtins

Возвращает список всех встроенных функций в формате name/arity. Поскольку функции с одинаковым именем, но различной арностью считаются отдельными функциями, all/0, all/1, и all/2 все будут присутствовать в списке.

==, !=

Выражение 'a == b' вернёт 'true', если результаты вычисления a и b равны (то есть, если они представляют эквивалентные значения JSON), и 'false' в противном случае. В частности, строки никогда не считаются равными числам. При проверке равенства JSON-объектов порядок ключей не имеет значения. Если вы переходите из JavaScript, обратите внимание, что jq's == аналогично JavaScript's ===, оператору "строгого равенства".

!= означает "не равно", и 'a != b' возвращает значение, противоположное 'a == b'

if-then-else-end

if A then B else C end будет действовать так же, как B, если A возвращает значение, отличное от false или null, но будет действовать так же, как C в противном случае.

if A then B end аналогично if A then B else . end. То есть, ветка else является необязательной, и в её отсутствие результат будет эквивалентен .. Это также относится к elif с отсутствующей веткой else.

Проверка на false или null — это более упрощённое понятие "истинности", чем в JavaScript или Python, но это означает, что иногда вам придётся быть более явным относительно требуемого условия. Вы не можете проверить, например, пустая ли строка, используя if .name then A else B end; вам понадобится что-то вроде if .name == "" then A else B end.

Если условие A производит несколько результатов, то B вычисляется один раз для каждого результата, не равного false или null, и C вычисляется один раз для каждого false или null.

Можно добавить больше случаев в оператор if, используя синтаксис elif A then B.

>, >=, <=, <

Операторы сравнения >, >=, <=, < возвращают, больше ли, больше или равно, меньше или равно или меньше левый аргумент, чем правый (соответственно).

Порядок такой же, как описано для sort выше.

and, or, not

jq поддерживает обычные булевы операторы and, or, not. У них те же стандарты истинности, что и у условных выражений — false и null считаются "ложными значениями", а всё остальное — "истинными значениями".

Если операнд одного из этих операторов производит несколько результатов, сам оператор произведёт результат для каждого входного значения.

not на самом деле является встроенной функцией, а не оператором, поэтому она вызывается как фильтр, к которому можно передавать вещи, а не со специальным синтаксисом, как в .foo and .bar | not.

Эти три оператора возвращают только значения true и false, и поэтому они полезны только для настоящих булевых операций, а не для общего приема Perl/Python/Ruby "значение_которое_может_быть_null или значение_по_умолчанию". Если вы хотите использовать эту форму "или", выбирая между двумя значениями, а не вычисляя условие, см. оператор // ниже.

Оператор альтернативы: //

Оператор // производит все значения его левой части, которые не являются false или null, или, если левая часть не производит никаких значений, кроме false или null, тогда // производит все значения его правой части.

Фильтр вида a // b производит все результаты a, которые не являются false или null. Если a не производит результатов или результаты не отличаются от false или null, то a // b производит результаты b.

Это полезно для предоставления значений по умолчанию: .foo // 1 будет вычисляться как 1 , если в вводе нет элемента .foo. Это похоже на то, как or иногда используется в Python (оператор or jq предназначен для строго булевых операций).

Примечание: some_generator // defaults_here не то же самое, что и some_generator | . // defaults_here. Последнее будет производить значения по умолчанию для всех значений левой части, которые не являются false, не null, в то время как первое – нет. Правила приоритета могут вызвать путаницу. Например, в false, 1 // 2 левая часть // – это 1, а не false, 1 – false, 1 // 2 анализируется так же, как false, (1 // 2). В (false, null, 1) | . // 42 левая часть // – это ., которая всегда производит только одно значение, а в (false, null, 1) // 42 левая часть – это генератор трёх значений, и поскольку она производит значение, отличное от false и null, значение по умолчанию 42 не производится.

try-catch

Ошибки можно перехватывать с помощью try EXP catch EXP. Первое выражение выполняется, а если оно терпит неудачу, то второе выполняется с сообщением об ошибке. Вывод обработчика, если таковой имеется, отображается так, как будто это был вывод выражения для попытки.

Форма try EXP использует empty в качестве обработчика исключений.

Прерывание управляющих структур

Удобное применение try/catch – это прерывание управляющих структур, таких как reduce, foreach, while, и так далее.

Например:

# Repeat an expression until it raises "break" as an
# error, then stop repeating without re-raising the error.
# But if the error caught is not "break" then re-raise it.
try repeat(exp) catch if .=="break" then empty else error

jq имеет синтаксис для именованных лексических меток для «прерывания» или «возвращения к»:

label $out | ... break $out ...

Выражение break $label_name заставит программу действовать так, как будто ближайшая (слева) label $label_name произвела empty.

Связь между break и соответствующим label является лексической: метка должна быть «видимой» из break.

Для выхода из reduce, например:

label $out | reduce .[] as $item (null; if .==false then break $out else ... end)

Следующая программа jq генерирует синтаксическую ошибку:

break $out

потому что метка $out не видна.

Подавление ошибок / Оператор необязательности: ?

Оператор ? , используемый как EXP?, является сокращением для try EXP.

test(val), test(regex; flags)

Как match, но не возвращает объекты совпадений, а только true или false для того, соответствует ли регулярное выражение входным данным или нет.

match(val), match(regex; flags)

match выводит объект для каждого найденного совпадения. Совпадения имеют следующие поля:

• offset - смещение в кодовых точках UTF-8 от начала входных данных
• length - длина в кодовых точках UTF-8 совпадения
• string - строка, с которой произошло совпадение
• captures - массив объектов, представляющих захватывающие группы.

Объекты захватывающих групп имеют следующие поля:

• offset - смещение в кодовых точках UTF-8 от начала входных данных
• length - длина в кодовых точках UTF-8 этой захватывающей группы
• string - захваченная строка
• name - имя захватывающей группы (или null, если она была безымянной)

Захватывающие группы, которые не совпали ни с чем, возвращают смещение -1

capture(val), capture(regex; flags)

Собирает именованные захваты в объект JSON, где имя каждого захвата является ключом, а соответствующая строка — значением.

scan(regex), scan(regex; flags)

Выдает поток непересекающихся подстрок входных данных, которые соответствуют регулярному выражению в соответствии с флагами, если таковые были указаны. Если совпадений нет, поток пуст. Чтобы захватить все совпадения для каждой входной строки, используйте идиому [ expr ], например [ scan(regex) ].

split(regex; flags)

Разделяет входную строку на каждой совпадении с регулярным выражением.

Для обратной совместимости, когда вызывается с одним аргументом, split разделяет по строке, а не по регулярному выражению.

splits(regex), splits(regex; flags)

Они дают те же результаты, что и их split аналоги, но в виде потока, а не массива.

sub(regex; tostring), sub(regex; tostring; flags)

Вывести строку, полученную путём замены первого совпадения регулярного выражения во входной строке на tostring, после интерполяции. tostring должна быть jq-строкой или потоком таких строк, каждая из которых может содержать ссылки на именованные захватчики. Именные захватчики фактически представляются как объект JSON (как построенный capture) для tostring, поэтому ссылка на захваченную переменную с именем "x" будет иметь вид: "\(.x)".

gsub(regex; tostring), gsub(regex; tostring; flags)

gsub аналогично sub, но все непересекающиеся вхождения регулярного выражения заменяются tostring, после интерполяции. Если второй аргумент является потоком jq-строк, то gsub будет производить соответствующий поток JSON-строк.

Оператор привязки переменных/символов: ... as $identifier | ...

В jq все фильтры имеют вход и выход, поэтому для передачи значения из одной части программы в другую не требуется ручная передача. Многие выражения, например, a + b, передают свой вход двум различным подвыражениям (здесь a и b оба получают тот же вход), поэтому переменные обычно не нужны для использования значения дважды.

Например, вычисление среднего значения массива чисел требует нескольких переменных в большинстве языков — по крайней мере, одной для хранения массива, возможно, одной для каждого элемента или для счётчика цикла. В jq это просто add / length — выражение add получает массив и вычисляет его сумму, а выражение length получает массив и вычисляет его длину.

Таким образом, в jq обычно существует более чистый способ решения большинства задач, чем определение переменных. Тем не менее, иногда они упрощают задачу, поэтому jq позволяет определять переменные с помощью expression as $variable. Все имена переменных начинаются с $. Вот немного менее удобная версия примера вычисления среднего значения массива:

length as $array_length | add / $array_length

Нам понадобится более сложная задача, чтобы найти ситуацию, в которой использование переменных действительно облегчит нам жизнь.

Предположим, у нас есть массив записей блога со полями «автор» и «заголовок», а также другой объект, который используется для сопоставления имен пользователей авторов с реальными именами. Наш вход выглядит следующим образом:

{"posts": [{"title": "First post", "author": "anon"},
           {"title": "A well-written article", "author": "person1"}],
 "realnames": {"anon": "Anonymous Coward",
               "person1": "Person McPherson"}}

Мы хотим получить записи с полем «автор», содержащим реальное имя, как в:

{"title": "First post", "author": "Anonymous Coward"}
{"title": "A well-written article", "author": "Person McPherson"}

Мы используем переменную $names для хранения объекта realnames, чтобы мы могли ссылаться на него позже при поиске имён пользователей авторов:

.realnames as $names | .posts[] | {title, author: $names[.author]}

Выражение exp as $x | ... означает: для каждого значения выражения exp, выполните остальную часть конвейера с исходным полным входом и со значением $x, установленным на это значение. Таким образом, as выполняет функцию цикла foreach.

Так же, как {foo} — удобный способ записи {foo: .foo}, так и {$foo} — удобный способ записи {foo: $foo}.

Несколько переменных можно объявить, используя одно выражение as выражением, указав шаблон, который соответствует структуре ввода (это называется «распаковкой»):

. as {realnames: $names, posts: [$first, $second]} | ...

Объявления переменных в шаблонах массивов (например, . as [$first, $second]) привязываются к элементам массива с элемента от индекса ноль и далее в порядке. Когда значения в массиве отсутствует для элемента шаблона массива, null привязывается к этой переменной.

Переменные имеют область действия в остальной части выражения, которое их определяет, поэтому

.realnames as $names | (.posts[] | {title, author: $names[.author]})

будет работать, но

(.realnames as $names | .posts[]) | {title, author: $names[.author]}

не будет.

Для теоретиков языков программирования точнее сказать, что переменные jq — это лексически связанные привязки. В частности, невозможно изменить значение привязки; можно только установить новую привязку с тем же именем, но которая не будет видна там, где была старая.

Альтернативный оператор деструктуризации: ?//

Альтернативный оператор деструктуризации предоставляет краткий механизм для деструктуризации входных данных, которые могут принимать одну из нескольких форм.

Предположим, у нас есть API, который возвращает список ресурсов и связанных с ними событий, и мы хотим получить user_id и timestamp первого события для каждого ресурса. API (неумело преобразованный из XML) будет заключать события в массив только в том случае, если у ресурса несколько событий:

{"resources": [{"id": 1, "kind": "widget", "events": {"action": "create", "user_id": 1, "ts": 13}},
               {"id": 2, "kind": "widget", "events": [{"action": "create", "user_id": 1, "ts": 14}, {"action": "destroy", "user_id": 1, "ts": 15}]}]}

Мы можем использовать альтернативный оператор деструктуризации для простого решения этой проблемы структурных изменений:

.resources[] as {$id, $kind, events: {$user_id, $ts}} ?// {$id, $kind, events: [{$user_id, $ts}]} | {$user_id, $kind, $id, $ts}

Или, если мы не уверены, является ли входной массив значений или объект:

.[] as [$id, $kind, $user_id, $ts] ?// {$id, $kind, $user_id, $ts} | ...

Каждая альтернатива не обязана определять все те же переменные, но все именованные переменные будут доступны последующему выражению. Переменные, не найденные в выбранной альтернативе, будут null:

.resources[] as {$id, $kind, events: {$user_id, $ts}} ?// {$id, $kind, events: [{$first_user_id, $first_ts}]} | {$user_id, $first_user_id, $kind, $id, $ts, $first_ts}

Кроме того, если последующее выражение возвращает ошибку, альтернативный оператор попытается использовать следующее привязку. Ошибки, возникающие в финальной альтернативе, передаются дальше.

[[3]] | .[] as [$a] ?// [$b] | if $a != null then error("err: \($a)") else {$a,$b} end

Определение функций

Вы можете дать фильтру имя, используя синтаксис "def":

def increment: . + 1;

С этого момента, increment можно использовать как фильтр, как и встроенную функцию (на самом деле, так определены многие встроенные функции). Функция может принимать аргументы:

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

Аргументы передаются как фильтры (функции без аргументов), а не как значения. Один и тот же аргумент может ссылаться несколько раз с разными входными данными (здесь f выполняется для каждого элемента входного массива). Аргументы функции работают больше как обратные вызовы, чем как аргументы значений. Это важно понимать. Рассмотрим:

def foo(f): f|f;
5|foo(.*2)

Результат будет 20, потому что f является .*2, и во время первого вызова f . будет 5, а во второй раз он будет 10 (5 * 2), поэтому результат будет 20. Аргументы функции являются фильтрами, а фильтры ожидают входные данные при вызове.

Если вам нужно поведение аргумента-значения для определения простых функций, вы можете просто использовать переменную:

def addvalue(f): f as $f | map(. + $f);

Или использовать сокращенный вариант:

def addvalue($f): ...;

С любым из этих определений, addvalue(.foo) будет добавлять поле .foo текущего ввода к каждому элементу массива. Обратите внимание, что вызов addvalue(.[]) приведет к тому, что часть map(. + $f) будет вычисляться один раз для каждого значения в значении . в точке вызова.

Разрешено несколько определений с использованием одного и того же имени функции. Каждое переопределение заменяет предыдущее для того же количества аргументов функции, но только для ссылок из функций (или основной программы), последующих за переопределением. См. также раздел ниже о области видимости.

Область видимости

В jq есть два типа символов: привязки значений (также называемые «переменными») и функции. Оба имеют лексическую область видимости, при этом выражения могут ссылаться только на символы, которые были определены «слева» от них. Единственным исключением из этого правила является то, что функции могут ссылаться сами на себя, чтобы создавать рекурсивные функции.

Например, в следующем выражении есть привязка, которая видна «справа» от нее, ... | .*3 as $times_three | [. + $times_three] | ..., но не «слева». Рассмотрим теперь это выражение, ... | (.*3 as $times_three | [. + $times_three]) | ...: здесь привязка $times_three не видна за закрывающей скобкой.

isempty(exp)

Возвращает true, если exp не производит выходных данных, false в противном случае.

limit(n; exp)

Функция limit извлекает до n выходных данных из exp.

first(expr), last(expr), nth(n; expr)

Функции first(expr) и last(expr) извлекают первое и последнее значения из expr, соответственно.

Функция nth(n; expr) извлекает n-ое значение, выводимое expr. Обратите внимание, что nth(n; expr) не поддерживает отрицательные значения n.

first, last, nth(n)

Функции first и last извлекают первое и последнее значения из любого массива в ..

Функция nth(n) извлекает n-ое значение любого массива в ..

reduce

Синтаксис reduce позволяет объединять все результаты выражения, накапливая их в одном ответе. Форма: reduce EXP as $var (INIT; UPDATE). В качестве примера мы передадим [1,2,3] этому выражению:

reduce .[] as $item (0; . + $item)

Для каждого результата, который .[] производит, . + $item запускается для накопления текущей суммы, начиная с 0 в качестве входного значения. В этом примере .[] производит результаты 1, 2 и 3, поэтому эффект аналогичен запуску чего-то подобного:

0 | 1 as $item | . + $item |
    2 as $item | . + $item |
    3 as $item | . + $item

foreach

Синтаксис foreach похож на reduce, но предназначен для создания limit и редукторов, которые производят промежуточные результаты.

Форма: foreach EXP as $var (INIT; UPDATE; EXTRACT). В качестве примера мы передадим [1,2,3] этому выражению:

foreach .[] as $item (0; . + $item; [$item, . * 2])

Как и синтаксис reduce, . + $item запускается для каждого результата, который .[] производит, но [$item, . * 2] запускается для каждого промежуточного значения. В этом примере, поскольку промежуточные значения равны 1, 3 и 6, выражение foreach производит [1,2], [2,6] и [3,12]. Таким образом, эффект аналогичен запуску чего-то подобного:

0 | 1 as $item | . + $item | [$item, . * 2],
    2 as $item | . + $item | [$item, . * 2],
    3 as $item | . + $item | [$item, . * 2]

Когда EXTRACT опущен, используется тождественный фильтр. То есть он выводит промежуточные значения такими, какие они есть.

Рекурсия

Как описано выше, recurse использует рекурсию, и любая функция jq может быть рекурсивной. Встроенная функция while также реализована с использованием рекурсии.

Рекурсивные вызовы оптимизируются, когда выражение слева от рекурсивного вызова выводит своё последнее значение. На практике это означает, что выражение слева от рекурсивного вызова не должно производить более одного результата для каждого входного значения.

Например:

def recurse(f): def r: ., (f | select(. != null) | r); r;

def while(cond; update):
  def _while:
    if cond then ., (update | _while) else empty end;
  _while;

def repeat(exp):
  def _repeat:
    exp, _repeat;
  _repeat;

Генераторы и итераторы

Некоторые операторы и функции jq фактически являются генераторами, так как они могут производить ноль, одно или более значений для каждого входного значения, как можно ожидать в других языках программирования, имеющих генераторы. Например, .[] генерирует все значения в своём входе (который должен быть массивом или объектом), range(0; 10) генерирует целые числа от 0 до 10 и так далее.

Даже оператор запятой является генератором, генерирующим сначала значения, сгенерированные выражением слева от запятой, а затем значения, сгенерированные выражением справа от запятой.

Встроенная функция empty — это генератор, который производит ноль выходов. Встроенная функция empty возвращается к предыдущему выражению генератора.

Все функции jq могут быть генераторами, просто используя встроенные генераторы. Также возможно создать новые генераторы, используя только рекурсию и оператор запятой. Если рекурсивные вызовы находятся «в хвостовой позиции», то генератор будет эффективным. В примере ниже рекурсивный вызов _range к самому себе находится в хвостовой позиции. Пример демонстрирует три продвинутых темы: хвостовую рекурсию, создание генераторов и подфункции.

input

Выводит один новый вход.

Обратите внимание, что при использовании input обычно необходимо вызвать jq с опцией командной строки -n, в противном случае первое значение будет потеряно.

echo 1 2 3 4 | jq '[., input]' # [1,2] [3,4]

inputs

Выводит все оставшиеся входы по одному.

Это в первую очередь полезно для редукций над входами программы. Обратите внимание, что при использовании inputs обычно необходимо вызвать jq с опцией командной строки -n, в противном случае первое значение будет потеряно.

echo 1 2 3 | jq -n 'reduce inputs as $i (0; . + $i)' # 6

debug, debug(msgs)

Эти два фильтра подобны ., но имеют побочное действие — вывод одного или нескольких сообщений в stderr.

Сообщение, выводимое фильтром debug, имеет вид

["DEBUG:",<input-value>]

где <input-value> — компактное представление входного значения. Этот формат может быть изменён в будущем.

Фильтр debug(msgs) определён как (msgs | debug | empty), ., что обеспечивает большую гибкость в содержании сообщения, а также позволяет создавать многострочные отладочные утверждения.

Например, выражение:

1 as $x | 2 | debug("Entering function foo with $x == \($x)", .) | (.+1)

выведет значение 3, но с двумя следующими строками в stderr:

["DEBUG:","Entering function foo with $x == 1"]
["DEBUG:",2]

stderr

Выводит свой вход в сыром и компактном формате в stderr без дополнительного форматирования, даже без новой строки.

input_filename

Возвращает имя файла, вход которого в данный момент фильтруется. Обратите внимание, что это не будет работать должным образом, если jq не запущен в локале UTF-8.

input_line_number

Возвращает номер строки текущего входного значения.

truncate_stream(stream_expression)

Принимает число в качестве входных данных и обрезает соответствующее количество элементов пути слева из выходных данных заданного потокового выражения.

fromstream(stream_expression)

Выводит значения, соответствующие выходным данным потокового выражения.

tostream

Встроенная функция tostream выводит потоковую форму своего входного значения.

Операция обновления: |=

Это оператор "обновления" |=. Он принимает фильтр в правой части и вычисляет новое значение для свойства ., которому присваивается значение, пропуская старое значение через это выражение. Например, (.foo, .bar) |= .+1 создаст объект со свойством foo , установленным в значение foo входных данных плюс 1, и свойством bar , установленным в значение bar входных данных плюс 1.

Левая часть может быть любым общим выражением пути; см. path().

Обратите внимание, что левая часть |= ссылается на значение в .. Таким образом $var.foo |= . + 1 не будет работать как ожидается ($var.foo не является допустимым или полезным выражением пути в .); используйте $var | .foo |= . + 1 вместо этого.

Если правая часть не выводит никаких значений (т.е., empty), то путь в левой части будет удалён, как в del(path).

Если правая часть выводит несколько значений, будет использовано только первое (ПРИМЕЧАНИЕ ПО СОГЛАСОВАНИЮ: в jq 1.5 и более ранних версиях использовалось только последнее).

Арифметическое присвоение с обновлением: +=, -=, *=, /=, %=, //=

В jq есть несколько операторов вида a op= b, которые все эквивалентны a |= . op b. Таким образом, += 1 можно использовать для увеличения значений, что эквивалентно |= . + 1.

Простое присвоение: =

Это оператор простого присвоения. В отличие от других, входные данные для правой части (RHS) такие же, как и входные данные для левой части (LHS), а не значение по пути LHS, и все значения, выведенные RHS, будут использованы (как показано ниже).

Если RHS = генерирует несколько значений, то для каждого такого значения jq установит пути в левой части в значение, а затем выведет изменённые .. Например, (.a,.b) = range(2) выводит {"a":0,"b":0}, а затем {"a":1,"b":1}. Операции присвоения с обновлением (см. выше) этого не делают.

Этот пример должен продемонстрировать разницу между = и |=:

Предоставьте входные данные {"a": {"b": 10}, "b": 20} программам

.a = .b

и

.a |= .b

В первом случае значение поля a входных данных будет установлено в значение поля b входных данных, и будет выведен результат {"a": 20, "b": 20}. Во втором случае значение поля a входных данных будет установлено в значение поля a входных данных, а именно в поле b , и будет выведен результат {"a": 10, "b": 20}.

Сложные присваивания

В jq допускается гораздо больше элементов в левой части оператора присваивания, чем в большинстве языков. Мы уже видели простые обращения к полям в левой части, и нет ничего удивительного в том, что обращение к элементам массива работает также:

.posts[0].title = "JQ Manual"

Что может удивить, так это то, что выражение слева может дать несколько результатов, относящихся к различным точкам входного документа:

.posts[].comments |= . + ["this is great"]

В данном примере к массиву "comments" каждого поста во входных данных (где входные данные — это объект со свойством "posts", которое представляет собой массив постов) добавляется строка "this is great".

Когда jq сталкивается с присваиванием типа 'a = b', оно записывает "путь", пройденный для выбора части входного документа при выполнении a. Этот путь затем используется для нахождения части входных данных, которую нужно изменить при выполнении присваивания. Любой фильтр может быть использован в левой части знака равенства — все пути, которые он выбирает из входных данных, будут использованы для выполнения присваивания.

Это очень мощная операция. Предположим, мы хотим добавить комментарий к записям блога, используя те же входные данные "blog", что и выше. На этот раз мы хотим добавить комментарий только к записям, написанным "stedolan". Мы можем найти эти записи с помощью функции "select", описанной ранее:

.posts[] | select(.author == "stedolan")

Пути, предоставленные этой операцией, указывают на каждую запись, написанную "stedolan", и мы можем добавить комментарии к каждой из них таким же образом, как и раньше:

(.posts[] | select(.author == "stedolan") | .comments) |=
    . + ["terrible."]

import RelativePathString as NAME [<metadata>];

Импортирует модуль, найденный по заданному пути относительно каталога в пути поиска. К строке относительного пути будет добавлен суффикс .jq. Символы модуля будут иметь префикс NAME::.

Необязательные метаданные должны быть выражением jq константы. Это должно быть объект с ключами, такими как homepage и т. д. В настоящее время jq использует только ключ/значение search метаданных. Метаданные также доступны пользователям через встроенную функцию modulemeta.

Ключ search в метаданных, если он присутствует, должен иметь строковое или массивно-строковое значение (массив строк); это путь поиска, который будет добавлен к верхнему уровню пути поиска.

include RelativePathString [<metadata>];

Импортирует модуль, найденный по заданному пути относительно каталога в пути поиска, как если бы он был включен на месте. К строке относительного пути будет добавлен суффикс .jq . Символы модуля импортируются в пространство имен вызывающего модуля так, как если бы содержимое модуля было включено непосредственно.

Необязательные метаданные должны быть выражением jq константы. Это должен быть объект с ключами, такими как homepage и т. д. В настоящее время jq использует только ключ/значение search метаданных. Метаданные также доступны пользователям через встроенную функцию modulemeta.

import RelativePathString as $NAME [<metadata>];

Импортирует JSON-файл, найденный по заданному пути относительно каталога в пути поиска. К строке относительного пути будет добавлен суффикс .json . Данные файла будут доступны как $NAME::NAME.

Необязательные метаданные должны быть выражением jq константы. Это должен быть объект с ключами, такими как homepage и т. д. В настоящее время jq использует только ключ/значение search метаданных. Метаданные также доступны пользователям через встроенную функцию modulemeta.

Ключ search в метаданных, если он присутствует, должен иметь строковое или массивно-строковое значение (массив строк); это путь поиска, который будет добавлен к верхнему уровню пути поиска.

module <metadata>;

Эта директива полностью необязательна. Она не требуется для правильной работы. Она служит только для предоставления метаданных, которые можно прочитать с помощью встроенной функции modulemeta.

Метаданные должны быть выражением jq константы. Это должен быть объект с ключами, такими как homepage. В настоящее время jq не использует эти метаданные, но они доступны пользователям через встроенную функцию modulemeta.

modulemeta

Принимает имя модуля в качестве входных данных и выводит метаданные модуля как объект, при этом импорты модуля (включая метаданные) — это значение массива для ключа deps, а определенные функции модуля — это значение массива для ключа defs.

Программы могут использовать это для запроса метаданных модуля, которые затем можно использовать для, например, поиска, скачивания и установки отсутствующих зависимостей.