-
Notifications
You must be signed in to change notification settings - Fork 0
/
company.info
1780 lines (1411 loc) · 77.2 KB
/
company.info
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
This is dociBJNK2.info, produced by makeinfo version 6.8 from
company.texi.
This user manual is for Company version 1.0.0 (21 September 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: dociBJNK2.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.0 (21 September 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: dociBJNK2.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: dociBJNK2.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: dociBJNK2.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: dociBJNK2.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: dociBJNK2.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: dociBJNK2.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: dociBJNK2.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: dociBJNK2.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 completion 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’.
File: dociBJNK2.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: dociBJNK2.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: dociBJNK2.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: dociBJNK2.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: dociBJNK2.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)
[image src="./images/small/tooltip-annotations.png" ]
-- User Option: company-tooltip-annotation-padding
Adds left padding to the candidates’ annotations. It is disabled
by default. If ‘company-tooltip-align-annotations’ is enabled,
‘company-tooltip-annotation-padding’ defines the minimum spacing
between a candidate and annotation, with the default value of 1.
(setq company-tooltip-annotation-padding 1)
-- User Option: company-tooltip-limit
Controls the maximum number of the candidates shown simultaneously
in the tooltip (the default value is ‘10’). When the number of the
available candidates is larger than this option’s value, Company
paginates the results.
(setq company-tooltip-limit 4)
[image src="./images/small/tooltip-limit.png" ]
-- User Option: company-tooltip-offset-display
Use this option to choose in which way to output paginated results.
The default value is ‘scrollbar’. Another supported value is
‘lines’; choose it to show the quantity of the candidates not
displayed by the current tooltip page.
(setq company-tooltip-offset-display 'lines)
[image src="./images/small/tooltip-offset-display.png" ]
-- User Option: company-tooltip-minimum
This user option acts only when a tooltip is shown close to the
bottom of a window. It guarantees visibility of this number of
completion candidates below point. When the number of lines
between point and the bottom of a window is less than
‘company-tooltip-minimum’ value, the tooltip is displayed above
point.
(setq company-tooltip-minimum 4)
[image src="./images/small/tooltip-minimum-below.png" ]
[image src="./images/small/tooltip-minimum-above.png" ]
-- User Option: company-tooltip-flip-when-above
When this setting is enabled, no matter if a tooltip is shown above
or below point, the candidates are always listed starting near
point. (Putting it differently, the candidates are mirrored
vertically if a tooltip changes its position, instead of being
commonly listed top-to-bottom.)
(setq company-tooltip-flip-when-above t)
[image src="./images/small/tooltip-flip.png" ]
-- User Option: company-tooltip-minimum-width
Sets the minimum width of a tooltip, excluding the margins and the
scroll bar. Changing this value especially makes sense if the user
navigates between tooltip pages. Keeping this value at the default
‘0’ allows Company to always adapt the width of the tooltip to the
longest shown candidate. Enlarging ‘company-tooltip-minimum-width’
prevents possible significant shifts in the width of the tooltip
when navigating to the next/previous tooltip page. (For an
alternate solution, see ‘company-tooltip-width-grow-only’.)
-- User Option: company-tooltip-width-grow-only
This is another way to restrict auto-adaptation of the tooltip
width (another is by adjusting ‘company-tooltip-minimum-width’
value) when navigating between the tooltip pages.
-- User Option: company-tooltip-maximum-width
This user option controls the maximum width of the tooltip inner
area. By default, its value is pseudo-limitless, potentially
permitting the output of extremely long candidates. But if long
lines become an issue, set this option to a smaller number, such as
‘60’ or ‘70’.
-- User Option: company-tooltip-margin
Controls the width of the “margin” on the sides of the tooltip
inner area. If ‘company-format-margin-function’ is set,
‘company-tooltip-margin’ defines only the right margin.
(setq company-tooltip-margin 3)
[image src="./images/small/tooltip-margin.png" ]
Candidates Icons
----------------
An “icon” is an image or a text that represents a candidate’s kind; it
is displayed in front of a candidate. The term “kind” here stands for a
high-level category a candidate fits into. (Such as ‘array’,
‘function’, ‘file’, ‘string’, ‘color’, etc. For an extended list of the
possible _kinds_, see the user option ‘company-text-icons-mapping’ or
the variable ‘company-vscode-icons-mapping’.)
-- User Option: company-format-margin-function
Allows setting a function to format the left margin of a tooltip
inner area; namely, to output candidate’s _icons_. The predefined
formatting functions are listed below. The user may also set this
option to a custom function. To disable left margin formatting,
set the value of the option to ‘nil’ (this way control over the
size of the left margin returns to the user option
‘company-tooltip-margin’).
-- Function: company-vscode-dark-icons-margin
-- Function: company-vscode-light-icons-margin
These functions utilize VSCode dark and light theme icon sets (1).
The related two user options are ‘company-icon-size’ and
‘company-icon-margin’.
[image src="./images/small/tooltip-icons-vscode.png" ]
-- Function: company-text-icons-margin
This function produces letters and symbols formatted according to
the ‘company-text-icons-format’. The rest of the user options
affecting this function behavior are listed below.
[image src="./images/small/tooltip-icons-text.png" ]
-- Function: company-dot-icons-margin
This function produces a colored Unicode symbol of a circle
formatted according to the ‘company-dot-icons-format’. Other user
options that affect the resulting output are listed below.
[image src="./images/small/tooltip-icons-dot.png" ]
The following user options influence appearance of the _text_ and _dot_
_icons_.
-- User Option: company-text-icons-mapping
Lists candidates’ _kinds_ with their corresponding _icons_
configurations.
-- User Option: company-text-face-extra-attributes
A list of face attributes to be applied to the _icons_.
(setq company-text-face-extra-attributes
'(:weight bold :slant italic))
[image src="./images/small/tooltip-icon-face.png" ]
-- User Option: company-text-icons-add-background
If this option is enabled, when an _icon_ doesn’t have a background
configured by ‘company-text-icons-mapping’, then a generated
background is applied.
(setq company-text-icons-add-background t)
[image src="./images/small/tooltip-icon-bg.png" ]
-- Function: company-detect-icons-margin
This is the default margin formatting function, that applies one of
the ‘company-vscode-*-icons-margin’ functions if ‘vscode’ icons set
is supported; otherwise applies a ‘company-text-icons-margin’
function.
Faces
-----
Out-of-the-box Company defines and configures distinguished faces (*note
(emacs)Faces::) for light and dark themes. Moreover, some of the
built-in and third-party themes fine-tune Company to fit their palettes.
That is why there’s often no real need to make such adjustments on the
user’s side. However, this chapter presents some hints on where to
start customizing Company interface.
Namely, the look of a tooltip is controlled by the ‘company-tooltip*’
named faces.
The following example suggests how users may approach tooltip faces
customization:
(custom-set-faces
'(company-tooltip
((t (:background "ivory" :foreground "MistyRose3"))))
'(company-tooltip-selection
((t (:background "LemonChiffon1" :foreground "MistyRose4"))))
'(company-tooltip-common ((t (:weight bold :foreground "pink1"))))
'(company-scrollbar-fg ((t (:background "ivory3"))))
'(company-scrollbar-bg ((t (:background "ivory2"))))
'(company-tooltip-annotation ((t (:foreground "MistyRose2")))))
[image src="./images/small/tooltip-faces-light.png" ]
---------- Footnotes ----------
(1) SVG images support has to be enabled in Emacs for these icons set
to be used. The supported images types can be checked with ‘C-h v
image-types’. Before compiling Emacs, make sure ‘librsvg’ is installed
on your system.
File: dociBJNK2.info, Node: Preview Frontends, Next: Echo Frontends, Prev: Tooltip Frontends, Up: Frontends
4.2 Preview Frontends
=====================
Frontends in this group output a completion candidate or a common part
of the candidates temporarily inline, as if the word had already been
completed (1).
-- Function: company-preview-if-just-one-frontend
This is one of the frontends enabled by default. This frontend
outputs a preview if only one completion candidate is available; it
is a good suit to be combined with
‘company-pseudo-tooltip-unless-just-one-frontend’, *note Tooltip
Frontends::.
-- Function: company-preview-frontend
This frontend outputs the first of the available completion
candidates inline for a preview.
-- Function: company-preview-common-frontend
As the name of this frontend suggests, it outputs for a preview
only a common part of the candidates.
The look of the preview is controlled by the following faces:
‘company-preview’, ‘company-preview-common’, and
‘company-preview-search’.
[image src="./images/small/preview-light.png" ]
[image src="./images/small/preview-dark.png" ]
---------- Footnotes ----------
(1) The candidates retrieved according to ‘non-prefix’ matches (*note
Terminology::) may be shown in full after point.
File: dociBJNK2.info, Node: Echo Frontends, Next: Candidates Search, Prev: Preview Frontends, Up: Frontends
4.3 Echo Frontends
==================
The frontends listed in this section display information in the Emacs’s
echo area, *note (emacs)Echo Area::.
-- Function: company-echo-metadata-frontend
This frontend is a part of the predefined frontends set. Its
responsibility is to output a short documentation string for a
completion candidate in the echo area.
[image src="./images/small/echo-meta.png" ]
The last pair of the built-in frontends isn’t that commonly used and not
as full-featured as the previously reviewed _tooltip-_ and _preview-_
frontends, but still, feel free to play with them and have some fun!
-- Function: company-echo-frontend
This frontend outputs all the available completion candidates in
the echo area.
[image src="./images/small/echo.png" ]
-- Function: company-echo-strip-common-frontend
It acts similarly to the previous frontend but outputs a common
part of the candidates once for all of them.
[image src="./images/small/echo-strip.png" ]
-- User Option: company-echo-truncate-lines
This is the only _echo frontends_ targeted setting. When enabled,
the output is truncated to fit the echo area. This setting is set
to ‘t’ by default.
To apply visual changes to the output of these frontends, configure the
faces ‘company-echo’ and ‘company-echo-common’.
File: dociBJNK2.info, Node: Candidates Search, Next: Filter Candidates, Prev: Echo Frontends, Up: Frontends
4.4 Candidates Search
=====================
By default, when _company-mode_ is in action, a key binding ‘C-s’ starts
looking for matches to additionally typed characters among the displayed
candidates. When a search is initiated, an indicator
‘Search: CHARACTERS’ is shown in the Emacs’s mode line.
To quit the search mode, hit ‘C-g’.
-- User Option: company-search-regexp-function
The value of this user option must be a function that interprets
the search input. By default it is set to the function
‘regexp-quote’, with looks for an exact match. Company defines
several more functions suitable for this option. They are listed
below.
-- Function: company-search-words-regexp
Searches for words separated with spaces in the given order.
-- Function: company-search-words-in-any-order-regexp
Searches for words separated with spaces in any order.
-- Function: company-search-flex-regexp
Searches for characters in the given order, with anything in
between.
Search matches are distinguished by the ‘company-tooltip-search’ and
‘company-tooltip-search-selection’ faces.
[image src="./images/small/tooltip-search.png" ]
File: dociBJNK2.info, Node: Filter Candidates, Next: Quick Access a Candidate, Prev: Candidates Search, Up: Frontends
4.5 Filter Candidates
=====================
Candidates filtering is started by typing the default key binding
‘C-M-s’. Filtering acts on a par with the search (*note Candidates
Search::), indicating its activation by the text ‘Filter: CHARACTERS’ in
the mode line and influencing the displayed candidates. The difference
is that the filtering, as its name suggests, keeps displaying only the
matching candidates (in addition to distinguishing the matches with a
face).
To quit the filtering, hit ‘C-g’. To toggle between search and filter
states, use key binding ‘C-o’.
[image src="./images/small/tooltip-filter.png" ]
File: dociBJNK2.info, Node: Quick Access a Candidate, Prev: Filter Candidates, Up: Frontends
4.6 Quick Access a Candidate
============================
Company provides a way to choose a candidate for completion without
having to navigate to that candidate: by hitting one of the quick-access
keys. By default, quick-access key bindings utilize a modifier <META>
and one of the digits, such that pressing ‘M-1’ completes with the first
candidate on the list and ‘M-0’ with the tenth candidate.
If ‘company-show-quick-access’ is enabled, _tooltip-_ and _echo-_
frontends show quick-access hints.
(setq company-show-quick-access 'left)
[image src="./images/small/tooltip-quick-access.png" ]
[image src="./images/small/echo-qa.png" ]
[image src="./images/small/echo-strip-qa.png" ]
To customize the key bindings, either do it via Customization Interface
(*note Customization Interface::) or use the following approach:
(custom-set-variables
'(company-quick-access-keys '("a" "o" "e" "u" "i"))
'(company-quick-access-modifier 'super))
A modifier should be one of ‘meta’, ‘super’, ‘hyper’, ‘ control’.
The following example applies a bit of customization and demonstrates
how to change quick-access hints faces.
(setq company-show-quick-access t)
(custom-set-faces
'(company-tooltip-quick-access ((t (:foreground "pink1"))))
'(company-tooltip-quick-access-selection
((t (:foreground "pink1" :slant italic)))))
[image src="./images/small/tooltip-qa-faces-light.png" ]
File: dociBJNK2.info, Node: Backends, Next: Troubleshooting, Prev: Frontends, Up: Top
5 Backends
**********
We can metaphorically say that each backend is like an engine. (The
reality is even better since backends are just functions.) Firing such
an engine with a command causes the production of material for Company
to work on. Typically, that means showing that output to the user via
one or several configured frontends, *note Frontends::.
Just like Company provides a preconfigured list of the enabled
frontends, it also defines a list of the backends to rely on by default.
This list is stored in the user option ‘company-backends’. The
docstring of this variable has the full description of what a backend is
and how to implement one. So we suggest reading the output of ‘C-h v
company-backends’ for more details. Nevertheless, the fundamental
concepts are described in this user manual too.
* Menu:
* Backends Usage Basics::
* Grouped Backends::
* Package Backends::
* Candidates Post-Processing::
File: dociBJNK2.info, Node: Backends Usage Basics, Next: Grouped Backends, Up: Backends
5.1 Backends Usage Basics
=========================
One of the significant concepts to understand about Company is that the
package relies on one backend at a time (1). The backends are invoked
one by one, in the sequential order of the items on the
‘company-backends’ list. The first one that reports itself applicable
in the current context (usually based on the value of ‘major-mode’ and
the text around point), is used for completion.
The name of the currently active backend is shown in the mode line and
in the output of the command ‘M-x company-diag’.
In most cases (mainly to exclude false-positive results), if the current
applicable backend returned no completions, the ones after it in the
list are not invoked. If you do want to query the next one, use the
command ‘company-other-backend’: either by calling it with ‘M-x’ or by
binding the command to the keys of your choice, like:
(global-set-key (kbd "C-c C-/") #'company-other-backend)
It is also possible to specifically start a backend with the command
‘M-x company-begin-backend’ or by calling a backend by its name, for
instance: ‘M-x company-capf’. As usual for Emacs, such backends calls
can be assigned to key bindings, for example:
(global-set-key (kbd "C-c y") 'company-yasnippet)
---------- Footnotes ----------
(1) The grouped backends act as one complex backend. *Note Grouped
Backends::.
File: dociBJNK2.info, Node: Grouped Backends, Next: Package Backends, Prev: Backends Usage Basics, Up: Backends
5.2 Grouped Backends
====================
In many cases, it can be desirable to receive candidates from several
backends simultaneously. This can be achieved by configuring “grouped
backends”: a sub-list of backends in the ‘company-backends’ list, that
is handled specifically by Company.
The most important part of this handling is the merge of the completion
candidates from the grouped backends.
To keep the candidates organized in accordance with the grouped backends
order, add the keyword ‘:separate’ to the list of the grouped backends.
The following example illustrates this.
(defun my-text-mode-hook ()
(setq-local company-backends
'((company-dabbrev company-ispell :separate)
company-files)))
(add-hook 'text-mode-hook #'my-text-mode-hook)
Another keyword ‘:with’ helps to make sure the results from major/minor
mode agnostic backends (such as _company-yasnippet_,