Skip to content

Commit

Permalink
Reorder the command line options in the manual
Browse files Browse the repository at this point in the history
  • Loading branch information
@itchyny
itchyny committed Jul 25, 2023
1 parent 8f49600 commit c96ae26
Show file tree
Hide file tree
Showing 6 changed files with 297 additions and 281 deletions.
174 changes: 89 additions & 85 deletions docs/content/manual/manual.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -104,74 +104,58 @@ sections:
You can affect how jq reads and writes its input and output
using some command-line options:
* `--version`/`-V`:
* `--null-input` / `-n`:
Output the jq version and exit with zero.
* `--seq`:
Use the `application/json-seq` MIME type scheme for separating
JSON texts in jq's input and output. This means that an ASCII
RS (record separator) character is printed before each value on
output and an ASCII LF (line feed) is printed after every
output. Input JSON texts that fail to parse are ignored (but
warned about), discarding all subsequent input until the next
RS. This mode also parses the output of jq without the `--seq`
option.
* `--stream`:
Parse the input in streaming fashion, outputting arrays of path
and leaf values (scalars and empty arrays or empty objects).
For example, `"a"` becomes `[[],"a"]`, and `[[],"a",["b"]]`
becomes `[[0],[]]`, `[[1],"a"]`, and `[[2,0],"b"]`.
This is useful for processing very large inputs. Use this in
conjunction with filtering and the `reduce` and `foreach` syntax
to reduce large inputs incrementally.
* `--stream-errors`:
Like `--stream`, but invalid JSON inputs yield array values
where the first element is the error and the second is a path.
For example, `["a",n]` produces ["Invalid literal at line 1,
column 9",[1]]`.
Implies `--stream`. Invalid JSON inputs produce no error values
when `--stream` without `--stream-errors`.
* `--slurp`/`-s`:
Instead of running the filter for each JSON object in the
input, read the entire input stream into a large array and run
the filter just once.
Don't read any input at all. Instead, the filter is run once
using `null` as the input. This is useful when using jq as a
simple calculator or to construct JSON data from scratch.
* `--raw-input`/`-R`:
* `--raw-input` / `-R`:
Don't parse the input as JSON. Instead, each line of text is
passed to the filter as a string. If combined with `--slurp`,
then the entire input is passed to the filter as a single long
string.
* `--null-input`/`-n`:
* `--slurp` / `-s`:
Don't read any input at all! Instead, the filter is run once
using `null` as the input. This is useful when using jq as a
simple calculator or to construct JSON data from scratch.
Instead of running the filter for each JSON object in the
input, read the entire input stream into a large array and run
the filter just once.
* `--compact-output` / `-c`:
By default, jq pretty-prints JSON output. Using this option
will result in more compact output by instead putting each
JSON object on a single line.
* `--tab`:
* `--raw-output` / `-r`:
Use a tab for each indentation level instead of two spaces.
With this option, if the filter's result is a string then it
will be written directly to standard output rather than being
formatted as a JSON string with quotes. This can be useful for
making jq filters talk to non-JSON-based systems.
* `--indent n`:
* `--join-output` / `-j`:
Use the given number of spaces (no more than 7) for indentation.
Like `-r` but jq won't print a newline after each output.
* `--nul-output` / `-0`:
Like `-r` but jq will print NUL instead of newline after each output.
This can be useful when the values being output can contain newlines.
* `--ascii-output` / `-a`:
jq usually outputs non-ASCII Unicode codepoints as UTF-8, even
if the input specified them as escape sequences (like
"\u03bc"). Using this option, you can force jq to produce pure
ASCII output with every non-ASCII character replaced with the
equivalent escape sequence.
* `--sort-keys` / `-S`:
Output the fields of each object with the keys in sorted order.
* `--color-output` / `-C` and `--monochrome-output` / `-M`:
Expand All @@ -184,69 +168,63 @@ sections:
Colors can be configured with the `JQ_COLORS` environment
variable (see below).
* `--binary` / `-b`:
* `--tab`:
Windows users using WSL, MSYS2, or Cygwin, should use this option
when using a native jq.exe, otherwise jq will turn newlines (LFs)
into carriage-return-then-newline (CRLF).
Use a tab for each indentation level instead of two spaces.
* `--ascii-output` / `-a`:
* `--indent n`:
jq usually outputs non-ASCII Unicode codepoints as UTF-8, even
if the input specified them as escape sequences (like
"\u03bc"). Using this option, you can force jq to produce pure
ASCII output with every non-ASCII character replaced with the
equivalent escape sequence.
Use the given number of spaces (no more than 7) for indentation.
* `--unbuffered`:
Flush the output after each JSON object is printed (useful if
you're piping a slow data source into jq and piping jq's
output elsewhere).
* `--sort-keys` / `-S`:
* `--stream`:
Output the fields of each object with the keys in sorted order.
Parse the input in streaming fashion, outputting arrays of path
and leaf values (scalars and empty arrays or empty objects).
For example, `"a"` becomes `[[],"a"]`, and `[[],"a",["b"]]`
becomes `[[0],[]]`, `[[1],"a"]`, and `[[2,0],"b"]`.
* `--raw-output` / `-r`:
This is useful for processing very large inputs. Use this in
conjunction with filtering and the `reduce` and `foreach` syntax
to reduce large inputs incrementally.
With this option, if the filter's result is a string then it
will be written directly to standard output rather than being
formatted as a JSON string with quotes. This can be useful for
making jq filters talk to non-JSON-based systems.
* `--stream-errors`:
* `--join-output` / `-j`:
Like `--stream`, but invalid JSON inputs yield array values
where the first element is the error and the second is a path.
For example, `["a",n]` produces `["Invalid literal at line 1,
column 7",[1]]`.
Like `-r` but jq won't print a newline after each output.
Implies `--stream`. Invalid JSON inputs produce no error values
when `--stream` without `--stream-errors`.
* `--nul-output` / `-0`:
* `--seq`:
Like `-r` but jq will print NUL instead of newline after each output.
This can be useful when the values being output can contain newlines.
Use the `application/json-seq` MIME type scheme for separating
JSON texts in jq's input and output. This means that an ASCII
RS (record separator) character is printed before each value on
output and an ASCII LF (line feed) is printed after every
output. Input JSON texts that fail to parse are ignored (but
warned about), discarding all subsequent input until the next
RS. This mode also parses the output of jq without the `--seq`
option.
* `-f filename` / `--from-file filename`:
Read filter from the file rather than from a command line, like
awk's -f option. You can also use '#' to make comments.
* `-Ldirectory` / `-L directory`:
* `-L directory`:
Prepend `directory` to the search list for modules. If this
option is used then no builtin search list is used. See the
section on modules below.
* `-e` / `--exit-status`:
Sets the exit status of jq to 0 if the last output value was
neither `false` nor `null`, 1 if the last output value was
either `false` or `null`, or 4 if no valid result was ever
produced. Normally jq exits with 2 if there was any usage
problem or system error, 3 if there was a jq program compile
error, or 0 if the jq program ran.
Another way to set the exit status is with the `halt_error`
builtin function.
* `--arg name value`:
This option passes a value to the jq program as a predefined
Expand Down Expand Up @@ -297,6 +275,32 @@ sections:
Remaining arguments are positional JSON text arguments. These
are available to the jq program as `$ARGS.positional[]`.
* `--exit-status` / `-e`:
Sets the exit status of jq to 0 if the last output value was
neither `false` nor `null`, 1 if the last output value was
either `false` or `null`, or 4 if no valid result was ever
produced. Normally jq exits with 2 if there was any usage
problem or system error, 3 if there was a jq program compile
error, or 0 if the jq program ran.
Another way to set the exit status is with the `halt_error`
builtin function.
* `--binary` / `-b`:
Windows users using WSL, MSYS2, or Cygwin, should use this option
when using a native jq.exe, otherwise jq will turn newlines (LFs)
into carriage-return-then-newline (CRLF).
* `--version` / `-V`:
Output the jq version and exit with zero.
* `--help` / `-h`:
Output the jq help and exit with zero.
* `--`:
Terminates argument processing. Remaining arguments are
Expand All @@ -311,7 +315,7 @@ sections:
program lines followed by one input line, as many lines of
output as are expected (one per output), and a terminating empty
line. Compilation failure tests start with a line containing
only "%%FAIL", then a line containing the program to compile,
only `%%FAIL`, then a line containing the program to compile,
then a line containing an error message to compare to the
actual.
Expand Down
36 changes: 18 additions & 18 deletions docs/content/manual/v1.3/manual.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -82,36 +82,37 @@ sections:
You can affect how jq reads and writes its input and output
using some command-line options:
* `--slurp`/`-s`:
* `--null-input` / `-n`:
Instead of running the filter for each JSON object in the
input, read the entire input stream into a large array and run
the filter just once.
Don't read any input at all. Instead, the filter is run once
using `null` as the input. This is useful when using jq as a
simple calculator or to construct JSON data from scratch.
* `--raw-input`/`-R`:
* `--raw-input` / `-R`:
Don't parse the input as JSON. Instead, each line of text is
passed to the filter as a string. If combined with `--slurp`,
then the entire input is passed to the filter as a single long
string.
* `--null-input`/`-n`:
* `--slurp` / `-s`:
Don't read any input at all! Instead, the filter is run once
using `null` as the input. This is useful when using jq as a
simple calculator or to construct JSON data from scratch.
Instead of running the filter for each JSON object in the
input, read the entire input stream into a large array and run
the filter just once.
* `--compact-output` / `-c`:
By default, jq pretty-prints JSON output. Using this option
will result in more compact output by instead putting each
JSON object on a single line.
* `--color-output` / `-C` and `--monochrome-output` / `-M`:
* `--raw-output` / `-r`:
By default, jq outputs colored JSON if writing to a
terminal. You can force it to produce color even if writing to
a pipe or a file using `-C`, and disable color with `-M`.
With this option, if the filter's result is a string then it
will be written directly to standard output rather than being
formatted as a JSON string with quotes. This can be useful for
making jq filters talk to non-JSON-based systems.
* `--ascii-output` / `-a`:
Expand All @@ -121,12 +122,11 @@ sections:
ASCII output with every non-ASCII character replaced with the
equivalent escape sequence.
* `--raw-output` / `-r`:
* `--color-output` / `-C` and `--monochrome-output` / `-M`:
With this option, if the filter's result is a string then it
will be written directly to standard output rather than being
formatted as a JSON string with quotes. This can be useful for
making jq filters talk to non-JSON-based systems.
By default, jq outputs colored JSON if writing to a
terminal. You can force it to produce color even if writing to
a pipe or a file using `-C`, and disable color with `-M`.
* `--arg name value`:
Expand Down

0 comments on commit c96ae26

Please sign in to comment.