spacemacs/layers/+completion/auto-completion/README.org

#+TITLE: Auto-completion layer

#+TAGS: completion|layer

* Table of Contents                     :TOC_5_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#install][Install]]
- [[#configuration][Configuration]]
  - [[#key-bindings][Key bindings]]
  - [[#snippets-directories][Snippets directories]]
  - [[#show-snippets-in-auto-completion-popup][Show snippets in auto-completion popup]]
  - [[#tooltips][Tooltips]]
  - [[#sort-results-by-usage][Sort results by usage]]
  - [[#disable-auto-completion-in-specific-layers][Disable auto-completion in specific layers]]
  - [[#enable-company-globally][Enable company globally]]
  - [[#replacing-company-by-auto-complete][Replacing company by auto-complete]]
  - [[#add-auto-completion-in-a-layer][Add auto-completion in a layer]]
  - [[#completion-back-ends][Completion back ends]]
  - [[#improved-faces][Improved faces]]
- [[#key-bindings-1][Key bindings]]
  - [[#company][Company]]
  - [[#auto-complete][Auto-complete]]
  - [[#yasnippet][Yasnippet]]
  - [[#auto-yasnippet][Auto-yasnippet]]

* Description
This layer adds auto-completion to all supported language layers.

** Features:
- Support for code completion with [[http://company-mode.github.io/][company]] or [[https://github.com/auto-complete/auto-complete][auto-complete]] for various language layers
- Frequency-based suggestions via [[https://github.com/company-mode/company-statistics][company-statistics]] for =company=
- Integration with [[https://github.com/capitaomorte/yasnippet][yasnippet]] and [[https://github.com/abo-abo/auto-yasnippet][auto-yasnippet]]
- Automatic configuration of [[https://www.emacswiki.org/emacs/HippieExpand][hippie-expand]]
- Automatic docstring tooltips are provided by [[https://github.com/expez/company-quickhelp][company-quickhelp]]

* Install
To use this configuration layer, add it to your =~/.spacemacs=. You will need to
add =auto-completion= 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.

* Configuration
** Key bindings
You can customize the user experience of auto-completion with the following
layer variables:
1. =auto-completion-return-key-behavior= set the action to perform when the
   ~RET~ key is pressed, the possible values are:
   - =complete= completes with the current selection
   - =nil= does nothing
2. =auto-completion-tab-key-behavior= set the action to perform when the ~TAB~
   key is pressed, the possible values are:
   - =complete= completes with the current selection
   - =cycle= completes the common prefix and cycle between candidates
   - =nil= does nothing
3. =auto-completion-complete-with-key-sequence= is a string of two characters
   denoting a key sequence that will perform a =complete action= if the sequence
   has been entered quickly enough. If its value is =nil= then the feature is
   disabled.
4. =auto-completion-complete-with-key-sequence-delay= is the number of seconds
   to wait for the auto-completion key sequence to be entered. The default value
   is 0.1 seconds.
5. =auto-completion-idle-delay= is the number of seconds to wait before suggesting
   completions. The default value is 0.2 seconds. Set to =nil= to disable
   automatic suggestions (the ~TAB~ key will still perform completion).
   Set to 0.0 for optimal results with lsp mode.
6. =auto-completion-minimum-prefix-length= is the minimum number of characters
   which must be entered before completions will be suggested automatically.
   Set to 1 for optimal results with lsp mode.

The default configuration of the layer is:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(
    (auto-completion :variables
                     auto-completion-return-key-behavior 'complete
                     auto-completion-tab-key-behavior 'cycle
                     auto-completion-complete-with-key-sequence nil
                     auto-completion-complete-with-key-sequence-delay 0.1
                     auto-completion-minimum-prefix-length 2
                     auto-completion-idle-delay 0.2
                     auto-completion-private-snippets-directory nil
                     auto-completion-enable-snippets-in-popup nil
                     auto-completion-enable-help-tooltip nil
                     auto-completion-use-company-box nil
                     auto-completion-enable-sort-by-usage nil)))
#+END_SRC

~jk~ is a good candidate for =auto-completion-complete-with-key-sequence= if
you don't use it already.

** Snippets directories
The following directories are added by default:
- =~/.emacs.d/elpa/yasnippet-xxxxx/snippets=
- =~/.emacs.d/layers/auto-completion/snippets=
- =~/.emacs.d/private/snippets= (conditional to the value of =auto-completion-private-snippets-directory=)
- =~/.spacemacs.d/snippets= (conditional to the existence of =~/.spacemacs.d= directory)

You can provide additional directories by setting the variable =auto-completion-private-snippets-directory=
which can either take a single path as string or a list of paths.

If its value is =nil= then the path =~/.emacs.d/private/snippets= is used.

** Show snippets in auto-completion popup
By default, snippets are not shown in the auto-completion popup. To show them in
the popup, set the variable =auto-completion-enable-snippets-in-popup= to =t=.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
                '((auto-completion :variables
                                   auto-completion-enable-snippets-in-popup t)))
#+END_SRC

** Tooltips
To enable automatic docstring tooltips set =auto-completion-enable-help-tooltip=
to =t=.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
    '((auto-completion :variables
                      auto-completion-enable-help-tooltip t)))
#+END_SRC

To enable manual non-automatic invocation of docstring tooltips, set it to
=manual=. The tooltip can be invoked manually by pressing ~M-h~.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
    '((auto-completion :variables
                      auto-completion-enable-help-tooltip 'manual)))
#+END_SRC

However the tooltip may overlap on text on macOS, you can use =company-box= on
Emacs 26+ by setting =auto-completion-use-company-box= to =t=.

** Sort results by usage
To enable sorting auto-completion results by their usage frequency set
=auto-completion-enable-sort-by-usage= to =t=.
This feature is provided by the [[https://github.com/company-mode/company-statistics][company-statistics]] package when =company=
is used. The variable has no effect when =auto-complete= is used.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
    '((auto-completion :variables
                      auto-completion-enable-sort-by-usage t)))
#+END_SRC

** Disable auto-completion in specific layers
See general documentation on how to [[https://github.com/syl20bnr/spacemacs/blob/develop/doc/DOCUMENTATION.org#disabling-layer-services-in-other-layers][disable a layer for specific layers]].

** Enable company globally
It can be done by adding =(global-company-mode)= in the
=dotspacemacs/user-config= function of your dotfile. But it is not recommended
to do so, you should instead open an issue to ask for auto-completion support
for the major-modes where it is missing.

If you choose to use =(global-company-mode)= then you loose some advantages
provided by the layer system like [[https://github.com/syl20bnr/spacemacs/blob/develop/doc/DOCUMENTATION.org#disabling-layer-services-in-other-layers][disabling auto-completion for specific layers]].

** Replacing company by auto-complete
You can disable =company= by adding it to the =dotspacemacs-excluded-packages=
variable, then you are free to enable =auto-complete= globally.

** Add auto-completion in a layer
Here is an example to add =company= auto-completion to python buffers via the
package =company-anaconda=.

In the file =packages.el= of the python layer:

#+BEGIN_SRC emacs-lisp
  ;; Add the relevant packages to the layer
  ;; here it is `company-anaconda'
  (setq python-packages
    '(...
      (company-anaconda :toggle (configuration-layer/package-used-p 'company))
      ...))

  (defun python/init-company-anaconda ()
    (use-package company-anaconda
      :defer t
      :init
      (spacemacs|add-company-backends
         :backends company-anaconda
         :modes python-mode)))
#+END_SRC

** Completion back ends
Many spacemacs layers (e.g., python, html, haskell) configure company mode
backends to provide mode-specific completion. These modes will include
completion backends specified in the =spacemacs-default-company-backends=
variable. The defaults should work well, but you can configure this variable in
your =.spacemacs= file with (e.g.)

#+BEGIN_SRC emacs-lisp
  (setq-default
   dotspacemacs-configuration-layers
   '((auto-completion :variables
                      spacemacs-default-company-backends '(company-files company-capf))))
#+END_SRC

** Improved faces
For nicer-looking faces, try adding the following to `custom-set-faces` in your dotspacemacs file.

#+BEGIN_SRC emacs-lisp
  (custom-set-faces
   '(company-tooltip-common
     ((t (:inherit company-tooltip :weight bold :underline nil))))
   '(company-tooltip-common-selection
     ((t (:inherit company-tooltip-selection :weight bold :underline nil)))))
#+END_SRC

* Key bindings
** Company

| Key binding | Description                                                                                          |
|-------------+------------------------------------------------------------------------------------------------------|
| ~C-d~       | open minibuffer with documentation of thing at point in company dropdown                             |
| ~C-/~       | show candidates in Helm or Ivy (for fuzzy searching)                                                 |
| ~C-M-/~     | filter the company dropdown menu                                                                     |
| ~M-h~       | show current candidate's documentation in a tooltip (requires =auto-completion-enable-help-tooltip=) |

Vim Style:

| Key binding | Description                                  |
|-------------+----------------------------------------------|
| ~C-j~       | (vim style) go down in company dropdown menu |
| ~C-k~       | (vim style) go up in company dropdown menu   |
| ~C-l~       | (vim style) complete selection               |

Emacs style:

| Key binding | Description                                    |
|-------------+------------------------------------------------|
| ~C-n~       | (emacs style) go down in company dropdown menu |
| ~C-p~       | (emacs style) go up in company dropdown menu   |

** Auto-complete

| Key binding | Description                                                          |
|-------------+----------------------------------------------------------------------|
| ~C-j~       | select next candidate                                                |
| ~C-k~       | select previous candidate                                            |
| ~TAB~       | expand selection or select next candidate                            |
| ~S-TAB~     | select previous candidate                                            |
| ~RET~       | complete word, if word is already completed insert a carriage return |

** Yasnippet

| Key binding | Description                                                    |
|-------------+----------------------------------------------------------------|
| ~M-/~       | Expand a snippet if text before point is a prefix of a snippet |
| ~SPC i s~   | List all current yasnippets for inserting                      |

** Auto-yasnippet

| Key binding | Description                                                               |
|-------------+---------------------------------------------------------------------------|
| ~SPC i S c~ | create a snippet from an active region                                    |
| ~SPC i S e~ | Expand the snippet just created with ~SPC i y~                            |
| ~SPC i S w~ | Write the snippet inside =private/snippets= directory for future sessions |