Backends

We can metaphorically say that each backend is like an engine. (The reality is even better since backends are just functions.) Fueling such an engine with a command causes the production of material for Company to move further on. Typically, moving on means outputting that material to a user via one or several configured frontends, Frontends.

Just like Company provides a preconfigured list of the enabled frontends, it also defines a list of the backends to rely on by default. This list is stored in the user option company-backends. The docstring of this variable has been a source of valuable information for years. That’s why we’re going to stick to a tradition and suggest reading the output of C-h v company-backends for insightful details about backends. Nevertheless, the fundamental concepts are described in this user manual too.


Backends Usage Basics

One of the significant concepts to understand about Company is that the package relies on one backend at a time 5. The backends are invoked one by one, in the sequential order of the items on the company-backends list.

The name of the currently active backend is shown in the mode line and in the output of the command M-x company-diag.

In most cases (mainly to exclude false-positive results), the next backend is not invoked automatically. For the purpose of invoking the next backend, use the command company-other-backend: either by calling it with M-x or by binding the command to the keys of your choice, such as:

(global-set-key (kbd "C-c C-/") #'company-other-backend)

It is also possible to specifically start a backend with the command M-x company-begin-backend or by calling a backend by its name, for instance: M-x company-capf. As usual for Emacs, such backends calls can be assigned to key bindings, for example:

(global-set-key (kbd "C-c y") 'company-yasnippet)

Grouped Backends

In many cases, it can be desirable to receive candidates from several backends simultaneously. This can be achieved by configuring grouped backends: a sub-list of backends in the company-backends list, that is handled specifically by Company.

The most important part of this handling is the merge of the completion candidates from the grouped backends. (But only from the backends that return the same prefix value, see C-h v company-backends for more details.)

To keep the candidates organized in accordance with the grouped backends order, add the keyword :separate to the list of the grouped backends. The following example illustrates this.

(defun my-text-mode-hook ()
  (setq-local company-backends
              '((company-dabbrev company-ispell :separate)
                company-files)))

(add-hook 'text-mode-hook #'my-text-mode-hook)

Another keyword :with helps to make sure the results from major/minor mode agnostic backends (such as company-yasnippet, company-dabbrev-code) are returned without preventing results from context-aware backends (such as company-capf or company-clang). For this feature to work, put backends dependent on a mode at the beginning of the grouped backends list, then put a keyword :with, and only then put context agnostic backend(s), as shown in the following concise example:

(setq company-backends '((company-capf :with company-yasnippet)))

Package Backends

The following sections give a short overview of the commonly used backends bundled with Company. Each section is devoted to one of the roughly outlined groups of the backends.

Some of the backends expose user options for customization; a few of these options are introduced below. For those who would like to fetch the full list of a backend’s user options, we suggest doing one of the following:

  • Execute command M-x customize-group RET <backend-name>.
  • Open the source file of the backend and run M-x occur RET ^(defcustom.
    • Optionally, search for the matches with M-x isearch RET (defcustom.

Code Completion

Function: company-capf

In the Emacs’s world, the current tendency is to have the completion logic provided by completion-at-point-functions (CAPF) implementations. [Among the other things, this is what the popular packages that support language server protocol (LSP) also rely on.]

Since company-capf works as a bridge to the standard CAPF facility, it is probably the most often used and recommended backend nowadays, including for Emacs Lisp coding.

Just to illustrate, the following minimal backends setup

(setq company-backends '((company-capf company-dabbrev-code)))

might cover a large number of basic use cases, especially so in major modes that have CAPF support implemented.

For more details on CAPF, (elisp)Completion in Buffers.

Function: company-dabbrev-code

This backend works similarly to the built-in Emacs package dabbrev, searching for completion candidates inside the contents of the open buffer(s). Internally, its based on the backend company-dabbrev (see Text Completion).

Function: company-keywords

This backend provides completions for many of the widely spread programming languages keywords: words bearing specific meaning in a language.

Function: company-clang

As the name suggests, use this backend to get completions from Clang compiler; that is, for the languages in the C language family: C, C++, Objective-C.

Function: company-semantic

This backend relies on a built-in Emacs package that provides language-aware editing commands based on source code parsers, (emacs)Semantic. Having enabled semantic-mode makes it to be used by the CAPF mechanism (see (emacs)Symbol Completion), hence a user may consider enabling company-capf backend instead.

Function: company-etags

This backend works on top of a built-in Emacs package etags, (emacs)Tags Tables. Similarly to aforementioned Semantic usage, tags-based completions now are a part of the Emacs’ CAPF facility, therefore a user may consider switching to company-capf backend.


Text Completion

Function: company-dabbrev

This backend works similarly to the built-in Emacs package dabbrev, searching for completion candidates inside the contents of the open buffer(s). It is one of the often used backends, and it has several interesting options for configuration. Let’s review a few of them.

User Option: company-dabbrev-minimum-length

This option sets the minimum length of a completion candidate to collect from the text. The default value of ‘4’ is intended to prevent potential performance issues. But in many scenarios, it may be acceptable to lower this value. Note that this option also affects the behavior of the company-dabbrev-code backend.

(setq company-dabbrev-minimum-length 2)
User Option: company-dabbrev-other-buffers

By default, company-dabbrev collects completion candidates from all not ignored buffers (see more on that below). This behavior can be changed to collecting candidates from the current buffer only (by setting the value to ‘nil’) or from the buffers with the same major mode:

(setq company-dabbrev-other-buffers t)
User Option: company-dabbrev-ignore-buffers

The value of this option should be a regexp or a predicate function that can be used to match a buffer name. The matched buffers are omitted from the search for completion candidates.

The last two options described here relate to handling uppercase and lowercase letters in completion candidates. The illustrative examples given below can be reproduced in the ‘*scratch*’ buffer, with the word ‘Enjoy’ typed in, and with this initial setup:

(setq-local company-backends '(company-dabbrev)
            company-dabbrev-other-buffers nil
            company-dabbrev-ignore-case nil
            company-dabbrev-downcase nil)
User Option: company-dabbrev-ignore-case

This user option controls whether the case is ignored when collecting completion candidates. When the option is set to nil, ‘Enjoy’ is suggested as a completion candidate for the typed ‘Enj’ letters, but not for ‘enj’. When the option is set to t, ‘Enjoy’ is suggested as a candidate for both ‘Enj’ and ‘enj’ input; note that ‘enj’ prefix is “overwritten” by completing with the ‘Enjoy’ candidate. The third, default, type of behavior solves this issue, keeping the case of the typed prefix (and still collecting candidates case-insensitively):

(setq company-dabbrev-ignore-case 'keep-prefix)

Now we can type ‘enj’, complete it with the suggested ‘Enjoy’, and enjoy the result.

User Option: company-dabbrev-downcase

This user option controls whether completion candidates are down-cased before their display. When the option is set to nil, no transformation is performed; in the environment described above, typing ‘Enj’ results in the candidate ‘Enjoy’ being suggested. When the option is set to t, the down-cased candidate ‘enjoy’ is suggested. By default, this option is set to case-replace, meaning taking a value of the Emacs’s variable case-replace (t is the current default).


Function: company-ispell

This backend returns completion candidates collected by Ispell, a built-in Emacs package that performs spell-checking. See (emacs)Checking and Correcting Spelling. Note that Ispell uses only one dictionary at a time (combining several dictionaries into one file is an accepted practice). By default, company-ispell suggests candidates from a dictionary specified by the Emacs’s setting ispell-complete-word-dict.

User Option: company-ispell-dictionary

Optionally, set a file path for company-ispell to use another dictionary.


File Name Completion

Function: company-files

This backend can be used to retrieve completion candidates for the absolute and relative paths in the directory structure of an operating system. The behavior of the company-files backend can be adjusted with the two user options.

User Option: company-files-exclusions

It may be desirable to exclude directories or files from the list of suggested completion candidates. For example, someone’s setup might look this way:

(setq company-files-exclusions '(".git/" ".DS_Store"))
User Option: company-files-chop-trailing-slash

This setting is enabled by default, which results in stripping off a trailing slash from an inserted directory name. On typing a trailing slash, the process of completion gets started again, from inside the just inserted directory.

Setting company-files-chop-trailing-slash to nil makes directory names to be inserted as is, with a trailing slash. In this case, the completion process can be continued, for example, either by explicitly calling company-files backend (see Backends Usage Basics) or by starting typing a name of a file/directory known to be located under the inserted directory.


Template Expansion

Function: company-abbrev

This is a completion backend for a built-in word abbreviation mode (see (emacs)Abbrevs), that allows completing abbreviations with their expansions.

Function: company-tempo

A backend for users of Tempo, one more built-in Emacs package for creating and inserting (expanding) templates.

Function: company-yasnippet

Used as a completion backend for the popular third-party template system YASnippet.


Candidates Post-Processing

A list of completion candidates, supplied by a backend, can be additionally manipulated (reorganized, reduced, sorted, etc) before its output. This is done by adding a processing function name to the user option company-transformers list, for example:

(setq company-transformers '(delete-consecutive-dups
                             company-sort-by-occurrence))

Company is bundled with several such transformer functions. They are listed below.

Function: company-sort-by-occurrence

Sorts candidates using company-occurrence-weight-function algorithm.

User Option: company-occurrence-weight-function

Can be set to one of company-occurrence-prefer-closest-above (default) or company-occurrence-prefer-any-closest. This user option defines the behavior of the company-sort-by-occurrence transformer function.

Function: company-sort-by-backend-importance

Sorts candidates as two priority groups, differentiated by the keyword :with (see Grouped Backends). Backends positioned in the backends list before the keyword :with are treated as more important.

Function: company-sort-prefer-same-case-prefix

Gives preference to the candidates that match the prefix case-insensitively.


Footnotes

(5)

The grouped backends act as one complex backend. See Grouped Backends.