Add debug(exp) builtin

docs/content/manual/v1.6/manual.yml

@@ -2924,13 +2924,24 @@ sections:
           This is primarily useful for reductions over a program's
           inputs.
 
-      - title: "`debug`"
+      - title: "`debug`, `debug(exp)`"
         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.
+          stderr, compactly.  This may change in the future. If given
+          an argument `exp`, the input is fed to `exp` before being
+          printed, but remains unchanged coming out.
+
+        examples:
+          - program: 'debug'
+            input: '1588708020'
+            output: ['["DEBUG:",1588708020]', '1588708020']
+          - program: 'debug(todate)'
+            input: '1588708020'
+            output: ['["DEBUG:","2020-05-05T19:47:00Z"]', '1588708020']
+
 
       - title: "`stderr`"
         body: |

src/builtin.jq

@@ -78,6 +78,8 @@ def scan(re):
       then [ .captures | .[] | .string ]
       else .string
       end ;
+def debug(f): . as $val | f | debug | $val;
+
 #
 # If input is an array, then emit a stream of successive subarrays of length n (or less),
 # and similarly for strings.