completion/company: rewrite README
This commit is contained in:
Henrik Lissner
parent
59d37334e3
commit
daa26a86ba
1 changed files with 132 additions and 32 deletions
|
|
@ -1,48 +1,148 @@
|
||||||
#+TITLE: :completion company
|
#+TITLE: completion/company
|
||||||
|
#+DATE: February 19, 2017
|
||||||
|
#+SINCE: v2.0
|
||||||
|
#+STARTUP: inlineimages
|
||||||
|
|
||||||
This module adds code-completion support, powered by [[https://github.com/company-mode/company-mode][company]].
|
* 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.]]
|
||||||
|
|
||||||
+ Uses ~company-quickhelp~ for documentation tooltips
|
* Description
|
||||||
+ Uses ~company-statistics~ to order results by usage frequency
|
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.
|
||||||
|
|
||||||
[[/../screenshots/company.png]]
|
https://assets.doomemacs.org/completion/company/overlay.png
|
||||||
|
|
||||||
* Table of Contents :TOC:
|
** Module Flags
|
||||||
- [[#install][Install]]
|
+ =+auto= Enables as-you-type completion.
|
||||||
- [[#configure][Configure]]
|
+ =+childframe= Enables displaying completion candidates in a child frame,
|
||||||
- [[#auto-completion][Auto-completion]]
|
rather than an overlay or tooltip (among with other UI enhancements). *This
|
||||||
- [[#troubleshooting][Troubleshooting]]
|
requires GUI Emacs 26.1+.*
|
||||||
|
|
||||||
* Install
|
** Plugins
|
||||||
Some languages require additional setup, and some languages may have no
|
+ [[https://github.com/company-mode/company-mode][company-mode]]
|
||||||
completion support at all.
|
+ [[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]]
|
||||||
|
|
||||||
Check the README.org in that language's module for details.
|
* Prerequisites
|
||||||
|
This module has no direct prerequisites.
|
||||||
|
|
||||||
* Configure
|
However, some major modes may require additional setup for code completion to
|
||||||
** Auto-completion
|
work in them. Some major modes may have no completion support at all. Check that
|
||||||
By default, I've disabled auto-completion. This is my preference. I prefer to
|
major mode's module's documentation for details.
|
||||||
invoke company when I need it by calling ~company-complete~ manually (typically,
|
|
||||||
bound to =C-SPC= in insert mode). However, some may not share my preference.
|
|
||||||
|
|
||||||
To enable auto-completion you must:
|
* 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.
|
||||||
|
|
||||||
1. Load ~company~,
|
| Keybind | Description |
|
||||||
2. and change ~company-idle-delay~ to a non-nil float (the default is 0.5)
|
|---------+------------------------------------------|
|
||||||
|
| =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 |
|
||||||
|
|
||||||
For example:
|
** 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
|
#+BEGIN_SRC emacs-lisp
|
||||||
(require 'company)
|
(after! js2-mode
|
||||||
(setq company-idle-delay 0.2
|
(set-company-backend! 'js2-mode 'company-tide 'company-yasnippet))
|
||||||
company-minimum-prefix-length 3)
|
|
||||||
|
(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
|
#+END_SRC
|
||||||
|
|
||||||
* Troubleshooting
|
* Troubleshooting
|
||||||
If completion isn't working for you, please consider the following before
|
If code completion isn't working for you, consider the following common causes
|
||||||
posting a bug report:
|
before you file a bug report:
|
||||||
|
|
||||||
+ If what you are expecting is popup-as-you-type completion (which is disabled
|
** Code-completion doesn't pop up automatically.
|
||||||
by default), see the "Configure > Auto-completion" section above, which will
|
This is by design. The expectation is that you invoke completion manually with
|
||||||
instruct you on how to enable this.
|
=C-SPC=. This was decided because code-completion backends can be slow, some
|
||||||
+ Some languages don't have any auto-completion support at all.
|
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.
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue