Feature request: Add 1-arity built-in function debug(f) for more control over debug output

[andremarianiello]

When working on large jq programs, I usually define a function like so:

def debug(f): . as $val | f | debug | $val;

Example usage:

$ echo '{"a": 1, "b": 2}' | ./jq 'debug(.a)'
["DEBUG:",1]
{
  "a": 1,
  "b": 2
}

As you can see, this function does not change it's input, just like 0-arity debug, but it prints a filtered value to stderr instead of its entire input. This function is incredibly useful for situations where the value you are printing is too large or complicated to be easily readable.

I usually use it when dealing with huge inputs that cannot fit on a single screen, but there are other applications as well. For example, imagine you are working on a jq filter that manipulates unix timestamps. When using debug to see the timestamps that are being processed, you will see unix time.

$ echo '1588708020' | ./jq 'debug | . + 10'
["DEBUG:",1588708020]
1588708030

but that can be hard to read. If you want formatted datetimes instead, you can do

$ echo '1588708020' | ./jq 'todate | debug | fromdate | . + 10'
["DEBUG:","2020-05-05T19:47:00Z"]
1588711630

This works, but is verbose, and will have to be undone if you go back and clean up the debug statements. Imagine if you could do

$ echo '1588708020' | ./jq 'debug(todate) | . + 10'
["DEBUG:","2020-05-05T19:47:00Z"]
1588708030

Easier to read, easier to use, easier to undo in the future. You get the same benefits as with_entries vs to_entries/from_entries.

I propose that this function be added to the list of builtins included with jq.

[emanuele6]

Closed by #2710