RFE: single value printf builtin

[benaryorg]

Context

• issue closed due to lack of varargs support: Add built in printf function #614
• potentially somewhat maybe obsoleted by dlopen(), random, I/O, eval, and co-expressions (co-routines) #1843

Reason

I use jq a lot.
For me it has become what awk has been for others in that I can go through a text file, grab some values out of each line and do some math on them.
Of course also when dealing with JSON.
As a side note, the Ansible module is also a great addition for Ansible users for complex data processing (mostly when having to do an operation on two dicts like complex lookups).

However the one thing that stood out through all of it was the lack of formatting.
The @ formatting filters are hands down awesome, but often even string interpolation is enough.
Every time I need to format something in a more nuanced way though I run into this issue and in some instances makes jq really hard to work with.
Padding numbers, doing rounding, adding sign prefixes, radix conversion, or even just aligning some text, it's all very difficult.
And while those problems can be solved within jq with a sizeable amount of code, that code is big and hard to maintain, especially out-of-tree.

With the lack of varargs I'd like to propose a single-value format filter that allows me to run .foo | format("% .2f") and go on with my day.
It can be used in string interpolation as-is, doesn't need any syntax additions.
The variadic versions of single-value formatting of printf (such as (%.*f, 1, 1.34) being 1.3) can be used via string interpolation a la "%\(.length)s" as $format | .value | format($format).

Implementation

Ideally implementing the full spectrum of printf(3) would be nice, however the padding and number formatting are probably the most pressing, while %x and friends would be extremely nice to have when generating shell commands (think of `@sh "chmod (.mode | format("%05o")) (.file)") for instance.
Delegating the actual format down to printf(3) would also be possible, with the caveat of jq having to trust user format strings to be correct, which – itself being a reasonable assumption – would also open jq scripts up to issues when they in turn pass unsanitized input through.
In hopes of it being common knowledge not to let an untrusted user (in this case the input which the script passes to jq and jq to printf) control the format string, this shouldn't be too bad.

Alternatives

Module implementations of printf are technically possible, but difficult (I just opened a bug with that one, which gave me the final push to opening an issue here).

With varargs support it could actually be implemented.

With string interpolation existing one could have special syntax for formatting in there, such as (making this up of course): \{"%.3f" .my_value}.

With formatting filters, which aren't limited to string values (compare @json) one could potentially implement something like: 3.1415 | @printf "the truncated value: \({format: "%+3.2f", value: .})"

The mentioned PR adding dlopen and similar features would technically allow loading printf from some form of libc, however this wouldn't work for Windows I imagine (while technically Not My Problem™, it would be nice to avoid that) and would probably require some path guessery.
I'm unsure about the viability of that.

[dmartin-isp]

Single value, meaning only one value expanded? So, 'foo | printf("%-10s")' would work, but 'foo | printf("%-10s %-10s", "bar")' would not?

[benaryorg]

So, 'foo | printf("%-10s")' would work, but 'foo | printf("%-10s %-10s", "bar")' would not?

I'm assuming you meant to use a semicolon (;) in place of the comma (,) in your inline example, as commas are the syntax for generating multiple values as opposed to semicolon which separates function arguments, please correct me if that assumption was off.

Single value, meaning only one value expanded?

Correct.

Single value specifically because it allows the user to implement anything requiring multiple values on top manually and makes sense to have by itself.
A function which does the same thing a varargs function would do, but only for a limited number of arguments¹ would be much better served by an actual varargs function, and would become obsolete when the latter is implemented eventually.

In the mean time pretty much any code I've seen so far can easily be written to work with single-value formatters, most of the time in an even more expressive way.
Your example could've been written:

# as a joined array
[ foo, "bar" | format("%-10s") ]
  | join(" ")

# using a more readable map
[ foo, "bar" ]
  | map(format("%-10s"))
  | join(" ")

# or an unwieldy but still perfectly fine string interpolation
"\(foo | format("%-10s")) \("bar" | format("%-10s"))"

# which is more or less equal to this string concatenation
(foo | format("%-10s")) + " " + ("bar" | format("%-10s"))

I find the second one the most easy to read, even compared with the multi-argument printf (where one has to remember that half the parameters are from the input and the other from the parameters).
To be honest, I'd probably write the first one if it was WORN² code.
However a reader may be confused as to whether the input or argument is formatted first.
This complexity feels (IMHO) "too much"

Footnotes

1. similar to the way Rust implements traits for tuples; it's not for arbitrary lengths, just for practically sufficiently large tuples ↩

2. write once, read never; aka. throwaway code ↩