From 32a304b912cdd8746f73525e2ff2c189e2e84c7c Mon Sep 17 00:00:00 2001 From: Thalia Archibald Date: Sat, 9 Nov 2024 06:48:24 -0800 Subject: [PATCH] Clarify -f argument parsing (#3199) --- docs/content/manual/dev/manual.yml | 11 ++++++----- jq.1.prebuilt | 8 ++++---- src/main.c | 2 +- 3 files changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/content/manual/dev/manual.yml b/docs/content/manual/dev/manual.yml index 96a7269d5e..82061f8234 100644 --- a/docs/content/manual/dev/manual.yml +++ b/docs/content/manual/dev/manual.yml @@ -221,10 +221,11 @@ sections: RS. This mode also parses the output of jq without the `--seq` option. - * `-f filename` / `--from-file filename`: + * `-f` / `--from-file`: - Read filter from the file rather than from a command line, like - awk's -f option. + Read the filter from a file rather than from a command line, + like awk's -f option. This changes the filter argument to be + interpreted as a filename, instead of the source of a program. * `-L directory` / `--library-path directory`: @@ -3633,7 +3634,7 @@ sections: # total - Output the sum of the given arguments (or stdin) # usage: total [numbers...] # \ - exec jq --args -MRnf "$0" -- "$@" + exec jq --args -MRnf -- "$0" "$@" $ARGS.positional | reduce ( @@ -3653,7 +3654,7 @@ sections: end of the line does not continue the comment. With this trick, when the script is invoked as `total 1 2`, `/bin/sh -- /path/to/total 1 2` will be run, and `sh` will then - run `exec jq --args -MRnf /path/to/total -- 1 2` replacing itself + run `exec jq --args -MRnf -- /path/to/total 1 2` replacing itself with a `jq` interpreter invoked with the specified options (`-M`, `-R`, `-n`, `--args`), that evaluates the current file (`$0`), with the arguments (`$@`) that were passed to `sh`. diff --git a/jq.1.prebuilt b/jq.1.prebuilt index 4091cd20b3..e391bf3c89 100644 --- a/jq.1.prebuilt +++ b/jq.1.prebuilt @@ -163,10 +163,10 @@ Implies \fB\-\-stream\fR\. Invalid JSON inputs produce no error values when \fB\ Use the \fBapplication/json\-seq\fR 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 \fB\-\-seq\fR option\. . .TP -\fB\-f filename\fR / \fB\-\-from\-file filename\fR: +\fB\-f\fR / \fB\-\-from\-file\fR: . .IP -Read filter from the file rather than from a command line, like awk\'s \-f option\. +Read the filter from a file rather than from a command line, like awk\'s \-f option\. This changes the filter argument to be interpreted as a filename, instead of the source of a program\. . .TP \fB\-L directory\fR / \fB\-\-library\-path directory\fR: @@ -4065,7 +4065,7 @@ Backslash continuing the comment on the next line can be useful when writing the # total \- Output the sum of the given arguments (or stdin) # usage: total [numbers\.\.\.] # \e -exec jq \-\-args \-MRnf "$0" \-\- "$@" +exec jq \-\-args \-MRnf \-\- "$0" "$@" $ARGS\.positional | reduce ( @@ -4085,7 +4085,7 @@ reduce ( .IP "" 0 . .P -The \fBexec\fR line is considered a comment by jq, so it is ignored\. But it is not ignored by \fBsh\fR, since in \fBsh\fR a backslash at the end of the line does not continue the comment\. With this trick, when the script is invoked as \fBtotal 1 2\fR, \fB/bin/sh \-\- /path/to/total 1 2\fR will be run, and \fBsh\fR will then run \fBexec jq \-\-args \-MRnf /path/to/total \-\- 1 2\fR replacing itself with a \fBjq\fR interpreter invoked with the specified options (\fB\-M\fR, \fB\-R\fR, \fB\-n\fR, \fB\-\-args\fR), that evaluates the current file (\fB$0\fR), with the arguments (\fB$@\fR) that were passed to \fBsh\fR\. +The \fBexec\fR line is considered a comment by jq, so it is ignored\. But it is not ignored by \fBsh\fR, since in \fBsh\fR a backslash at the end of the line does not continue the comment\. With this trick, when the script is invoked as \fBtotal 1 2\fR, \fB/bin/sh \-\- /path/to/total 1 2\fR will be run, and \fBsh\fR will then run \fBexec jq \-\-args \-MRnf \-\- /path/to/total 1 2\fR replacing itself with a \fBjq\fR interpreter invoked with the specified options (\fB\-M\fR, \fB\-R\fR, \fB\-n\fR, \fB\-\-args\fR), that evaluates the current file (\fB$0\fR), with the arguments (\fB$@\fR) that were passed to \fBsh\fR\. . .SH "MODULES" jq has a library/module system\. Modules are files whose names end in \fB\.jq\fR\. diff --git a/src/main.c b/src/main.c index 372342c94c..2f25105292 100644 --- a/src/main.c +++ b/src/main.c @@ -94,7 +94,7 @@ static void usage(int code, int keep_it_short) { " --stream-errors implies --stream and report parse error as\n" " an array;\n" " --seq parse input/output as application/json-seq;\n" - " -f, --from-file file load filter from the file;\n" + " -f, --from-file load the filter from a file;\n" " -L, --library-path dir search modules from the directory;\n" " --arg name value set $name to the string value;\n" " --argjson name value set $name to the JSON value;\n"