diff --git a/modules/completion/company/README.org b/modules/completion/company/README.org index f2a1bc6fc..48973f228 100644 --- a/modules/completion/company/README.org +++ b/modules/completion/company/README.org @@ -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.