Skip to content

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
printFn object You can configure Calva to use a custom nREPL compatible print function, more 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.

Or configure printFn

If the selection of built-in printEngine support doesn't cut it, you can configure a custom function. This function will need to conform to the requirements of nREPL print functions. The VS Code settings editor will help you configure this one.

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

If pprint is not working, try a different pprint engine or use Calva's jack-in to make sure the necessary dependencies are loaded in your REPL. If you are starting your REPL without jack-in and want to continue doing so, you can use the command Copy Jack-in Command to Clipboard then paste the command somewhere to see what dependencies it injects. You can then add these dependencies to your REPL in whatever way suits your needs.

Enjoy Prettiful Printing! ❤️