diff options
Diffstat (limited to 'doc/navigating_stacktraces.md')
| -rw-r--r-- | doc/navigating_stacktraces.md | 86 |
1 files changed, 51 insertions, 35 deletions
diff --git a/doc/navigating_stacktraces.md b/doc/navigating_stacktraces.md index 14c3ff64..934ff5f1 100644 --- a/doc/navigating_stacktraces.md +++ b/doc/navigating_stacktraces.md @@ -1,8 +1,10 @@ -CIDER comes with a powerful solution to the problem of verbose Clojure -stacktraces. Stacktraces are presented in a special major mode -(`cider-stacktrace-mode`), which gives you the possibility to filter out certain -stack frames and some handy ways to navigate causes. You'll also be able to go -to the code in question with a single keystroke. +CIDER comes with a powerful solution for dealing with Clojure +stacktraces. CIDER presents stack traces in a special major mode, +`cider-stacktrace-mode`, which gives you gives you some key features: + +- the ability to filter out certain stack frames to reduce clutter +- some handy ways to navigate to the cause of the exception +- the ability to jump straight to code with a single keystroke Command | Keyboard shortcut | Description ---------------------------------------|-------------------------------------|-------------- @@ -24,33 +26,33 @@ Command | Keyboard shortcut | D `cider-stacktrace-show-only-project` |<kbd>p</kbd> | Toggle display only project frames `cider-stacktrace-toggle-all` |<kbd>a</kbd> | Toggle display of all frames -You can configure whether the error buffer with stacktraces should be automatically -shown on error. By default it will be displayed, but you can change this: +By default, when an exception occurs, CIDER will display the exception +in an error buffer using `cider-stacktrace-mode`. You can suppress +this behavior, however: ```el (setq cider-show-error-buffer nil) ``` -At times, the error being displayed will originate from a bug in the -CIDER code itself. These internal errors might frequently occur and -interrupt your workflow, but you might not want to suppress **all** -stacktrace buffers via the `cider-show-error-buffer` variable as -above; instead, you might only want to suppress *this specific type* -of internal error. The stacktrace buffers provide such an option when -displaying an internal error. A toggle button will be displayed with -the error type's name, and you can toggle whether this particular type -of error will cause the stacktrace buffer to automatically show -itself. The toggle button controls this behavior only during the -current Emacs session, but if you would like to make the suppression -more permanent, you can do so by customizing the -`cider-stacktrace-suppressed-errors` variable. The buffer will also -provide a direct link to the bug reporting page to help facilitate its -diagnosis and repair. +At times, the error being displayed will originate from a bug in CIDER +itself. These internal errors might frequently occur and interrupt +your workflow, but you might not want to suppress **all** stacktrace +buffers by using `cider-show-error-buffer`. Instead, you might only +want to suppress *this specific type* of internal error. The +stacktrace buffers provide such an option when displaying an internal +error. A toggle button will be displayed with the error type's name, +and you can toggle whether this particular type of error will cause +the stacktrace buffer to automatically show itself. The toggle button +controls this behavior only during the current Emacs session, but if +you would like to make the suppression more permanent, you can do so +by customizing the `cider-stacktrace-suppressed-errors` variable. The +buffer will also provide a direct link to the bug reporting page to +help facilitate its diagnosis and repair. Independently of the value of `cider-show-error-buffer` or -`cider-stacktrace-suppressed-errors`, the error buffer is always -generated in the background. Use `cider-selector` (`C-c M-s`) to visit -this buffer. +`cider-stacktrace-suppressed-errors`, CIDER always generates the error +buffer in the background. You can use `cider-selector` (<kbd>C-c M-s</kbd>) to +visit this buffer if you decide that you need to. There are two more selective strategies for the error buffer: @@ -59,18 +61,23 @@ There are two more selective strategies for the error buffer: (setq cider-show-error-buffer 'only-in-repl) ``` -* To disable auto-selection of the error buffer when it's displayed: +To disable auto-selection of the error buffer when it's displayed: ```el (setq cider-auto-select-error-buffer nil) ``` -* Error buffer stacktraces may be filtered by default. Valid filter -types include `java`, `clj`, `repl`, `tooling`, and `dup`. There are -also "positive" filtering types. The value `project` will cause only -project frames to be shown or `all` will force all stackframes to be -shown. Note that `project` and `all` are mutually exclusive. Whichever -one is first will determine the behavior if they are both present. +CIDER helps you cut through the clutter of Clojure stacktraces by +allowing you to apply a list of filters using the +`cider-stacktrace-default-filters` variable. Valid filter types +include `java`, `clj`, `repl`, `tooling`, and `dup`. Specifying one of +these filters will remove the corresponding frames from the stacktrace +display. There are also "positive" filtering types (reverse filters) +that specify what should be shown. The value of `project`, for +instance, will cause only project frames to be shown, and `all` will +force all stackframes to be shown. Note that `project` and `all` are +mutually exclusive. Whichever one is first will determine the behavior +if they are both present. ```el (setq cider-stacktrace-default-filters '(tooling dup)) @@ -78,9 +85,18 @@ one is first will determine the behavior if they are both present. (setq cider-stacktrace-default-filters '(project)) ``` -* Error messages may be wrapped for readability. If this value is nil, messages -will not be wrapped; if it is truthy but non-numeric, the default `fill-column` -will be used. +Finally, CIDER can wrap error messages when they are displayed in a +buffer to help improve their readability. CIDER uses +`cider-stacktrace-fill-column` for this, which can take on three +types of values: + +- `nil`: The error is not wrapped. +- numeric: The error message is wrapped to the specified fill column. +- Something truthy but non-numeric: The error message is wrapped using + the value of `fill-column`. + +The following will cause error messages to be wrapped to 80 columns, +for instance: ```el (setq cider-stacktrace-fill-column 80) |