From e045af5d9c9106594bc2a5f609b14dbc603f7253 Mon Sep 17 00:00:00 2001 From: Andreas Hochsteger Date: Thu, 29 Dec 2022 23:01:05 +0100 Subject: Add coll.JQ using gojq library (#1585) * feat: add coll.JQ using gojq library * fix: jq function naming (gojq -> jq) * test: add tests (take from jsonpath_test.go) * chore: add TODO for nil values (are they allowed?) * refactor: use fmt.Errorf instead of errors.Wrapf Co-authored-by: Dave Henderson * fix: wrong alias for coll.JQ Co-authored-by: Dave Henderson * docs: add links to JQ Co-authored-by: Dave Henderson * test: add assertions after json marshal/unmarshal Co-authored-by: Dave Henderson * refactor: use fmt.Errorf instead of errors.Wrapf Co-authored-by: Dave Henderson * fix: test syntax and null handling * docs: improve documentation * docs: add blank line * Support cancellation Signed-off-by: Dave Henderson * Support (almost) all types, not just map[string]interface{} and []interface{} Signed-off-by: Dave Henderson * add an integration test for coll.JQ Signed-off-by: Dave Henderson Signed-off-by: Dave Henderson Co-authored-by: Andreas Hochsteger Co-authored-by: Dave Henderson --- docs/content/functions/coll.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) (limited to 'docs') diff --git a/docs/content/functions/coll.md b/docs/content/functions/coll.md index e441da9b..55f2b9cf 100644 --- a/docs/content/functions/coll.md +++ b/docs/content/functions/coll.md @@ -200,6 +200,48 @@ $ gomplate -i '{{ .books | jsonpath `$..works[?( @.edition_count > 400 )].title` [Alice's Adventures in Wonderland Gulliver's Travels] ``` +## `coll.JQ` + +**Alias:** `jq` + +Filters an input object or list using the [jq](https://stedolan.github.io/jq/) language, as implemented by [gojq](https://github.com/itchyny/gojq). + +Any JSON datatype may be used as input (NOTE: strings are not JSON-parsed but passed in as is). +If the expression results in multiple items (no matter if streamed or as an array) they are wrapped in an array. +Otherwise a single item is returned (even if resulting in an array with a single contained element). + +JQ filter expressions can be tested at https://jqplay.org/ + +See also: + +- [jq manual](https://stedolan.github.io/jq/manual/) +- [gojq differences to jq](https://github.com/itchyny/gojq#difference-to-jq) + +### Usage + +```go +coll.JQ expression in +``` +```go +in | coll.JQ expression +``` + +### Arguments + +| name | description | +|------|-------------| +| `expression` | _(required)_ The JQ expression | +| `in` | _(required)_ The object or list to query | + +### Examples + +```console +$ gomplate \ + -i '{{ .books | jq `[.works[]|{"title":.title,"authors":[.authors[].name],"published":.first_publish_year}][0]` }}' \ + -c books=https://openlibrary.org/subjects/fantasy.json +map[authors:[Lewis Carroll] published:1865 title:Alice's Adventures in Wonderland] +``` + ## `coll.Keys` **Alias:** `keys` -- cgit v1.2.3