syntax-checking: Improved documentation and clean-ups
This commit is contained in:
Lucius Hu
parent
67bb7e69ec
commit
e13c5c7147
|
|
@ -6,75 +6,89 @@
|
|||
|
||||
* Table of Contents :TOC_5_gh:noexport:
|
||||
- [[#description][Description]]
|
||||
- [[#features][Features:]]
|
||||
- [[#install][Install]]
|
||||
- [[#layer][Layer]]
|
||||
- [[#enablingdisabling-tooltips][Enabling/Disabling tooltips]]
|
||||
- [[#disabling-by-default][Disabling by default]]
|
||||
- [[#enable-flycheck-globally][Enable flycheck globally]]
|
||||
- [[#error-list-pop-window-configuration][Error list pop window configuration]]
|
||||
- [[#error-list-interaction][Error list interaction]]
|
||||
- [[#enable-traditional-error-navigation][Enable traditional error navigation]]
|
||||
- [[#error-indication][Error indication]]
|
||||
- [[#auto-hide-tooltips][Auto hide tooltips]]
|
||||
- [[#features][Features]]
|
||||
- [[#installation][Installation]]
|
||||
- [[#customization][Customization]]
|
||||
- [[#enable-flycheck-manually][Enable Flycheck Manually]]
|
||||
- [[#tooltip-pop-up][Tooltip Pop-up]]
|
||||
- [[#error-list-pop-up][Error List Pop-up]]
|
||||
- [[#error-indicator-on-fringemargin][Error Indicator on Fringe/Margin]]
|
||||
- [[#enable-traditional-error-navigation][Enable Traditional Error Navigation]]
|
||||
- [[#key-bindings][Key bindings]]
|
||||
- [[#error-list-interaction][Error list interaction]]
|
||||
|
||||
* Description
|
||||
This layer adds on the fly syntax checking to all supported language layers.
|
||||
This layer adds on-the-fly syntax checking to all supported language layers.
|
||||
|
||||
** Features:
|
||||
- Support for automatic syntax checking with [[http://www.flycheck.org/][Flycheck]] for various language layers
|
||||
- Tooltip syntax errors with =popwin=
|
||||
** Features
|
||||
- Automatic syntax checking with [[http://www.flycheck.org/][Flycheck]] for various language layers.
|
||||
- Shows syntax error in pop-up window via [[https://github.com/flycheck/flycheck-pos-tip][flycheck-pos-tip]].
|
||||
|
||||
* Install
|
||||
** Layer
|
||||
To use this configuration layer, add it to your =~/.spacemacs=. You will need to
|
||||
add =syntax-checking= to the existing =dotspacemacs-configuration-layers= list in this
|
||||
file.
|
||||
|
||||
As this is a support layer you will also have to install at least one supported language
|
||||
layer for it to have any effect.
|
||||
|
||||
** Enabling/Disabling tooltips
|
||||
By default tooltips are enabled and used whenever it is possible.
|
||||
You can disable them by setting the variable =syntax-checking-enable-tooltips=
|
||||
to =nil=:
|
||||
* Installation
|
||||
To use this configuration layer, add =syntax-checking= to
|
||||
=dotspacemacs-configuration-layers= in your =~/.spacemacs=.
|
||||
|
||||
#+BEGIN_SRC emacs-lisp
|
||||
(setq-default dotspacemacs-configuration-layers
|
||||
'((syntax-checking :variables syntax-checking-enable-tooltips nil)))
|
||||
'(syntax-checking))
|
||||
#+END_SRC
|
||||
|
||||
** Disabling by default
|
||||
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 [[https://github.com/syl20bnr/spacemacs/issues/new][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.
|
||||
|
||||
* Customization
|
||||
** 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 default this to off
|
||||
by setting the variable =syntax-checking-enable-by-default= to =nil=:
|
||||
=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=.
|
||||
|
||||
#+BEGIN_SRC emacs-lisp
|
||||
(setq-default dotspacemacs-configuration-layers
|
||||
'((syntax-checking :variables syntax-checking-enable-by-default nil)))
|
||||
'((syntax-checking :variables
|
||||
syntax-checking-enable-by-default nil)))
|
||||
#+END_SRC
|
||||
|
||||
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=.
|
||||
=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.)
|
||||
|
||||
** Enable flycheck globally
|
||||
Normally Spacemacs goes a long mile to enable syntax checking only where it
|
||||
makes sense. If syntax checking support is missing it is normally only a
|
||||
matter of declaring it in the layer. The best approach in this case is
|
||||
to open an issue and ask for syntax checking support.
|
||||
** 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=.
|
||||
|
||||
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 the layer system.
|
||||
In the contrary by doing so the layer system cannot longer decide for
|
||||
which modes activating flycheck would bring any useful outcome.
|
||||
This may result in loading slow or not properly configured checkers
|
||||
as well as break some of the more advanced configuration settings
|
||||
of the layer system.
|
||||
#+BEGIN_SRC emacs-lisp
|
||||
(setq-default dotspacemacs-configuration-layers
|
||||
'((syntax-checking :variables
|
||||
syntax-checking-enable-tooltips nil)))
|
||||
#+END_SRC
|
||||
|
||||
** Error list pop window configuration
|
||||
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:
|
||||
|
||||
#+BEGIN_SRC emacs-lisp
|
||||
(setq-default dotspacemacs-configuration-layers
|
||||
'((syntax-checking :variables
|
||||
syntax-checking-auto-hide-tooltips 5)))
|
||||
#+END_SRC
|
||||
|
||||
** 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.
|
||||
|
||||
|
|
@ -97,52 +111,29 @@ For example, to have the pop window appear on the right side of the frame with
|
|||
syntax-checking-window-width 60
|
||||
#+END_SRC
|
||||
|
||||
** 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. |
|
||||
|
||||
** 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 [[https://www.flycheck.org/en/latest/user/error-interaction.html#navigate-errors][the manual]] for detailed explanation.
|
||||
|
||||
To do so, set =syntax-checking-use-standard-error-navigation= to non-nil.
|
||||
|
||||
#+BEGIN_SRC emacs-lisp
|
||||
(setq-default dotspacemacs-configuration-layers
|
||||
'((syntax-checking :variables syntax-checking-use-standard-error-navigation t)))
|
||||
#+END_SRC
|
||||
|
||||
** Error indication
|
||||
** 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 changed via =flycheck-indication-mode=.
|
||||
window. The position of the indicator can be changed by setting the variable
|
||||
=flycheck-indication-mode=.
|
||||
|
||||
If =flycheck-indication-mode= is set to =left-fringe= or =right-fringe=, a
|
||||
bitmap is used for fringe indicator. Where the bitmap is a string or a vector of
|
||||
bits, see =define-fringe-bitmap= for details. The default fringe bitmap in
|
||||
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 set to =left-margin= or =right-margin=, a
|
||||
string is used for margin indicator. Spacemacs doesn't change the margin string
|
||||
so the default value is defined in =flycheck=.
|
||||
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.
|
||||
If =flycheck-indication-mode= is =nil=, no indicator is displayed for errors.
|
||||
|
||||
To change the fringe or margin indicator, you can customize
|
||||
=syntax-checking-indicatin-symbol=, which is cons cell of a fringe bitmap and
|
||||
To change the indicator symbol, you can customize
|
||||
=syntax-checking-indicatin-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.
|
||||
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:
|
||||
|
||||
|
|
@ -163,19 +154,20 @@ Or say if you want to display the indicator on the =left-margin= as an asterisk,
|
|||
syntax-checking-indication-symbol '(nil . "*"))))
|
||||
#+END_SRC
|
||||
|
||||
** Auto hide tooltips
|
||||
You can set time in seconds after which tooltips are automatically hidden by setting
|
||||
the variable =syntax-checking-auto-hide-tooltips= to a positive number of seconds.
|
||||
** 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 [[https://www.flycheck.org/en/latest/user/error-interaction.html#navigate-errors][the manual]] for detailed explanation.
|
||||
|
||||
Default value of =syntax-checking-auto-hide-tooltips= is =nil=, and in that case tooltips
|
||||
are kept open until the cursor is moved.
|
||||
To do so, set =syntax-checking-use-standard-error-navigation= to non-nil.
|
||||
|
||||
#+BEGIN_SRC emacs-lisp
|
||||
(setq-default dotspacemacs-configuration-layers
|
||||
'((syntax-checking :variables syntax-checking-auto-hide-tooltips 10)))
|
||||
'((syntax-checking :variables
|
||||
syntax-checking-use-standard-error-navigation t)))
|
||||
#+END_SRC
|
||||
|
||||
|
||||
* Key bindings
|
||||
|
||||
| Key binding | Description |
|
||||
|
|
@ -186,8 +178,22 @@ are kept open until the cursor is moved.
|
|||
| ~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 |
|
||||
| ~SPC e S~ | set flycheck checker executable |
|
||||
| ~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 |
|
||||
|
||||
** 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. |
|
||||
|
|
|
|||
|
|
@ -20,6 +20,21 @@
|
|||
;; You should have received a copy of the GNU General Public License
|
||||
;; along with this program. If not, see <http://www.gnu.org/licenses/>.
|
||||
|
||||
;; Variables
|
||||
|
||||
(spacemacs|defc syntax-checking-enable-by-default t
|
||||
"If non-nil enable syntax-checking by default in `prog-mode'."
|
||||
'(boolean))
|
||||
|
||||
(spacemacs|defc syntax-checking-enable-tooltips t
|
||||
"If non-nil display tooltips when hovering on errors."
|
||||
'(boolean))
|
||||
|
||||
(spacemacs|defc syntax-checking-auto-hide-tooltips nil
|
||||
"Auto hide tooltips after the given number of seconds.
|
||||
If non-positive or nil, do not hide tooltip."
|
||||
'(number))
|
||||
|
||||
;; a small circle used for flycheck-indication-mode
|
||||
(define-fringe-bitmap 'syntax-checking--fringe-indicator
|
||||
(vector #b00000000
|
||||
|
|
@ -40,20 +55,6 @@
|
|||
#b00000000
|
||||
#b00000000))
|
||||
|
||||
;; Variables
|
||||
|
||||
(spacemacs|defc syntax-checking-enable-tooltips t
|
||||
"If non nil some feedback are displayed in tooltips."
|
||||
'(boolean))
|
||||
|
||||
(spacemacs|defc syntax-checking-auto-hide-tooltips nil
|
||||
"If non-nil and positive number, auto hide tooltips after number of seconds."
|
||||
'(natnum))
|
||||
|
||||
(spacemacs|defc syntax-checking-enable-by-default t
|
||||
"Enable syntax-checking by default."
|
||||
'(boolean))
|
||||
|
||||
(define-obsolete-variable-alias 'syntax-checking-use-original-bitmaps
|
||||
'syntax-checking-indication-symbol "July 2022"
|
||||
"If non-nil, use the original bitmaps from flycheck.")
|
||||
|
|
@ -62,11 +63,11 @@
|
|||
'(syntax-checking--fringe-indicator . nil)
|
||||
"The fringe bitmap or margin symbol used for `flycheck-indication-mode'.
|
||||
|
||||
The value is a cons cell (BITMAP . MARGIN-STR), in which a nil value means the default
|
||||
symbol is chosen by `flycheck'.
|
||||
The value is a cons cell (BITMAP . MARGIN-STR), in which a nil value means the
|
||||
default indicator is chosen by `flycheck'.
|
||||
|
||||
BITMAP is a bitmap displayed in left or right fringe, which defaults to
|
||||
a small circle as defined in `syntax-checking--fringe-indicator'.
|
||||
BITMAP is a bitmap symbol displayed in left or right fringe, which defaults
|
||||
to a small circle as defined in `syntax-checking--fringe-indicator'.
|
||||
MARGIN-STR is a string to be displayed in the margin (Defaults to nil).
|
||||
|
||||
Note only one of BITMAP and MARGIN-STR is used, which is dictated by
|
||||
|
|
@ -97,7 +98,6 @@ Note only one of BITMAP and MARGIN-STR is used, which is dictated by
|
|||
(integer :tag "Width")
|
||||
(float :tag "Width (%)")))
|
||||
|
||||
|
||||
;; internals
|
||||
(defvar syntax-checking--buffer-config
|
||||
(list "^\\*Flycheck.+\\*$"
|
||||
|
|
|
|||
|
|
@ -22,8 +22,7 @@
|
|||
|
||||
|
||||
(defun spacemacs/enable-flycheck (mode)
|
||||
"Use flycheck in MODE by default, if `syntax-checking-enable-by-default' is
|
||||
true."
|
||||
"Use flycheck in MODE by default, if `syntax-checking-enable-by-default' t."
|
||||
(when (and syntax-checking-enable-by-default
|
||||
(listp flycheck-global-modes)
|
||||
(not (eq 'not (car flycheck-global-modes))))
|
||||
|
|
@ -43,6 +42,5 @@ If the error list is visible, hide it. Otherwise, show it."
|
|||
(interactive)
|
||||
(if (flycheck-get-error-list-window)
|
||||
(switch-to-buffer flycheck-error-list-buffer)
|
||||
(progn
|
||||
(flycheck-list-errors)
|
||||
(switch-to-buffer-other-window flycheck-error-list-buffer))))
|
||||
(flycheck-list-errors)
|
||||
(switch-to-buffer-other-window flycheck-error-list-buffer)))
|
||||
|
|
|
|||
|
|
@ -20,6 +20,10 @@
|
|||
;; You should have received a copy of the GNU General Public License
|
||||
;; along with this program. If not, see <http://www.gnu.org/licenses/>.
|
||||
|
||||
;;; Commentary:
|
||||
|
||||
;;; Code:
|
||||
|
||||
|
||||
(defconst syntax-checking-packages
|
||||
'(
|
||||
|
|
@ -27,10 +31,10 @@
|
|||
flycheck-pos-tip
|
||||
popwin))
|
||||
|
||||
|
||||
(defun syntax-checking/init-flycheck ()
|
||||
(use-package flycheck
|
||||
:defer t
|
||||
:spacediminish (" ⓢ" " s")
|
||||
:init
|
||||
(progn
|
||||
(spacemacs|add-transient-hook prog-mode-hook
|
||||
|
|
@ -58,12 +62,12 @@
|
|||
:evil-leader "ts"))
|
||||
:config
|
||||
(progn
|
||||
(spacemacs|diminish flycheck-mode " ⓢ" " s")
|
||||
;; Custom fringe/margin indicator
|
||||
(pcase-let ((`(,bitmap . ,margin-str) syntax-checking-indication-symbol))
|
||||
(when (booleanp syntax-checking-use-original-bitmaps)
|
||||
(warn "`syntax-checking-use-original-bitmaps' is deprecated. Use `syntax-checking-indication-symbol' instead.")
|
||||
(setq bitmap (unless syntax-checking-use-original-bitmaps 'syntax-checking--fringe-indicator)))
|
||||
(setq bitmap (unless syntax-checking-use-original-bitmaps
|
||||
'syntax-checking--fringe-indicator)))
|
||||
(flycheck-redefine-standard-error-levels margin-str bitmap))
|
||||
|
||||
(evilified-state-evilify-map flycheck-error-list-mode-map
|
||||
|
|
@ -77,9 +81,9 @@
|
|||
(defun syntax-checking/init-flycheck-pos-tip ()
|
||||
(use-package flycheck-pos-tip
|
||||
:if syntax-checking-enable-tooltips
|
||||
:defer t
|
||||
:after (flycheck)
|
||||
:init
|
||||
(with-eval-after-load 'flycheck
|
||||
(progn
|
||||
(flycheck-pos-tip-mode)
|
||||
(setq flycheck-pos-tip-timeout (or syntax-checking-auto-hide-tooltips 0)))))
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue