mirror of
https://github.com/stedolan/jq.git
synced 2024-05-11 05:55:39 +00:00
More docs + docs cleanup
This commit is contained in:
@@ -236,4 +236,6 @@ body:
|
|||||||
|
|
||||||
- - -
|
- - -
|
||||||
|
|
||||||
asdf
|
Here endeth the tutorial! There's lots more to play with, go
|
||||||
|
read [the manual](/manual) if you're interested, and [download
|
||||||
|
jq](/download) if you haven't already.
|
@@ -1,13 +1,40 @@
|
|||||||
headline: jq Manual
|
headline: jq Manual
|
||||||
|
body: |
|
||||||
|
|
||||||
|
A jq program is a "filter": it takes an input, and produces an
|
||||||
|
output. There are a lot of builtin filters for extracting a
|
||||||
|
particular field of an object, or converting a number to a string,
|
||||||
|
or various other standard tasks.
|
||||||
|
|
||||||
|
Filters can be combined in various ways - you can pipe the output of
|
||||||
|
one filter into another filter, or collect the output of a filter
|
||||||
|
into an array.
|
||||||
|
|
||||||
|
Some filters produce multiple results, for instance there's one that
|
||||||
|
produces all the elements of its input array. Piping that filter
|
||||||
|
into a second runs the second filter for each element of the
|
||||||
|
array. Generally, things that would be done with loops and iteration
|
||||||
|
in other languages are just done by gluing filters together in jq.
|
||||||
|
|
||||||
|
It's important to remember that every filter has an input and an
|
||||||
|
output. Even literals like "hello" or 42 are filters - they take an
|
||||||
|
input but always produce the same literal as output. Operations that
|
||||||
|
combine two filters, like addition, generally feed the same input to
|
||||||
|
both and combine the results. So, you can implement an averaging
|
||||||
|
filter as `add / length` - feeding the input array both to the `add`
|
||||||
|
filter and the `length` filter and dividing the results.
|
||||||
|
|
||||||
|
But that's getting ahead of ourselves. :) Let's start with something
|
||||||
|
simpler:
|
||||||
|
|
||||||
sections:
|
sections:
|
||||||
- title: Basics
|
- title: Basics
|
||||||
body: "{ some *intro* text \n\n\n}\n"
|
|
||||||
entries:
|
entries:
|
||||||
- title: "`.`"
|
- title: "`.`"
|
||||||
body: |
|
body: |
|
||||||
|
|
||||||
The absolute simplest (and least interesting) jq expression
|
The absolute simplest (and least interesting) filter
|
||||||
is `.`. This is a jq expression that takes its input and
|
is `.`. This is a filter that takes its input and
|
||||||
produces it unchanged as output.
|
produces it unchanged as output.
|
||||||
|
|
||||||
Since jq by default pretty-prints all output, this trivial
|
Since jq by default pretty-prints all output, this trivial
|
||||||
@@ -22,7 +49,7 @@ sections:
|
|||||||
- title: "`.foo`"
|
- title: "`.foo`"
|
||||||
body: |
|
body: |
|
||||||
|
|
||||||
The simplest *useful* jq expression is .foo. When given a
|
The simplest *useful* filter is .foo. When given a
|
||||||
JSON object (aka dictionary or hash) as input, it produces
|
JSON object (aka dictionary or hash) as input, it produces
|
||||||
the value at the key "foo", or null if there\'s none present.
|
the value at the key "foo", or null if there\'s none present.
|
||||||
|
|
||||||
@@ -75,11 +102,11 @@ sections:
|
|||||||
- title: "`,`"
|
- title: "`,`"
|
||||||
body: |
|
body: |
|
||||||
|
|
||||||
If two jq expressions are separated by a comma, then the
|
If two filters are separated by a comma, then the
|
||||||
input will be fed into both and there will be multiple
|
input will be fed into both and there will be multiple
|
||||||
outputs: first, all of the outputs produced by the left
|
outputs: first, all of the outputs produced by the left
|
||||||
expression, and then all of the outputs produced by the
|
expression, and then all of the outputs produced by the
|
||||||
right. For instance, jq expression `.foo, .bar`, produces
|
right. For instance, filter `.foo, .bar`, produces
|
||||||
both the "foo" fields and "bar" fields as separate outputs.
|
both the "foo" fields and "bar" fields as separate outputs.
|
||||||
|
|
||||||
examples:
|
examples:
|
||||||
@@ -97,7 +124,7 @@ sections:
|
|||||||
|
|
||||||
- title: "`|`"
|
- title: "`|`"
|
||||||
body: |
|
body: |
|
||||||
The | operator combines two jq expressions by feeding the output(s) of
|
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
|
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
|
pretty much the same as the Unix shell\'s pipe, if you\'re used to
|
||||||
that.
|
that.
|
||||||
@@ -135,7 +162,7 @@ sections:
|
|||||||
expressions are collected into one big array. You can use it
|
expressions are collected into one big array. You can use it
|
||||||
to construct an array out of a known quantity of values (as
|
to construct an array out of a known quantity of values (as
|
||||||
in `[.foo, .bar, .baz]`) or to "collect" all the results of a
|
in `[.foo, .bar, .baz]`) or to "collect" all the results of a
|
||||||
jq expression into an array (as in `[.items[].name]`)
|
filter into an array (as in `[.items[].name]`)
|
||||||
|
|
||||||
Once you understand the "," operator, you can look at jq\'s array
|
Once you understand the "," operator, you can look at jq\'s array
|
||||||
syntax in a different light: the expression [1,2,3] is not using a
|
syntax in a different light: the expression [1,2,3] is not using a
|
||||||
@@ -143,7 +170,7 @@ sections:
|
|||||||
the `[]` operator (collect results) to the expression 1,2,3 (which
|
the `[]` operator (collect results) to the expression 1,2,3 (which
|
||||||
produces three different results).
|
produces three different results).
|
||||||
|
|
||||||
If you have a jq expression `X` that produces four results,
|
If you have a filter `X` that produces four results,
|
||||||
then the expression `[X]` will produce a single result, an
|
then the expression `[X]` will produce a single result, an
|
||||||
array of four elements.
|
array of four elements.
|
||||||
|
|
||||||
@@ -161,7 +188,7 @@ sections:
|
|||||||
the quotes can be left off. The value can be any expression
|
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
|
(although you may need to wrap it in parentheses if it\'s a
|
||||||
complicated one), which gets applied to the {} expression\'s
|
complicated one), which gets applied to the {} expression\'s
|
||||||
input (remember, all jq expressions have an input and an
|
input (remember, all filters have an input and an
|
||||||
output).
|
output).
|
||||||
|
|
||||||
{foo: .bar}
|
{foo: .bar}
|
||||||
@@ -222,7 +249,7 @@ sections:
|
|||||||
- title: Addition - `+`
|
- title: Addition - `+`
|
||||||
body: |
|
body: |
|
||||||
|
|
||||||
The operator `+` takes two jq expressions, applies them both
|
The operator `+` takes two filters, applies them both
|
||||||
to the same input, and adds the results together. What
|
to the same input, and adds the results together. What
|
||||||
"adding" means depends on the types involved:
|
"adding" means depends on the types involved:
|
||||||
|
|
||||||
@@ -435,7 +462,7 @@ sections:
|
|||||||
- title: Alternative operator - `//`
|
- title: Alternative operator - `//`
|
||||||
body: |
|
body: |
|
||||||
|
|
||||||
A jq expression of the form `a // b` produces the same
|
A filter of the form `a // b` produces the same
|
||||||
results as `a`, if `a` produces results other than `false`
|
results as `a`, if `a` produces results other than `false`
|
||||||
and `null`. Otherwise, `a // b` produces the same results as `b`.
|
and `null`. Otherwise, `a // b` produces the same results as `b`.
|
||||||
|
|
||||||
@@ -474,7 +501,7 @@ sections:
|
|||||||
- title: Variables
|
- title: Variables
|
||||||
body: |
|
body: |
|
||||||
|
|
||||||
In jq, all jq expressions have an input and an output, so manual
|
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
|
plumbing is not necessary to pass a value from one part of a program
|
||||||
to the next. Many expressions, for instance `a + b`, pass their input
|
to the next. Many expressions, for instance `a + b`, pass their input
|
||||||
to two distinct subexpressions (here `a` and `b` are both passed the
|
to two distinct subexpressions (here `a` and `b` are both passed the
|
||||||
@@ -520,9 +547,9 @@ sections:
|
|||||||
|
|
||||||
.realnames as $names | .posts[] | {title, author: $names[.author]}
|
.realnames as $names | .posts[] | {title, author: $names[.author]}
|
||||||
|
|
||||||
The expression "asdf as $x" runs asdf, puts the result in $x, and
|
The expression "foo as $x" runs foo, puts the result in $x,
|
||||||
returns the original input. Apart from the side-effect of binding the
|
and returns the original input. Apart from the side-effect
|
||||||
variable, it has the same effect as ".".
|
of binding the variable, it has the same effect as ".".
|
||||||
|
|
||||||
Variables are scoped over the rest of the expression that defines
|
Variables are scoped over the rest of the expression that defines
|
||||||
them, so
|
them, so
|
||||||
@@ -543,7 +570,7 @@ sections:
|
|||||||
- title: 'Defining Functions'
|
- title: 'Defining Functions'
|
||||||
body: |
|
body: |
|
||||||
|
|
||||||
You can give a jq expression a name using "def" syntax:
|
You can give a filter a name using "def" syntax:
|
||||||
|
|
||||||
def increment: . + 1;
|
def increment: . + 1;
|
||||||
|
|
||||||
@@ -553,7 +580,7 @@ sections:
|
|||||||
|
|
||||||
def map(f): [.[] | f];
|
def map(f): [.[] | f];
|
||||||
|
|
||||||
Arguments are passed as jq expressions, not as values. The
|
Arguments are passed as filters, not as values. The
|
||||||
same argument may be referenced multiple times with
|
same argument may be referenced multiple times with
|
||||||
different inputs (here `f` is run for each element of the
|
different inputs (here `f` is run for each element of the
|
||||||
input array). Arguments to a function work more like
|
input array). Arguments to a function work more like
|
||||||
@@ -597,7 +624,7 @@ sections:
|
|||||||
- title: "`=`"
|
- title: "`=`"
|
||||||
body: |
|
body: |
|
||||||
|
|
||||||
The jq expression `.foo = 1` will take as input an object
|
The filter `.foo = 1` will take as input an object
|
||||||
and produce as output an object with the "foo" field set to
|
and produce as output an object with the "foo" field set to
|
||||||
1. There is no notion of "modifying" or "changing" something
|
1. There is no notion of "modifying" or "changing" something
|
||||||
in jq - all jq values are immutable. For instance,
|
in jq - all jq values are immutable. For instance,
|
||||||
@@ -621,7 +648,7 @@ sections:
|
|||||||
- title: "`|=`"
|
- title: "`|=`"
|
||||||
body: |
|
body: |
|
||||||
As well as the assignment operator '=', jq provides the "update"
|
As well as the assignment operator '=', jq provides the "update"
|
||||||
operator '|=', which takes a jq expression on the right-hand side and
|
operator '|=', which takes a filter on the right-hand side and
|
||||||
works out the new value for the property being assigned to by running
|
works out the new value for the property being assigned to by running
|
||||||
the old value through this expression. For instance, .foo |= .+1 will
|
the old value through this expression. For instance, .foo |= .+1 will
|
||||||
build an object with the "foo" field set to the input's "foo" plus 1.
|
build an object with the "foo" field set to the input's "foo" plus 1.
|
||||||
@@ -670,7 +697,7 @@ sections:
|
|||||||
When jq encounters an assignment like 'a = b', it records the "path"
|
When jq encounters an assignment like 'a = b', it records the "path"
|
||||||
taken to select a part of the input document while executing a. This
|
taken to select a part of the input document while executing a. This
|
||||||
path is then used to find which part of the input to change while
|
path is then used to find which part of the input to change while
|
||||||
executing the assignment. Any jq expression may be used on the
|
executing the assignment. Any filter may be used on the
|
||||||
left-hand side of an equals - whichever paths it selects from the
|
left-hand side of an equals - whichever paths it selects from the
|
||||||
input will be where the assignment is performed.
|
input will be where the assignment is performed.
|
||||||
|
|
||||||
|
@@ -2,11 +2,26 @@ headline: jq
|
|||||||
|
|
||||||
blurb: |
|
blurb: |
|
||||||
|
|
||||||
jq is a command-line JSON processor.
|
jq is a lightweight and flexible command-line JSON processor.
|
||||||
|
|
||||||
body: |
|
body1: |
|
||||||
|
|
||||||
|
jq is like `sed` for JSON data - you can use it to slice and filter
|
||||||
|
and map and transform structured data with the same ease that `sed`,
|
||||||
|
`awk`, `grep` and friends let you play with text.
|
||||||
|
|
||||||
|
body2: |
|
||||||
|
|
||||||
|
jq is written in portable C, and it has zero runtime
|
||||||
|
dependencies. You can download a single binary, `scp` it to a far away
|
||||||
|
machine, and expect it to work.
|
||||||
|
|
||||||
|
body3: |
|
||||||
|
|
||||||
|
jq can mangle the data format that you have into the one that you
|
||||||
|
want with very little effort, and the program to do so is often
|
||||||
|
shorter and simpler than you'd expect.
|
||||||
|
|
||||||
|
tail: |
|
||||||
Go read the [tutorial](/tutorial) for more, or the [manual](/manual)
|
Go read the [tutorial](/tutorial) for more, or the [manual](/manual)
|
||||||
for *way* more.
|
for *way* more.
|
@@ -59,13 +59,29 @@ section {
|
|||||||
|
|
||||||
|
|
||||||
#blurb {
|
#blurb {
|
||||||
padding-top: 20px;
|
padding-top: 40px;
|
||||||
|
padding-right: 50px;
|
||||||
}
|
}
|
||||||
|
|
||||||
#blurb p {
|
#blurb p {
|
||||||
font-size: 20pt;
|
font-size: 20pt;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
#blurb .btn-group {
|
||||||
|
margin-top: 20px;
|
||||||
|
}
|
||||||
|
|
||||||
|
#multiblurb {
|
||||||
|
line-height: 1.7;
|
||||||
|
text-align: center;
|
||||||
|
font-size: 12pt;
|
||||||
|
}
|
||||||
|
|
||||||
|
#multiblurb code {
|
||||||
|
border: 0;
|
||||||
|
font-size: 12pt;
|
||||||
|
}
|
||||||
|
|
||||||
h3 code {
|
h3 code {
|
||||||
border: 0;
|
border: 0;
|
||||||
font-size: 20px;
|
font-size: 20px;
|
||||||
|
11
docs/templates/index.liquid
vendored
11
docs/templates/index.liquid
vendored
@@ -27,10 +27,13 @@
|
|||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
<div class="row">
|
<div class="row" id="multiblurb">
|
||||||
|
<div class="span4">{{body1 | markdownify}}</div>
|
||||||
|
<div class="span4">{{body2 | markdownify}}</div>
|
||||||
{{body | markdownify}}
|
<div class="span4">{{body3 | markdownify}}</div>
|
||||||
|
</div>
|
||||||
|
<div class="row" style="text-align:center; margin-top: 30px">
|
||||||
|
{{tail | markdownify}}
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
{% include "shared/footer" %}
|
{% include "shared/footer" %}
|
||||||
|
1
docs/templates/manual.liquid
vendored
1
docs/templates/manual.liquid
vendored
@@ -46,6 +46,7 @@
|
|||||||
</div>
|
</div>
|
||||||
<div class="span9">
|
<div class="span9">
|
||||||
<h1>{{headline}}</h1>
|
<h1>{{headline}}</h1>
|
||||||
|
{{ body | markdownify }}
|
||||||
{% for section in sections %}
|
{% for section in sections %}
|
||||||
<section id="{{section.title | sanitize}}">
|
<section id="{{section.title | sanitize}}">
|
||||||
<h2>{{section.title}}</h2>
|
<h2>{{section.title}}</h2>
|
||||||
|
Reference in New Issue
Block a user