TakeV/spacemacs
Archived
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

syntax-checking: Improved documentation and clean-ups

Browse source
This commit is contained in:
Lucius Hu 2022-07-14 23:26:24 -04:00
parent 67bb7e69ec
commit e13c5c7147
No known key found for this signature in database
GPG key ID: 7E474E82E29B5A7A
4 changed files with 134 additions and 126 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

200
layers/+checkers/syntax-checking/README.org
View file

@ -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. |

38
layers/+checkers/syntax-checking/config.el
View file

@ -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.+\\*$"

8
layers/+checkers/syntax-checking/funcs.el
View file

@ -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)))

14
layers/+checkers/syntax-checking/packages.el
View file

@ -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)))))