# -*- mode: doom-docs-org -*-
#+title:    :completion company
#+subtitle: The ultimate code completion backend
#+created:  February 19, 2017
#+since:    2.0.0

* Description :unfold:
This module provides code completion, powered by [[https://github.com/company-mode/company-mode][company-mode]]. Many of Doom's
[[doom-module:][:lang]] modules require it for "intellisense" functionality.

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

** Maintainers
- [[doom-user:][@hlissner]]

[[doom-contrib-maintainer:][Become a maintainer?]]

** Module flags
- +childframe ::
  Display completion candidates in a [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Child-Frames.html][child frame]] rather than an overlay or
  tooltip. *Requires GUI Emacs.*
- +tng ::
  Invoke completion on [[kbd:][TAB]] instad of [[kbd:][C-SPC]]. When company is active, [[kbd:][TAB]] and
  [[kbd:][S-TAB]] will navigate the completion candidates.

** Packages
- [[doom-package:][company-box]] if [[doom-module:][+childframe]]
- [[doom-package:][company-dict]]
- [[doom-package:][company-mode]]

** Hacks
/No hacks documented for this module./

** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./

* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]

This module has no direct requirements, but some languages may have their own
requirements to fulfill before you get code completion in them (and some
languages may lack code completion support altogether). Run ~$ doom doctor~ to
find out if you're missing any dependencies.

* TODO Usage
#+begin_quote
 🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

** Code completion
By default, completion is triggered after a short idle period or with the
[[kbd:][C-SPC]] key. While the popup is visible, the following keys are available:

| Keybind | Description                              |
|---------+------------------------------------------|
| [[kbd:][C-n]]     | Go to next candidate                     |
| [[kbd:][C-p]]     | Go to previous candidate                 |
| [[kbd:][C-j]]     | (evil) Go to next candidate              |
| [[kbd:][C-k]]     | (evil) Go to previous candidate          |
| [[kbd:][C-h]]     | Display documentation (if available)     |
| [[kbd:][C-u]]     | Move to previous page of candidates      |
| [[kbd:][C-d]]     | Move to next page of candidates          |
| [[kbd:][C-s]]     | Filter candidates                        |
| [[kbd:][C-S-s]]   | Search candidates with helm/ivy          |
| [[kbd:][C-SPC]]   | Complete common                          |
| [[kbd:][TAB]]     | Complete common or select next candidate |
| [[kbd:][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                       |
|---------+-----------------------------------|
| [[kbd:][C-x C-]]​] | Complete etags                    |
| [[kbd:][C-x C-f]] | Complete file path                |
| [[kbd:][C-x C-k]] | Complete from dictionary/keyword  |
| [[kbd:][C-x C-l]] | Complete full line                |
| [[kbd:][C-x C-o]] | Invoke complete-at-point function |
| [[kbd:][C-x C-n]] | Complete next symbol at point     |
| [[kbd:][C-x C-p]] | Complete previous symbol at point |
| [[kbd:][C-x C-s]] | Complete snippet                  |
| [[kbd:][C-x s]]   | Complete spelling suggestions     |

** Searching with multiple keywords
If the =vertico= module is enabled, users can perform code completion with multiple search keywords with an ampersand =&=.
More information can be found [[https://github.com/oantolin/orderless#company][here]].

* TODO Configuration
#+begin_quote
 🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

** 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
[[doom-report:][Report an issue?]]

** 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 ~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~ ([[kbd:][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.

* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

* TODO Appendix
#+begin_quote
 🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote