Auto-completion layer
Table of ContentsClose
- 1. Description
- 2. Install
- 3. Configuration
- 4. Key Bindings
1 Description
This layer provides auto-completion to Spacemacs.
The following completion engines are supported:
Snippets are supported via yasnippet and auto-yasnippet.
This layer also configures hippie-expand
.
2 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.
3 Configuration
3.1 Key bindings
You can customize the user experience of auto-completion with the following layer variables:
auto-completion-return-key-behavior
set the action to perform when theRET
key is pressed, the possible values are:complete
completes with the current selectionnil
does nothing
auto-completion-tab-key-behavior
set the action to perform when theTAB
key is pressed, the possible values are:complete
completes with the current selectioncycle
completes the common prefix and cycle between candidatesnil
does nothing
auto-completion-complete-with-key-sequence
is a string of two characters denoting a key sequence that will perform acomplete
action if the sequence as been entered quickly enough. If its value isnil
then the feature is disabled.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.
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-private-snippets-directory nil) ))
jk
is a good candidate for auto-completion-complete-with-key-sequence
if
you don't use it already.
3.2 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 take a string in case of
a single path or a list of paths.
If its value is nil
then the path ~/.emacs.d/private/snippets
is used.
3.3 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)))
3.4 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)))
3.5 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.
(setq-default dotspacemacs-configuration-layers '((auto-completion :variables auto-completion-enable-sort-by-usage t)))
3.6 Enable company or auto-complete globally
By default Spacemacs enables auto-completion explicitly for each supported
major-mode, it means that company
and auto-complete
are not enabled
globally, it allows more flexibility to choose an auto-completion engine
for a given mode.
You may want to enable company globally to get auto-completion
everywhere even in the modes which are not configured by Spacemacs. To do
so, you just have to add (global-company-mode)
in the
dotspacemacs/user -config
function of your dotfile.
Note that if you want to enable auto-complete
globally you will have to
disable company
first, see the next section to do so.
3.7 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.
3.8 Add auto-completion in a layer
Here is an example to add company
auto-completion to python buffer:
3.8.1 In config.el
;; Define the buffer local company backend variable (spacemacs|defvar-company-backends python-mode)
3.8.2 In packages.el
;; Add the relevant packages to the layer (setq python-packages '(... company (company-anaconda :toggle (configuration-layer/package-usedp 'company)) ...)) ;; Hook company to python-mode (defun python/post-init-company () (spacemacs|add-company-hook python-mode)) ;; Add the backend to the major-mode specific backend list (defun python/init-company-anaconda () (use-package company-anaconda :defer t :init (push 'company-anaconda company-backends-python-mode)))
3.9 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))))
3.10 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)))))
4 Key Bindings
4.1 Company
Key Binding | Description |
---|---|
C-d |
open minibuffer with documentation of thing at point in company dropdown |
C-/ |
show candidates in Helm (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-f |
(emacs style) complete selection |
C-n |
(emacs style) go down in company dropdown menu |
C-p |
(emacs style) go up in company dropdown menu |
4.2 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 |
return |
complete word, if word is already completed insert a carriage return |