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

Auto-completion layer

• Description
  • Features:
• Install
• Configuration
  • Key bindings
  • Snippets directories
  • Show snippets in auto-completion popup
  • Tooltips
  • Sort results by usage
  • Disable auto-completion in specific layers
  • Enable company globally
  • Replacing company by auto-complete
  • Add auto-completion in a layer
  • Completion back ends
  • Improved faces
• Key bindings
  • Company
  • Auto-complete
  • Yasnippet
  • Auto-yasnippet

Description

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

Features:

• Support for code completion with company or auto-complete for various language layers
• Frequency-based suggestions via company-statistics for company
• Integration with yasnippet and auto-yasnippet
• Automatic configuration of hippie-expand
• Automatic docstring tooltips are provided by 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:

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

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.

  (setq-default dotspacemacs-configuration-layers
                '((auto-completion :variables
                                   auto-completion-enable-snippets-in-popup t)))

Tooltips

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

  (setq-default dotspacemacs-configuration-layers
    '((auto-completion :variables
                      auto-completion-enable-help-tooltip t)))

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

  (setq-default dotspacemacs-configuration-layers
    '((auto-completion :variables
                      auto-completion-enable-help-tooltip 'manual)))

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 company-statistics package when company is used. The variable has no effect when auto-complete is used.

Beware: Sorting completion results is often done already by the completion backend, doing it again in company may degrate performance.

  (setq-default dotspacemacs-configuration-layers
    '((auto-completion :variables
                      auto-completion-enable-sort-by-usage t)))

Disable auto-completion in specific layers

See general documentation on how to 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 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:

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

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

  (setq-default
   dotspacemacs-configuration-layers
   '((auto-completion :variables
                      spacemacs-default-company-backends '(company-files company-capf))))

Improved faces

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

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

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