Table of Contents

Syntax Checking layer

Table of ContentsClose


1. Description

This layer adds on-the-fly syntax checking to all supported language layers.

1.1. Features:

  • Automatic syntax checking with Flycheck for various language layers.
  • Shows syntax error in pop-up window via flycheck-pos-tip.

2. Installation

To use this configuration layer, add syntax-checking to dotspacemacs-configuration-layers in your ~/.spacemacs.

(setq-default dotspacemacs-configuration-layers

You will need to install at least one supported language layer for syntax-checking to take effect. Some syntax checkers requires external dependencies, consult the respective language layer for more information.

If syntax checking support is missing for a language, please open an issue to ask for syntax checking support.

Some guides on the web suggest to enable flycheck globally by setting (global-flycheck-mode) in your dotspacemacs/user-config. This is neither necessary nor is it good for our layer system. In the contrary by doing so the layer system can longer decide for which modes activating flycheck would bring any useful outcome. This may result in slow loading or not properly configured checkers as well as breaking some of the more advanced configuration settings of the layer system.

3. Customization

3.1. Enable Flycheck Manually

By default, syntax-checking is enabled in all available major modes (except for emacs-lisp-mode) and may be toggled off with SPC t s. You can turn off this feature and make flycheck manually available by setting the variable syntax-checking-enable-by-default to nil.

(setq-default dotspacemacs-configuration-layers
              '((syntax-checking :variables
                                 syntax-checking-enable-by-default nil)))

If you want more fine-grained control, you can configure the variable flycheck-global-modes instead. Note that this variable should be manipulated in dotspacemacs/user-config. (Because dotspacemacs/user-config is evaluated after layers so your settings won't be overridden.)

3.2. Tooltip Pop-up

By default, tooltips are shown when the point is on erros after a short delay. You can disable them by setting the variable syntax-checking-enable-tooltips to nil.

(setq-default dotspacemacs-configuration-layers
              '((syntax-checking :variables
                                 syntax-checking-enable-tooltips nil)))

By default the tooltip pop-up window persists. If you prefer it to be hidden automatically after a certain number of seconds, you can set the variable syntax-checking-auto-hide-tooltips to a positive value. For example, to hide it after 5 seconds:

(setq-default dotspacemacs-configuration-layers
              '((syntax-checking :variables
                                 syntax-checking-auto-hide-tooltips 5)))

Because flycheck almost immediately shows the tooltip pop-up window it can potentially hide code before or after the current line you're on. If you prefer it to show up only after a certain amount of time has passed, you can set the variable syntax-checking-tooltips-delay to a positive value. Otherwise flychecks default value of 0.9 is used. Example:

(setq-default dotspacemacs-configuration-layers
              '((syntax-checking :variables
                                 syntax-checking-tooltips-delay 5)))

3.3. Error List Pop-up

By default, the flycheck-error-list-mode is displayed in a pop window to the bottom of the frame, with 30% of the frame's height.

You can customize where the pop window is shown by setting the variable syntax-checking-window-position to one of 'bottom, 'top, 'left, and 'right.

You can also set the initial window width and height by setting syntax-checking-window-width and syntax-checking-window-height respectively, where an integer value is the number of columns it takes while a float value is the relative size to the current frame.

For example, to have the pop window appear on the right side of the frame with 60 columns:

(setq-default dotspacemacs-configuration-layers
  '((syntax-checking :variables
                     syntax-checking-window-position 'right
                     syntax-checking-window-width 60

3.4. Error Indicator on Fringe/Margin

By default, errors are indicated by a small circle on the left fringe of each window. The position of the indicator can be changed by setting the variable flycheck-indication-mode.

If flycheck-indication-mode is left-fringe or right-fringe, a bitmap is displayed on the fringe to indicate an error. (A bitmap is a string or a vector of bits, see define-fringe-bitmap for details.) The default fringe bitmap in Spacemacs is a small solid circle.

If flycheck-indication-mode is to left-margin or right-margin, a string displayed on the fringe to indicate an error. Spacemacs doesn't change the margin string so the default value is defined in flycheck.

If flycheck-indication-mode is nil, no indicator is displayed for errors.

To change the indicator symbol, you can customize syntax-checking-indication-symbol, which is a cons cell of a fringe bitmap and margin string. When any of the element is nil, it's left to flycheck to determine a default indicator. (At any time, only one of the fringe bitmap and margin string is needed, since error indicator cannot be both *-fringe and *-margin. So when setting this variable, you only need too set the one you need and leave the other one nil.)

For example, if you prefer the original fringe bitmap to Spacemacs's default:

(setq-default dotspacemacs-configuration-layers
  '((syntax-checking :variables
                     ;; unset the first value to use flycheck's default fringe
                     syntax-checking-indication-symbol '(nil . nil)))

Or say if you want to display the indicator on the left-margin as an asterisk,

(setq-default dotspacemacs-configuration-layers
  '((syntax-checking :variables
                     flycheck-indication-mode 'left-margin
                     ;; set the second value for custom margin string
                     syntax-checking-indication-symbol '(nil . "*"))))

3.5. Enable Traditional Error Navigation

By default Spacemacs takes care to call the right function to jump to the next or previous error. However if wished flycheck can also override next-error and previous-error, allowing to use alternative general emacs bindings instead of those Spacemacs specific ones. See the manual for detailed explanation.

To do so, set syntax-checking-use-standard-error-navigation to non-nil.

(setq-default dotspacemacs-configuration-layers
              '((syntax-checking :variables
                                 syntax-checking-use-standard-error-navigation t)))

4. Key bindings

Key binding Description
SPC e b check for errors now
SPC e c clear errors
SPC e d disable a checker in current buffer
SPC e h describe flycheck checker
SPC e l display a list of all the errors
SPC e L display a list of all the errors and focus the errors buffer
SPC e s set flycheck checker in current buffer
SPC e S set flycheck checker executable in current buffer
SPC e v verify flycheck setup
SPC t s toggle flycheck
SPC e x explain the error at point

4.1. Error list interaction

Inside flycheck-error-list-mode pop window, the following key bindings are available:

Key binding Description
j~/~k Move focus to next/previous error and show it in the main buffer.
J~/~K Move focus to next/previous error.
RET Go to the selected error.
f Filter errors by urgency.
F Remove any filter.
g Refresh error list.
e Explain the selected error, if the checker supports it.

Author: root

Created: 2024-06-14 Fri 18:50