Pretty Printing
In Calva, pretty printing is a mode. Prettiness is on by default and all your evaluation results will get that treatment.
Toggle it
There is a pprint indicator to the right in the status bar which shows the status of the mode. Click the indicator to toggle prettification on and off. There is also a Calva: Toggle Pretty Printing for All Evaluations command.
Tip: If you have evaluated something time consuming, or that is not idempotent, with pretty printing mistakenly off: toggle it on and evaluate *1.
Configuration
For most people the defaults will probably work, but Calva pretty printing comes a few knobs you can turn, and they are all available through the calva.prettyPrintingOptions settings. Things you can set are:
| Setting | Type | Effect |
|---|---|---|
enabled |
boolean | So this is a third way you can change this mode 😄 |
printEngine |
enum | Which printer function that will be used. Default is pprint, more about this setting below |
width |
number | The maximum line length of printed output (or at least the printers will try) |
maxLength |
number | The maximum number of elements printed in nested nodes, good for evaluating something like (iterate inc 0), which you shouldn't do without setting maxLength. Most printers will indicate truncated lists with ... at the end. |
maxDepth |
number | The maximum number of levels deep that will get printed. Different printers mark a stop different ways. puget doesn't support it at all. |
See Customizing Calva for some tips on adding settings like these.
Here's an example of how zprint handles maxDepth (from the Calva implementation of it's client side pretty printing.).
(pretty-print [[[[[[[[:deeper]]]]]]]] {:max-depth 4})
;; => {:value "[[[[##]]]]"}
Your Selection of Prettifiers
Pretty printing can happen on the server (i.e. in the JVM, via nREPL), or on the client (i.e. in node, via VS Code/Calva). Client side always uses zprint. Server side you can choose from these printers:
| Print Engine | Client or Server Side | Comments |
|---|---|---|
calva |
client | The nREPL server will plain print the results, and then Calva will pretty it. |
pprint |
server | Current Calva default (clojure.core/pprint is a bit basic, but it's tried and tested, and has none of the server side printing issues mentioned below. |
fipp |
server | |
puget |
server | Lacks maxDepth option. |
zprint |
server | Recommended. Will need to be configured before Jack-in if you want Calva's help to inject its dependencies |
These particular server side functions were chosen because they have pre-configured print-functions in cider-nrepl.
Why does Server or Client Side Matter?
This matters because on the server all pretty printers, except pprint does more than just pretty print the result that would be printed with plain printing. Pretty printing results on the server causes some results to get expanded. This can have huge implications depending on the results and which printer is used. E.g. for Datomic transaction results, you will get the whole database printed. Twice. Depending on the database, you could be so unlucky that nothing gets printed, and instead you will soon have a very hot computer.
Note: With the help of zprint creator, Kim Kinnear, we have found ways to compensate for this problem. Ways that are not yet implemented, but please stay tuned.
Then why not always do it client side? It turns out that on the client side there are also things going on. Calva gets the results back as a string and therefore it needs to first be parsed back to EDN, before it can be pretty printed by zprint. And – here's the catch – all results are not valid EDN and therefore can't be pretty printed by zprint. Datomic transaction results are one example.
Need More Configurability?
The current options are limited, because our time developing Calva is limited. But cider-nrepl really allows for fully configurable pretty printing, so it is within reach. Please feel invited to give us feedback on what you would want to configure for the printing of results. File issues and/or chat us up in #calva in the Clojurians slack.
Troubleshooting
pprint is not working for ClojureScript
If you're using shadow-cljs and not using the calva pprint engine, you need to set :repl-pprint to true in :devtools of your shadow-cljs build. See here for more details.
Enjoy Prettiful Printing! ❤️