jq-extra-utils v1.1.0
🧰 jq-extra-utils
This is a module containing some useful filters and functions for use in jq scripts. It aims to fill gaps in the built-in library, speed up development and make scripts more expressive.
Features
- Equivalents of
contains
andinside
that behave as usually expected - Useful functions that are missing from the built-ins:
repeat
,find
,find_index
,array_xor
, etc. - Convenient aliases of common operations for more expressive scripts:
filter
,array_last
, etc. - Thoroughly tested
Installation
Obviously, you need to install jq
first.
Install this module with npm:
npm i jq-extra-utils
Or directly download the contents of the file:
curl https://raw.githubusercontent.com/cheap-glitch/jq-extra-utils/main/src/utils.jq > utils.jq
Usage
To use in your scripts, indicate the path of the directory containing the module
with the -L
option and import it with include
(without the extension):
jq -L path/to/module/dir 'include "utils"; repeat_str(13) + "Batman!"' <<< '"Na "'
> "Na Na Na Na Na Na Na Na Na Na Na Na Na Batman!"
You can also place the file at ~/.jq
to have it automatically loaded when
running jq
on the command-line.
Read more about importing modules in the manual.
API
array_last
Returns the last element of an array.
[1, 2, 3] | array_last
> 3
repeat(n)
Returns an array containing the input repeated n
times.
[] | repeat(3)
> [[], [], []]
repeat_str(n)
Returns a string made of the input repeated n
times.
"words" | repeat_str(3)
> "wordswordswords"
includes(needle)
Returns true
if the array contains the exact needle, false
otherwise.
Takes the needle as argument.
[1, 2, 3] | includes(3)
> true
Note: this is not the same as the built-in
contains
function. It checks for strict equality between the needle and every element just likeArray.includes
in JavaScript does, whereascontains
checks if each element contains the needle, which can give surprising results when using strings or nested arrays:jq '["bar", "baz", "foobar"] | contains(["foo"])' > true
included_in(array)
Returns true
if the array contains the exact needle, false
otherwise.
Takes the array as argument.
"3" | included_in([1, 2, 3])
> false
filter(sieve)
Filters the array.
["foo", "bar", "foobar"] | filter(length <= 3)
> ["foo", "bar"]
filter_obj(sieve)
Filters the object.
{ "foo": "foo", "bar": 2 } | filter_obj(.key != .value)
> { "bar": 2 }
find(condition)
Returns the first element in the array to satisfy the condition, or null
if there is none.
["a", 2, false, "b", true] | find(type == "string")
> "a"
rfind(condition)
Returns the last element in the array to satisfy the condition, or null
if there is none.
["a", 2, false, "b", true] | rfind(type == "string")
> "b"
find_index(condition)
Returns the index of the first element in the array to satisfy the condition, or null
if there is none.
["a", 2, false, "b", true] | find_index(type == "string")
> 0
rfind_index(condition)
Returns the index of the last element in the array to satisfy the condition, or null
if there is none.
["a", 2, false, "b", true] | rfind_index(type == "string")
> 0
arrays_and(first; second)
Returns the intersection of the two arrays passed as arguments.
arrays_and([1, "a", true], ["b", 1, false, 1])
> [1]
arrays_xor(first; second)
Returns an array containing the elements that are exclusive to both arrays passed as arguments.
arrays_xor([1, "a", true], ["b", 1, false, 1])
> [false, true, "a", "b"]
zip
Takes an array of arrays and zip them together.
[[1, 2, 3], [], ["a", "b"]] | zip
> [[1, null, "a"], [2, null, "b"], [3, null, null]]
zip_with(array)
Zip two arrays together.
["a", "b"] | zip_with([true, false, true])
> [["a", true], ["b", false]]
Changelog
See the full changelog here.
Contributing
Contributions are welcomed! Please open an issue before proposing any significant changes.
Related
- https://stedolan.github.io/jq/manual - The official
jq
manual
License
ISC