completion/company: rewrite README
This commit is contained in:
Henrik Lissner
parent
59d37334e3
commit
daa26a86ba
|
|
@ -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
|
||||
+ Uses ~company-statistics~ to order results by usage frequency
|
||||
* 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.
|
||||
|
||||
[[/../screenshots/company.png]]
|
||||
https://assets.doomemacs.org/completion/company/overlay.png
|
||||
|
||||
* Table of Contents :TOC:
|
||||
- [[#install][Install]]
|
||||
- [[#configure][Configure]]
|
||||
- [[#auto-completion][Auto-completion]]
|
||||
- [[#troubleshooting][Troubleshooting]]
|
||||
** 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+.*
|
||||
|
||||
* Install
|
||||
Some languages require additional setup, and some languages may have no
|
||||
completion support at all.
|
||||
** 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]]
|
||||
|
||||
Check the README.org in that language's module for details.
|
||||
* Prerequisites
|
||||
This module has no direct prerequisites.
|
||||
|
||||
* Configure
|
||||
** Auto-completion
|
||||
By default, I've disabled auto-completion. This is my preference. I prefer to
|
||||
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.
|
||||
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.
|
||||
|
||||
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~,
|
||||
2. and change ~company-idle-delay~ to a non-nil float (the default is 0.5)
|
||||
| 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 |
|
||||
|
||||
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
|
||||
(require 'company)
|
||||
(setq company-idle-delay 0.2
|
||||
company-minimum-prefix-length 3)
|
||||
(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 completion isn't working for you, please consider the following before
|
||||
posting a bug report:
|
||||
If code completion isn't working for you, consider the following common causes
|
||||
before you file a bug report:
|
||||
|
||||
+ If what you are expecting is popup-as-you-type completion (which is disabled
|
||||
by default), see the "Configure > Auto-completion" section above, which will
|
||||
instruct you on how to enable this.
|
||||
+ Some languages don't have any auto-completion support at all.
|
||||
** 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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user