Skip to content

Commit 4705a22

Browse files
itchynyitchyny
authored
Reorder the command line options in the manual (jqlang#2766)
1 parent 8f49600 commit 4705a22

File tree

7 files changed

+358
-336
lines changed

7 files changed

+358
-336
lines changed

‎docs/content/manual/manual.yml

Lines changed: 89 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -104,74 +104,58 @@ sections:
104104
You can affect how jq reads and writes its input and output
105105
using some command-line options:
106106
107-
* `--version`/`-V`:
107+
* `--null-input` / `-n`:
108108
109-
Output the jq version and exit with zero.
110-
111-
* `--seq`:
112-
113-
Use the `application/json-seq` MIME type scheme for separating
114-
JSON texts in jq's input and output. This means that an ASCII
115-
RS (record separator) character is printed before each value on
116-
output and an ASCII LF (line feed) is printed after every
117-
output. Input JSON texts that fail to parse are ignored (but
118-
warned about), discarding all subsequent input until the next
119-
RS. This mode also parses the output of jq without the `--seq`
120-
option.
121-
122-
* `--stream`:
123-
124-
Parse the input in streaming fashion, outputting arrays of path
125-
and leaf values (scalars and empty arrays or empty objects).
126-
For example, `"a"` becomes `[[],"a"]`, and `[[],"a",["b"]]`
127-
becomes `[[0],[]]`, `[[1],"a"]`, and `[[2,0],"b"]`.
128-
129-
This is useful for processing very large inputs. Use this in
130-
conjunction with filtering and the `reduce` and `foreach` syntax
131-
to reduce large inputs incrementally.
132-
133-
* `--stream-errors`:
134-
135-
Like `--stream`, but invalid JSON inputs yield array values
136-
where the first element is the error and the second is a path.
137-
For example, `["a",n]` produces ["Invalid literal at line 1,
138-
column 9",[1]]`.
139-
140-
Implies `--stream`. Invalid JSON inputs produce no error values
141-
when `--stream` without `--stream-errors`.
142-
143-
* `--slurp`/`-s`:
144-
145-
Instead of running the filter for each JSON object in the
146-
input, read the entire input stream into a large array and run
147-
the filter just once.
109+
Don't read any input at all. Instead, the filter is run once
110+
using `null` as the input. This is useful when using jq as a
111+
simple calculator or to construct JSON data from scratch.
148112
149-
* `--raw-input`/`-R`:
113+
* `--raw-input` / `-R`:
150114
151115
Don't parse the input as JSON. Instead, each line of text is
152116
passed to the filter as a string. If combined with `--slurp`,
153117
then the entire input is passed to the filter as a single long
154118
string.
155119
156-
* `--null-input`/`-n`:
120+
* `--slurp` / `-s`:
157121
158-
Don't read any input at all! Instead, the filter is run once
159-
using `null` as the input. This is useful when using jq as a
160-
simple calculator or to construct JSON data from scratch.
122+
Instead of running the filter for each JSON object in the
123+
input, read the entire input stream into a large array and run
124+
the filter just once.
161125
162126
* `--compact-output` / `-c`:
163127
164128
By default, jq pretty-prints JSON output. Using this option
165129
will result in more compact output by instead putting each
166130
JSON object on a single line.
167131
168-
* `--tab`:
132+
* `--raw-output` / `-r`:
169133
170-
Use a tab for each indentation level instead of two spaces.
134+
With this option, if the filter's result is a string then it
135+
will be written directly to standard output rather than being
136+
formatted as a JSON string with quotes. This can be useful for
137+
making jq filters talk to non-JSON-based systems.
171138
172-
* `--indent n`:
139+
* `--join-output` / `-j`:
173140
174-
Use the given number of spaces (no more than 7) for indentation.
141+
Like `-r` but jq won't print a newline after each output.
142+
143+
* `--nul-output` / `-0`:
144+
145+
Like `-r` but jq will print NUL instead of newline after each output.
146+
This can be useful when the values being output can contain newlines.
147+
148+
* `--ascii-output` / `-a`:
149+
150+
jq usually outputs non-ASCII Unicode codepoints as UTF-8, even
151+
if the input specified them as escape sequences (like
152+
"\u03bc"). Using this option, you can force jq to produce pure
153+
ASCII output with every non-ASCII character replaced with the
154+
equivalent escape sequence.
155+
156+
* `--sort-keys` / `-S`:
157+
158+
Output the fields of each object with the keys in sorted order.
175159
176160
* `--color-output` / `-C` and `--monochrome-output` / `-M`:
177161
@@ -184,69 +168,63 @@ sections:
184168
Colors can be configured with the `JQ_COLORS` environment
185169
variable (see below).
186170
187-
* `--binary` / `-b`:
171+
* `--tab`:
188172
189-
Windows users using WSL, MSYS2, or Cygwin, should use this option
190-
when using a native jq.exe, otherwise jq will turn newlines (LFs)
191-
into carriage-return-then-newline (CRLF).
173+
Use a tab for each indentation level instead of two spaces.
192174
193-
* `--ascii-output` / `-a`:
175+
* `--indent n`:
194176
195-
jq usually outputs non-ASCII Unicode codepoints as UTF-8, even
196-
if the input specified them as escape sequences (like
197-
"\u03bc"). Using this option, you can force jq to produce pure
198-
ASCII output with every non-ASCII character replaced with the
199-
equivalent escape sequence.
177+
Use the given number of spaces (no more than 7) for indentation.
200178
201179
* `--unbuffered`:
202180
203181
Flush the output after each JSON object is printed (useful if
204182
you're piping a slow data source into jq and piping jq's
205183
output elsewhere).
206184
207-
* `--sort-keys` / `-S`:
185+
* `--stream`:
208186
209-
Output the fields of each object with the keys in sorted order.
187+
Parse the input in streaming fashion, outputting arrays of path
188+
and leaf values (scalars and empty arrays or empty objects).
189+
For example, `"a"` becomes `[[],"a"]`, and `[[],"a",["b"]]`
190+
becomes `[[0],[]]`, `[[1],"a"]`, and `[[2,0],"b"]`.
210191
211-
* `--raw-output` / `-r`:
192+
This is useful for processing very large inputs. Use this in
193+
conjunction with filtering and the `reduce` and `foreach` syntax
194+
to reduce large inputs incrementally.
212195
213-
With this option, if the filter's result is a string then it
214-
will be written directly to standard output rather than being
215-
formatted as a JSON string with quotes. This can be useful for
216-
making jq filters talk to non-JSON-based systems.
196+
* `--stream-errors`:
217197
218-
* `--join-output` / `-j`:
198+
Like `--stream`, but invalid JSON inputs yield array values
199+
where the first element is the error and the second is a path.
200+
For example, `["a",n]` produces `["Invalid literal at line 1,
201+
column 7",[1]]`.
219202
220-
Like `-r` but jq won't print a newline after each output.
203+
Implies `--stream`. Invalid JSON inputs produce no error values
204+
when `--stream` without `--stream-errors`.
221205
222-
* `--nul-output` / `-0`:
206+
* `--seq`:
223207
224-
Like `-r` but jq will print NUL instead of newline after each output.
225-
This can be useful when the values being output can contain newlines.
208+
Use the `application/json-seq` MIME type scheme for separating
209+
JSON texts in jq's input and output. This means that an ASCII
210+
RS (record separator) character is printed before each value on
211+
output and an ASCII LF (line feed) is printed after every
212+
output. Input JSON texts that fail to parse are ignored (but
213+
warned about), discarding all subsequent input until the next
214+
RS. This mode also parses the output of jq without the `--seq`
215+
option.
226216
227217
* `-f filename` / `--from-file filename`:
228218
229219
Read filter from the file rather than from a command line, like
230220
awk's -f option. You can also use '#' to make comments.
231221
232-
* `-Ldirectory` / `-L directory`:
222+
* `-L directory`:
233223
234224
Prepend `directory` to the search list for modules. If this
235225
option is used then no builtin search list is used. See the
236226
section on modules below.
237227
238-
* `-e` / `--exit-status`:
239-
240-
Sets the exit status of jq to 0 if the last output value was
241-
neither `false` nor `null`, 1 if the last output value was
242-
either `false` or `null`, or 4 if no valid result was ever
243-
produced. Normally jq exits with 2 if there was any usage
244-
problem or system error, 3 if there was a jq program compile
245-
error, or 0 if the jq program ran.
246-
247-
Another way to set the exit status is with the `halt_error`
248-
builtin function.
249-
250228
* `--arg name value`:
251229
252230
This option passes a value to the jq program as a predefined
@@ -297,6 +275,32 @@ sections:
297275
Remaining arguments are positional JSON text arguments. These
298276
are available to the jq program as `$ARGS.positional[]`.
299277
278+
* `--exit-status` / `-e`:
279+
280+
Sets the exit status of jq to 0 if the last output value was
281+
neither `false` nor `null`, 1 if the last output value was
282+
either `false` or `null`, or 4 if no valid result was ever
283+
produced. Normally jq exits with 2 if there was any usage
284+
problem or system error, 3 if there was a jq program compile
285+
error, or 0 if the jq program ran.
286+
287+
Another way to set the exit status is with the `halt_error`
288+
builtin function.
289+
290+
* `--binary` / `-b`:
291+
292+
Windows users using WSL, MSYS2, or Cygwin, should use this option
293+
when using a native jq.exe, otherwise jq will turn newlines (LFs)
294+
into carriage-return-then-newline (CRLF).
295+
296+
* `--version` / `-V`:
297+
298+
Output the jq version and exit with zero.
299+
300+
* `--help` / `-h`:
301+
302+
Output the jq help and exit with zero.
303+
300304
* `--`:
301305
302306
Terminates argument processing. Remaining arguments are
@@ -311,7 +315,7 @@ sections:
311315
program lines followed by one input line, as many lines of
312316
output as are expected (one per output), and a terminating empty
313317
line. Compilation failure tests start with a line containing
314-
only "%%FAIL", then a line containing the program to compile,
318+
only `%%FAIL`, then a line containing the program to compile,
315319
then a line containing an error message to compare to the
316320
actual.
317321

‎docs/content/manual/v1.3/manual.yml

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -82,36 +82,37 @@ sections:
8282
You can affect how jq reads and writes its input and output
8383
using some command-line options:
8484
85-
* `--slurp`/`-s`:
85+
* `--null-input` / `-n`:
8686
87-
Instead of running the filter for each JSON object in the
88-
input, read the entire input stream into a large array and run
89-
the filter just once.
87+
Don't read any input at all. Instead, the filter is run once
88+
using `null` as the input. This is useful when using jq as a
89+
simple calculator or to construct JSON data from scratch.
9090
91-
* `--raw-input`/`-R`:
91+
* `--raw-input` / `-R`:
9292
9393
Don't parse the input as JSON. Instead, each line of text is
9494
passed to the filter as a string. If combined with `--slurp`,
9595
then the entire input is passed to the filter as a single long
9696
string.
9797
98-
* `--null-input`/`-n`:
98+
* `--slurp` / `-s`:
9999
100-
Don't read any input at all! Instead, the filter is run once
101-
using `null` as the input. This is useful when using jq as a
102-
simple calculator or to construct JSON data from scratch.
100+
Instead of running the filter for each JSON object in the
101+
input, read the entire input stream into a large array and run
102+
the filter just once.
103103
104104
* `--compact-output` / `-c`:
105105
106106
By default, jq pretty-prints JSON output. Using this option
107107
will result in more compact output by instead putting each
108108
JSON object on a single line.
109109
110-
* `--color-output` / `-C` and `--monochrome-output` / `-M`:
110+
* `--raw-output` / `-r`:
111111
112-
By default, jq outputs colored JSON if writing to a
113-
terminal. You can force it to produce color even if writing to
114-
a pipe or a file using `-C`, and disable color with `-M`.
112+
With this option, if the filter's result is a string then it
113+
will be written directly to standard output rather than being
114+
formatted as a JSON string with quotes. This can be useful for
115+
making jq filters talk to non-JSON-based systems.
115116
116117
* `--ascii-output` / `-a`:
117118
@@ -121,12 +122,11 @@ sections:
121122
ASCII output with every non-ASCII character replaced with the
122123
equivalent escape sequence.
123124
124-
* `--raw-output` / `-r`:
125+
* `--color-output` / `-C` and `--monochrome-output` / `-M`:
125126
126-
With this option, if the filter's result is a string then it
127-
will be written directly to standard output rather than being
128-
formatted as a JSON string with quotes. This can be useful for
129-
making jq filters talk to non-JSON-based systems.
127+
By default, jq outputs colored JSON if writing to a
128+
terminal. You can force it to produce color even if writing to
129+
a pipe or a file using `-C`, and disable color with `-M`.
130130
131131
* `--arg name value`:
132132

0 commit comments

Comments
 (0)