[config.git] / djavu-asus / emacs / elpa / company-20230926.32 / company.info

This is company.info, produced by makeinfo version 6.7 from
company.texi.

This user manual is for Company version 0.9.14snapshot (16 April 2023).

Copyright © 2021-2023 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

\1f
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 0.9.14snapshot (16 April 2023).

Copyright © 2021-2023 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::


\1f
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::

\1f
File: company.info,  Node: Terminology,  Next: Structure,  Up: Overview

1.1 Terminology
===============

“Completion” is an act of intelligibly 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 (“non-prefix matches”) of a candidate
(1).

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.

   ---------- Footnotes ----------

   (1) A good starting point to learn about types of matches is to play
with the Emacs’s user option ‘completion-styles’.  For illustrations on
how Company visualizes the matches, *note Frontends::.

\1f
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 outputted 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 per particular needs, goals, 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 a 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)

\1f
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::

\1f
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::.

\1f
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 a 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::).

\1f
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 a user types in 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 complete with the “common part”: characters present at
     the beginning of all the candidates.

   • Hit ‘C-g’ to stop activity of Company.

\1f
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’).

‘TAB’
‘<tab>’
     Insert the common part of all the candidates
     (‘company-complete-common’).

‘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))

     (with-eval-after-load 'company
       (define-key company-active-map
                   (kbd "TAB")
                   #'company-complete-common-or-cycle)
       (define-key company-active-map
                   (kbd "<backtab>")
                   (lambda ()
                     (interactive)
                     (company-complete-common-or-cycle -1))))

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’.

\1f
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::

\1f
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::.

\1f
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 the overall behavior of the _company-mode_.

 -- 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-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 a user
     manually enables completion 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

\1f
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::

\1f
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)