debug/1

This def ensures the output of debug(m1,m2) is kept together. See #2709 #2111 #2112 Update jq.1.prebuilt manual.yml: debug/1: more typos manual.yml: debug/1: typo msgs builtin.jq: spacing
jqlang · Jul 13, 2023 · 7f55c9d · 7f55c9d
1 parent ab2779e
commit 7f55c9d
Show file tree

Hide file tree

Showing 3 changed files with 59 additions and 7 deletions.
diff --git a/docs/content/manual/manual.yml b/docs/content/manual/manual.yml
@@ -3075,13 +3075,29 @@ 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
diff --git 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);