1824 lines
80 KiB
Plaintext
1824 lines
80 KiB
Plaintext
This is company.info, produced by makeinfo version 6.8 from
|
||
company.texi.
|
||
|
||
This user manual is for Company version 1.0.3-snapshot
|
||
(7 December 2024).
|
||
|
||
Copyright © 2021-2024 Free Software Foundation, Inc.
|
||
|
||
Permission is granted to copy, distribute and/or modify this
|
||
document under the terms of the GNU Free Documentation License,
|
||
Version 1.3 or any later version published by the Free Software
|
||
Foundation.
|
||
INFO-DIR-SECTION Emacs misc features
|
||
START-INFO-DIR-ENTRY
|
||
* Company: (company). A modular text completion framework.
|
||
END-INFO-DIR-ENTRY
|
||
|
||
|
||
File: company.info, Node: Top, Next: Overview, Up: (dir)
|
||
|
||
Company
|
||
*******
|
||
|
||
Company is a modular text completion framework for GNU Emacs.
|
||
|
||
The goal of this document is to lay out the foundational knowledge of
|
||
the package, so that the readers of the manual could competently start
|
||
adapting Company to their needs and preferences.
|
||
|
||
This user manual is for Company version 1.0.3-snapshot
|
||
(7 December 2024).
|
||
|
||
Copyright © 2021-2024 Free Software Foundation, Inc.
|
||
|
||
Permission is granted to copy, distribute and/or modify this
|
||
document under the terms of the GNU Free Documentation License,
|
||
Version 1.3 or any later version published by the Free Software
|
||
Foundation.
|
||
|
||
* Menu:
|
||
|
||
* Overview:: Terminology and Structure
|
||
* Getting Started:: Quick Start Guide
|
||
* Customization:: User Options
|
||
* Frontends:: Frontends Usage Instructions
|
||
* Backends:: Backends Usage Instructions
|
||
* Troubleshooting:: When Something Goes Wrong
|
||
* Index::
|
||
|
||
— The Detailed Node Listing —
|
||
|
||
Overview
|
||
|
||
* Terminology::
|
||
* Structure::
|
||
|
||
Getting Started
|
||
|
||
* Installation::
|
||
* Initial Setup::
|
||
* Usage Basics::
|
||
* Commands::
|
||
|
||
Customization
|
||
|
||
* Customization Interface::
|
||
* Configuration File::
|
||
|
||
Frontends
|
||
|
||
* Tooltip Frontends::
|
||
* Preview Frontends::
|
||
* Echo Frontends::
|
||
* Candidates Search::
|
||
* Filter Candidates::
|
||
* Quick Access a Candidate::
|
||
|
||
Backends
|
||
|
||
* Backends Usage Basics::
|
||
* Grouped Backends::
|
||
* Package Backends::
|
||
* Candidates Post-Processing::
|
||
|
||
|
||
|
||
File: company.info, Node: Overview, Next: Getting Started, Prev: Top, Up: Top
|
||
|
||
1 Overview
|
||
**********
|
||
|
||
“Company” is a modular text completion framework for GNU Emacs.
|
||
|
||
In other words, it is a package for retrieving, manipulating, and
|
||
displaying text completion candidates. It aims to assist developers,
|
||
writers, and scientists during code and text writing.
|
||
|
||
* Menu:
|
||
|
||
* Terminology::
|
||
* Structure::
|
||
|
||
|
||
File: company.info, Node: Terminology, Next: Structure, Up: Overview
|
||
|
||
1.1 Terminology
|
||
===============
|
||
|
||
“Completion” is an act of intelligently guessing possible variants of
|
||
words based on already typed characters. To “complete” a word means to
|
||
insert a correctly guessed variant into the buffer.
|
||
|
||
Consequently, the “candidates” are the aforementioned guessed variants
|
||
of words. Each of the candidates has the potential to be chosen for
|
||
successful completion. And each of the candidates contains the
|
||
initially typed characters: either only at the beginning (so-called
|
||
“prefix matches”), or also inside of a candidate (“non-prefix matches”).
|
||
Which matching method is used, depends on the current _backend_ (*note
|
||
Structure::). ‘company-capf’ is an example of a backend that supports a
|
||
number of particular non-prefix matching algorithms which are
|
||
configurable through the user option ‘completion-styles’, which see.
|
||
For illustrations on how Company visualizes the matches, *note
|
||
Frontends::.
|
||
|
||
The package’s name ‘Company’ is based on the combination of the two
|
||
words: ‘Complete’ and ‘Anything’. These words reflect the package’s
|
||
commitment to handling completion candidates and its extensible nature
|
||
allowing it to cover a wide range of usage scenarios.
|
||
|
||
|
||
File: company.info, Node: Structure, Prev: Terminology, Up: Overview
|
||
|
||
1.2 Structure
|
||
=============
|
||
|
||
The Company is easily extensible because its significant building blocks
|
||
are pluggable modules: backends (*note Backends::) and frontends (*note
|
||
Frontends::).
|
||
|
||
The “backends” are responsible for retrieving completion candidates;
|
||
which are then displayed by the “frontends”. For an easy and quick
|
||
initial setup, Company is supplied with the preconfigured sets of the
|
||
backends and frontends. The default behavior of the modules can be
|
||
adjusted for particular needs, and preferences. It is also typical to
|
||
utilize backends from a variety of third-party libraries
|
||
(https://github.com/company-mode/company-mode/wiki/Third-Party-Packages),
|
||
developed to be pluggable with Company.
|
||
|
||
But Company consists not only of the backends and frontends.
|
||
|
||
A core of the package plays the role of a controller, connecting the
|
||
modules, making them work together; and exposing configurations and
|
||
commands for the user to operate with. For more details, *note
|
||
Customization:: and *note Commands::.
|
||
|
||
Also, Company is bundled with an alternative workflow configuration
|
||
“company-tng” — defining ‘company-tng-frontend’, ‘company-tng-mode’, and
|
||
‘company-tng-map’ — that allows performing completion with just <TAB>.
|
||
To enable this configuration, add the following line to the Emacs
|
||
initialization file (*note (emacs)Init File::):
|
||
|
||
(add-hook 'after-init-hook 'company-tng-mode)
|
||
|
||
|
||
File: company.info, Node: Getting Started, Next: Customization, Prev: Overview, Up: Top
|
||
|
||
2 Getting Started
|
||
*****************
|
||
|
||
This chapter provides basic instructions for Company setup and usage.
|
||
|
||
* Menu:
|
||
|
||
* Installation::
|
||
* Initial Setup::
|
||
* Usage Basics::
|
||
* Commands::
|
||
|
||
|
||
File: company.info, Node: Installation, Next: Initial Setup, Up: Getting Started
|
||
|
||
2.1 Installation
|
||
================
|
||
|
||
Company package is distributed via commonly used package archives in a
|
||
form of both stable and development releases. To install Company, type
|
||
‘M-x package-install <RET> company <RET>’.
|
||
|
||
For more details on Emacs package archives, *note (emacs)Packages::.
|
||
|
||
|
||
File: company.info, Node: Initial Setup, Next: Usage Basics, Prev: Installation, Up: Getting Started
|
||
|
||
2.2 Initial Setup
|
||
=================
|
||
|
||
The package Company provides a minor mode “company-mode”.
|
||
|
||
To activate the _company-mode_, execute the command ‘M-x company-mode’
|
||
that toggles the mode on and off. When it is switched on, the mode line
|
||
(*note (emacs)Mode line::) should indicate its presence with an
|
||
indicator ‘company’.
|
||
|
||
After _company-mode_ had been enabled, the package auto-starts
|
||
suggesting completion candidates. The candidates are retrieved and
|
||
shown according to the typed characters and the default (until the user
|
||
specifies otherwise) configurations.
|
||
|
||
To have Company always enabled for the following sessions, add the line
|
||
‘(global-company-mode)’ to the Emacs configuration file (*note
|
||
(emacs)Init File::).
|
||
|
||
|
||
File: company.info, Node: Usage Basics, Next: Commands, Prev: Initial Setup, Up: Getting Started
|
||
|
||
2.3 Usage Basics
|
||
================
|
||
|
||
By default — having _company-mode_ enabled (*note Initial Setup::) — a
|
||
tooltip with completion candidates is shown when the user types a few
|
||
characters.
|
||
|
||
To initiate completion manually, use the command ‘M-x company-complete’.
|
||
|
||
To select next or previous of the shown completion candidates, use
|
||
respectively key bindings ‘C-n’ and ‘C-p’, then do one of the following:
|
||
|
||
• Hit <RET> to choose a selected candidate for completion.
|
||
|
||
• Hit <TAB> to expand the “common part” of all completions. Exactly
|
||
what that means, can vary by backend. In the simplest case it’s
|
||
the longest string that all completion start with, but when a
|
||
backend returns _non-prefix matches_, it can implement the same
|
||
kind of expansion logic for the input string.
|
||
|
||
• Hit ‘C-g’ to stop activity of Company.
|
||
|
||
|
||
File: company.info, Node: Commands, Prev: Usage Basics, Up: Getting Started
|
||
|
||
2.4 Commands
|
||
============
|
||
|
||
Under the hood, mentioned in the previous section keys are bound to the
|
||
commands of the out-of-the-box Company.
|
||
|
||
‘C-n’
|
||
‘M-n’
|
||
Select the next candidate (‘company-select-next-or-abort’,
|
||
‘company-select-next’).
|
||
|
||
‘C-p’
|
||
‘M-p’
|
||
Select the previous candidate (‘company-select-previous-or-abort’,
|
||
‘company-select-previous’).
|
||
|
||
‘RET’
|
||
‘<return>’
|
||
Insert the selected candidate (‘company-complete-selection’).
|
||
Restart completion if a new field is entered.
|
||
|
||
‘TAB’
|
||
‘<tab>’
|
||
Insert the _common part_ of all completion candidates or — if no
|
||
_common part_ is present — select the next candidate
|
||
(‘company-complete-common-or-cycle’). In the latter case,
|
||
wraparound is implicitly enabled (*note
|
||
company-selection-wrap-around::).
|
||
|
||
‘C-g’
|
||
‘<ESC ESC ESC>’
|
||
Cancel _company-mode_ activity (‘company-abort’).
|
||
|
||
‘C-h’
|
||
‘<F1>’
|
||
Display a buffer with the documentation for the selected candidate
|
||
(‘company-show-doc-buffer’). With a prefix argument (‘C-u C-h’,
|
||
‘C-u <F1>’), this command toggles between temporary showing the
|
||
documentation and keeping the documentation buffer up-to-date
|
||
whenever the selection changes.
|
||
|
||
‘C-w’
|
||
Display a buffer with the definition of the selected candidate
|
||
(‘company-show-location’).
|
||
|
||
The full list of the default key bindings is stored in the variables
|
||
‘company-active-map’ and ‘company-search-map’ (1).
|
||
|
||
Moreover, Company is bundled with a number of convenience commands that
|
||
do not have default key bindings defined. The following examples
|
||
illustrate how to assign key bindings to such commands.
|
||
|
||
(global-set-key (kbd "<tab>") #'company-indent-or-complete-common)
|
||
|
||
(with-eval-after-load 'company
|
||
(define-key company-active-map (kbd "M-/") #'company-complete)
|
||
(define-key company-active-map (kbd "C-M-/") #'company-complete-common))
|
||
|
||
In the same manner, an additional key can be assigned to a command or a
|
||
command can be unbound from a key. For instance:
|
||
|
||
(with-eval-after-load 'company
|
||
(define-key company-active-map (kbd "M-.") #'company-show-location)
|
||
(define-key company-active-map (kbd "RET") nil))
|
||
|
||
---------- Footnotes ----------
|
||
|
||
(1) For a more user-friendly output of the pre-defined key bindings,
|
||
utilize ‘M-x describe-keymap <RET> company-active-map’ or
|
||
‘C-h f <RET> company-mode’.
|
||
|
||
|
||
File: company.info, Node: Customization, Next: Frontends, Prev: Getting Started, Up: Top
|
||
|
||
3 Customization
|
||
***************
|
||
|
||
Emacs provides two equally acceptable ways for user preferences
|
||
configuration: via customization interface (for more details, *note
|
||
(emacs)Easy Customization::) and a configuration file (*note (emacs)Init
|
||
File::). Naturally, Company can be configured by both of these
|
||
approaches.
|
||
|
||
* Menu:
|
||
|
||
* Customization Interface::
|
||
* Configuration File::
|
||
|
||
|
||
File: company.info, Node: Customization Interface, Next: Configuration File, Up: Customization
|
||
|
||
3.1 Customization Interface
|
||
===========================
|
||
|
||
In order to employ the customization interface, run
|
||
‘M-x customize-group <RET> company’.
|
||
|
||
This interface outputs all the options available for user customization,
|
||
so you may find it beneficial to review this list even if you are going
|
||
to configure Company with the configuration file.
|
||
|
||
For instructions on how to change the settings, *note (emacs)Changing a
|
||
Variable::.
|
||
|
||
|
||
File: company.info, Node: Configuration File, Prev: Customization Interface, Up: Customization
|
||
|
||
3.2 Configuration File
|
||
======================
|
||
|
||
Company is a customization-rich package. This section lists some of the
|
||
core settings that influence its overall behavior.
|
||
|
||
-- User Option: company-minimum-prefix-length
|
||
This is one of the values (together with ‘company-idle-delay’),
|
||
based on which Company auto-stars looking up completion candidates.
|
||
This option configures how many characters have to be typed in by a
|
||
user before candidates start to be collected and displayed. An
|
||
often choice nowadays is to configure this option to a lower number
|
||
than the default value of ‘3’.
|
||
|
||
-- User Option: company-idle-delay
|
||
This is the second of the options that configure Company’s
|
||
auto-start behavior (together with
|
||
‘company-minimum-prefix-length’). The value of this option defines
|
||
how fast Company is going to react to the typed input, such that
|
||
setting ‘company-idle-delay’ to ‘0’ makes Company react
|
||
immediately, ‘nil’ disables auto-starting, and a larger value
|
||
postpones completion auto-start for that number of seconds. For an
|
||
even fancier setup, set this option value to a predicate function,
|
||
as shown in the following example:
|
||
|
||
(setq company-idle-delay
|
||
(lambda () (if (company-in-string-or-comment) nil 0.3)))
|
||
|
||
-- User Option: company-inhibit-inside-symbols
|
||
You can set this option to ‘t’ to disable the auto-start behavior
|
||
when in the middle of a symbol.
|
||
|
||
-- User Option: company-global-modes
|
||
This option allows to specify in which major modes _company-mode_
|
||
can be enabled by ‘(global-company-mode)’. *Note Initial Setup::.
|
||
The default value of ‘t’ enables Company in all major modes.
|
||
Setting ‘company-global-modes’ to ‘nil’ equal in action to toggling
|
||
off _global-company-mode_. Providing a list of major modes results
|
||
in having _company-mode_ enabled in the listed modes only. For the
|
||
opposite result, provide a list of major modes with ‘not’ being the
|
||
first element of the list, as shown in the following example:
|
||
|
||
(setq company-global-modes '(not erc-mode message-mode eshell-mode))
|
||
|
||
-- User Option: company-selection-wrap-around
|
||
Enable this option to loop (cycle) the candidates’ selection: after
|
||
selecting the last candidate on the list, a command to select the
|
||
next candidate does so with the first candidate. By default, this
|
||
option is disabled, which means the selection of the next candidate
|
||
stops on the last item. The selection of the previous candidate is
|
||
influenced by this option similarly.
|
||
|
||
-- User Option: company-require-match
|
||
To allow typing in characters that don’t match the candidates, set
|
||
the value of this option to ‘nil’. For an opposite behavior (that
|
||
is, to disallow non-matching input), set it to ‘t’. By default,
|
||
Company is configured to require a matching input only if the user
|
||
invokes completion manually or selects a candidate; by having the
|
||
option configured to call the function ‘company-explicit-action-p’.
|
||
|
||
-- User Option: company-lighter-base
|
||
This user options allows to configure a string indicator of the
|
||
enabled _company-mode_ in the mode line. The default value is
|
||
‘company’.
|
||
|
||
-- User Option: company-insertion-on-trigger
|
||
One more pair of the user options may instruct Company to complete
|
||
with the selected candidate by typing one of the
|
||
‘company-insertion-triggers’. The user option
|
||
‘company-insertion-on-trigger’ can be enabled or disabled by
|
||
setting its value to one of: ‘nil’, ‘t’, or a predicate function
|
||
name. *note Predicate: (eintr)Wrong Type of Argument.
|
||
|
||
-- User Option: company-insertion-triggers
|
||
This option has an effect only when ‘company-insertion-on-trigger’
|
||
is enabled. The value can be one of: a string of characters, a
|
||
list of syntax description characters (*note (elisp)Syntax Class
|
||
Table::), or a predicate function. By default, this user option is
|
||
set to the list of the syntax characters: ‘(?\ ?\) ?.)’, which
|
||
translates to the whitespaces, close parenthesis, and punctuation.
|
||
It is safe to configure the value to a character that can
|
||
potentially be part of a valid completion; in this case, Company
|
||
does not treat such characters as triggers.
|
||
|
||
Hooks
|
||
-----
|
||
|
||
Company exposes the following life-cycle hooks:
|
||
|
||
-- User Option: company-completion-started-hook
|
||
|
||
-- User Option: company-completion-cancelled-hook
|
||
|
||
-- User Option: company-completion-finished-hook
|
||
|
||
-- User Option: company-after-completion-hook
|
||
|
||
|
||
File: company.info, Node: Frontends, Next: Backends, Prev: Customization, Up: Top
|
||
|
||
4 Frontends
|
||
***********
|
||
|
||
Company is packaged with several frontends and provides a predefined set
|
||
of enabled frontends. A list of the enabled frontends can be changed by
|
||
configuring the user option ‘company-frontends’.
|
||
|
||
Each frontend is simply a function that receives a command and acts
|
||
accordingly to it: outputs candidates, hides its output, refreshes
|
||
displayed data, and so on.
|
||
|
||
All of the Company frontends can be categorized by the type of the
|
||
output into the three groups: “tooltip-”, “preview-”, and “echo-”
|
||
frontends. We overview these groups in the first sections of this
|
||
chapter. The sections that follow are dedicated to the ways the
|
||
displayed candidates can be searched, filtered, and quick-accessed.
|
||
|
||
* Menu:
|
||
|
||
* Tooltip Frontends::
|
||
* Preview Frontends::
|
||
* Echo Frontends::
|
||
* Candidates Search::
|
||
* Filter Candidates::
|
||
* Quick Access a Candidate::
|
||
|
||
|
||
File: company.info, Node: Tooltip Frontends, Next: Preview Frontends, Up: Frontends
|
||
|
||
4.1 Tooltip Frontends
|
||
=====================
|
||
|
||
This group of frontends displays completion candidates in an overlayed
|
||
tooltip (aka pop-up). Company provides three _tooltip frontends_,
|
||
listed below.
|
||
|
||
-- Function: company-pseudo-tooltip-unless-just-one-frontend
|
||
This is one of the default frontends. It starts displaying a
|
||
tooltip only if more than one completion candidate is available,
|
||
which nicely combines — and it is done so by default — with
|
||
‘company-preview-if-just-one-frontend’, *note Preview Frontends::.
|
||
|
||
-- Function: company-pseudo-tooltip-frontend
|
||
This frontend outputs a tooltip for any number of completion
|
||
candidates.
|
||
|
||
-- Function: company-pseudo-tooltip-unless-just-one-frontend-with-delay
|
||
This is a peculiar frontend, that displays a tooltip only if more
|
||
than one candidate is available, and only after a delay. The delay
|
||
can be configured with the user option
|
||
‘company-tooltip-idle-delay’. A typical use case for plugging in
|
||
this frontend would be displaying a tooltip only on a manual
|
||
request (when needed), as shown in the following example:
|
||
|
||
(setq company-idle-delay 0
|
||
company-tooltip-idle-delay 10
|
||
company-require-match nil
|
||
company-frontends
|
||
'(company-pseudo-tooltip-unless-just-one-frontend-with-delay
|
||
company-preview-frontend
|
||
company-echo-metadata-frontend)
|
||
company-backends '(company-capf))
|
||
|
||
(global-set-key (kbd "<tab>")
|
||
(lambda ()
|
||
(interactive)
|
||
(let ((company-tooltip-idle-delay 0.0))
|
||
(company-complete)
|
||
(and company-candidates
|
||
(company-call-frontends 'post-command)))))
|
||
|
||
User Options
|
||
------------
|
||
|
||
To change the _tooltip frontends_ configuration, adjust the following
|
||
user options.
|
||
|
||
-- User Option: company-tooltip-align-annotations
|
||
An “annotation” is a string that carries additional information
|
||
about a candidate; such as a data type, function arguments, or
|
||
whatever a backend appoints to be a valuable piece of information
|
||
about a candidate. By default, the annotations are shown right
|
||
beside the candidates. Setting the option value to ‘t’ aligns
|
||
annotations to the right side of the tooltip.
|
||
|
||
(setq company-tooltip-align-annotations t)
|
||
|
||
|