Different kinds of JSON writers, and naming them Lassi Kortela 22 Jan 2020 11:52 UTC

> Having more procedures doesn't add complexity, but having more
> *exported* procedures does.  Each one is another attack surface for
> penetration testing, another bit of documentation, another  item to
> master in order to master the API.  I have in general gone much further
> in this direction, following Olin Shivers's SRFI 1, than many people
> think I should have.

While that is true, it's also an inherent property of successful
general-purpose languages that they do a lot, and do it conveniently.
The long-term trend is toward all software converging into one system
(we just can't agree on whose system that should be).

I'm in favor of your and Olin's comprehensive approach for libraries and
it pushed my own thinking more in that direction. I don't always see the
point of a particular procedure in a SRFI, but if it's logically
specified (and they generally are) I give it the benefit of the doubt.

I also think there's a point to having a mix of minimalist SRFIs and
maximalist SRFIs (maximalism is a word in some circles).

> I am less convinced about json-prettyprint.  It's a
> lot more code, more things to go wrong.  "The most efficient, the
> fastest, the easiest to read, and the most secure code is that which
> does not exist."  If you are convinced that this is something that
> everyone needs, then make that case.

I agree that in the REPL, Scheme `pp` is enough.

The point is that there's a constant need to store JSON in files and to
view those files in a text editor, terminal, web browser or what have
you. It has made my work much easier when I store files pretty-printed
(and keys sorted). Diffs also become human-readable.

Isn't JSON pretty-print just JSON write with custom delimiters (most
notably, newline instead of space) and a non-zero indent width? You
could be fancier and figure out whether you can fit a small array into
one line, for example, but that's less important than the basics of
having multi-line, indented output.

Something I've also wanted in other languages is the ability to put JSON
keys in a convenient application-specific order. Alphabetical order is
not always easiest to read. This can be done by taking a procedure to
compare two keys; it can be symbol<? by default.

>     But if `json-write` writes a condensed format like Scheme `write`,
>     is it
>     much different from a `json-write-line` that would write a JSON Lines
>     compatible value? Would there in fact be any difference other than a
>     final newline?
>
> There would not, but having a separate convenience procedure makes sense
> because you can be sure that when you call it the output is conforming
> (this is your own argument).  Another possibility is to always write out
> a trailing newline in all cases, and then json-write would be inherently
> JSON Lines conformant as well as guaranteeing read-write consistency.

I would be in favor of always writing a newline, making it JSON Lines
compliant, unless there's a particular situation where people need to
write a JSON value without a newline. I can't think of any.

But the names of the procedures would need some thought.

`json-write-line` may be the most natural name for a JSON Lines writer
(Scheme has `write-char` and `write-string`, and Common Lisp has
`write-line`).

It could also be `json-lines-write`. Then the JSON Sequences writer
could be `json-sequences-write` which would be symmetrical.

Or `json-line-write` and `json-sequence-write`. This may actually be best.

`json-write-line` and `json-write-sequence` would be my favorite
combination, but AFAICT "sequence" means the sequence of many "texts",
not an individual text, so it would be incorrect terminology.

Finally, one could add a `json-pretty-write` or `json-pretty-print` (or
`json-indented-write` or `json-custom-write`, etc.)

The main problem with these is that a plain `json-write` (by analogy to
Scheme `write`) would be missing. But that may be a good thing - it
calls attention to the fact that there isn't one obvious way to write JSON.