To optimise performance of lsp mode in emacs 27 and above I have introduced a new dotfile variable to define the size of data read from external processes. The default I have set to the recommended setting from lsp-mode. In addition I have introduced a new layer variable for auto-complete-layer to define the minimum prefix length. I have also added instructions to auto-complete's readme how to set these variables to the recommended settings for lsp-mode. Changes inspired from #13507 |
||
---|---|---|
.. | ||
local/snippets/emacs-lisp-mode | ||
config.el | ||
funcs.el | ||
packages.el | ||
README.org |
Auto-completion layer
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:
-
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 has 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.auto-completion-idle-delay
is the number of seconds to wait before suggesting completions. The default value is 0.2 seconds. Set tonil
to disable automatic suggestions (theTAB
key will still perform completion). Set to 0.0 for optimal results with lsp mode.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 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 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.
(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 |