branch: elpa/cider
commit fb23d52ef067f2c71f43315b967f5ce00fee17d4
Author: Bozhidar Batsov <[email protected]>
Commit: Bozhidar Batsov <[email protected]>
Restore clojure.pprint as the default printer, add an orchard option
cider-nrepl 0.61 pointed its default pprint var at orchard.pp, which is
faster but renders some values differently than clojure.pprint. Map
cider-print-fn's `pprint` to the explicit clojure-pprint wrapper so the
default output stays the familiar one, and add an `orchard` value for
opting into orchard.pp where its speed and lazy-seq safety matter.
---
CHANGELOG.md | 3 +-
doc/modules/ROOT/pages/usage/pretty_printing.adoc | 41 ++++++++++++-----------
lisp/cider-client.el | 24 ++++++++-----
lisp/cider-eval.el | 4 +--
test/cider-client-tests.el | 13 +++++++
test/cider-eval-tests.el | 1 +
6 files changed, 55 insertions(+), 31 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index db21bbd3c3..6a393fe44f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,7 @@
### New features
+- Add an `orchard` value for `cider-print-fn`, selecting cider-nrepl's
`orchard.pp`-backed pretty-printer - significantly faster than the default
`clojure.pprint` and it doesn't realize lazy seqs while printing.
- [#4108](https://github.com/clojure-emacs/cider/pull/4108): Add `C-c C-d` at
the stdin prompt (shown when evaluated code reads input) to send end-of-input,
so `read-line` returns `nil` and `(slurp *in*)` completes - code reading to EOF
can now be satisfied interactively instead of only by interrupting the
evaluation.
- [#4094](https://github.com/clojure-emacs/cider/pull/4094): Add
`cider-doctor`, which checks your Emacs setup (and the active nREPL session, if
any) for common problems and shows a copy-pasteable report -
Emacs/CIDER/dependency versions, build tools on the path, stale byte-code,
leftover obsolete config, and cider-nrepl/nREPL/Clojure compatibility.
- Render fetched `text/html` content as formatted text (via `shr`) in the REPL
and the rich-content popup, and make the URL of an external-content result a
clickable link that opens in the browser (next to its `[show content]` button).
Remote images in that HTML are not fetched, so rendering a result never makes a
network request on its own (only inline `data:` images render).
@@ -100,7 +101,7 @@
- [#4059](https://github.com/clojure-emacs/cider/pull/4059): Use the public
`sesman-sessions` (via `cider-sessions`) instead of a private sesman function
in `cider-debug-sesman-friendly-session-p`
([#4037](https://github.com/clojure-emacs/cider/issues/4037)).
- [#4056](https://github.com/clojure-emacs/cider/pull/4056): Show the
interactive-evaluation spinner in the buffer you evaluated from (the source
buffer, or the REPL when evaluating at its prompt) instead of always in the
REPL buffer, which is often not even visible
([#3516](https://github.com/clojure-emacs/cider/issues/3516)).
- [#4052](https://github.com/clojure-emacs/cider/pull/4052): Rename the inline
evaluation-result options into a consistent `cider-eval-result-*` family:
`cider-use-overlays` -> `cider-eval-result-display`,
`cider-result-overlay-position` -> `cider-eval-result-position`,
`cider-result-use-clojure-font-lock` and `cider-overlays-use-font-lock` ->
`cider-eval-result-font-lock`, `cider-interactive-eval-output-destination` ->
`cider-eval-output-destination`, and `cider-use-fringe-indicators` - [...]
-- [#4050](https://github.com/clojure-emacs/cider/pull/4050): Bump the injected
`cider-nrepl` to 0.61.0 (and `piggieback` to 0.6.2). Code formatting now honors
the project's cljfmt configuration, and the default `pprint` printer is backed
by `orchard.pp`.
+- [#4050](https://github.com/clojure-emacs/cider/pull/4050): Bump the injected
`cider-nrepl` to 0.61.0 (and `piggieback` to 0.6.2). Code formatting now honors
the project's cljfmt configuration.
- [#4047](https://github.com/clojure-emacs/cider/pull/4047): Render the doc
buffer's "See also" section as a bulleted list (one entry per line) instead of
an inline space-separated run, matching the ClojureDocs buffer.
- [#4046](https://github.com/clojure-emacs/cider/pull/4046): Make eldoc
asynchronous - the arglist/var lookup no longer blocks Emacs on an nREPL
round-trip as you move the cursor (it uses eldoc's callback protocol and
delivers the result when it arrives). Declines the eldoc slot when CIDER has
nothing, so other sources (e.g. clojure-lsp) compose cleanly.
- [#4035](https://github.com/clojure-emacs/cider/pull/4035): Rename
`cider-ensure-connected` to `cider-ensure-session` (it ensures a linked CIDER
session); the old name remains as an obsolete alias.
diff --git a/doc/modules/ROOT/pages/usage/pretty_printing.adoc
b/doc/modules/ROOT/pages/usage/pretty_printing.adoc
index c51a8e5eb2..c3bf45a67c 100644
--- a/doc/modules/ROOT/pages/usage/pretty_printing.adoc
+++ b/doc/modules/ROOT/pages/usage/pretty_printing.adoc
@@ -14,9 +14,9 @@ following possible values:
bound value of `+nrepl.middleware.print/*print-fn*+`, which defaults to the
equivalent of `clojure.core/pr`.
* `pr` to use the equivalent of `clojure.core/pr`.
-* `pprint` to use a fast `clojure.pprint/pprint`-style printer (this is the
-default). As of `cider-nrepl` 0.61 it's backed by `orchard.pp`; with older
-versions of the middleware it's the built-in `clojure.pprint/pprint`.
+* `pprint` to use the classic `clojure.pprint` printer (this is the default).
+* `orchard` to use `orchard.pp`, a fast pretty-printer bundled with
+`cider-nrepl`. See <<trying-orchard-pp,below>> for why you might want it.
* `fipp` to use the https://github.com/brandonbloom/fipp[Fast Idiomatic
Pretty-Printer]. This is approximately 5-10x faster than `clojure.core/pprint`.
* `puget` to use https://github.com/greglook/puget[Puget], which provides
@@ -28,27 +28,28 @@ flexible alternative to the libraries mentioned above.
IMPORTANT: For `fipp`, `puget`, and `zprint` printers to work, you need to add
the
respective dependency in your project explicitly.
-=== Why `orchard.pp` is the default
+[#trying-orchard-pp]
+=== Give `orchard.pp` a try
-The default `pprint` printer is backed by `orchard.pp` rather than
-`clojure.pprint`. It was made the default because it fits a tooling context
-better: it honors `+*print-length*+` and `+*print-level*+`, bounds the total
-size of what it prints (so a huge, deeply nested, or lazy/infinite value won't
-hang the REPL or flood the buffer), and it's noticeably faster.
`clojure.pprint`,
-by contrast, realizes lazy seqs in full as it prints, so an infinite sequence
-can hang it.
+The default `pprint` printer produces the `clojure.pprint` output everyone
+knows, but `orchard.pp` fits a tooling context better in a few ways:
-If you hit a value that `orchard.pp` renders differently than you'd like, you
-can switch back to the classic `clojure.pprint` output by pointing
-`cider-print-fn` at cider-nrepl's compatibility wrapper:
+* it's noticeably faster
+* it doesn't realize lazy seqs in full as it prints, so an infinite or huge
+lazy sequence won't hang the printer or trigger its side effects mid-print
+* it honors `+*print-length*+` and `+*print-level*+` and bounds the total size
+of what it prints, so a deeply nested value won't flood the REPL buffer
+
+Its output differs slightly from `clojure.pprint` in places, which is why it
+hasn't been made the default (yet), but it's well worth a try:
[source,lisp]
----
-(setq cider-print-fn "cider.nrepl.pprint/clojure-pprint")
+(setq cider-print-fn 'orchard)
----
-Note that this brings back `clojure.pprint`'s trade-offs: it fully realizes
lazy
-seqs and doesn't cap its output the way `orchard.pp` does.
+Like the default printer, it requires no extra dependencies - it ships with
+`cider-nrepl`.
Alternatively, `cider-print-fn` can be set to the namespace-qualified name of a
Clojure var whose function takes three arguments:
@@ -81,9 +82,9 @@ Here's one example:
TIP: You can also pick a printer for a single evaluation, without changing
`cider-print-fn`: the pretty-print menu (kbd:[C-c C-v f]) has a kbd:[-p]
-(`--print-fn=`) argument accepting `pr`, `pprint`, `fipp`, `puget`, `zprint`
-or the name of a custom var, honored by the pretty-printing commands invoked
-from the menu.
+(`--print-fn=`) argument accepting `pr`, `pprint`, `orchard`, `fipp`, `puget`,
+`zprint` or the name of a custom var, honored by the pretty-printing commands
+invoked from the menu.
== Limiting printed output
diff --git a/lisp/cider-client.el b/lisp/cider-client.el
index b0cca1f09e..f4e9a2a624 100644
--- a/lisp/cider-client.el
+++ b/lisp/cider-client.el
@@ -444,9 +444,13 @@ defaults to the equivalent of \\=`clojure.core/pr\\=`.
`pr' – to use the equivalent of \\=`clojure.core/pr\\=`.
-`pprint' – to use cider-nrepl's bundled pretty-printer, which is backed by
-\\=`orchard.pp\\=` (as of cider-nrepl 0.61.0; it used
\\=`clojure.pprint/pprint\\=`
-before). This is the default.
+`pprint' – to use a printer backed by \\=`clojure.pprint\\=`. This is the
+default.
+
+`orchard' – to use \\=`orchard.pp\\=`, a pretty-printer bundled with
+cider-nrepl. It's significantly faster than \\=`clojure.pprint\\=` and
+doesn't realize lazy sequences while printing them, although its output
+differs from that of \\=`clojure.pprint\\=` in places.
`fipp' – to use the Fast Idiomatic Pretty Printer, approximately 5-10x
faster than \\=`clojure.core/pprint\\=`.
@@ -465,6 +469,7 @@ nil."
:type '(choice (const nil)
(const pr)
(const pprint)
+ (const orchard)
(const fipp)
(const puget)
(const zprint)
@@ -512,11 +517,14 @@ requests `cider-doc' on a Java class or a member of the
class."
(defun cider--print-fn ()
"Return the value to send in the nrepl.middleware.print/print slot."
(pcase cider-print-fn
- (`pr "cider.nrepl.pprint/pr")
- (`pprint "cider.nrepl.pprint/pprint")
- (`fipp "cider.nrepl.pprint/fipp-pprint")
- (`puget "cider.nrepl.pprint/puget-pprint")
- (`zprint "cider.nrepl.pprint/zprint-pprint")
+ (`pr "cider.nrepl.pprint/pr")
+ ;; cider-nrepl 0.61 pointed its `pprint` var at orchard.pp, so target the
+ ;; explicit wrappers to keep `pprint` meaning clojure.pprint everywhere.
+ (`pprint "cider.nrepl.pprint/clojure-pprint")
+ (`orchard "cider.nrepl.pprint/orchard-pprint")
+ (`fipp "cider.nrepl.pprint/fipp-pprint")
+ (`puget "cider.nrepl.pprint/puget-pprint")
+ (`zprint "cider.nrepl.pprint/zprint-pprint")
(_ cider-print-fn)))
(defvar cider--print-options-mapping
diff --git a/lisp/cider-eval.el b/lisp/cider-eval.el
index e6009b2ed5..2910bb9067 100644
--- a/lisp/cider-eval.el
+++ b/lisp/cider-eval.el
@@ -1505,14 +1505,14 @@ passing arguments."
PROMPT, INITIAL-INPUT and HISTORY are as for `completing-read'. A value
outside the known printers is treated as a namespace-qualified var name."
(completing-read (or prompt "Print function: ")
- '("pr" "pprint" "fipp" "puget" "zprint")
+ '("pr" "pprint" "orchard" "fipp" "puget" "zprint")
nil nil initial-input history))
(defun cider-eval-pprint-menu--print-fn (value)
"Convert VALUE, a string, into a `cider-print-fn' value.
The known printers become symbols so `cider--print-fn' recognizes them;
any other value (a custom var name) is kept as a string."
- (if (member value '("pr" "pprint" "fipp" "puget" "zprint"))
+ (if (member value '("pr" "pprint" "orchard" "fipp" "puget" "zprint"))
(intern value)
value))
diff --git a/test/cider-client-tests.el b/test/cider-client-tests.el
index 460887f4d5..dee500a084 100644
--- a/test/cider-client-tests.el
+++ b/test/cider-client-tests.el
@@ -230,6 +230,19 @@
(setq cider-repl-type nil)
(expect (cider-repl-type-for-buffer) :to-be nil)))
+(describe "cider--print-fn"
+ (it "maps the pprint symbol to the clojure.pprint-backed printer"
+ (let ((cider-print-fn 'pprint))
+ (expect (cider--print-fn) :to-equal
"cider.nrepl.pprint/clojure-pprint")))
+
+ (it "maps the orchard symbol to the orchard.pp-backed printer"
+ (let ((cider-print-fn 'orchard))
+ (expect (cider--print-fn) :to-equal
"cider.nrepl.pprint/orchard-pprint")))
+
+ (it "passes a custom var name through unchanged"
+ (let ((cider-print-fn "my.ns/printer"))
+ (expect (cider--print-fn) :to-equal "my.ns/printer"))))
+
(describe "cider-nrepl-send-unhandled-request"
(it "returns the id of the request sent to nREPL server and ignores the
response"
(spy-on 'process-send-string :and-return-value nil)
diff --git a/test/cider-eval-tests.el b/test/cider-eval-tests.el
index 19bb2af817..b5f39e165b 100644
--- a/test/cider-eval-tests.el
+++ b/test/cider-eval-tests.el
@@ -487,6 +487,7 @@
(describe "cider-eval-pprint-menu--print-fn"
(it "interns a known printer to a symbol"
(expect (cider-eval-pprint-menu--print-fn "pprint") :to-equal 'pprint)
+ (expect (cider-eval-pprint-menu--print-fn "orchard") :to-equal 'orchard)
(expect (cider-eval-pprint-menu--print-fn "fipp") :to-equal 'fipp))
(it "keeps a custom var name as a string"
(expect (cider-eval-pprint-menu--print-fn "my.ns/printer") :to-equal
"my.ns/printer")))
