spacemacs/layers/+checkers/syntax-checking/README.org

#+TITLE: Syntax Checking layer

#+TAGS: checker|layer

[[file:img/flycheck.png]]

* 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]]
  - [[#enable-support-for-traditional-error-navigation][Enable support for traditional error navigation]]
  - [[#bitmaps][Bitmaps]]
  - [[#auto-hide-tooltips][Auto hide tooltips]]
- [[#key-bindings][Key bindings]]

* Description
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=

* 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=:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
    '((syntax-checking :variables syntax-checking-enable-tooltips nil)))
#+END_SRC

** Disabling by default
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=:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
    '((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=.

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

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.

** Enable support for 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= respectively allowing
to use alternative general emacs bindings instead of the spacemacs
specific ones. 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

** Bitmaps
If the original flycheck fringe bitmaps are more to your liking, you can set the
variable =syntax-checking-use-original-bitmaps= to =t=:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
    '((syntax-checking :variables syntax-checking-use-original-bitmaps t)))
#+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.

Default value of =syntax-checking-auto-hide-tooltips= is =nil=, and in that case tooltips
are kept open until the cursor is moved.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
    '((syntax-checking :variables syntax-checking-auto-hide-tooltips 10)))
#+END_SRC

* Key bindings

| Key binding | Description                                                  |
|-------------+--------------------------------------------------------------|
| ~SPC e b~   | check for errors now                                         |
| ~SPC e c~   | clear errors                                                 |
| ~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 v~   | verify flycheck setup                                        |
| ~SPC t s~   | toggle flycheck                                              |
| ~SPC e x~   | explain the error at point                                   |