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
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
|
*insert.txt* For Vim version 8.2. Last change: 2021 Aug 31
VIM REFERENCE MANUAL by Bram Moolenaar
*Insert* *Insert-mode*
Inserting and replacing text *mode-ins-repl*
Most of this file is about Insert and Replace mode. At the end are a few
commands for inserting text in other ways.
An overview of the most often used commands can be found in chapter 24 of the
user manual |usr_24.txt|.
1. Special keys |ins-special-keys|
2. Special special keys |ins-special-special|
3. 'textwidth' and 'wrapmargin' options |ins-textwidth|
4. 'expandtab', 'smarttab' and 'softtabstop' options |ins-expandtab|
5. Replace mode |Replace-mode|
6. Virtual Replace mode |Virtual-Replace-mode|
7. Insert mode completion |ins-completion|
8. Insert mode commands |inserting|
9. Ex insert commands |inserting-ex|
10. Inserting a file |inserting-file|
Also see 'virtualedit', for moving the cursor to positions where there is no
character. Useful for editing a table.
==============================================================================
1. Special keys *ins-special-keys*
In Insert and Replace mode, the following characters have a special meaning;
other characters are inserted directly. To insert one of these special
characters into the buffer, precede it with CTRL-V. To insert a <Nul>
character use "CTRL-V CTRL-@" or "CTRL-V 000". On some systems, you have to
use "CTRL-V 003" to insert a CTRL-C. Note: When CTRL-V is mapped you can
often use CTRL-Q instead |i_CTRL-Q|.
If you are working in a special language mode when inserting text, see the
'langmap' option, |'langmap'|, on how to avoid switching this mode on and off
all the time.
If you have 'insertmode' set, <Esc> and a few other keys get another meaning.
See |'insertmode'|.
char action ~
-----------------------------------------------------------------------
*i_CTRL-[* *i_<Esc>*
<Esc> or CTRL-[ End insert or Replace mode, go back to Normal mode. Finish
abbreviation.
Note: If your <Esc> key is hard to hit on your keyboard, train
yourself to use CTRL-[.
If Esc doesn't work and you are using a Mac, try CTRL-Esc.
Or disable Listening under Accessibility preferences.
*i_CTRL-C*
CTRL-C Quit insert mode, go back to Normal mode. Do not check for
abbreviations. Does not trigger the |InsertLeave| autocommand
event.
*i_CTRL-@*
CTRL-@ Insert previously inserted text and stop insert.
*i_CTRL-A*
CTRL-A Insert previously inserted text.
*i_CTRL-H* *i_<BS>* *i_BS*
<BS> or CTRL-H Delete the character before the cursor (see |i_backspacing|
about joining lines).
See |:fixdel| if your <BS> key does not do what you want.
*i_<Del>* *i_DEL*
<Del> Delete the character under the cursor. If the cursor is at
the end of the line, and the 'backspace' option includes
"eol", delete the <EOL>; the next line is appended after the
current one.
See |:fixdel| if your <Del> key does not do what you want.
*i_CTRL-W*
CTRL-W Delete the word before the cursor (see |i_backspacing| about
joining lines). See the section "word motions",
|word-motions|, for the definition of a word.
*i_CTRL-U*
CTRL-U Delete all entered characters before the cursor in the current
line. If there are no newly entered characters and
'backspace' is not empty, delete all characters before the
cursor in the current line.
See |i_backspacing| about joining lines.
*i_CTRL-I* *i_<Tab>* *i_Tab*
<Tab> or CTRL-I Insert a tab. If the 'expandtab' option is on, the
equivalent number of spaces is inserted (use CTRL-V <Tab> to
avoid the expansion; use CTRL-Q <Tab> if CTRL-V is mapped
|i_CTRL-Q|). See also the 'smarttab' option and
|ins-expandtab|.
*i_CTRL-J* *i_<NL>*
<NL> or CTRL-J Begin new line.
*i_CTRL-M* *i_<CR>*
<CR> or CTRL-M Begin new line.
*i_CTRL-K*
CTRL-K {char1} [char2]
Enter digraph (see |digraphs|). When {char1} is a special
key, the code for that key is inserted in <> form. For
example, the string "<S-Space>" can be entered by typing
<C-K><S-Space> (two keys). Neither char is considered for
mapping.
CTRL-N Find next keyword (see |i_CTRL-N|).
CTRL-P Find previous keyword (see |i_CTRL-P|).
CTRL-R {register} *i_CTRL-R*
Insert the contents of a register. Between typing CTRL-R and
the second character, '"' will be displayed to indicate that
you are expected to enter the name of a register.
The text is inserted as if you typed it, but mappings and
abbreviations are not used. If you have options like
'textwidth', 'formatoptions', or 'autoindent' set, this will
influence what will be inserted. This is different from what
happens with the "p" command and pasting with the mouse.
Special registers:
'"' the unnamed register, containing the text of
the last delete or yank
'%' the current file name
'#' the alternate file name
'*' the clipboard contents (X11: primary selection)
'+' the clipboard contents
'/' the last search pattern
':' the last command-line
'.' the last inserted text
'-' the last small (less than a line) delete
*i_CTRL-R_=*
'=' the expression register: you are prompted to
enter an expression (see |expression|)
Note that 0x80 (128 decimal) is used for
special keys. E.g., you can use this to move
the cursor up:
CTRL-R ="\<Up>"
Use CTRL-R CTRL-R to insert text literally.
When the result is a |List| the items are used
as lines. They can have line breaks inside
too.
When the result is a Float it's automatically
converted to a String.
When append() or setline() is invoked the undo
sequence will be broken.
See |registers| about registers.
CTRL-R CTRL-R {register} *i_CTRL-R_CTRL-R*
Insert the contents of a register. Works like using a single
CTRL-R, but the text is inserted literally, not as if typed.
This differs when the register contains characters like <BS>.
Example, where register a contains "ab^Hc": >
CTRL-R a results in "ac".
CTRL-R CTRL-R a results in "ab^Hc".
< Options 'textwidth', 'formatoptions', etc. still apply. If
you also want to avoid these, use CTRL-R CTRL-O, see below.
The '.' register (last inserted text) is still inserted as
typed.
After this command, the '.' register contains the text from
the register as if it was inserted by typing it.
CTRL-R CTRL-O {register} *i_CTRL-R_CTRL-O*
Insert the contents of a register literally and don't
auto-indent. Does the same as pasting with the mouse
|<MiddleMouse>|. When the register is linewise this will
insert the text above the current line, like with `P`.
Does not replace characters!
The '.' register (last inserted text) is still inserted as
typed.
After this command, the '.' register contains the command
typed and not the text. I.e., the literals "^R^O" and not the
text from the register.
CTRL-R CTRL-P {register} *i_CTRL-R_CTRL-P*
Insert the contents of a register literally and fix the
indent, like |[<MiddleMouse>|.
Does not replace characters!
The '.' register (last inserted text) is still inserted as
typed.
After this command, the '.' register contains the command
typed and not the text. I.e., the literals "^R^P" and not the
text from the register.
*i_CTRL-T*
CTRL-T Insert one shiftwidth of indent at the start of the current
line. The indent is always rounded to a 'shiftwidth' (this is
vi compatible).
*i_CTRL-D*
CTRL-D Delete one shiftwidth of indent at the start of the current
line. The indent is always rounded to a 'shiftwidth' (this is
vi compatible).
*i_0_CTRL-D*
0 CTRL-D Delete all indent in the current line.
*i_^_CTRL-D*
^ CTRL-D Delete all indent in the current line. The indent is
restored in the next line. This is useful when inserting a
label.
*i_CTRL-V*
CTRL-V Insert next non-digit literally. For special keys, the
terminal code is inserted. It's also possible to enter the
decimal, octal or hexadecimal value of a character
|i_CTRL-V_digit|.
The characters typed right after CTRL-V are not considered for
mapping.
Note: When CTRL-V is mapped (e.g., to paste text) you can
often use CTRL-Q instead |i_CTRL-Q|.
When |modifyOtherKeys| is enabled then special Escape sequence
is converted back to what it was without |modifyOtherKeys|,
unless the Shift key is also pressed.
*i_CTRL-Q*
CTRL-Q Same as CTRL-V.
Note: Some terminal connections may eat CTRL-Q, it doesn't
work then. It does work in the GUI.
CTRL-SHIFT-V *i_CTRL-SHIFT-V* *i_CTRL-SHIFT-Q*
CTRL-SHIFT-Q Works just like CTRL-V, unless |modifyOtherKeys| is active,
then it inserts the Escape sequence for a key with modifiers.
CTRL-X Enter CTRL-X mode. This is a sub-mode where commands can
be given to complete words or scroll the window. See
|i_CTRL-X| and |ins-completion|.
*i_CTRL-E*
CTRL-E Insert the character which is below the cursor.
*i_CTRL-Y*
CTRL-Y Insert the character which is above the cursor.
Note that for CTRL-E and CTRL-Y 'textwidth' is not used, to be
able to copy characters from a long line.
*i_CTRL-_*
CTRL-_ Switch between languages, as follows:
- When in a rightleft window, revins and nohkmap are toggled,
since English will likely be inserted in this case.
- When in a norightleft window, revins and hkmap are toggled,
since Hebrew will likely be inserted in this case.
CTRL-_ moves the cursor to the end of the typed text.
This command is only available when the 'allowrevins' option
is set.
Please refer to |rileft.txt| for more information about
right-to-left mode.
Only if compiled with the |+rightleft| feature.
*i_CTRL-^*
CTRL-^ Toggle the use of typing language characters.
When language |:lmap| mappings are defined:
- If 'iminsert' is 1 (langmap mappings used) it becomes 0 (no
langmap mappings used).
- If 'iminsert' has another value it becomes 1, thus langmap
mappings are enabled.
When no language mappings are defined:
- If 'iminsert' is 2 (Input Method used) it becomes 0 (no
Input Method used).
- If 'iminsert' has another value it becomes 2, thus the Input
Method is enabled.
When set to 1, the value of the "b:keymap_name" variable, the
'keymap' option or "<lang>" appears in the status line.
The language mappings are normally used to type characters
that are different from what the keyboard produces. The
'keymap' option can be used to install a whole number of them.
*i_CTRL-]*
CTRL-] Trigger abbreviation, without inserting a character.
*i_<Insert>*
<Insert> Toggle between Insert and Replace mode.
-----------------------------------------------------------------------
*i_backspacing*
The effect of the <BS>, CTRL-W, and CTRL-U depend on the 'backspace' option
(unless 'revins' is set). This is a comma separated list of items:
item action ~
indent allow backspacing over autoindent
eol allow backspacing over end-of-line (join lines)
start allow backspacing over the start position of insert; CTRL-W and
CTRL-U stop once at the start position
When 'backspace' is empty, Vi compatible backspacing is used. You cannot
backspace over autoindent, before column 1 or before where insert started.
For backwards compatibility the values "0", "1" and "2" are also allowed, see
|'backspace'|.
If the 'backspace' option does contain "eol" and the cursor is in column 1
when one of the three keys is used, the current line is joined with the
previous line. This effectively deletes the <EOL> in front of the cursor.
*i_CTRL-V_digit*
With CTRL-V the decimal, octal or hexadecimal value of a character can be
entered directly. This way you can enter any character, except a line break
(<NL>, value 10). There are five ways to enter the character value:
first char mode max nr of chars max value ~
(none) decimal 3 255
o or O octal 3 377 (255)
x or X hexadecimal 2 ff (255)
u hexadecimal 4 ffff (65535)
U hexadecimal 8 7fffffff (2147483647)
Normally you would type the maximum number of characters. Thus to enter a
space (value 32) you would type <C-V>032. You can omit the leading zero, in
which case the character typed after the number must be a non-digit. This
happens for the other modes as well: As soon as you type a character that is
invalid for the mode, the value before it will be used and the "invalid"
character is dealt with in the normal way.
If you enter a value of 10, it will end up in the file as a 0. The 10 is a
<NL>, which is used internally to represent the <Nul> character. When writing
the buffer to a file, the <NL> character is translated into <Nul>. The <NL>
character is written at the end of each line. Thus if you want to insert a
<NL> character in a file you will have to make a line break.
Also see 'fileformat'.
*i_CTRL-X* *insert_expand*
CTRL-X enters a sub-mode where several commands can be used. Most of these
commands do keyword completion; see |ins-completion|.
Two commands can be used to scroll the window up or down, without exiting
insert mode:
*i_CTRL-X_CTRL-E*
CTRL-X CTRL-E scroll window one line up.
When doing completion look here: |complete_CTRL-E|
*i_CTRL-X_CTRL-Y*
CTRL-X CTRL-Y scroll window one line down.
When doing completion look here: |complete_CTRL-Y|
After CTRL-X is pressed, each CTRL-E (CTRL-Y) scrolls the window up (down) by
one line unless that would cause the cursor to move from its current position
in the file. As soon as another key is pressed, CTRL-X mode is exited and
that key is interpreted as in Insert mode.
==============================================================================
2. Special special keys *ins-special-special*
The following keys are special. They stop the current insert, do something,
and then restart insertion. This means you can do something without getting
out of Insert mode. This is very handy if you prefer to use the Insert mode
all the time, just like editors that don't have a separate Normal mode. You
may also want to set the 'backspace' option to "indent,eol,start" and set the
'insertmode' option. You can use CTRL-O if you want to map a function key to
a command.
The changes (inserted or deleted characters) before and after these keys can
be undone separately. Only the last change can be redone and always behaves
like an "i" command.
char action ~
-----------------------------------------------------------------------
<Up> cursor one line up *i_<Up>*
<Down> cursor one line down *i_<Down>*
CTRL-G <Up> cursor one line up, insert start column *i_CTRL-G_<Up>*
CTRL-G k cursor one line up, insert start column *i_CTRL-G_k*
CTRL-G CTRL-K cursor one line up, insert start column *i_CTRL-G_CTRL-K*
CTRL-G <Down> cursor one line down, insert start column *i_CTRL-G_<Down>*
CTRL-G j cursor one line down, insert start column *i_CTRL-G_j*
CTRL-G CTRL-J cursor one line down, insert start column *i_CTRL-G_CTRL-J*
<Left> cursor one character left *i_<Left>*
<Right> cursor one character right *i_<Right>*
<S-Left> cursor one word back (like "b" command) *i_<S-Left>*
<C-Left> cursor one word back (like "b" command) *i_<C-Left>*
<S-Right> cursor one word forward (like "w" command) *i_<S-Right>*
<C-Right> cursor one word forward (like "w" command) *i_<C-Right>*
<Home> cursor to first char in the line *i_<Home>*
<End> cursor to after last char in the line *i_<End>*
<C-Home> cursor to first char in the file *i_<C-Home>*
<C-End> cursor to after last char in the file *i_<C-End>*
<LeftMouse> cursor to position of mouse click *i_<LeftMouse>*
<S-Up> move window one page up *i_<S-Up>*
<PageUp> move window one page up *i_<PageUp>*
<S-Down> move window one page down *i_<S-Down>*
<PageDown> move window one page down *i_<PageDown>*
<ScrollWheelDown> move window three lines down *i_<ScrollWheelDown>*
<S-ScrollWheelDown> move window one page down *i_<S-ScrollWheelDown>*
<ScrollWheelUp> move window three lines up *i_<ScrollWheelUp>*
<S-ScrollWheelUp> move window one page up *i_<S-ScrollWheelUp>*
<ScrollWheelLeft> move window six columns left *i_<ScrollWheelLeft>*
<S-ScrollWheelLeft> move window one page left *i_<S-ScrollWheelLeft>*
<ScrollWheelRight> move window six columns right *i_<ScrollWheelRight>*
<S-ScrollWheelRight> move window one page right *i_<S-ScrollWheelRight>*
CTRL-O execute one command, return to Insert mode *i_CTRL-O*
CTRL-\ CTRL-O like CTRL-O but don't move the cursor *i_CTRL-\_CTRL-O*
CTRL-L when 'insertmode' is set: go to Normal mode *i_CTRL-L*
CTRL-G u break undo sequence, start new change *i_CTRL-G_u*
CTRL-G U don't break undo with next left/right cursor *i_CTRL-G_U*
movement, if the cursor stays within the
same line
-----------------------------------------------------------------------
Note: If the cursor keys take you out of Insert mode, check the 'noesckeys'
option.
The CTRL-O command sometimes has a side effect: If the cursor was beyond the
end of the line, it will be put on the last character in the line. In
mappings it's often better to use <Esc> (first put an "x" in the text, <Esc>
will then always put the cursor on it). Or use CTRL-\ CTRL-O, but then
beware of the cursor possibly being beyond the end of the line. Note that the
command following CTRL-\ CTRL-O can still move the cursor, it is not restored
to its original position.
The CTRL-O command takes you to Normal mode. If you then use a command enter
Insert mode again it normally doesn't nest. Thus when typing "a<C-O>a" and
then <Esc> takes you back to Normal mode, you do not need to type <Esc> twice.
An exception is when not typing the command, e.g. when executing a mapping or
sourcing a script. This makes mappings work that briefly switch to Insert
mode.
The shifted cursor keys are not available on all terminals.
Another side effect is that a count specified before the "i" or "a" command is
ignored. That is because repeating the effect of the command after CTRL-O is
too complicated.
An example for using CTRL-G u: >
:inoremap <C-H> <C-G>u<C-H>
This redefines the backspace key to start a new undo sequence. You can now
undo the effect of the backspace key, without changing what you typed before
that, with CTRL-O u. Another example: >
:inoremap <CR> <C-]><C-G>u<CR>
This breaks undo at each line break. It also expands abbreviations before
this.
An example for using CTRL-G U: >
inoremap <Left> <C-G>U<Left>
inoremap <Right> <C-G>U<Right>
inoremap <expr> <Home> col('.') == match(getline('.'), '\S') + 1 ?
\ repeat('<C-G>U<Left>', col('.') - 1) :
\ (col('.') < match(getline('.'), '\S') ?
\ repeat('<C-G>U<Right>', match(getline('.'), '\S') + 0) :
\ repeat('<C-G>U<Left>', col('.') - 1 - match(getline('.'), '\S')))
inoremap <expr> <End> repeat('<C-G>U<Right>', col('$') - col('.'))
inoremap ( ()<C-G>U<Left>
This makes it possible to use the cursor keys in Insert mode, without breaking
the undo sequence and therefore using |.| (redo) will work as expected.
Also entering a text like (with the "(" mapping from above):
Lorem ipsum (dolor
will be repeatable by using |.| to the expected
Lorem ipsum (dolor)
Using CTRL-O splits undo: the text typed before and after it is undone
separately. If you want to avoid this (e.g., in a mapping) you might be able
to use CTRL-R = |i_CTRL-R|. E.g., to call a function: >
:imap <F2> <C-R>=MyFunc()<CR>
When the 'whichwrap' option is set appropriately, the <Left> and <Right>
keys on the first/last character in the line make the cursor wrap to the
previous/next line.
The CTRL-G j and CTRL-G k commands can be used to insert text in front of a
column. Example: >
int i;
int j;
Position the cursor on the first "int", type "istatic <C-G>j ". The
result is: >
static int i;
int j;
When inserting the same text in front of the column in every line, use the
Visual blockwise command "I" |v_b_I|.
==============================================================================
3. 'textwidth' and 'wrapmargin' options *ins-textwidth*
The 'textwidth' option can be used to automatically break a line before it
gets too long. Set the 'textwidth' option to the desired maximum line
length. If you then type more characters (not spaces or tabs), the
last word will be put on a new line (unless it is the only word on the
line). If you set 'textwidth' to 0, this feature is disabled.
The 'wrapmargin' option does almost the same. The difference is that
'textwidth' has a fixed width while 'wrapmargin' depends on the width of the
screen. When using 'wrapmargin' this is equal to using 'textwidth' with a
value equal to (columns - 'wrapmargin'), where columns is the width of the
screen.
When 'textwidth' and 'wrapmargin' are both set, 'textwidth' is used.
If you don't really want to break the line, but view the line wrapped at a
convenient place, see the 'linebreak' option.
The line is only broken automatically when using Insert mode, or when
appending to a line. When in replace mode and the line length is not
changed, the line will not be broken.
Long lines are broken if you enter a non-white character after the margin.
The situations where a line will be broken can be restricted by adding
characters to the 'formatoptions' option:
"l" Only break a line if it was not longer than 'textwidth' when the insert
started.
"v" Only break at a white character that has been entered during the
current insert command. This is mostly Vi-compatible.
"lv" Only break if the line was not longer than 'textwidth' when the insert
started and only at a white character that has been entered during the
current insert command. Only differs from "l" when entering non-white
characters while crossing the 'textwidth' boundary.
Normally an internal function will be used to decide where to break the line.
If you want to do it in a different way set the 'formatexpr' option to an
expression that will take care of the line break.
If you want to format a block of text, you can use the "gq" operator. Type
"gq" and a movement command to move the cursor to the end of the block. In
many cases, the command "gq}" will do what you want (format until the end of
paragraph). Alternatively, you can use "gqap", which will format the whole
paragraph, no matter where the cursor currently is. Or you can use Visual
mode: hit "v", move to the end of the block, and type "gq". See also |gq|.
==============================================================================
4. 'expandtab', 'smarttab' and 'softtabstop' options *ins-expandtab*
If the 'expandtab' option is on, spaces will be used to fill the amount of
whitespace of the tab. If you want to enter a real <Tab>, type CTRL-V first
(use CTRL-Q when CTRL-V is mapped |i_CTRL-Q|).
The 'expandtab' option is off by default. Note that in Replace mode, a single
character is replaced with several spaces. The result of this is that the
number of characters in the line increases. Backspacing will delete one
space at a time. The original character will be put back for only one space
that you backspace over (the last one).
*ins-smarttab*
When the 'smarttab' option is on, a <Tab> inserts 'shiftwidth' positions at
the beginning of a line and 'tabstop' positions in other places. This means
that often spaces instead of a <Tab> character are inserted. When 'smarttab'
is off, a <Tab> always inserts 'tabstop' positions, and 'shiftwidth' is only
used for ">>" and the like.
*ins-softtabstop*
When the 'softtabstop' option is non-zero, a <Tab> inserts 'softtabstop'
positions, and a <BS> used to delete white space, will delete 'softtabstop'
positions. This feels like 'tabstop' was set to 'softtabstop', but a real
<Tab> character still takes 'tabstop' positions, so your file will still look
correct when used by other applications.
If 'softtabstop' is non-zero, a <BS> will try to delete as much white space to
move to the previous 'softtabstop' position, except when the previously
inserted character is a space, then it will only delete the character before
the cursor. Otherwise you cannot always delete a single character before the
cursor. You will have to delete 'softtabstop' characters first, and then type
extra spaces to get where you want to be.
==============================================================================
5. Replace mode *Replace* *Replace-mode* *mode-replace*
Enter Replace mode with the "R" command in normal mode.
In Replace mode, one character in the line is deleted for every character you
type. If there is no character to delete (at the end of the line), the
typed character is appended (as in Insert mode). Thus the number of
characters in a line stays the same until you get to the end of the line.
If a <NL> is typed, a line break is inserted and no character is deleted.
Be careful with <Tab> characters. If you type a normal printing character in
its place, the number of characters is still the same, but the number of
columns will become smaller.
If you delete characters in Replace mode (with <BS>, CTRL-W, or CTRL-U), what
happens is that you delete the changes. The characters that were replaced
are restored. If you had typed past the existing text, the characters you
added are deleted. This is effectively a character-at-a-time undo.
If the 'expandtab' option is on, a <Tab> will replace one character with
several spaces. The result of this is that the number of characters in the
line increases. Backspacing will delete one space at a time. The original
character will be put back for only one space that you backspace over (the
last one).
==============================================================================
6. Virtual Replace mode *vreplace-mode* *Virtual-Replace-mode*
Enter Virtual Replace mode with the "gR" command in normal mode.
{not available when compiled without the |+vreplace| feature}
Virtual Replace mode is similar to Replace mode, but instead of replacing
actual characters in the file, you are replacing screen real estate, so that
characters further on in the file never appear to move.
So if you type a <Tab> it may replace several normal characters, and if you
type a letter on top of a <Tab> it may not replace anything at all, since the
<Tab> will still line up to the same place as before.
Typing a <NL> still doesn't cause characters later in the file to appear to
move. The rest of the current line will be replaced by the <NL> (that is,
they are deleted), and replacing continues on the next line. A new line is
NOT inserted unless you go past the end of the file.
Interesting effects are seen when using CTRL-T and CTRL-D. The characters
before the cursor are shifted sideways as normal, but characters later in the
line still remain still. CTRL-T will hide some of the old line under the
shifted characters, but CTRL-D will reveal them again.
As with Replace mode, using <BS> etc will bring back the characters that were
replaced. This still works in conjunction with 'smartindent', CTRL-T and
CTRL-D, 'expandtab', 'smarttab', 'softtabstop', etc.
In 'list' mode, Virtual Replace mode acts as if it was not in 'list' mode,
unless "L" is in 'cpoptions'.
Note that the only situations for which characters beyond the cursor should
appear to move are in List mode |'list'|, and occasionally when 'wrap' is set
(and the line changes length to become shorter or wider than the width of the
screen). In other cases spaces may be inserted to avoid following characters
to move.
This mode is very useful for editing <Tab> separated columns in tables, for
entering new data while keeping all the columns aligned.
==============================================================================
7. Insert mode completion *ins-completion*
In Insert and Replace mode, there are several commands to complete part of a
keyword or line that has been typed. This is useful if you are using
complicated keywords (e.g., function names with capitals and underscores).
Completion can be done for:
1. Whole lines |i_CTRL-X_CTRL-L|
2. keywords in the current file |i_CTRL-X_CTRL-N|
3. keywords in 'dictionary' |i_CTRL-X_CTRL-K|
4. keywords in 'thesaurus', thesaurus-style |i_CTRL-X_CTRL-T|
5. keywords in the current and included files |i_CTRL-X_CTRL-I|
6. tags |i_CTRL-X_CTRL-]|
7. file names |i_CTRL-X_CTRL-F|
8. definitions or macros |i_CTRL-X_CTRL-D|
9. Vim command-line |i_CTRL-X_CTRL-V|
10. User defined completion |i_CTRL-X_CTRL-U|
11. omni completion |i_CTRL-X_CTRL-O|
12. Spelling suggestions |i_CTRL-X_s|
13. keywords in 'complete' |i_CTRL-N| |i_CTRL-P|
Additionally, |i_CTRL-X_CTRL-Z| stops completion without changing the text.
All these, except CTRL-N and CTRL-P, are done in CTRL-X mode. This is a
sub-mode of Insert and Replace modes. You enter CTRL-X mode by typing CTRL-X
and one of the CTRL-X commands. You exit CTRL-X mode by typing a key that is
not a valid CTRL-X mode command. Valid keys are the CTRL-X command itself,
CTRL-N (next), and CTRL-P (previous).
To get the current completion information, |complete_info()| can be used.
Also see the 'infercase' option if you want to adjust the case of the match.
*complete_CTRL-E*
When completion is active you can use CTRL-E to stop it and go back to the
originally typed text. The CTRL-E will not be inserted.
*complete_CTRL-Y*
When the popup menu is displayed you can use CTRL-Y to stop completion and
accept the currently selected entry. The CTRL-Y is not inserted. Typing a
space, Enter, or some other unprintable character will leave completion mode
and insert that typed character.
When the popup menu is displayed there are a few more special keys, see
|popupmenu-keys|.
Note: The keys that are valid in CTRL-X mode are not mapped. This allows for
":map ^F ^X^F" to work (where ^F is CTRL-F and ^X is CTRL-X). The key that
ends CTRL-X mode (any key that is not a valid CTRL-X mode command) is mapped.
Also, when doing completion with 'complete' mappings apply as usual.
*E578* *E565*
Note: While completion is active Insert mode can't be used recursively and
buffer text cannot be changed. Mappings that somehow invoke ":normal i.."
will generate an E565 error.
The following mappings are suggested to make typing the completion commands
a bit easier (although they will hide other commands): >
:inoremap ^] ^X^]
:inoremap ^F ^X^F
:inoremap ^D ^X^D
:inoremap ^L ^X^L
As a special case, typing CTRL-R to perform register insertion (see
|i_CTRL-R|) will not exit CTRL-X mode. This is primarily to allow the use of
the '=' register to call some function to determine the next operation. If
the contents of the register (or result of the '=' register evaluation) are
not valid CTRL-X mode keys, then CTRL-X mode will be exited as if those keys
had been typed.
For example, the following will map <Tab> to either actually insert a <Tab> if
the current line is currently only whitespace, or start/continue a CTRL-N
completion operation: >
function! CleverTab()
if strpart( getline('.'), 0, col('.')-1 ) =~ '^\s*$'
return "\<Tab>"
else
return "\<C-N>"
endif
endfunction
inoremap <Tab> <C-R>=CleverTab()<CR>
Completing whole lines *compl-whole-line*
*i_CTRL-X_CTRL-L*
CTRL-X CTRL-L Search backwards for a line that starts with the
same characters as those in the current line before
the cursor. Indent is ignored. The matching line is
inserted in front of the cursor.
The 'complete' option is used to decide which buffers
are searched for a match. Both loaded and unloaded
buffers are used.
CTRL-L or
CTRL-P Search backwards for next matching line. This line
replaces the previous matching line.
CTRL-N Search forward for next matching line. This line
replaces the previous matching line.
CTRL-X CTRL-L After expanding a line you can additionally get the
line next to it by typing CTRL-X CTRL-L again, unless
a double CTRL-X is used. Only works for loaded
buffers.
Completing keywords in current file *compl-current*
*i_CTRL-X_CTRL-P*
*i_CTRL-X_CTRL-N*
CTRL-X CTRL-N Search forwards for words that start with the keyword
in front of the cursor. The found keyword is inserted
in front of the cursor.
CTRL-X CTRL-P Search backwards for words that start with the keyword
in front of the cursor. The found keyword is inserted
in front of the cursor.
CTRL-N Search forward for next matching keyword. This
keyword replaces the previous matching keyword.
CTRL-P Search backwards for next matching keyword. This
keyword replaces the previous matching keyword.
CTRL-X CTRL-N or
CTRL-X CTRL-P Further use of CTRL-X CTRL-N or CTRL-X CTRL-P will
copy the words following the previous expansion in
other contexts unless a double CTRL-X is used.
If there is a keyword in front of the cursor (a name made out of alphabetic
characters and characters in 'iskeyword'), it is used as the search pattern,
with "\<" prepended (meaning: start of a word). Otherwise "\<\k\k" is used
as search pattern (start of any keyword of at least two characters).
In Replace mode, the number of characters that are replaced depends on the
length of the matched string. This works like typing the characters of the
matched string in Replace mode.
If there is not a valid keyword character before the cursor, any keyword of
at least two characters is matched.
e.g., to get:
printf("(%g, %g, %g)", vector[0], vector[1], vector[2]);
just type:
printf("(%g, %g, %g)", vector[0], ^P[1], ^P[2]);
The search wraps around the end of the file, the value of 'wrapscan' is not
used here.
Multiple repeats of the same completion are skipped; thus a different match
will be inserted at each CTRL-N and CTRL-P (unless there is only one
matching keyword).
Single character matches are never included, as they usually just get in
the way of what you were really after.
e.g., to get:
printf("name = %s\n", name);
just type:
printf("name = %s\n", n^P);
or even:
printf("name = %s\n", ^P);
The 'n' in '\n' is skipped.
After expanding a word, you can use CTRL-X CTRL-P or CTRL-X CTRL-N to get the
word following the expansion in other contexts. These sequences search for
the text just expanded and further expand by getting an extra word. This is
useful if you need to repeat a sequence of complicated words. Although CTRL-P
and CTRL-N look just for strings of at least two characters, CTRL-X CTRL-P and
CTRL-X CTRL-N can be used to expand words of just one character.
e.g., to get:
México
you can type:
M^N^P^X^P^X^P
CTRL-N starts the expansion and then CTRL-P takes back the single character
"M", the next two CTRL-X CTRL-P's get the words "é" and ";xico".
If the previous expansion was split, because it got longer than 'textwidth',
then just the text in the current line will be used.
If the match found is at the end of a line, then the first word in the next
line will be inserted and the message "word from next line" displayed, if
this word is accepted the next CTRL-X CTRL-P or CTRL-X CTRL-N will search
for those lines starting with this word.
Completing keywords in 'dictionary' *compl-dictionary*
*i_CTRL-X_CTRL-K*
CTRL-X CTRL-K Search the files given with the 'dictionary' option
for words that start with the keyword in front of the
cursor. This is like CTRL-N, but only the dictionary
files are searched, not the current file. The found
keyword is inserted in front of the cursor. This
could potentially be pretty slow, since all matches
are found before the first match is used. By default,
the 'dictionary' option is empty.
For suggestions where to find a list of words, see the
'dictionary' option.
CTRL-K or
CTRL-N Search forward for next matching keyword. This
keyword replaces the previous matching keyword.
CTRL-P Search backwards for next matching keyword. This
keyword replaces the previous matching keyword.
*i_CTRL-X_CTRL-T*
CTRL-X CTRL-T Works as CTRL-X CTRL-K, but in a special way. It uses
the 'thesaurus' option instead of 'dictionary'. If a
match is found in the thesaurus file, all the
remaining words on the same line are included as
matches, even though they don't complete the word.
Thus a word can be completely replaced.
For an example, imagine the 'thesaurus' file has a
line like this: >
angry furious mad enraged
< Placing the cursor after the letters "ang" and typing
CTRL-X CTRL-T would complete the word "angry";
subsequent presses would change the word to "furious",
"mad" etc.
Other uses include translation between two languages,
or grouping API functions by keyword.
CTRL-T or
CTRL-N Search forward for next matching keyword. This
keyword replaces the previous matching keyword.
CTRL-P Search backwards for next matching keyword. This
keyword replaces the previous matching keyword.
Completing keywords in the current and included files *compl-keyword*
The 'include' option is used to specify a line that contains an include file
name. The 'path' option is used to search for include files.
*i_CTRL-X_CTRL-I*
CTRL-X CTRL-I Search for the first keyword in the current and
included files that starts with the same characters
as those before the cursor. The matched keyword is
inserted in front of the cursor.
CTRL-N Search forwards for next matching keyword. This
keyword replaces the previous matching keyword.
Note: CTRL-I is the same as <Tab>, which is likely to
be typed after a successful completion, therefore
CTRL-I is not used for searching for the next match.
CTRL-P Search backward for previous matching keyword. This
keyword replaces the previous matching keyword.
CTRL-X CTRL-I Further use of CTRL-X CTRL-I will copy the words
following the previous expansion in other contexts
unless a double CTRL-X is used.
Completing tags *compl-tag*
*i_CTRL-X_CTRL-]*
CTRL-X CTRL-] Search for the first tag that starts with the same
characters as before the cursor. The matching tag is
inserted in front of the cursor. Alphabetic
characters and characters in 'iskeyword' are used
to decide which characters are included in the tag
name (same as for a keyword). See also |CTRL-]|.
The 'showfulltag' option can be used to add context
from around the tag definition.
CTRL-] or
CTRL-N Search forwards for next matching tag. This tag
replaces the previous matching tag.
CTRL-P Search backward for previous matching tag. This tag
replaces the previous matching tag.
Completing file names *compl-filename*
*i_CTRL-X_CTRL-F*
CTRL-X CTRL-F Search for the first file name that starts with the
same characters as before the cursor. The matching
file name is inserted in front of the cursor.
Alphabetic characters and characters in 'isfname'
are used to decide which characters are included in
the file name. Note: the 'path' option is not used
here (yet).
CTRL-F or
CTRL-N Search forwards for next matching file name. This
file name replaces the previous matching file name.
CTRL-P Search backward for previous matching file name.
This file name replaces the previous matching file
name.
Completing definitions or macros *compl-define*
The 'define' option is used to specify a line that contains a definition.
The 'include' option is used to specify a line that contains an include file
name. The 'path' option is used to search for include files.
*i_CTRL-X_CTRL-D*
CTRL-X CTRL-D Search in the current and included files for the
first definition (or macro) name that starts with
the same characters as before the cursor. The found
definition name is inserted in front of the cursor.
CTRL-D or
CTRL-N Search forwards for next matching macro name. This
macro name replaces the previous matching macro
name.
CTRL-P Search backward for previous matching macro name.
This macro name replaces the previous matching macro
name.
CTRL-X CTRL-D Further use of CTRL-X CTRL-D will copy the words
following the previous expansion in other contexts
unless a double CTRL-X is used.
Completing Vim commands *compl-vim*
Completion is context-sensitive. It works like on the Command-line. It
completes an Ex command as well as its arguments. This is useful when writing
a Vim script.
*i_CTRL-X_CTRL-V*
CTRL-X CTRL-V Guess what kind of item is in front of the cursor and
find the first match for it.
Note: When CTRL-V is mapped you can often use CTRL-Q
instead of |i_CTRL-Q|.
CTRL-V or
CTRL-N Search forwards for next match. This match replaces
the previous one.
CTRL-P Search backwards for previous match. This match
replaces the previous one.
CTRL-X CTRL-V Further use of CTRL-X CTRL-V will do the same as
CTRL-V. This allows mapping a key to do Vim command
completion, for example: >
:imap <Tab> <C-X><C-V>
User defined completion *compl-function*
Completion is done by a function that can be defined by the user with the
'completefunc' option. See below for how the function is called and an
example |complete-functions|.
*i_CTRL-X_CTRL-U*
CTRL-X CTRL-U Guess what kind of item is in front of the cursor and
find the first match for it.
CTRL-U or
CTRL-N Use the next match. This match replaces the previous
one.
CTRL-P Use the previous match. This match replaces the
previous one.
Omni completion *compl-omni*
Completion is done by a function that can be defined by the user with the
'omnifunc' option. This is to be used for filetype-specific completion.
See below for how the function is called and an example |complete-functions|.
For remarks about specific filetypes see |compl-omni-filetypes|.
More completion scripts will appear, check www.vim.org. Currently there is a
first version for C++.
*i_CTRL-X_CTRL-O*
CTRL-X CTRL-O Guess what kind of item is in front of the cursor and
find the first match for it.
CTRL-O or
CTRL-N Use the next match. This match replaces the previous
one.
CTRL-P Use the previous match. This match replaces the
previous one.
Spelling suggestions *compl-spelling*
A word before or at the cursor is located and correctly spelled words are
suggested to replace it. If there is a badly spelled word in the line, before
or under the cursor, the cursor is moved to after it. Otherwise the word just
before the cursor is used for suggestions, even though it isn't badly spelled.
NOTE: CTRL-S suspends display in many Unix terminals. Use 's' instead. Type
CTRL-Q to resume displaying.
*i_CTRL-X_CTRL-S* *i_CTRL-X_s*
CTRL-X CTRL-S or
CTRL-X s Locate the word in front of the cursor and find the
first spell suggestion for it.
CTRL-S or
CTRL-N Use the next suggestion. This replaces the previous
one. Note that you can't use 's' here.
CTRL-P Use the previous suggestion. This replaces the
previous one.
Completing keywords from different sources *compl-generic*
*i_CTRL-N*
CTRL-N Find next match for words that start with the
keyword in front of the cursor, looking in places
specified with the 'complete' option. The found
keyword is inserted in front of the cursor.
*i_CTRL-P*
CTRL-P Find previous match for words that start with the
keyword in front of the cursor, looking in places
specified with the 'complete' option. The found
keyword is inserted in front of the cursor.
CTRL-N Search forward for next matching keyword. This
keyword replaces the previous matching keyword.
CTRL-P Search backwards for next matching keyword. This
keyword replaces the previous matching keyword.
CTRL-X CTRL-N or
CTRL-X CTRL-P Further use of CTRL-X CTRL-N or CTRL-X CTRL-P will
copy the words following the previous expansion in
other contexts unless a double CTRL-X is used.
Stop completion *compl-stop*
*i_CTRL-X_CTRL-Z*
CTRL-X CTRL-Z Stop completion without changing the text.
FUNCTIONS FOR FINDING COMPLETIONS *complete-functions*
This applies to 'completefunc' and 'omnifunc'.
The function is called in two different ways:
- First the function is called to find the start of the text to be completed.
- Later the function is called to actually find the matches.
On the first invocation the arguments are:
a:findstart 1
a:base empty
The function must return the column where the completion starts. It must be a
number between zero and the cursor column "col('.')". This involves looking
at the characters just before the cursor and including those characters that
could be part of the completed item. The text between this column and the
cursor column will be replaced with the matches. If the returned value is
larger than the cursor column, the cursor column is used.
Negative return values:
-2 To cancel silently and stay in completion mode.
-3 To cancel silently and leave completion mode.
Another negative value: completion starts at the cursor column
On the second invocation the arguments are:
a:findstart 0
a:base the text with which matches should match; the text that was
located in the first call (can be empty)
The function must return a List with the matching words. These matches
usually include the "a:base" text. When there are no matches return an empty
List. Note that the cursor may have moved since the first invocation, the
text may have been changed.
In order to return more information than the matching words, return a Dict
that contains the List. The Dict can have these items:
words The List of matching words (mandatory).
refresh A string to control re-invocation of the function
(optional).
The only value currently recognized is "always", the
effect is that the function is called whenever the
leading text is changed.
If you want to suppress the warning message for an empty result, return
|v:none|. This is useful to implement asynchronous completion with
|complete()|.
Other items are ignored.
For acting upon end of completion, see the |CompleteDonePre| and
|CompleteDone| autocommand event.
For example, the function can contain this: >
let matches = ... list of words ...
return {'words': matches, 'refresh': 'always'}
<
*complete-items*
Each list item can either be a string or a Dictionary. When it is a string it
is used as the completion. When it is a Dictionary it can contain these
items:
word the text that will be inserted, mandatory
abbr abbreviation of "word"; when not empty it is used in
the menu instead of "word"
menu extra text for the popup menu, displayed after "word"
or "abbr"
info more information about the item, can be displayed in a
preview or popup window
kind single letter indicating the type of completion
icase when non-zero case is to be ignored when comparing
items to be equal; when omitted zero is used, thus
items that only differ in case are added
equal when non-zero, always treat this item to be equal when
comparing. Which means, "equal=1" disables filtering
of this item.
dup when non-zero this match will be added even when an
item with the same word is already present.
empty when non-zero this match will be added even when it is
an empty string
user_data custom data which is associated with the item and
available in |v:completed_item|; it can be any type;
defaults to an empty string
All of these except "icase", "equal", "dup" and "empty" must be a string. If
an item does not meet these requirements then an error message is given and
further items in the list are not used. You can mix string and Dictionary
items in the returned list.
The "menu" item is used in the popup menu and may be truncated, thus it should
be relatively short. The "info" item can be longer, it will be displayed in
the preview window when "preview" appears in 'completeopt' or in a popup
window when "popup" appears in 'completeopt'. In the preview window the
"info" item will also remain displayed after the popup menu has been removed.
This is useful for function arguments. Use a single space for "info" to
remove existing text in the preview window. The size of the preview window is
three lines, but 'previewheight' is used when it has a value of 1 or 2.
*complete-popup*
When "popup" is in 'completeopt' a popup window is used to display the "info".
Then the 'completepopup' option specifies the properties of the popup. This
is used when the info popup is created. The option is a comma separated list
of values:
height maximum height of the popup
width maximum width of the popup
highlight highlight group of the popup (default is PmenuSel)
align "item" (default) or "menu"
border "on" (default) or "off"
Example: >
:set completepopup=height:10,width:60,highlight:InfoPopup
When the "align" value is "item" then the popup is positioned close to the
selected item. Changing the selection will also move the popup. When "align"
is "menu" then the popup is aligned with the top of the menu if the menu is
below the text, and the bottom of the menu otherwise.
After the info popup is created it can be found with |popup_findinfo()| and
properties can be changed with |popup_setoptions()|.
*complete-popuphidden*
If the information for the popup is obtained asynchronously, use "popuphidden"
in 'completeopt'. The info popup will then be initially hidden and
|popup_show()| must be called once it has been filled with the info. This can
be done with a |CompleteChanged| autocommand, something like this: >
set completeopt+=popuphidden
au CompleteChanged * call UpdateCompleteInfo()
func UpdateCompleteInfo()
" Cancel any pending info fetch
let item = v:event.completed_item
" Start fetching info for the item then call ShowCompleteInfo(info)
endfunc
func ShowCompleteInfo(info)
let id = popup_findinfo()
if id
call popup_settext(id, 'async info: ' .. a:info)
call popup_show(id)
endif
endfunc
< *complete-item-kind*
The "kind" item uses a single letter to indicate the kind of completion. This
may be used to show the completion differently (different color or icon).
Currently these types can be used:
v variable
f function or method
m member of a struct or class
t typedef
d #define or macro
When searching for matches takes some time call |complete_add()| to add each
match to the total list. These matches should then not appear in the returned
list! Call |complete_check()| now and then to allow the user to press a key
while still searching for matches. Stop searching when it returns non-zero.
*E840*
The function is allowed to move the cursor, it is restored afterwards.
The function is not allowed to move to another window or delete text.
An example that completes the names of the months: >
fun! CompleteMonths(findstart, base)
if a:findstart
" locate the start of the word
let line = getline('.')
let start = col('.') - 1
while start > 0 && line[start - 1] =~ '\a'
let start -= 1
endwhile
return start
else
" find months matching with "a:base"
let res = []
for m in split("Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec")
if m =~ '^' . a:base
call add(res, m)
endif
endfor
return res
endif
endfun
set completefunc=CompleteMonths
<
The same, but now pretending searching for matches is slow: >
fun! CompleteMonths(findstart, base)
if a:findstart
" locate the start of the word
let line = getline('.')
let start = col('.') - 1
while start > 0 && line[start - 1] =~ '\a'
let start -= 1
endwhile
return start
else
" find months matching with "a:base"
for m in split("Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec")
if m =~ '^' . a:base
call complete_add(m)
endif
sleep 300m " simulate searching for next match
if complete_check()
break
endif
endfor
return []
endif
endfun
set completefunc=CompleteMonths
<
INSERT COMPLETION POPUP MENU *ins-completion-menu*
*popupmenu-completion*
Vim can display the matches in a simplistic popup menu.
The menu is used when:
- The 'completeopt' option contains "menu" or "menuone".
- The terminal supports at least 8 colors.
- There are at least two matches. One if "menuone" is used.
The 'pumheight' option can be used to set a maximum height. The default is to
use all space available.
The 'pumwidth' option can be used to set a minimum width. The default is 15
characters.
There are three states:
1. A complete match has been inserted, e.g., after using CTRL-N or CTRL-P.
2. A cursor key has been used to select another match. The match was not
inserted then, only the entry in the popup menu is highlighted.
3. Only part of a match has been inserted and characters were typed or the
backspace key was used. The list of matches was then adjusted for what is
in front of the cursor.
You normally start in the first state, with the first match being inserted.
When "longest" is in 'completeopt' and there is more than one match you start
in the third state.
If you select another match, e.g., with CTRL-N or CTRL-P, you go to the first
state. This doesn't change the list of matches.
When you are back at the original text then you are in the third state. To
get there right away you can use a mapping that uses CTRL-P right after
starting the completion: >
:imap <F7> <C-N><C-P>
<
*popupmenu-keys*
In the first state these keys have a special meaning:
<BS> and CTRL-H Delete one character, find the matches for the word before
the cursor. This reduces the list of matches, often to one
entry, and switches to the second state.
Any non-special character:
Stop completion without changing the match and insert the
typed character.
In the second and third state these keys have a special meaning:
<BS> and CTRL-H Delete one character, find the matches for the shorter word
before the cursor. This may find more matches.
CTRL-L Add one character from the current match, may reduce the
number of matches.
any printable, non-white character:
Add this character and reduce the number of matches.
In all three states these can be used:
CTRL-Y Yes: Accept the currently selected match and stop completion.
CTRL-E End completion, go back to what was there before selecting a
match (what was typed or longest common string).
<PageUp> Select a match several entries back, but don't insert it.
<PageDown> Select a match several entries further, but don't insert it.
<Up> Select the previous match, as if CTRL-P was used, but don't
insert it.
<Down> Select the next match, as if CTRL-N was used, but don't
insert it.
<Space> or <Tab> Stop completion without changing the match and insert the
typed character.
The behavior of the <Enter> key depends on the state you are in:
first state: Use the text as it is and insert a line break.
second state: Insert the currently selected match.
third state: Use the text as it is and insert a line break.
In other words: If you used the cursor keys to select another entry in the
list of matches then the <Enter> key inserts that match. If you typed
something else then <Enter> inserts a line break.
The colors of the menu can be changed with these highlight groups:
Pmenu normal item |hl-Pmenu|
PmenuSel selected item |hl-PmenuSel|
PmenuSbar scrollbar |hl-PmenuSbar|
PmenuThumb thumb of the scrollbar |hl-PmenuThumb|
There are no special mappings for when the popup menu is visible. However,
you can use an Insert mode mapping that checks the |pumvisible()| function to
do something different. Example: >
:inoremap <Down> <C-R>=pumvisible() ? "\<lt>C-N>" : "\<lt>Down>"<CR>
You can use of <expr> in mapping to have the popup menu used when typing a
character and some condition is met. For example, for typing a dot: >
inoremap <expr> . MayComplete()
func MayComplete()
if (can complete)
return ".\<C-X>\<C-O>"
endif
return '.'
endfunc
See |:map-<expr>| for more info.
FILETYPE-SPECIFIC REMARKS FOR OMNI COMPLETION *compl-omni-filetypes*
The file used for {filetype} should be autoload/{filetype}complete.vim
in 'runtimepath'. Thus for "java" it is autoload/javacomplete.vim.
C *ft-c-omni*
Completion of C code requires a tags file. You should use Exuberant ctags,
because it adds extra information that is needed for completion. You can find
it here: http://ctags.sourceforge.net/ Version 5.6 or later is recommended.
For version 5.5.4 you should add a patch that adds the "typename:" field:
ftp://ftp.vim.org/pub/vim/unstable/patches/ctags-5.5.4.patch
A compiled .exe for MS-Windows can be found at:
http://ctags.sourceforge.net/
https://github.com/universal-ctags/ctags-win32
If you want to complete system functions you can do something like this. Use
ctags to generate a tags file for all the system header files: >
% ctags -R -f ~/.vim/systags /usr/include /usr/local/include
In your vimrc file add this tags file to the 'tags' option: >
set tags+=~/.vim/systags
When using CTRL-X CTRL-O after a name without any "." or "->" it is completed
from the tags file directly. This works for any identifier, also function
names. If you want to complete a local variable name, which does not appear
in the tags file, use CTRL-P instead.
When using CTRL-X CTRL-O after something that has "." or "->" Vim will attempt
to recognize the type of the variable and figure out what members it has.
This means only members valid for the variable will be listed.
When a member name already was complete, CTRL-X CTRL-O will add a "." or
"->" for composite types.
Vim doesn't include a C compiler, only the most obviously formatted
declarations are recognized. Preprocessor stuff may cause confusion.
When the same structure name appears in multiple places all possible members
are included.
CSS *ft-css-omni*
Complete properties and their appropriate values according to CSS 2.1
specification.
HTML *ft-html-omni*
XHTML *ft-xhtml-omni*
CTRL-X CTRL-O provides completion of various elements of (X)HTML files. It is
designed to support writing of XHTML 1.0 Strict files but will also work for
other versions of HTML. Features:
- after "<" complete tag name depending on context (no div suggestion inside
of an a tag); '/>' indicates empty tags
- inside of tag complete proper attributes (no width attribute for an a tag);
show also type of attribute; '*' indicates required attributes
- when attribute has limited number of possible values help to complete them
- complete names of entities
- complete values of "class" and "id" attributes with data obtained from
<style> tag and included CSS files
- when completing value of "style" attribute or working inside of "style" tag
switch to |ft-css-omni| completion
- when completing values of events attributes or working inside of "script"
tag switch to |ft-javascript-omni| completion
- when used after "</" CTRL-X CTRL-O will close the last opened tag
Note: When used first time completion menu will be shown with little delay
- this is time needed for loading of data file.
Note: Completion may fail in badly formatted documents. In such case try to
run |:make| command to detect formatting problems.
HTML flavor *html-flavor*
The default HTML completion depends on the filetype. For HTML files it is
HTML 4.01 Transitional ('filetype' is "html"), for XHTML it is XHTML 1.0
Strict ('filetype' is "xhtml").
When doing completion outside of any other tag you will have possibility to
choose DOCTYPE and the appropriate data file will be loaded and used for all
next completions.
More about format of data file in |xml-omni-datafile|. Some of the data files
may be found on the Vim website (|www|).
Note that b:html_omni_flavor may point to a file with any XML data. This
makes possible to mix PHP (|ft-php-omni|) completion with any XML dialect
(assuming you have data file for it). Without setting that variable XHTML 1.0
Strict will be used.
JAVASCRIPT *ft-javascript-omni*
Completion of most elements of JavaScript language and DOM elements.
Complete:
- variables
- function name; show function arguments
- function arguments
- properties of variables trying to detect type of variable
- complete DOM objects and properties depending on context
- keywords of language
Completion works in separate JavaScript files (&ft==javascript), inside of
<script> tag of (X)HTML and in values of event attributes (including scanning
of external files).
DOM compatibility
At the moment (beginning of 2006) there are two main browsers - MS Internet
Explorer and Mozilla Firefox. These two applications are covering over 90% of
market. Theoretically standards are created by W3C organisation
(http://www.w3c.org) but they are not always followed/implemented.
IE FF W3C Omni completion ~
+/- +/- + + ~
+ + - + ~
+ - - - ~
- + - - ~
Regardless from state of implementation in browsers but if element is defined
in standards, completion plugin will place element in suggestion list. When
both major engines implemented element, even if this is not in standards it
will be suggested. All other elements are not placed in suggestion list.
PHP *ft-php-omni*
Completion of PHP code requires a tags file for completion of data from
external files and for class aware completion. You should use Exuberant ctags
version 5.5.4 or newer. You can find it here: http://ctags.sourceforge.net/
Script completes:
- after $ variables name
- if variable was declared as object add "->", if tags file is available show
name of class
- after "->" complete only function and variable names specific for given
class. To find class location and contents tags file is required. Because
PHP isn't strongly typed language user can use @var tag to declare class: >
/* @var $myVar myClass */
$myVar->
<
Still, to find myClass contents tags file is required.
- function names with additional info:
- in case of built-in functions list of possible arguments and after | type
data returned by function
- in case of user function arguments and name of file where function was
defined (if it is not current file)
- constants names
- class names after "new" declaration
Note: when doing completion first time Vim will load all necessary data into
memory. It may take several seconds. After next use of completion delay
should not be noticeable.
Script detects if cursor is inside <?php ?> tags. If it is outside it will
automatically switch to HTML/CSS/JavaScript completion. Note: contrary to
original HTML files completion of tags (and only tags) isn't context aware.
RUBY *ft-ruby-omni*
Completion of Ruby code requires that vim be built with |+ruby|.
Ruby completion will parse your buffer on demand in order to provide a list of
completions. These completions will be drawn from modules loaded by 'require'
and modules defined in the current buffer.
The completions provided by CTRL-X CTRL-O are sensitive to the context:
CONTEXT COMPLETIONS PROVIDED ~
1. Not inside a class definition Classes, constants and globals
2. Inside a class definition Methods or constants defined in the class
3. After '.', '::' or ':' Methods applicable to the object being
dereferenced
4. After ':' or ':foo' Symbol name (beginning with 'foo')
Notes:
- Vim will load/evaluate code in order to provide completions. This may
cause some code execution, which may be a concern. This is no longer
enabled by default, to enable this feature add >
let g:rubycomplete_buffer_loading = 1
<- In context 1 above, Vim can parse the entire buffer to add a list of
classes to the completion results. This feature is turned off by default,
to enable it add >
let g:rubycomplete_classes_in_global = 1
< to your vimrc
- In context 2 above, anonymous classes are not supported.
- In context 3 above, Vim will attempt to determine the methods supported by
the object.
- Vim can detect and load the Rails environment for files within a rails
project. The feature is disabled by default, to enable it add >
let g:rubycomplete_rails = 1
< to your vimrc
SYNTAX *ft-syntax-omni*
Vim has the ability to color syntax highlight nearly 500 languages. Part of
this highlighting includes knowing what keywords are part of a language. Many
filetypes already have custom completion scripts written for them, the
syntaxcomplete plugin provides basic completion for all other filetypes. It
does this by populating the omni completion list with the text Vim already
knows how to color highlight. It can be used for any filetype and provides a
minimal language-sensitive completion.
To enable syntax code completion you can run: >
setlocal omnifunc=syntaxcomplete#Complete
You can automate this by placing the following in your |.vimrc| (after any
":filetype" command): >
if has("autocmd") && exists("+omnifunc")
autocmd Filetype *
\ if &omnifunc == "" |
\ setlocal omnifunc=syntaxcomplete#Complete |
\ endif
endif
The above will set completion to this script only if a specific plugin does
not already exist for that filetype.
Each filetype can have a wide range of syntax items. The plugin allows you to
customize which syntax groups to include or exclude from the list. Let's have
a look at the PHP filetype to see how this works.
If you edit a file called, index.php, run the following command: >
syntax list
The first thing you will notice is that there are many different syntax groups.
The PHP language can include elements from different languages like HTML,
JavaScript and many more. The syntax plugin will only include syntax groups
that begin with the filetype, "php", in this case. For example these syntax
groups are included by default with the PHP: phpEnvVar, phpIntVar,
phpFunctions.
If you wish non-filetype syntax items to also be included, you can use a
regular expression syntax (added in version 13.0 of
autoload/syntaxcomplete.vim) to add items. Looking at the output from
":syntax list" while editing a PHP file I can see some of these entries: >
htmlArg,htmlTag,htmlTagName,javaScriptStatement,javaScriptGlobalObjects
To pick up any JavaScript and HTML keyword syntax groups while editing a PHP
file, you can use 3 different regexs, one for each language. Or you can
simply restrict the include groups to a particular value, without using
a regex string: >
let g:omni_syntax_group_include_php = 'php\w\+,javaScript\w\+,html\w\+'
let g:omni_syntax_group_include_php = 'phpFunctions,phpMethods'
<
The basic form of this variable is: >
let g:omni_syntax_group_include_{filetype} = 'regex,comma,separated'
The PHP language has an enormous number of items which it knows how to syntax
highlight. These items will be available within the omni completion list.
Some people may find this list unwieldy or are only interested in certain
items. There are two ways to prune this list (if necessary). If you find
certain syntax groups you do not wish displayed you can use two different
methods to identify these groups. The first specifically lists the syntax
groups by name. The second uses a regular expression to identify both
syntax groups. Simply add one the following to your vimrc: >
let g:omni_syntax_group_exclude_php = 'phpCoreConstant,phpConstant'
let g:omni_syntax_group_exclude_php = 'php\w*Constant'
Add as many syntax groups to this list by comma separating them. The basic
form of this variable is: >
let g:omni_syntax_group_exclude_{filetype} = 'regex,comma,separated'
You can create as many of these variables as you need, varying only the
filetype at the end of the variable name.
The plugin uses the isKeyword option to determine where word boundaries are
for the syntax items. For example, in the Scheme language completion should
include the "-", call-with-output-file. Depending on your filetype, this may
not provide the words you are expecting. Setting the
g:omni_syntax_use_iskeyword option to 0 will force the syntax plugin to break
on word characters. This can be controlled adding the following to your
vimrc: >
let g:omni_syntax_use_iskeyword = 0
For plugin developers, the plugin exposes a public function OmniSyntaxList.
This function can be used to request a List of syntax items. When editing a
SQL file (:e syntax.sql) you can use the ":syntax list" command to see the
various groups and syntax items. For example: >
syntax list
Yields data similar to this:
sqlOperator xxx some prior all like and any escape exists in is not ~
or intersect minus between distinct ~
links to Operator ~
sqlType xxx varbit varchar nvarchar bigint int uniqueidentifier ~
date money long tinyint unsigned xml text smalldate ~
double datetime nchar smallint numeric time bit char ~
varbinary binary smallmoney ~
image float integer timestamp real decimal ~
There are two syntax groups listed here: sqlOperator and sqlType. To retrieve
a List of syntax items you can call OmniSyntaxList a number of different
ways. To retrieve all syntax items regardless of syntax group: >
echo OmniSyntaxList( [] )
To retrieve only the syntax items for the sqlOperator syntax group: >
echo OmniSyntaxList( ['sqlOperator'] )
To retrieve all syntax items for both the sqlOperator and sqlType groups: >
echo OmniSyntaxList( ['sqlOperator', 'sqlType'] )
A regular expression can also be used: >
echo OmniSyntaxList( ['sql\w\+'] )
From within a plugin, you would typically assign the output to a List: >
let myKeywords = []
let myKeywords = OmniSyntaxList( ['sqlKeyword'] )
SQL *ft-sql-omni*
Completion for the SQL language includes statements, functions, keywords.
It will also dynamically complete tables, procedures, views and column lists
with data pulled directly from within a database. For detailed instructions
and a tutorial see |omni-sql-completion|.
The SQL completion plugin can be used in conjunction with other completion
plugins. For example, the PHP filetype has its own completion plugin.
Since PHP is often used to generate dynamic website by accessing a database,
the SQL completion plugin can also be enabled. This allows you to complete
PHP code and SQL code at the same time.
XML *ft-xml-omni*
Vim 7 provides a mechanism for context aware completion of XML files. It
depends on a special |xml-omni-datafile| and two commands: |:XMLns| and
|:XMLent|. Features are:
- after "<" complete the tag name, depending on context
- inside of a tag complete proper attributes
- when an attribute has a limited number of possible values help to complete
them
- complete names of entities (defined in |xml-omni-datafile| and in the
current file with "<!ENTITY" declarations)
- when used after "</" CTRL-X CTRL-O will close the last opened tag
Format of XML data file *xml-omni-datafile*
XML data files are stored in the "autoload/xml" directory in 'runtimepath'.
Vim distribution provides examples of data files in the
"$VIMRUNTIME/autoload/xml" directory. They have a meaningful name which will
be used in commands. It should be a unique name which will not create
conflicts. For example, the name xhtml10s.vim means it is the data file for
XHTML 1.0 Strict.
Each file contains a variable with a name like g:xmldata_xhtml10s . It is
a compound from two parts:
1. "g:xmldata_" general prefix, constant for all data files
2. "xhtml10s" the name of the file and the name of the described XML
dialect; it will be used as an argument for the |:XMLns|
command
Part two must be exactly the same as name of file.
The variable is a |Dictionary|. Keys are tag names and each value is a two
element |List|. The first element of the List is also a List with the names
of possible children. The second element is a |Dictionary| with the names of
attributes as keys and the possible values of attributes as values. Example: >
let g:xmldata_crippled = {
\ "vimxmlentities": ["amp", "lt", "gt", "apos", "quot"],
\ 'vimxmlroot': ['tag1'],
\ 'tag1':
\ [ ['childoftag1a', 'childoftag1b'], {'attroftag1a': [],
\ 'attroftag1b': ['valueofattr1', 'valueofattr2']}],
\ 'childoftag1a':
\ [ [], {'attrofchild': ['attrofchild']}],
\ 'childoftag1b':
\ [ ['childoftag1a'], {'attrofchild': []}],
\ "vimxmltaginfo": {
\ 'tag1': ['Menu info', 'Long information visible in preview window']},
\ 'vimxmlattrinfo': {
\ 'attrofchild': ['Menu info', 'Long information visible in preview window']}}
This example would be put in the "autoload/xml/crippled.vim" file and could
help to write this file: >
<tag1 attroftag1b="valueofattr1">
<childoftag1a attrofchild>
& <
</childoftag1a>
<childoftag1b attrofchild="5">
<childoftag1a>
> ' "
</childoftag1a>
</childoftag1b>
</tag1>
In the example four special elements are visible:
1. "vimxmlentities" - a special key with List containing entities of this XML
dialect.
2. If the list containing possible values of attributes has one element and
this element is equal to the name of the attribute this attribute will be
treated as boolean and inserted as 'attrname' and not as 'attrname="'
3. "vimxmltaginfo" - a special key with a Dictionary containing tag
names as keys and two element List as values, for additional menu info and
the long description.
4. "vimxmlattrinfo" - special key with Dictionary containing attribute names
as keys and two element List as values, for additional menu info and long
description.
Note: Tag names in the data file MUST not contain a namespace description.
Check xsl.vim for an example.
Note: All data and functions are publicly available as global
variables/functions and can be used for personal editing functions.
DTD -> Vim *dtd2vim*
On |www| is the script |dtd2vim| which parses DTD and creates an XML data file
for Vim XML omni completion.
dtd2vim: http://www.vim.org/scripts/script.php?script_id=1462
Check the beginning of that file for usage details.
The script requires perl and:
perlSGML: http://savannah.nongnu.org/projects/perlsgml
Commands
:XMLns {name} [{namespace}] *:XMLns*
Vim has to know which data file should be used and with which namespace. For
loading of the data file and connecting data with the proper namespace use
|:XMLns| command. The first (obligatory) argument is the name of the data
(xhtml10s, xsl). The second argument is the code of namespace (h, xsl). When
used without a second argument the dialect will be used as default - without
namespace declaration. For example to use XML completion in .xsl files: >
:XMLns xhtml10s
:XMLns xsl xsl
:XMLent {name} *:XMLent*
By default entities will be completed from the data file of the default
namespace. The XMLent command should be used in case when there is no default
namespace: >
:XMLent xhtml10s
Usage
While used in this situation (after declarations from previous part, | is
cursor position): >
<|
Will complete to an appropriate XHTML tag, and in this situation: >
<xsl:|
Will complete to an appropriate XSL tag.
The script xmlcomplete.vim, provided through the |autoload| mechanism,
has the xmlcomplete#GetLastOpenTag() function which can be used in XML files
to get the name of the last open tag (b:unaryTagsStack has to be defined): >
:echo xmlcomplete#GetLastOpenTag("b:unaryTagsStack")
==============================================================================
8. Insert mode commands *inserting*
The following commands can be used to insert new text into the buffer. They
can all be undone and repeated with the "." command.
*a*
a Append text after the cursor [count] times. If the
cursor is in the first column of an empty line Insert
starts there. But not when 'virtualedit' is set!
*A*
A Append text at the end of the line [count] times.
For using "A" in Visual block mode see |v_b_A|.
<insert> or *i* *insert* *<Insert>*
i Insert text before the cursor [count] times.
When using CTRL-O in Insert mode |i_CTRL-O| the count
is not supported.
*I*
I Insert text before the first non-blank in the line
[count] times.
When the 'H' flag is present in 'cpoptions' and the
line only contains blanks, insert start just before
the last blank.
For using "I" in Visual block mode see |v_b_I|.
*gI*
gI Insert text in column 1 [count] times.
*gi*
gi Insert text in the same position as where Insert mode
was stopped last time in the current buffer.
This uses the |'^| mark. It's different from "`^i"
when the mark is past the end of the line.
The position is corrected for inserted/deleted lines,
but NOT for inserted/deleted characters.
When the |:keepjumps| command modifier is used the |'^|
mark won't be changed.
*o*
o Begin a new line below the cursor and insert text,
repeat [count] times.
When the '#' flag is in 'cpoptions' the count is
ignored.
*O*
O Begin a new line above the cursor and insert text,
repeat [count] times.
When the '#' flag is in 'cpoptions' the count is
ignored.
These commands are used to start inserting text. You can end insert mode with
<Esc>. See |mode-ins-repl| for the other special characters in Insert mode.
The effect of [count] takes place after Insert mode is exited.
When 'autoindent' is on, the indent for a new line is obtained from the
previous line. When 'smartindent' or 'cindent' is on, the indent for a line
is automatically adjusted for C programs.
'textwidth' can be set to the maximum width for a line. When a line becomes
too long when appending characters a line break is automatically inserted.
==============================================================================
9. Ex insert commands *inserting-ex*
*:a* *:append*
:{range}a[ppend][!] Insert several lines of text below the specified
line. If the {range} is missing, the text will be
inserted after the current line.
Adding [!] toggles 'autoindent' for the time this
command is executed.
*:i* *:in* *:insert*
:{range}i[nsert][!] Insert several lines of text above the specified
line. If the {range} is missing, the text will be
inserted before the current line.
Adding [!] toggles 'autoindent' for the time this
command is executed.
These two commands will keep on asking for lines, until you type a line
containing only a ".". Watch out for lines starting with a backslash, see
|line-continuation|.
When in Ex mode (see |-e|) a backslash at the end of the line can be used to
insert a NUL character. To be able to have a line ending in a backslash use
two backslashes. This means that the number of backslashes is halved, but
only at the end of the line.
NOTE: These commands cannot be used with |:global| or |:vglobal|.
":append" and ":insert" don't work properly in between ":if" and
":endif", ":for" and ":endfor", ":while" and ":endwhile".
*:start* *:startinsert*
:star[tinsert][!] Start Insert mode just after executing this command.
Works like typing "i" in Normal mode. When the ! is
included it works like "A", append to the line.
Otherwise insertion starts at the cursor position.
Note that when using this command in a function or
script, the insertion only starts after the function
or script is finished.
This command does not work from |:normal|.
*:stopi* *:stopinsert*
:stopi[nsert] Stop Insert mode as soon as possible. Works like
typing <Esc> in Insert mode.
Can be used in an autocommand, example: >
:au BufEnter scratch stopinsert
<
*replacing-ex* *:startreplace*
:startr[eplace][!] Start Replace mode just after executing this command.
Works just like typing "R" in Normal mode. When the
! is included it acts just like "$R" had been typed
(ie. begin replace mode at the end-of-line). Other-
wise replacement begins at the cursor position.
Note that when using this command in a function or
script that the replacement will only start after
the function or script is finished.
*:startgreplace*
:startg[replace][!] Just like |:startreplace|, but use Virtual Replace
mode, like with |gR|.
==============================================================================
10. Inserting a file *inserting-file*
*:r* *:re* *:read*
:r[ead] [++opt] [name]
Insert the file [name] (default: current file) below
the cursor.
See |++opt| for the possible values of [++opt].
:{range}r[ead] [++opt] [name]
Insert the file [name] (default: current file) below
the specified line.
See |++opt| for the possible values of [++opt].
*:r!* *:read!*
:[range]r[ead] [++opt] !{cmd}
Execute {cmd} and insert its standard output below
the cursor or the specified line. A temporary file is
used to store the output of the command which is then
read into the buffer. 'shellredir' is used to save
the output of the command, which can be set to include
stderr or not. {cmd} is executed like with ":!{cmd}",
any '!' is replaced with the previous command |:!|.
See |++opt| for the possible values of [++opt].
These commands insert the contents of a file, or the output of a command,
into the buffer. They can be undone. They cannot be repeated with the "."
command. They work on a line basis, insertion starts below the line in which
the cursor is, or below the specified line. To insert text above the first
line use the command ":0r {name}".
After the ":read" command, the cursor is left on the first non-blank in the
first new line. Unless in Ex mode, then the cursor is left on the last new
line (sorry, this is Vi compatible).
If a file name is given with ":r", it becomes the alternate file. This can be
used, for example, when you want to edit that file instead: ":e! #". This can
be switched off by removing the 'a' flag from the 'cpoptions' option.
Of the [++opt] arguments one is specifically for ":read", the ++edit argument.
This is useful when the ":read" command is actually used to read a file into
the buffer as if editing that file. Use this command in an empty buffer: >
:read ++edit filename
The effect is that the 'fileformat', 'fileencoding', 'bomb', etc. options are
set to what has been detected for "filename". Note that a single empty line
remains, you may want to delete it.
*file-read*
The 'fileformat' option sets the <EOL> style for a file:
'fileformat' characters name ~
"dos" <CR><NL> or <NL> DOS format
"unix" <NL> Unix format
"mac" <CR> Mac format
Previously 'textmode' was used. It is obsolete now.
If 'fileformat' is "dos", a <CR> in front of an <NL> is ignored and a CTRL-Z
at the end of the file is ignored.
If 'fileformat' is "mac", a <NL> in the file is internally represented by a
<CR>. This is to avoid confusion with a <NL> which is used to represent a
<NUL>. See |CR-used-for-NL|.
If the 'fileformats' option is not empty Vim tries to recognize the type of
<EOL> (see |file-formats|). However, the 'fileformat' option will not be
changed, the detected format is only used while reading the file.
A similar thing happens with 'fileencodings'.
On non-Win32 systems the message "[dos format]" is shown if a file is read in
DOS format, to remind you that something unusual is done.
On Macintosh and Win32 the message "[unix format]" is shown if a file is read
in Unix format.
On non-Macintosh systems, the message "[mac format]" is shown if a file is
read in Mac format.
An example on how to use ":r !": >
:r !uuencode binfile binfile
This command reads "binfile", uuencodes it and reads it into the current
buffer. Useful when you are editing e-mail and want to include a binary
file.
*read-messages*
When reading a file Vim will display a message with information about the read
file. In the table is an explanation for some of the items. The others are
self explanatory. Using the long or the short version depends on the
'shortmess' option.
long short meaning ~
[readonly] {RO} the file is write protected
[fifo/socket] using a stream
[fifo] using a fifo stream
[socket] using a socket stream
[CR missing] reading with "dos" 'fileformat' and a
NL without a preceding CR was found.
[NL found] reading with "mac" 'fileformat' and a
NL was found (could be "unix" format)
[long lines split] at least one line was split in two
[NOT converted] conversion from 'fileencoding' to
'encoding' was desired but not
possible
[converted] conversion from 'fileencoding' to
'encoding' done
[crypted] file was decrypted
[READ ERRORS] not all of the file could be read
vim:tw=78:ts=8:noet:ft=help:norl:
|