spacemacs/contrib/auto-completion/README.org

Auto-Completion configuration layer for Spacemacs

• Table of Contents
• Description
• Install
• Configuration
  • Key bindings
  • Tooltips
  • Sort results by usage
  • Show snippets in auto-completion popup
  • Enable company or auto-complete globally
  • Replacing company by auto-complete
  • Add auto-completion in a layer
    • In config.el
    • In packages.el
• Key Bindings
  • Company
  • Auto-complete
  • Yasnippet
  • Auto-yasnippet

Table of Contents   TOC@4

• Description
• Install

• Configuration

  • Key bindings
  • Tooltips
  • Sort results by usage
  • Show snippets in auto-completion popup
  • Enable company or auto-complete globally
  • Replacing company by auto-complete

  • Add auto-completion in a layer

    • In config.el
    • In packages.el

• Key Bindings

  • Company
  • Auto-complete
  • Yasnippet
  • Auto-yasnippet

Description

This layer provides auto-completion to Spacemacs.

The following completion engines are supported:

• company
• auto-complete

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

  (setq-default dotspacemacs-configuration-layers '(auto-completion))

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 as been entered quickly enough. If its value is nil then the feature is disabled.
4. auto-completion-private-snippets-directory is a path to your private snippets directory. If its value is nil then the spacemacs default is used.

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-private-snippets-directory nil)
                   ))

jk is a good candidate for auto-completion-complete-with-key-sequence if you don't use it already.

Tooltips

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

(setq-default dotspacemacs-configuration-layers
  '(auto-completion :variables
                    auto-completion-enable-help-tooltip 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))

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

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/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 buffer:

In config.el

  ;; Define the buffer local company backend variable
  (spacemacs|defvar-company-backends python-mode)

In packages.el

  ;; Add the relevant packages to the layer
  (setq python-packages
    '(...
      company
      company-anaconda
      ...))

  ;; Configure the packages
  (when (configuration-layer/layer-usedp 'auto-completion)

    ;; 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
        :if (configuration-layer/package-usedp 'company)
        :defer t
        :init (push 'company-anaconda company-backends-python-mode))))

Key Bindings

Company

Key Binding	Description
C-j	go down in company dropdown menu
C-k	go up in company dropdown menu
C-/	search in company dropdown
C-M-/	filter the company dropdown menu
C-d	open minibuffer with documentation of thing at point in company dropdown

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