74fdbb6795
Enabling a company backend for a specific mode was a tedious tasks with code scattered at different locations, one for local variable definitions, one for company hook function definitions and another where the backends were pushed to the local variables (which was problematic, since we ended up pushing the same backends over and over again with `SPC f e R`, pushes have been replaced by add-to-list calls in the new macro). All these steps are now put together at one place with the new macro spacemacs|add-company-backends, check its docstring for more info on its arguments. This macro also allows to define arbitrary buffer local variables to tune company for specific modes (similar to layer variables via a keyword :variables) The code related to company backends management has been moved to the auto-completion layer in the funcs.el file. A nice side effect of this move is that it enforces correct encapsulation of company backends related code. We can now easily detect if there is some configuration leakage when the auto-completion layer is not used. But we loose macro expansion at file loading time (not sue it is a big concern though). The function spacemacs|enable-auto-complete was never used so it has been deleted which led to the deletion of the now empty file core-auto-completion.el. The example in LAYERS.org regarding auto-completion is now out of date and has been deleted. An example to setup auto-completion is provided in the README.org file of the auto-completion layer. |
||
---|---|---|
.. | ||
local/snippets/emacs-lisp-mode | ||
config.el | ||
funcs.el | ||
packages.el | ||
README.org |
Auto-completion layer
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
.
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.
Configuration
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.
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 ofauto-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.
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)))
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)))
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.
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-usedp '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 (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 |
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 |
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 |