- title: Basic filters
entries:
- - title: "`.`"
+ - title: "Identity: `.`"
body: |
- The absolute simplest (and least interesting) filter
- is `.`. This is a filter that takes its input and
- produces it unchanged as output.
+ The absolute simplest filter is `.` . This is a filter that
+ takes its input and produces it unchanged as output. That is,
+ this is the identity operator.
Since jq by default pretty-prints all output, this trivial
program can be a useful way of formatting JSON output from,
input: '"Hello, world!"'
output: ['"Hello, world!"']
- - title: "`.foo`, `.foo.bar`"
+ - title: "Object Identifier-Index: `.foo`, `.foo.bar`"
body: |
The simplest *useful* filter is `.foo`. When given a
JSON object (aka dictionary or hash) as input, it produces
the value at the key "foo", or null if there's none present.
+ A filter of the form `.foo.bar` is equivalent to `.foo|.bar`.
+
+ This syntax only works for simple, identifier-like keys, that
+ is, keys that are all made of alphanumeric characters and
+ underscore, and which do not start with a digit.
+
If the key contains special characters, you need to surround
- it with double quotes like this: `."foo$"`.
+ it with double quotes like this: `."foo$"`, or else `.["foo$"]`.
- A filter of the form `.foo.bar` is equivalent to `.foo|.bar`.
+ For example `.["foo::bar"]` and `.["foo.bar"]` work while
+ `.foo::bar` does not, and `.foo.bar` means `.["foo"].["bar"]`.
examples:
- program: '.foo'
input: '{"foo": 42}'
output: [42]
- - title: "`.foo?`"
+ - title: "Optional Object Identifier-Index: `.foo?`"
body: |
Just like `.foo`, but does not output even an error when `.`
input: '[1,2]'
output: ['[]']
- - title: "`.[<string>]`, `.[2]`, `.[10:15]`"
+ - title: "Generic Object Index: `.[<string>]`"
body: |
You can also look up fields of an object using syntax like
- `.["foo"]` (.foo above is a shorthand version of this). This
- one works for arrays as well, if the key is an
- integer. Arrays are zero-based (like javascript), so `.[2]`
- returns the third element of the array.
+ `.["foo"]` (.foo above is a shorthand version of this, but
+ only for identifier-like strings).
- The `.[10:15]` syntax can be used to return a subarray of an
- array or substring of a string. The array returned by
- `.[10:15]` will be of length 5, containing the elements from
- index 10 (inclusive) to index 15 (exclusive). Either index may
- be negative (in which case it counts backwards from the end of
- the array), or omitted (in which case it refers to the start
- or end of the array).
+ - title: "Array Index: `.[2]`"
+ body: |
- The `.[2]` syntax can be used to return the element at the
- given index. Negative indices are allowed, with -1 referring
- to the last element, -2 referring to the next to last element,
- and so on.
+ When the index value is an integer, `.[<value>]` can index
+ arrays. Arrays are zero-based, so `.[2]` returns the third
+ element.
- The `.foo` syntax only works for simply keys i.e. keys that
- are all alphanumeric characters. `.[<string>]` works with
- keys that contain special characters such as colons and dots.
- For example `.["foo::bar"]` and `.["foo.bar"]` work while
- `.foo::bar` and `.foo.bar` would not.
-
- The `?` "operator" can also be used with the slice operator,
- as in `.[10:15]?`, which outputs values where the inputs are
- slice-able.
+ Negative indices are allowed, with -1 referring to the last
+ element, -2 referring to the next to last element, and so on.
examples:
- program: '.[0]'
input: '[{"name":"JSON", "good":true}, {"name":"XML", "good":false}]'
output: ['null']
+ - program: '.[-2]'
+ input: '[1,2,3]'
+ output: ['2']
+
+ - title: "Array/String Slice: `.[10:15]`"
+ body: |
+
+ The `.[10:15]` syntax can be used to return a subarray of an
+ array or substring of a string. The array returned by
+ `.[10:15]` will be of length 5, containing the elements from
+ index 10 (inclusive) to index 15 (exclusive). Either index may
+ be negative (in which case it counts backwards from the end of
+ the array), or omitted (in which case it refers to the start
+ or end of the array).
+
+ examples:
- program: '.[2:4]'
input: '["a","b","c","d","e"]'
output: ['["c", "d"]']
input: '["a","b","c","d","e"]'
output: ['["d", "e"]']
- - program: '.[-2]'
- input: '[1,2,3]'
- output: ['2']
-
- - title: "`.[]`"
+ - title: "Array/Object Value Iterator: `.[]`"
body: |
If you use the `.[index]` syntax, but omit the index
Like `.[]`, but no errors will be output if . is not an array
or object.
- - title: "`,`"
+ - title: "Comma: `,`"
body: |
If two filters are separated by a comma, then the
- input will be fed into both and there will be multiple
- outputs: first, all of the outputs produced by the left
- expression, and then all of the outputs produced by the
- right. For instance, filter `.foo, .bar`, produces
- both the "foo" fields and "bar" fields as separate outputs.
+ same input will be fed into both and the two filters' output
+ value streams will be concatenated in order: first, all of the
+ outputs produced by the left expression, and then all of the
+ outputs produced by the right. For instance, filter `.foo,
+ .bar`, produces both the "foo" fields and "bar" fields as
+ separate outputs.
examples:
- program: '.foo, .bar'
input: '["a","b","c","d","e"]'
output: ['"e"', '"c"']
- - title: "`|`"
+ - title: "Pipe: `|`"
body: |
The | operator combines two filters by feeding the output(s) of
instead.
entries:
- - title: Array construction - `[]`
+ - title: "Array construction: `[]`"
body: |
As in JSON, `[]` is used to construct arrays, as in
- program: "[.user, .projects[]]"
input: '{"user":"stedolan", "projects": ["jq", "wikiflow"]}'
output: ['["stedolan", "jq", "wikiflow"]']
- - title: Objects - `{}`
+ - title: "Object Construction: `{}`"
body: |
Like JSON, `{}` is for constructing objects (aka
dictionaries or hashes), as in: `{"a": 42, "b": 17}`.
- If the keys are "sensible" (all alphabetic characters), then
- the quotes can be left off. The value can be any expression
- (although you may need to wrap it in parentheses if it's a
- complicated one), which gets applied to the {} expression's
- input (remember, all filters have an input and an
- output).
+ If the keys are "identifier-like", then the quotes can be left
+ off, as in `{a:42, b:17}. Keys generated by expressions need
+ to be parenthesized, e.g., `{("a"+"b"):59}`.
+
+ The value can be any expression (although you may need to
+ wrap it in parentheses if it's a complicated one), which gets
+ applied to the {} expression's input (remember, all filters
+ have an input and an output).
{foo: .bar}
will produce the JSON object `{"foo": 42}` if given the JSON
- object `{"bar":42, "baz":43}`. You can use this to select
- particular fields of an object: if the input is an object
- with "user", "title", "id", and "content" fields and you
- just want "user" and "title", you can write
+ object `{"bar":42, "baz":43}` as its input. You can use this
+ to select particular fields of an object: if the input is an
+ object with "user", "title", "id", and "content" fields and
+ you just want "user" and "title", you can write
{user: .user, title: .title}
- Because that's so common, there's a shortcut syntax: `{user, title}`.
+ Because that is so common, there's a shortcut syntax for it:
+ `{user, title}`.
If one of the expressions produces multiple results,
multiple dictionaries will be produced. If the input's
input: '{"user":"stedolan","titles":["JQ Primer", "More JQ"]}'
output: ['{"stedolan": ["JQ Primer", "More JQ"]}']
+ - title: "Recursive Descent: `..`"
+ body: |
+
+ Recursively descends `.`, producing every value. This is the
+ same as the zero-argument `recurse` builtin (see below). This
+ is intended to resemble the XPath `//` operator. Note that
+ `..a` does not work; use `..|.a` instead. In the example
+ below we use `..|.a?` to find all the values of object keys
+ "a" in any object found "below" `.`.
+
+ This is particularly useful in conjunction with `path(EXP)`
+ (also see below) and the `?` operator.
+
+ examples:
+ - program: '..|.a?'
+ input: '[[{"a":1}]]'
+ output: ['1']
+
- title: Builtin operators and functions
body: |
no result.
entries:
- - title: Addition - `+`
+ - title: "Addition: `+`"
body: |
The operator `+` takes two filters, applies them both
input: 'null'
output: ['{"a": 42, "b": 2, "c": 3}']
- - title: Subtraction - `-`
+ - title: "Subtraction: `-`"
body: |
As well as normal arithmetic subtraction on numbers, the `-`
input: '["xml", "yaml", "json"]'
output: ['["json"]']
- - title: Multiplication, division, modulo - `*`, `/`, and `%`
+ - title: "Multiplication, division, modulo: `*`, `/`, and `%`"
body: |
These infix operators behave as expected when given two numbers.
output:
- '[{"a":{"b":2}}]'
-
- - title: "`..`"
- body: |
-
- Short-hand for `recurse` without arguments. This is intended
- to resemble the XPath `//` operator. Note that `..a` does not
- work; use `..|a` instead. In the example below we use
- `..|.a?` to find all the values of object keys "a" in any
- object found "below" `.`.
-
- examples:
- - program: '..|.a?'
- input: '[[{"a":1}]]'
- output: ['1']
-
- title: "`env`"
body: |
input: 'null'
output: ['[false, true]']
- - title: Alternative operator - `//`
+ - title: "Alternative operator: `//`"
body: |
A filter of the form `a // b` produces the same
because no label `$out` is visible.
- - title: "`?` operator"
+ - title: "Error Suppresion / Optional Operator: `?`"
body: |
The `?` operator, used as `EXP?`, is shorthand for `try EXP`.
Finally, there is a module/library system.
entries:
- - title: Variables
+ - title: "Variable / Symbolic Binding Operator: `... as $identifier | ...`"
body: |
In jq, all filters have an input and an output, so manual
.
.SH "BASIC FILTERS"
.
-.SS "\."
-The absolute simplest (and least interesting) filter is \fB\.\fR\. This is a filter that takes its input and produces it unchanged as output\.
+.SS "Identity: \."
+The absolute simplest filter is \fB\.\fR \. This is a filter that takes its input and produces it unchanged as output\. That is, this is the identity operator\.
.
.P
Since jq by default pretty\-prints all output, this trivial program can be a useful way of formatting JSON output from, say, \fBcurl\fR\.
.
.IP "" 0
.
-.SS "\.foo, \.foo\.bar"
+.SS "Object Identifier\-Index: \.foo, \.foo\.bar"
The simplest \fIuseful\fR filter is \fB\.foo\fR\. When given a JSON object (aka dictionary or hash) as input, it produces the value at the key "foo", or null if there\'s none present\.
.
.P
-If the key contains special characters, you need to surround it with double quotes like this: \fB\."foo$"\fR\.
+A filter of the form \fB\.foo\.bar\fR is equivalent to \fB\.foo|\.bar\fR\.
.
.P
-A filter of the form \fB\.foo\.bar\fR is equivalent to \fB\.foo|\.bar\fR\.
+This syntax only works for simple, identifier\-like keys, that is, keys that are all made of alphanumeric characters and underscore, and which do not start with a digit\.
+.
+.P
+If the key contains special characters, you need to surround it with double quotes like this: \fB\."foo$"\fR, or else \fB\.["foo$"]\fR\.
+.
+.P
+For example \fB\.["foo::bar"]\fR and \fB\.["foo\.bar"]\fR work while \fB\.foo::bar\fR does not, and \fB\.foo\.bar\fR means \fB\.["foo"]\.["bar"]\fR\.
.
.IP "" 4
.
.
.IP "" 0
.
-.SS "\.foo?"
+.SS "Optional Object Identifier\-Index: \.foo?"
Just like \fB\.foo\fR, but does not output even an error when \fB\.\fR is not an array or an object\.
.
.IP "" 4
.
.IP "" 0
.
-.SS "\.[<string>], \.[2], \.[10:15]"
-You can also look up fields of an object using syntax like \fB\.["foo"]\fR (\.foo above is a shorthand version of this)\. This one works for arrays as well, if the key is an integer\. Arrays are zero\-based (like javascript), so \fB\.[2]\fR returns the third element of the array\.
+.SS "Generic Object Index: \.[<string>]"
+You can also look up fields of an object using syntax like \fB\.["foo"]\fR (\.foo above is a shorthand version of this, but only for identifier\-like strings)\.
.
-.P
-The \fB\.[10:15]\fR syntax can be used to return a subarray of an array or substring of a string\. The array returned by \fB\.[10:15]\fR will be of length 5, containing the elements from index 10 (inclusive) to index 15 (exclusive)\. Either index may be negative (in which case it counts backwards from the end of the array), or omitted (in which case it refers to the start or end of the array)\.
+.SS "Array Index: \.[2]"
+When the index value is an integer, \fB\.[<value>]\fR can index arrays\. Arrays are zero\-based, so \fB\.[2]\fR returns the third element\.
.
.P
-The \fB\.[2]\fR syntax can be used to return the element at the given index\. Negative indices are allowed, with \-1 referring to the last element, \-2 referring to the next to last element, and so on\.
-.
-.P
-The \fB\.foo\fR syntax only works for simply keys i\.e\. keys that are all alphanumeric characters\. \fB\.[<string>]\fR works with keys that contain special characters such as colons and dots\. For example \fB\.["foo::bar"]\fR and \fB\.["foo\.bar"]\fR work while \fB\.foo::bar\fR and \fB\.foo\.bar\fR would not\.
-.
-.P
-The \fB?\fR "operator" can also be used with the slice operator, as in \fB\.[10:15]?\fR, which outputs values where the inputs are slice\-able\.
+Negative indices are allowed, with \-1 referring to the last element, \-2 referring to the next to last element, and so on\.
.
.IP "" 4
.
[{"name":"JSON", "good":true}, {"name":"XML", "good":false}]
=> null
+jq \'\.[\-2]\'
+ [1,2,3]
+=> 2
+.
+.fi
+.
+.IP "" 0
+.
+.SS "Array/String Slice: \.[10:15]"
+The \fB\.[10:15]\fR syntax can be used to return a subarray of an array or substring of a string\. The array returned by \fB\.[10:15]\fR will be of length 5, containing the elements from index 10 (inclusive) to index 15 (exclusive)\. Either index may be negative (in which case it counts backwards from the end of the array), or omitted (in which case it refers to the start or end of the array)\.
+.
+.IP "" 4
+.
+.nf
+
jq \'\.[2:4]\'
["a","b","c","d","e"]
=> ["c", "d"]
jq \'\.[\-2:]\'
["a","b","c","d","e"]
=> ["d", "e"]
-
-jq \'\.[\-2]\'
- [1,2,3]
-=> 2
.
.fi
.
.IP "" 0
.
-.SS "\.[]"
+.SS "Array/Object Value Iterator: \.[]"
If you use the \fB\.[index]\fR syntax, but omit the index entirely, it will return \fIall\fR of the elements of an array\. Running \fB\.[]\fR with the input \fB[1,2,3]\fR will produce the numbers as three separate results, rather than as a single array\.
.
.P
.SS "\.[]?"
Like \fB\.[]\fR, but no errors will be output if \. is not an array or object\.
.
-.SS ","
-If two filters are separated by a comma, then the input will be fed into both and there will be multiple outputs: first, all of the outputs produced by the left expression, and then all of the outputs produced by the right\. For instance, filter \fB\.foo, \.bar\fR, produces both the "foo" fields and "bar" fields as separate outputs\.
+.SS "Comma: ,"
+If two filters are separated by a comma, then the same input will be fed into both and the two filters\' output value streams will be concatenated in order: first, all of the outputs produced by the left expression, and then all of the outputs produced by the right\. For instance, filter \fB\.foo, \.bar\fR, produces both the "foo" fields and "bar" fields as separate outputs\.
.
.IP "" 4
.
.
.IP "" 0
.
-.SS "|"
+.SS "Pipe: |"
The | operator combines two filters by feeding the output(s) of the one on the left into the input of the one on the right\. It\'s pretty much the same as the Unix shell\'s pipe, if you\'re used to that\.
.
.P
.P
Booleans, null, strings and numbers are written the same way as in javascript\. Just like everything else in jq, these simple values take an input and produce an output \- \fB42\fR is a valid jq expression that takes an input, ignores it, and returns 42 instead\.
.
-.SS "Array construction \- []"
+.SS "Array construction: []"
As in JSON, \fB[]\fR is used to construct arrays, as in \fB[1,2,3]\fR\. The elements of the arrays can be any jq expression\. All of the results produced by all of the expressions are collected into one big array\. You can use it to construct an array out of a known quantity of values (as in \fB[\.foo, \.bar, \.baz]\fR) or to "collect" all the results of a filter into an array (as in \fB[\.items[]\.name]\fR)
.
.P
.
.IP "" 0
.
-.SS "Objects \- {}"
+.SS "Object Construction: {}"
Like JSON, \fB{}\fR is for constructing objects (aka dictionaries or hashes), as in: \fB{"a": 42, "b": 17}\fR\.
.
.P
-If the keys are "sensible" (all alphabetic characters), then the quotes can be left off\. The value can be any expression (although you may need to wrap it in parentheses if it\'s a complicated one), which gets applied to the {} expression\'s input (remember, all filters have an input and an output)\.
+If the keys are "identifier\-like", then the quotes can be left off, as in \fB{a:42, b:17}\. Keys generated by expressions need to be parenthesized, e\.g\.,\fR{("a"+"b"):59}`\.
+.
+.P
+The value can be any expression (although you may need to wrap it in parentheses if it\'s a complicated one), which gets applied to the {} expression\'s input (remember, all filters have an input and an output)\.
.
.IP "" 4
.
.IP "" 0
.
.P
-will produce the JSON object \fB{"foo": 42}\fR if given the JSON object \fB{"bar":42, "baz":43}\fR\. You can use this to select particular fields of an object: if the input is an object with "user", "title", "id", and "content" fields and you just want "user" and "title", you can write
+will produce the JSON object \fB{"foo": 42}\fR if given the JSON object \fB{"bar":42, "baz":43}\fR as its input\. You can use this to select particular fields of an object: if the input is an object with "user", "title", "id", and "content" fields and you just want "user" and "title", you can write
.
.IP "" 4
.
.IP "" 0
.
.P
-Because that\'s so common, there\'s a shortcut syntax: \fB{user, title}\fR\.
+Because that is so common, there\'s a shortcut syntax for it: \fB{user, title}\fR\.
.
.P
If one of the expressions produces multiple results, multiple dictionaries will be produced\. If the input\'s
.
.IP "" 0
.
+.SS "Recursive Descent: \.\."
+Recursively descends \fB\.\fR, producing every value\. This is the same as the zero\-argument \fBrecurse\fR builtin (see below)\. This is intended to resemble the XPath \fB//\fR operator\. Note that \fB\.\.a\fR does not work; use \fB\.\.|\.a\fR instead\. In the example below we use \fB\.\.|\.a?\fR to find all the values of object keys "a" in any object found "below" \fB\.\fR\.
+.
+.P
+This is particularly useful in conjunction with \fBpath(EXP)\fR (also see below) and the \fB?\fR operator\.
+.
+.IP "" 4
+.
+.nf
+
+jq \'\.\.|\.a?\'
+ [[{"a":1}]]
+=> 1
+.
+.fi
+.
+.IP "" 0
+.
.SH "BUILTIN OPERATORS AND FUNCTIONS"
Some jq operator (for instance, \fB+\fR) do different things depending on the type of their arguments (arrays, numbers, etc\.)\. However, jq never does implicit type conversions\. If you try to add a string to an object you\'ll get an error message and no result\.
.
-.SS "Addition \- +"
+.SS "Addition: +"
The operator \fB+\fR takes two filters, applies them both to the same input, and adds the results together\. What "adding" means depends on the types involved:
.
.IP "\(bu" 4
.
.IP "" 0
.
-.SS "Subtraction \- \-"
+.SS "Subtraction: \-"
As well as normal arithmetic subtraction on numbers, the \fB\-\fR operator can be used on arrays to remove all occurrences of the second array\'s elements from the first array\.
.
.IP "" 4
.
.IP "" 0
.
-.SS "Multiplication, division, modulo \- *, /, and %"
+.SS "Multiplication, division, modulo: *, /, and %"
These infix operators behave as expected when given two numbers\. Division by zero raises an error\. \fBx % y\fR computes x modulo y\.
.
.P
.
.IP "" 0
.
-.SS "\.\."
-Short\-hand for \fBrecurse\fR without arguments\. This is intended to resemble the XPath \fB//\fR operator\. Note that \fB\.\.a\fR does not work; use \fB\.\.|a\fR instead\. In the example below we use \fB\.\.|\.a?\fR to find all the values of object keys "a" in any object found "below" \fB\.\fR\.
-.
-.IP "" 4
-.
-.nf
-
-jq \'\.\.|\.a?\'
- [[{"a":1}]]
-=> 1
-.
-.fi
-.
-.IP "" 0
-.
.SS "env"
Outputs an object representing jq\'s environment\.
.
.IP
The input is converted to base64 as specified by RFC 4648\.
.
+.TP
+\fB@base64d\fR:
+.
+.IP
+The inverse of \fB@base64\fR, input is decoded as specified by RFC 4648\. Note: If the decoded string is not UTF\-8, the results are undefined\.
+.
.P
This syntax can be combined with string interpolation in a useful way\. You can follow a \fB@foo\fR token with a string literal\. The contents of the string literal will \fInot\fR be escaped\. However, all interpolations made inside that string literal will be escaped\. For instance,
.
jq \'@sh "echo \e(\.)"\'
"O\'Hara\'s Ale"
=> "echo \'O\'\e\e\'\'Hara\'\e\e\'\'s Ale\'"
+
+jq \'@base64\'
+ "This is a message"
+=> "VGhpcyBpcyBhIG1lc3NhZ2U="
+
+jq \'@base64d\'
+ "VGhpcyBpcyBhIG1lc3NhZ2U="
+=> "This is a message"
.
.fi
.
.IP
This builtin outputs \fBtrue\fR if any value in the source stream appears in the second stream, otherwise it outputs \fBfalse\fR\.
.
+.SS "builtins"
+Returns a list of all builtin functions in the format \fBname/arity\fR\. Since functions with the same name but different arities are considered separate functions, \fBall/0\fR, \fBall/1\fR, and \fBall/2\fR would all be present in the list\.
+.
.SH "CONDITIONALS AND COMPARISONS"
.
.SS "==, !="
.
.IP "" 0
.
-.SS "Alternative operator \- //"
+.SS "Alternative operator: //"
A filter of the form \fBa // b\fR produces the same results as \fBa\fR, if \fBa\fR produces results other than \fBfalse\fR and \fBnull\fR\. Otherwise, \fBa // b\fR produces the same results as \fBb\fR\.
.
.P
.P
because no label \fB$out\fR is visible\.
.
-.SS "? operator"
+.SS "Error Suppresion / Optional Operator: ?"
The \fB?\fR operator, used as \fBEXP?\fR, is shorthand for \fBtry EXP\fR\.
.
.IP "" 4
.P
Finally, there is a module/library system\.
.
-.SS "Variables"
+.SS "Variable / Symbolic Binding Operator: \.\.\. as $identifier | \.\.\."
In jq, all filters have an input and an output, so manual plumbing is not necessary to pass a value from one part of a program to the next\. Many expressions, for instance \fBa + b\fR, pass their input to two distinct subexpressions (here \fBa\fR and \fBb\fR are both passed the same input), so variables aren\'t usually necessary in order to use a value twice\.
.
.P
projects / jq / commitdiff