djavu-asus/emacs/elpa/company-20230926.32/company.info

   1 This is company.info, produced by makeinfo version 6.7 from
   2 company.texi.
   3
   4 This user manual is for Company version 0.9.14snapshot (16 April 2023).
   5
   6 Copyright © 2021-2023 Free Software Foundation, Inc.
   7
   8      Permission is granted to copy, distribute and/or modify this
   9      document under the terms of the GNU Free Documentation License,
  10      Version 1.3 or any later version published by the Free Software
  11      Foundation.
  12 INFO-DIR-SECTION Emacs misc features
  13 START-INFO-DIR-ENTRY
  14 * Company: (company).           A modular text completion framework.
  15 END-INFO-DIR-ENTRY
  16
  17 \1f
  18 File: company.info,  Node: Top,  Next: Overview,  Up: (dir)
  19
  20 Company
  21 *******
  22
  23 Company is a modular text completion framework for GNU Emacs.
  24
  25 The goal of this document is to lay out the foundational knowledge of
  26 the package, so that the readers of the manual could competently start
  27 adapting Company to their needs and preferences.
  28
  29 This user manual is for Company version 0.9.14snapshot (16 April 2023).
  30
  31 Copyright © 2021-2023 Free Software Foundation, Inc.
  32
  33      Permission is granted to copy, distribute and/or modify this
  34      document under the terms of the GNU Free Documentation License,
  35      Version 1.3 or any later version published by the Free Software
  36      Foundation.
  37
  38 * Menu:
  39
  40 * Overview:: Terminology and Structure
  41 * Getting Started:: Quick Start Guide
  42 * Customization:: User Options
  43 * Frontends:: Frontends Usage Instructions
  44 * Backends:: Backends Usage Instructions
  45 * Troubleshooting:: When Something Goes Wrong
  46 * Index::
  47
  48 — The Detailed Node Listing —
  49
  50 Overview
  51
  52 * Terminology::
  53 * Structure::
  54
  55 Getting Started
  56
  57 * Installation::
  58 * Initial Setup::
  59 * Usage Basics::
  60 * Commands::
  61
  62 Customization
  63
  64 * Customization Interface::
  65 * Configuration File::
  66
  67 Frontends
  68
  69 * Tooltip Frontends::
  70 * Preview Frontends::
  71 * Echo Frontends::
  72 * Candidates Search::
  73 * Filter Candidates::
  74 * Quick Access a Candidate::
  75
  76 Backends
  77
  78 * Backends Usage Basics::
  79 * Grouped Backends::
  80 * Package Backends::
  81 * Candidates Post-Processing::
  82
  83
  84 \1f
  85 File: company.info,  Node: Overview,  Next: Getting Started,  Prev: Top,  Up: Top
  86
  87 1 Overview
  88 **********
  89
  90 “Company” is a modular text completion framework for GNU Emacs.
  91
  92 In other words, it is a package for retrieving, manipulating, and
  93 displaying text completion candidates.  It aims to assist developers,
  94 writers, and scientists during code and text writing.
  95
  96 * Menu:
  97
  98 * Terminology::
  99 * Structure::
 100
 101 \1f
 102 File: company.info,  Node: Terminology,  Next: Structure,  Up: Overview
 103
 104 1.1 Terminology
 105 ===============
 106
 107 “Completion” is an act of intelligibly guessing possible variants of
 108 words based on already typed characters.  To “complete” a word means to
 109 insert a correctly guessed variant into the buffer.
 110
 111 Consequently, the “candidates” are the aforementioned guessed variants
 112 of words.  Each of the candidates has the potential to be chosen for
 113 successful completion.  And each of the candidates contains the
 114 initially typed characters: either only at the beginning (so-called
 115 “prefix matches”), or also inside (“non-prefix matches”) of a candidate
 116 (1).
 117
 118 The package’s name “Company” is based on the combination of the two
 119 words: ‘Complete’ and ‘Anything’.  These words reflect the package’s
 120 commitment to handling completion candidates and its extensible nature
 121 allowing it to cover a wide range of usage scenarios.
 122
 123    ---------- Footnotes ----------
 124
 125    (1) A good starting point to learn about types of matches is to play
 126 with the Emacs’s user option ‘completion-styles’.  For illustrations on
 127 how Company visualizes the matches, *note Frontends::.
 128
 129 \1f
 130 File: company.info,  Node: Structure,  Prev: Terminology,  Up: Overview
 131
 132 1.2 Structure
 133 =============
 134
 135 The Company is easily extensible because its significant building blocks
 136 are pluggable modules: backends (*note Backends::) and frontends (*note
 137 Frontends::).
 138
 139 The “backends” are responsible for retrieving completion candidates;
 140 which are then outputted by the “frontends”.  For an easy and quick
 141 initial setup, Company is supplied with the preconfigured sets of the
 142 backends and frontends.  The default behavior of the modules can be
 143 adjusted per particular needs, goals, and preferences.  It is also
 144 typical to utilize backends from a variety of third-party libraries
 145 (https://github.com/company-mode/company-mode/wiki/Third-Party-Packages),
 146 developed to be pluggable with Company.
 147
 148 But Company consists not only of the backends and frontends.
 149
 150 A core of the package plays the role of a controller, connecting the
 151 modules, making them work together; and exposing configurations and
 152 commands for a user to operate with.  For more details, *note
 153 Customization:: and *note Commands::.
 154
 155 Also, Company is bundled with an alternative workflow configuration
 156 “company-tng” — defining ‘company-tng-frontend’, ‘company-tng-mode’, and
 157 ‘company-tng-map’ — that allows performing completion with just <TAB>.
 158 To enable this configuration, add the following line to the Emacs
 159 initialization file (*note (emacs)Init File::):
 160
 161      (add-hook 'after-init-hook 'company-tng-mode)
 162
 163 \1f
 164 File: company.info,  Node: Getting Started,  Next: Customization,  Prev: Overview,  Up: Top
 165
 166 2 Getting Started
 167 *****************
 168
 169 This chapter provides basic instructions for Company setup and usage.
 170
 171 * Menu:
 172
 173 * Installation::
 174 * Initial Setup::
 175 * Usage Basics::
 176 * Commands::
 177
 178 \1f
 179 File: company.info,  Node: Installation,  Next: Initial Setup,  Up: Getting Started
 180
 181 2.1 Installation
 182 ================
 183
 184 Company package is distributed via commonly used package archives in a
 185 form of both stable and development releases.  To install Company, type
 186 ‘M-x package-install <RET> company <RET>’.
 187
 188 For more details on Emacs package archives, *note (emacs)Packages::.
 189
 190 \1f
 191 File: company.info,  Node: Initial Setup,  Next: Usage Basics,  Prev: Installation,  Up: Getting Started
 192
 193 2.2 Initial Setup
 194 =================
 195
 196 The package Company provides a minor mode “company-mode”.
 197
 198 To activate the _company-mode_, execute the command ‘M-x company-mode’
 199 that toggles the mode on and off.  When it is switched on, the mode line
 200 (*note (emacs)Mode line::) should indicate its presence with an
 201 indicator ‘company’.
 202
 203 After _company-mode_ had been enabled, the package auto-starts
 204 suggesting completion candidates.  The candidates are retrieved and
 205 shown according to the typed characters and the default (until a user
 206 specifies otherwise) configurations.
 207
 208 To have Company always enabled for the following sessions, add the line
 209 ‘(global-company-mode)’ to the Emacs configuration file (*note
 210 (emacs)Init File::).
 211
 212 \1f
 213 File: company.info,  Node: Usage Basics,  Next: Commands,  Prev: Initial Setup,  Up: Getting Started
 214
 215 2.3 Usage Basics
 216 ================
 217
 218 By default — having _company-mode_ enabled (*note Initial Setup::) — a
 219 tooltip with completion candidates is shown when a user types in a few
 220 characters.
 221
 222 To initiate completion manually, use the command ‘M-x company-complete’.
 223
 224 To select next or previous of the shown completion candidates, use
 225 respectively key bindings ‘C-n’ and ‘C-p’, then do one of the following:
 226
 227    • Hit <RET> to choose a selected candidate for completion.
 228
 229    • Hit <TAB> to complete with the “common part”: characters present at
 230      the beginning of all the candidates.
 231
 232    • Hit ‘C-g’ to stop activity of Company.
 233
 234 \1f
 235 File: company.info,  Node: Commands,  Prev: Usage Basics,  Up: Getting Started
 236
 237 2.4 Commands
 238 ============
 239
 240 Under the hood, mentioned in the previous section keys are bound to the
 241 commands of the out-of-the-box Company.
 242
 243 ‘C-n’
 244 ‘M-n’
 245      Select the next candidate (‘company-select-next-or-abort’,
 246      ‘company-select-next’).
 247
 248 ‘C-p’
 249 ‘M-p’
 250      Select the previous candidate (‘company-select-previous-or-abort’,
 251      ‘company-select-previous’).
 252
 253 ‘RET’
 254 ‘<return>’
 255      Insert the selected candidate (‘company-complete-selection’).
 256
 257 ‘TAB’
 258 ‘<tab>’
 259      Insert the common part of all the candidates
 260      (‘company-complete-common’).
 261
 262 ‘C-g’
 263 ‘<ESC ESC ESC>’
 264      Cancel _company-mode_ activity (‘company-abort’).
 265
 266 ‘C-h’
 267 ‘<F1>’
 268      Display a buffer with the documentation for the selected candidate
 269      (‘company-show-doc-buffer’).  With a prefix argument (‘C-u C-h’,
 270      ‘C-u <F1>’), this command toggles between temporary showing the
 271      documentation and keeping the documentation buffer up-to-date
 272      whenever the selection changes.
 273
 274 ‘C-w’
 275      Display a buffer with the definition of the selected candidate
 276      (‘company-show-location’).
 277
 278 The full list of the default key bindings is stored in the variables
 279 ‘company-active-map’ and ‘company-search-map’ (1).
 280
 281 Moreover, Company is bundled with a number of convenience commands that
 282 do not have default key bindings defined.  The following examples
 283 illustrate how to assign key bindings to such commands.
 284
 285      (global-set-key (kbd "<tab>") #'company-indent-or-complete-common)
 286
 287      (with-eval-after-load 'company
 288        (define-key company-active-map (kbd "M-/") #'company-complete))
 289
 290      (with-eval-after-load 'company
 291        (define-key company-active-map
 292                    (kbd "TAB")
 293                    #'company-complete-common-or-cycle)
 294        (define-key company-active-map
 295                    (kbd "<backtab>")
 296                    (lambda ()
 297                      (interactive)
 298                      (company-complete-common-or-cycle -1))))
 299
 300 In the same manner, an additional key can be assigned to a command or a
 301 command can be unbound from a key.  For instance:
 302
 303      (with-eval-after-load 'company
 304        (define-key company-active-map (kbd "M-.") #'company-show-location)
 305        (define-key company-active-map (kbd "RET") nil))
 306
 307    ---------- Footnotes ----------
 308
 309    (1) For a more user-friendly output of the pre-defined key bindings,
 310 utilize ‘M-x describe-keymap <RET> company-active-map’ or
 311 ‘C-h f <RET> company-mode’.
 312
 313 \1f
 314 File: company.info,  Node: Customization,  Next: Frontends,  Prev: Getting Started,  Up: Top
 315
 316 3 Customization
 317 ***************
 318
 319 Emacs provides two equally acceptable ways for user preferences
 320 configuration: via customization interface (for more details, *note
 321 (emacs)Easy Customization::) and a configuration file (*note (emacs)Init
 322 File::).  Naturally, Company can be configured by both of these
 323 approaches.
 324
 325 * Menu:
 326
 327 * Customization Interface::
 328 * Configuration File::
 329
 330 \1f
 331 File: company.info,  Node: Customization Interface,  Next: Configuration File,  Up: Customization
 332
 333 3.1 Customization Interface
 334 ===========================
 335
 336 In order to employ the customization interface, run
 337 ‘M-x customize-group <RET> company’.
 338
 339 This interface outputs all the options available for user customization,
 340 so you may find it beneficial to review this list even if you are going
 341 to configure Company with the configuration file.
 342
 343 For instructions on how to change the settings, *note (emacs)Changing a
 344 Variable::.
 345
 346 \1f
 347 File: company.info,  Node: Configuration File,  Prev: Customization Interface,  Up: Customization
 348
 349 3.2 Configuration File
 350 ======================
 351
 352 Company is a customization-rich package.  This section lists some of the
 353 core settings that influence the overall behavior of the _company-mode_.
 354
 355  -- User Option: company-minimum-prefix-length
 356      This is one of the values (together with ‘company-idle-delay’),
 357      based on which Company auto-stars looking up completion candidates.
 358      This option configures how many characters have to be typed in by a
 359      user before candidates start to be collected and displayed.  An
 360      often choice nowadays is to configure this option to a lower number
 361      than the default value of ‘3’.
 362
 363  -- User Option: company-idle-delay
 364      This is the second of the options that configure Company’s
 365      auto-start behavior (together with
 366      ‘company-minimum-prefix-length’).  The value of this option defines
 367      how fast Company is going to react to the typed input, such that
 368      setting ‘company-idle-delay’ to ‘0’ makes Company react
 369      immediately, ‘nil’ disables auto-starting, and a larger value
 370      postpones completion auto-start for that number of seconds.  For an
 371      even fancier setup, set this option value to a predicate function,
 372      as shown in the following example:
 373
 374           (setq company-idle-delay
 375                 (lambda () (if (company-in-string-or-comment) nil 0.3)))
 376
 377  -- User Option: company-global-modes
 378      This option allows to specify in which major modes _company-mode_
 379      can be enabled by ‘(global-company-mode)’.  *Note Initial Setup::.
 380      The default value of ‘t’ enables Company in all major modes.
 381      Setting ‘company-global-modes’ to ‘nil’ equal in action to toggling
 382      off _global-company-mode_.  Providing a list of major modes results
 383      in having _company-mode_ enabled in the listed modes only.  For the
 384      opposite result, provide a list of major modes with ‘not’ being the
 385      first element of the list, as shown in the following example:
 386
 387           (setq company-global-modes '(not erc-mode message-mode eshell-mode))
 388
 389  -- User Option: company-selection-wrap-around
 390      Enable this option to loop (cycle) the candidates’ selection: after
 391      selecting the last candidate on the list, a command to select the
 392      next candidate does so with the first candidate.  By default, this
 393      option is disabled, which means the selection of the next candidate
 394      stops on the last item.  The selection of the previous candidate is
 395      influenced by this option similarly.
 396
 397  -- User Option: company-require-match
 398      To allow typing in characters that don’t match the candidates, set
 399      the value of this option to ‘nil’.  For an opposite behavior (that
 400      is, to disallow non-matching input), set it to ‘t’.  By default,
 401      Company is configured to require a matching input only if a user
 402      manually enables completion or selects a candidate; by having the
 403      option configured to call the function ‘company-explicit-action-p’.
 404
 405  -- User Option: company-lighter-base
 406      This user options allows to configure a string indicator of the
 407      enabled _company-mode_ in the mode line.  The default value is
 408      ‘company’.
 409
 410  -- User Option: company-insertion-on-trigger
 411      One more pair of the user options may instruct Company to complete
 412      with the selected candidate by typing one of the
 413      ‘company-insertion-triggers’.  The user option
 414      ‘company-insertion-on-trigger’ can be enabled or disabled by
 415      setting its value to one of: ‘nil’, ‘t’, or a predicate function
 416      name.  *note Predicate: (eintr)Wrong Type of Argument.
 417
 418  -- User Option: company-insertion-triggers
 419      This option has an effect only when ‘company-insertion-on-trigger’
 420      is enabled.  The value can be one of: a string of characters, a
 421      list of syntax description characters (*note (elisp)Syntax Class
 422      Table::), or a predicate function.  By default, this user option is
 423      set to the list of the syntax characters: ‘(?\ ?\) ?.)’, which
 424      translates to the whitespaces, close parenthesis, and punctuation.
 425      It is safe to configure the value to a character that can
 426      potentially be part of a valid completion; in this case, Company
 427      does not treat such characters as triggers.
 428
 429 Hooks
 430 -----
 431
 432 Company exposes the following life-cycle hooks:
 433
 434  -- User Option: company-completion-started-hook
 435
 436  -- User Option: company-completion-cancelled-hook
 437
 438  -- User Option: company-completion-finished-hook
 439
 440  -- User Option: company-after-completion-hook
 441
 442 \1f
 443 File: company.info,  Node: Frontends,  Next: Backends,  Prev: Customization,  Up: Top
 444
 445 4 Frontends
 446 ***********
 447
 448 Company is packaged with several frontends and provides a predefined set
 449 of enabled frontends.  A list of the enabled frontends can be changed by
 450 configuring the user option ‘company-frontends’.
 451
 452 Each frontend is simply a function that receives a command and acts
 453 accordingly to it: outputs candidates, hides its output, refreshes
 454 displayed data, and so on.
 455
 456 All of the Company frontends can be categorized by the type of the
 457 output into the three groups: “tooltip-”, “preview-”, and “echo-”
 458 frontends.  We overview these groups in the first sections of this
 459 chapter.  The sections that follow are dedicated to the ways the
 460 displayed candidates can be searched, filtered, and quick-accessed.
 461
 462 * Menu:
 463
 464 * Tooltip Frontends::
 465 * Preview Frontends::
 466 * Echo Frontends::
 467 * Candidates Search::
 468 * Filter Candidates::
 469 * Quick Access a Candidate::
 470
 471 \1f
 472 File: company.info,  Node: Tooltip Frontends,  Next: Preview Frontends,  Up: Frontends
 473
 474 4.1 Tooltip Frontends
 475 =====================
 476
 477 This group of frontends displays completion candidates in an overlayed
 478 tooltip (aka pop-up).  Company provides three _tooltip frontends_,
 479 listed below.
 480
 481  -- Function: company-pseudo-tooltip-unless-just-one-frontend
 482      This is one of the default frontends.  It starts displaying a
 483      tooltip only if more than one completion candidate is available,
 484      which nicely combines — and it is done so by default — with
 485      ‘company-preview-if-just-one-frontend’, *note Preview Frontends::.
 486
 487  -- Function: company-pseudo-tooltip-frontend
 488      This frontend outputs a tooltip for any number of completion
 489      candidates.
 490
 491  -- Function: company-pseudo-tooltip-unless-just-one-frontend-with-delay
 492      This is a peculiar frontend, that displays a tooltip only if more
 493      than one candidate is available, and only after a delay.  The delay
 494      can be configured with the user option
 495      ‘company-tooltip-idle-delay’.  A typical use case for plugging in
 496      this frontend would be displaying a tooltip only on a manual
 497      request (when needed), as shown in the following example:
 498
 499           (setq company-idle-delay 0
 500                 company-tooltip-idle-delay 10
 501                 company-require-match nil
 502                 company-frontends
 503                 '(company-pseudo-tooltip-unless-just-one-frontend-with-delay
 504                   company-preview-frontend
 505                   company-echo-metadata-frontend)
 506                 company-backends '(company-capf))
 507
 508           (global-set-key (kbd "<tab>")
 509                           (lambda ()
 510                             (interactive)
 511                             (let ((company-tooltip-idle-delay 0.0))
 512                               (company-complete)
 513                               (and company-candidates
 514                                    (company-call-frontends 'post-command)))))
 515
 516 User Options
 517 ------------
 518
 519 To change the _tooltip frontends_ configuration, adjust the following
 520 user options.
 521
 522  -- User Option: company-tooltip-align-annotations
 523      An “annotation” is a string that carries additional information
 524      about a candidate; such as a data type, function arguments, or
 525      whatever a backend appoints to be a valuable piece of information
 526      about a candidate.  By default, the annotations are shown right
 527      beside the candidates.  Setting the option value to ‘t’ aligns
 528      annotations to the right side of the tooltip.
 529
 530           (setq company-tooltip-align-annotations t)
 531
 532