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.
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)
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)))
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:
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.
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).
This backend provides completions for many of the widely spread programming languages keywords: words bearing specific meaning in a language.
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.
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.
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.
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.
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)
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)
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)
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.
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).
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.
Optionally, set a file path for company-ispell to use another dictionary.
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.
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"))
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.
This is a completion backend for a built-in word abbreviation mode (see (emacs)Abbrevs), that allows completing abbreviations with their expansions.
A backend for users of Tempo, one more built-in Emacs package for creating and inserting (expanding) templates.
Used as a completion backend for the popular third-party template system YASnippet.
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.
Sorts candidates using company-occurrence-weight-function
algorithm.
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.
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.
Gives preference to the candidates that match the prefix case-insensitively.