diff options
author | pkoppstein <pkoppstein@gmail.com> | 2023-07-13 18:17:42 -0400 |
---|---|---|
committer | GitHub <noreply@github.com> | 2023-07-14 00:17:42 +0200 |
commit | 07ef97c414ef0370683a30a392223610912025fb (patch) | |
tree | 072cfee6f5603e17bea471755416fde7a258e2c5 | |
parent | 4b1ac7c95fc72b1fd59211f5af46cdf13f4ad478 (diff) |
debug/1 (#2710)
* debug/1
This def ensures the output of debug(m1,m2) is kept together.
Closes #2709 #2111 #2112
-rw-r--r-- | docs/content/manual/manual.yml | 29 | ||||
-rw-r--r-- | jq.1.prebuilt | 50 | ||||
-rw-r--r-- | src/builtin.jq | 3 |
3 files changed, 75 insertions, 7 deletions
diff --git a/docs/content/manual/manual.yml b/docs/content/manual/manual.yml index 9dbd1b19..24db2daf 100644 --- a/docs/content/manual/manual.yml +++ b/docs/content/manual/manual.yml @@ -3075,13 +3075,32 @@ sections: to invoke jq with the -n command-line option, otherwise the first entity will be lost. - - title: "`debug`" + - title: "`debug`, `debug(msgs)`" body: | - Causes a debug message based on the input value to be - produced. The jq executable wraps the input value with - `["DEBUG:", <input-value>]` and prints that and a newline on - stderr, compactly. This may change in the future. + These two filters are like `.` but have as a side-effect the + production of one or more messages on stderr. + + The message produced by the `debug` filter has the form + + ["DEBUG:",<input-value>] + + where `<input-value>` is a compact rendition of the input + value. This format may change in the future. + + The `debug(msgs)` filter is defined as `(msgs | debug | empty), .` + thus allowing great flexibility in the content of the message, + while also allowing multi-line debugging statements to be created. + + For example, the expression: + + 1 as $x | 2 | debug("Entering function foo with $x == \($x)", .) | (.+1) + + would produce the value 3 but with the following two lines + being written to stderr: + + ["DEBUG:","Entering function foo with $x == 1"] + ["DEBUG:",2] - title: "`stderr`" body: | diff --git a/jq.1.prebuilt b/jq.1.prebuilt index 37f40341..d4979985 100644 --- a/jq.1.prebuilt +++ b/jq.1.prebuilt @@ -3353,8 +3353,54 @@ Outputs all remaining inputs, one by one\. .P This is primarily useful for reductions over a program\'s inputs\. Note that when using \fBinputs\fR it is generally necessary to invoke jq with the \-n command\-line option, otherwise the first entity will be lost\. . -.SS "debug" -Causes a debug message based on the input value to be produced\. The jq executable wraps the input value with \fB["DEBUG:", <input\-value>]\fR and prints that and a newline on stderr, compactly\. This may change in the future\. +.SS "debug, debug(msgs)" +These two filters are like \fB\.\fR but have as a side\-effect the production of one or more messages on stderr\. +. +.P +The message produced by the \fBdebug\fR filter has the form +. +.IP "" 4 +. +.nf + +["DEBUG:",<input\-value>] +. +.fi +. +.IP "" 0 +. +.P +where \fB<input\-value>\fR is a compact rendition of the input value\. This format may change in the future\. +. +.P +The \fBdebug(msgs)\fR filter is defined as \fB(msgs | debug | empty), \.\fR thus allowing great flexibility in the content of the message, while also allowing multi\-line debugging statements to be created\. +. +.P +For example, the expression: +. +.IP "" 4 +. +.nf + +1 as $x | 2 | debug("Entering function foo with $x == \e($x)", \.) | (\.+1) +. +.fi +. +.IP "" 0 +. +.P +would produce the value 3 but with the following two lines being written to stderr: +. +.IP "" 4 +. +.nf + +["DEBUG:","Entering function foo with $x == 1"] +["DEBUG:",2] +. +.fi +. +.IP "" 0 . .SS "stderr" Prints its input in raw and compact mode to stderr with no additional decoration, not even a newline\. diff --git a/src/builtin.jq b/src/builtin.jq index 146a64a3..a13d7845 100644 --- a/src/builtin.jq +++ b/src/builtin.jq @@ -266,6 +266,9 @@ def pick(pathexps): | reduce path(pathexps) as $a (null; setpath($a; $in|getpath($a)) ); +# ensure the output of debug(m1,m2) is kept together: +def debug(msgs): (msgs | debug | empty), .; + # SQL-ish operators here: def INDEX(stream; idx_expr): reduce stream as $row ({}; .[$row|idx_expr|tostring] = $row); |