From 027361534555a7c87af27c3ea612585ba18eb65b Mon Sep 17 00:00:00 2001
From: yertto <yerrto@gmail.com>
Date: Sat, 3 Sep 2022 09:50:49 +1000
Subject: [PATCH] feat: Add debug/1 to log debug messages without consuming
 stdin

Define `debug/1` to call `debug/0`, but send `stdin` to `stdout` without consuming it,
while printing the debug messages to `stderr`.

Example usage:
```sh
seq 2 | LOG_LEVEL=DEBUG jq '
  debug({$ENV})                          |
  debug({line: input_line_number})       |
  debug("\(now | todate) here1: .=\(.)") |
  . * 10                                 |
  debug("\(now | todate) here2: .=\(.)") |
  . + 1
'
```
=>
```
["DEBUG:",{"ENV":{"PWD":"/tmp","SHELL":"/bin/zsh","PATH":"/usr/bin:/bin", ...}}]
["DEBUG:",{"line":1}]
["DEBUG:","2022-09-03T10:52:24Z here1: .=1"]
["DEBUG:","2022-09-03T10:52:24Z here2: .=10"]
11
["DEBUG:",{"ENV":{"PWD":"/tmp","SHELL":"/bin/zsh","PATH":"/usr/bin:/bin", ...}}]
["DEBUG:",{"line":2}]
["DEBUG:","2022-09-03T10:52:24Z here1: .=2"]
["DEBUG:","2022-09-03T10:52:24Z here2: .=20"]
21
```

ie. a *slightly* less efficient way of achieving:
```sh
seq 2 | jq '
   . * 10 |
   . + 1
'
```
=>
```
11
21
```
---
 docs/content/manual/manual.yml | 11 +++++++++++
 src/builtin.jq                 |  1 +
 2 files changed, 12 insertions(+)

diff --git a/docs/content/manual/manual.yml b/docs/content/manual/manual.yml
index 442fc0d4f1..849692e11c 100644
--- a/docs/content/manual/manual.yml
+++ b/docs/content/manual/manual.yml
@@ -2984,6 +2984,17 @@ sections:
           `["DEBUG:", <input-value>]` and prints that and a newline on
           stderr, compactly.  This may change in the future.
 
+      - title: "`debug(msg)`"
+        body: |
+
+          Calls `debug/0` to print the debug `msg` to stderr, but this
+          version sends stdin to stdout without consuming it.
+
+        examples:
+          - program: 'debug("here1") | . + 1'
+            input: '1'
+            output: ['2']
+
       - title: "`stderr`"
         body: |
 
diff --git a/src/builtin.jq b/src/builtin.jq
index a102fd51a0..bdb83407c3 100644
--- a/src/builtin.jq
+++ b/src/builtin.jq
@@ -1,5 +1,6 @@
 def halt_error: halt_error(5);
 def error(msg): msg|error;
+def debug(msg): . as $dot | msg | debug | $dot;
 def map(f): [.[] | f];
 def select(f): if f then . else empty end;
 def sort_by(f): _sort_by_impl(map([f]));