diff --git a/layers/+checkers/syntax-checking/README.org b/layers/+checkers/syntax-checking/README.org index ab35d4f82..89c815324 100644 --- a/layers/+checkers/syntax-checking/README.org +++ b/layers/+checkers/syntax-checking/README.org @@ -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. | diff --git a/layers/+checkers/syntax-checking/config.el b/layers/+checkers/syntax-checking/config.el index 41caceaf8..44e249cd2 100644 --- a/layers/+checkers/syntax-checking/config.el +++ b/layers/+checkers/syntax-checking/config.el @@ -20,6 +20,21 @@ ;; You should have received a copy of the GNU General Public License ;; along with this program. If not, see . +;; 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.+\\*$" diff --git a/layers/+checkers/syntax-checking/funcs.el b/layers/+checkers/syntax-checking/funcs.el index 1831794b1..1ae65c590 100644 --- a/layers/+checkers/syntax-checking/funcs.el +++ b/layers/+checkers/syntax-checking/funcs.el @@ -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))) diff --git a/layers/+checkers/syntax-checking/packages.el b/layers/+checkers/syntax-checking/packages.el index b4e2f7a06..70a55665b 100644 --- a/layers/+checkers/syntax-checking/packages.el +++ b/layers/+checkers/syntax-checking/packages.el @@ -20,6 +20,10 @@ ;; You should have received a copy of the GNU General Public License ;; along with this program. If not, see . +;;; 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)))))