doomemacs/modules/completion/company/README.org

#+TITLE:   completion/company
#+DATE:    February 19, 2017
#+SINCE:   v2.0
#+STARTUP: inlineimages

* Table of Contents :TOC_3:noexport:
- [[Description][Description]]
  - [[Module Flags][Module Flags]]
  - [[Plugins][Plugins]]
- [[Prerequisites][Prerequisites]]
- [[Features][Features]]
  - [[Code completion][Code completion]]
  - [[Vim-esque omni-completion prefix (C-x)][Vim-esque omni-completion prefix (C-x)]]
- [[Configuration][Configuration]]
  - [[Enable as-you-type code completion][Enable as-you-type code completion]]
  - [[Enable company backend(s) in certain modes][Enable company backend(s) in certain modes]]
- [[Troubleshooting][Troubleshooting]]
  - [[Code-completion doesn't pop up automatically.][Code-completion doesn't pop up automatically.]]
  - [[X-mode doesn't have code completion support or requires extra setup.][X-mode doesn't have code completion support or requires extra setup.]]
  - [[No backends (or the incorrect ones) have been registered for X-mode.][No backends (or the incorrect ones) have been registered for X-mode.]]

* Description
This module provides code completion, powered by [[https://github.com/company-mode/company-mode][company-mode]]. It is required
for code completion in many of Doom's :lang modules.

https://assets.doomemacs.org/completion/company/overlay.png

** Module Flags
+ =+auto= Enables as-you-type completion.
+ =+childframe= Enables displaying completion candidates in a child frame,
  rather than an overlay or tooltip (among with other UI enhancements). *This
  requires GUI Emacs 26.1+.*

** Plugins
+ [[https://github.com/company-mode/company-mode][company-mode]]
+ [[https://github.com/hlissner/emacs-company-dict][company-dict]]
+ [[https://github.com/raxod502/prescient.el][company-prescient]]
+ [[https://github.com/sebastiencs/company-box][company-box]]

* Prerequisites
This module has no direct prerequisites.

However, some major modes may require additional setup for code completion to
work in them. Some major modes may have no completion support at all. Check that
major mode's module's documentation for details.

* Features
** Code completion
Ccompletion must be triggered manually with the =C-SPC= key. If you want
as-you-type code completion, the ~+auto~ module flag will enable it.

| Keybind | Description                              |
|---------+------------------------------------------|
| =C-SPC= | Invoke code completion manually          |
| =C-n=   | Go to next candidate                     |
| =C-p=   | Go to previous candidate                 |
| =C-j=   | (evil) Go to next candidate              |
| =C-k=   | (evil) Go to previous candidate          |
| =C-h=   | Display documentation (if available)     |
| =C-u=   | Move to previous page of candidates      |
| =C-d=   | Move to next page of candidates          |
| =C-s=   | Filter candidates                        |
| =C-S-s= | Search candidates with helm/ivy          |
| =C-SPC= | Complete common                          |
| =TAB=   | Complete common or select next candidate |
| =S-TAB= | Select previous candidate                |

** Vim-esque omni-completion prefix (C-x)
In the spirit of Vim's omni-completion, the following insert mode keybinds are
available to evil users to access specific company backends:

| Keybind   | Description                       |
|-----------+-----------------------------------|
| =C-x C-]= | Complete etags                    |
| =C-x C-f= | Complete file path                |
| =C-x C-k= | Complete from dictionary/keyword  |
| =C-x C-l= | Complete full line                |
| =C-x C-o= | Invoke complete-at-point function |
| =C-x C-n= | Complete next symbol at point     |
| =C-x C-p= | Complete previous symbol at point |
| =C-x C-s= | Complete snippet                  |
| =C-x s=   | Complete spelling suggestions     |

* Configuration
** Enable as-you-type code completion
The =+auto= module flag enables this. You may customize ~company-idle-delay~ to
control how quickly the popup should appear.

The ~+company/toggle-auto-completion~ command is also available to toggle this
interactively.

** Enable company backend(s) in certain modes
The ~set-company-backend!~ function exists for setting ~company-backends~
buffer-locally in MODES, which is either a major-mode symbol, a minor-mode
symbol, or a list of either. BACKENDS are prepended to ~company-backends~ for
those modes.

#+BEGIN_SRC emacs-lisp
(after! js2-mode
  (set-company-backend! 'js2-mode 'company-tide 'company-yasnippet))

(after! sh-script
  (set-company-backend! 'sh-mode
    '(company-shell :with company-yasnippet)))

(after! cc-mode
  (set-company-backend! 'c-mode
    '(:separate company-irony-c-headers company-irony)))
#+END_SRC

To unset the backends for a particular mode, pass ~nil~ to it:

#+BEGIN_SRC emacs-lisp
(after! sh-script
  (set-company-backend! 'sh-mode nil))
#+END_SRC

* Troubleshooting
If code completion isn't working for you, consider the following common causes
before you file a bug report:

** Code-completion doesn't pop up automatically.
This is by design. The expectation is that you invoke completion manually with
=C-SPC=. This was decided because code-completion backends can be slow, some
dreadfully so, and invoking them every time you move your cursor can add pauses
and delays while editing.

If, despite that, you still want this functionality, use the =+auto= flag to
enable it.

** X-mode doesn't have code completion support or requires extra setup.
There is no guarantee your language mode will have completion support.

Some, like ~lua-mode~, don't have completion support in Emacs at all. Others may
requires additional setup to get code completion working. For instance,
~go-mode~ requires ~guru~ to be installed on your system, and ~enh-ruby-mode~
requires that you have a Robe server running (~M-x robe-start~).

Check the relevant module's documentation for this kind of information.

** No backends (or the incorrect ones) have been registered for X-mode.
Doom expects every mode to have an explicit list of company-backends (and as
short a list as possible). This may mean you aren't getting all the completion
you want or any at all.

Check the value of ~company-backends~ (=SPC h v company-backends=) from that
mode to see what backends are available. Check the [[*Assigning company backend(s) to modes][Configuration section]] for
details on changing what backends are available for that mode.