Руководство по jq 1.8

Тождественный фильтр: .

Самый простой фильтр — это . . Этот фильтр принимает входное значение и выдает его же в качестве результата. Иными словами, это оператор тождества.

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

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

1E1234567890 | .

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

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

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

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

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

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

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

Индекс объекта по идентификатору: .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 shell, если вы с ним знакомы.

Если левый фильтр выдает несколько результатов, правый будет запущен для каждого из них. Таким образом, выражение .[] | .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 возвращает длину значения различных типов:

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

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

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

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

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

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

utf8bytelength

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

keys, keys_unsorted

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

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

Если 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_values(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 в . в значение VALUE.

delpaths(PATHS)

Встроенная функция delpaths удаляет PATHS из .. 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, ненулевыми значениями и неитерируемыми значениями соответственно.

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(generator)

Фильтр add принимает на вход массив и выдаёт его элементы, сложенные вместе. В зависимости от типов элементов входного массива это может означать арифметическое суммирование, конкатенацию или объединение — правила такие же, как для оператора + (описанного выше).

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

add(generator) работает с указанным генератором, а не с входными данными.

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 разбирает входные данные как число. Она преобразует строки в правильном формате в соответствующие числа, оставляет числа без изменений и выдаёт ошибку для всех остальных входных данных.

toboolean

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

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)

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

trimstr(str)

Выводит входное значение, удалив заданную строку с обоих концов, если оно начинается или заканчивается ею.

trim, ltrim, rtrim

trim удаляет пробельные символы в начале и в конце.

ltrim удаляет только пробельные символы в начале (слева).

rtrim удаляет только пробельные символы в конце (справа).

К пробельным символам относятся обычные " ", "\n" "\t", "\r", а также все символы в базе данных символов Unicode, обладающие свойством пробельного символа. Обратите внимание, что определение пробельных символов может измениться в будущем.

explode

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

implode

Обратная функция для explode.

split(str)

Разбивает входную строку по аргументу-разделителю.

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

join(str)

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

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

ascii_downcase, ascii_upcase

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

while(cond; update)

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

Обратите внимание, что 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 обычно проверяет тип входных данных, как показано в следующих примерах. В первом примере показана полезность обработки элементов массива массивов до обработки самого массива. Во втором примере показано, как можно рассматривать для изменения все ключи всех объектов во входных данных.

have_literal_numbers

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

have_decnum

Эта встроенная функция возвращает true, если jq был собран с «decnum» — текущей реализацией числового серверного компонента jq, сохраняющей литералы.

$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. Если массив не отсортирован, 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.

• @urid:

Обратная операция для @uri: выполняет процентное декодирование, заменяя все последовательности %XX соответствующими символами URI.

• @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. Результат представлен в виде «разложенного времени», который принимает функция mktime и выводит функция gmtime.

Встроенная функция 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, если какое-либо значение исходного потока встречается во втором потоке; в противном случае она выводит false.

builtins

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

==, !=

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

!= означает «не равно», а '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. Они используют то же стандартное понятие истинности, что и выражения if: 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 определяется лексически: метка должна быть «видна» из точки прерывания.

Например, чтобы выйти из 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 или потоком таких строк, каждая из которых может содержать ссылки на именованные захваты. Именованные захваты фактически передаются в tostring в виде объекта JSON (созданного с помощью capture), поэтому ссылка на захваченную переменную с именем «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

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

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

{"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 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 и временную метку первого события для каждого ресурса. 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; expr)

Функция limit извлекает до n результатов из expr.

skip(n; expr)

Функция skip пропускает первые n результатов из expr.

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 входного значения получит значение поля b поля a, и результатом будет {"a": 10, "b": 20}.

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

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

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

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

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

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

Когда 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.

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