Archived

This repository has been archived on 2024-10-22. You can view files and clone it, but cannot push or open issues or pull requests.

History

duianto 6472dfe3c2 [auto-completion] List feature pkg company-quickhelp The company-quickhelp package wasn't mentioned in the auto-completion readme. And the variable name auto-completion-enable-help-tooltip that enables the package doesn't mention the package name either (which is fine). This just makes it somewhat easier to see/find that the company-quickhelp package is related to tooltips and that it's part of the auto-completion layer.		2019-10-19 23:03:05 +02:00
..
local/snippets/emacs-lisp-mode
config.el	Add company-box and basic setup	2019-10-18 13:20:55 +02:00
funcs.el	Fix C-k in company with tooltip	2019-10-19 19:42:21 +02:00
packages.el	Add company-box and basic setup	2019-10-18 13:20:55 +02:00
README.org	[auto-completion] List feature pkg company-quickhelp	2019-10-19 23:03:05 +02:00

README.org

Auto-completion layer

Description
- Features:
Install
Configuration
Key bindings

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 the RET key is pressed, the possible values are:
- complete completes with the current selection
- nil does nothing
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
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.
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 to nil to disable automatic suggestions (the TAB key will still perform completion).

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

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