vim: runtime/doc/map.txt annotate

annotate runtime/doc/map.txt @ 34219:a0a4a774117b v9.1.0058

patch 9.1.0058: Cannot map Super Keys in GTK UI Commit: https://github.com/vim/vim/commit/92e90a1e102825aa9149262cacfc991264db05df Author: Casey Tucker <dctucker@hotmail.com> Date: Thu Jan 25 22:44:00 2024 +0100 patch 9.1.0058: Cannot map Super Keys in GTK UI Problem: Cannot map Super Keys in GTK UI (Casey Tucker) Solution: Enable Super Key mappings in GTK using <D-Key> (Casey Tucker) As a developer who works in both Mac and Linux using the same keyboard, it can be frustrating having to remember different key combinations or having to rely on system utilities to remap keys. This change allows `<D-z>` `<D-x>` `<D-c>` `<D-v>` etc. to be recognized by the `map` commands, along with the `<D-S-...>` shifted variants. ```vimrc if has('gui_gtk') nnoremap <D-z> u nnoremap <D-S-Z> <C-r> vnoremap <D-x> "+d vnoremap <D-c> "+y cnoremap <D-v> <C-R>+ inoremap <D-v> <C-o>"+gP nnoremap <D-v> "+P vnoremap <D-v> "-d"+P nnoremap <D-s> :w<CR> inoremap <D-s> <C-o>:w<CR> nnoremap <D-w> :q<CR> nnoremap <D-q> :qa<CR> nnoremap <D-t> :tabe<CR> nnoremap <D-S-T> :vs#<CR><C-w>T nnoremap <D-a> ggVG vnoremap <D-a> <ESC>ggVG inoremap <D-a> <ESC>ggVG nnoremap <D-f> / nnoremap <D-g> n nnoremap <D-S-G> N vnoremap <D-x> "+x endif ``` closes: #12698 Signed-off-by: Casey Tucker <dctucker@hotmail.com> Signed-off-by: Christian Brabandt <cb@256bit.org>

author	Christian Brabandt <cb@256bit.org>
date	Thu, 25 Jan 2024 23:00:03 +0100
parents	a197265a2e07
children	a0754587f167

rev	line source
34219 a0a4a774117b patch 9.1.0058: Cannot map Super Keys in GTK UI Christian Brabandt <cb@256bit.org> parents: 34082 diff changeset	1 map.txt For Vim version 9.1. Last change: 2024 Jan 25
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4 VIM REFERENCE MANUAL by Bram Moolenaar
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	5
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	6
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	7 Key mapping, abbreviations and user-defined commands.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	8
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	9 This subject is introduced in sections \|05.4\|, \|24.7\| and \|40.1\| of the user
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	10 manual.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	11
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	12 1. Key mapping \|key-mapping\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	13 1.1 MAP COMMANDS \|:map-commands\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	14 1.2 Special arguments \|:map-arguments\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	15 1.3 Mapping and modes \|:map-modes\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	16 1.4 Listing mappings \|map-listing\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	17 1.5 Mapping special keys \|:map-special-keys\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	18 1.6 Special characters \|:map-special-chars\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	19 1.7 What keys to map \|map-which-keys\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	20 1.8 Examples \|map-examples\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	21 1.9 Using mappings \|map-typing\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	22 1.10 Mapping alt-keys \|:map-alt-keys\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	23 1.11 Mapping meta-keys \|:map-meta-keys\|
34219 a0a4a774117b patch 9.1.0058: Cannot map Super Keys in GTK UI Christian Brabandt <cb@256bit.org> parents: 34082 diff changeset	24 1.12 Mapping super-keys or command keys \|:map-super-keys\|
a0a4a774117b patch 9.1.0058: Cannot map Super Keys in GTK UI Christian Brabandt <cb@256bit.org> parents: 34082 diff changeset	25 1.13 Mapping in modifyOtherKeys mode \|modifyOtherKeys\|
a0a4a774117b patch 9.1.0058: Cannot map Super Keys in GTK UI Christian Brabandt <cb@256bit.org> parents: 34082 diff changeset	26 1.14 Mapping with Kitty keyboard protocol \|kitty-keyboard-protocol\|
a0a4a774117b patch 9.1.0058: Cannot map Super Keys in GTK UI Christian Brabandt <cb@256bit.org> parents: 34082 diff changeset	27 1.15 Mapping an operator \|:map-operator\|
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	28 2. Abbreviations \|abbreviations\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	29 3. Local mappings and functions \|script-local\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	30 4. User-defined commands \|user-commands\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	31
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	32 ==============================================================================
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	33 1. Key mapping key-mapping mapping macro
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	34
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	35 Key mapping is used to change the meaning of typed keys. The most common use
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	36 is to define a sequence of commands for a function key. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	37
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	38 :map <F2> a<C-R>=strftime("%c")<CR><Esc>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	39
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	40 This appends the current date and time after the cursor (in <> notation \|<>\|).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	41
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	42
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	43 1.1 MAP COMMANDS :map-commands
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	44
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	45 There are commands to enter new mappings, remove mappings and list mappings.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	46 See \|map-overview\| for the various forms of "map" and their relationships with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	47 modes.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	48
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	49 {lhs} means left-hand-side {lhs}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	50 {rhs} means right-hand-side {rhs}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	51
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	52 :map {lhs} {rhs} \|mapmode-nvo\| :map
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	53 :nm[ap] {lhs} {rhs} \|mapmode-n\| :nm :nmap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	54 :vm[ap] {lhs} {rhs} \|mapmode-v\| :vm :vmap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	55 :xm[ap] {lhs} {rhs} \|mapmode-x\| :xm :xmap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	56 :smap {lhs} {rhs} \|mapmode-s\| :smap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	57 :om[ap] {lhs} {rhs} \|mapmode-o\| :om :omap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	58 :map! {lhs} {rhs} \|mapmode-ic\| :map!
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	59 :im[ap] {lhs} {rhs} \|mapmode-i\| :im :imap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	60 :lm[ap] {lhs} {rhs} \|mapmode-l\| :lm :lma :lmap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	61 :cm[ap] {lhs} {rhs} \|mapmode-c\| :cm :cmap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	62 :tma[p] {lhs} {rhs} \|mapmode-t\| :tma :tmap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	63 Map the key sequence {lhs} to {rhs} for the modes
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	64 where the map command applies. The result, including
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	65 {rhs}, is then further scanned for mappings. This
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	66 allows for nested and recursive use of mappings.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	67 Note: Trailing spaces are included in the {rhs},
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	68 because space is a valid Normal mode command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	69 See \|map-trailing-white\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	70
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	71 :nore :norem
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	72 :no[remap] {lhs} {rhs} \|mapmode-nvo\| :no :noremap :nor
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	73 :nn[oremap] {lhs} {rhs} \|mapmode-n\| :nn :nnoremap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	74 :vn[oremap] {lhs} {rhs} \|mapmode-v\| :vn :vnoremap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	75 :xn[oremap] {lhs} {rhs} \|mapmode-x\| :xn :xnoremap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	76 :snor[emap] {lhs} {rhs} \|mapmode-s\| :snor :snore :snoremap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	77 :ono[remap] {lhs} {rhs} \|mapmode-o\| :ono :onoremap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	78 :no[remap]! {lhs} {rhs} \|mapmode-ic\| :no! :noremap!
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	79 :ino[remap] {lhs} {rhs} \|mapmode-i\| :ino :inor :inoremap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	80 :ln[oremap] {lhs} {rhs} \|mapmode-l\| :ln :lnoremap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	81 :cno[remap] {lhs} {rhs} \|mapmode-c\| :cno :cnor :cnoremap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	82 :tno[remap] {lhs} {rhs} \|mapmode-t\| :tno :tnoremap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	83 Map the key sequence {lhs} to {rhs} for the modes
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	84 where the map command applies. Disallow mapping of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	85 {rhs}, to avoid nested and recursive mappings. Often
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	86 used to redefine a command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	87 Note: When <Plug> appears in the {rhs} this part is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	88 always applied even if remapping is disallowed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	89
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	90
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	91 :unm[ap] {lhs} \|mapmode-nvo\| :unm :unmap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	92 :nun[map] {lhs} \|mapmode-n\| :nun :nunmap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	93 :vu[nmap] {lhs} \|mapmode-v\| :vu :vunmap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	94 :xu[nmap] {lhs} \|mapmode-x\| :xu :xunmap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	95 :sunm[ap] {lhs} \|mapmode-s\| :sunm :sunmap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	96 :ou[nmap] {lhs} \|mapmode-o\| :ou :ounmap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	97 :unm[ap]! {lhs} \|mapmode-ic\| :unm! :unmap!
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	98 :iu[nmap] {lhs} \|mapmode-i\| :iu :iunmap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	99 :lu[nmap] {lhs} \|mapmode-l\| :lu :lunmap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	100 :cu[nmap] {lhs} \|mapmode-c\| :cu :cun :cunmap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	101 :tunma[p] {lhs} \|mapmode-t\| :tunma :tunmap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	102 Remove the mapping of {lhs} for the modes where the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	103 map command applies. The mapping may remain defined
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	104 for other modes where it applies.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	105 It also works when {lhs} matches the {rhs} of a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	106 mapping. This is for when an abbreviation applied.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	107 Note: Trailing spaces are included in the {lhs}.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	108 See \|map-trailing-white\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	109
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	110 :mapc[lear] \|mapmode-nvo\| :mapc :mapclear
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	111 :nmapc[lear] \|mapmode-n\| :nmapc :nmapclear
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	112 :vmapc[lear] \|mapmode-v\| :vmapc :vmapclear
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	113 :xmapc[lear] \|mapmode-x\| :xmapc :xmapclear
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	114 :smapc[lear] \|mapmode-s\| :smapc :smapclear
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	115 :omapc[lear] \|mapmode-o\| :omapc :omapclear
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	116 :mapc[lear]! \|mapmode-ic\| :mapc! :mapclear!
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	117 :imapc[lear] \|mapmode-i\| :imapc :imapclear
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	118 :lmapc[lear] \|mapmode-l\| :lmapc :lmapclear
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	119 :cmapc[lear] \|mapmode-c\| :cmapc :cmapclear
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	120 :tmapc[lear] \|mapmode-t\| :tmapc :tmapclear
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	121 Remove ALL mappings for the modes where the map
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	122 command applies.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	123 Use the <buffer> argument to remove buffer-local
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	124 mappings \|:map-<buffer>\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	125 Warning: This also removes the \|mac-standard-mappings\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	126 and the \|dos-standard-mappings\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	127
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	128 :map \|mapmode-nvo\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	129 :nm[ap] \|mapmode-n\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	130 :vm[ap] \|mapmode-v\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	131 :xm[ap] \|mapmode-x\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	132 :sm[ap] \|mapmode-s\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	133 :om[ap] \|mapmode-o\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	134 :map! \|mapmode-ic\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	135 :im[ap] \|mapmode-i\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	136 :lm[ap] \|mapmode-l\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	137 :cm[ap] \|mapmode-c\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	138 :tma[p] \|mapmode-t\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	139 List all key mappings for the modes where the map
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	140 command applies. Note that ":map" and ":map!" are
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	141 used most often, because they include the other modes.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	142
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	143 :map {lhs} \|mapmode-nvo\| :map_l
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	144 :nm[ap] {lhs} \|mapmode-n\| :nmap_l
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	145 :vm[ap] {lhs} \|mapmode-v\| :vmap_l
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	146 :xm[ap] {lhs} \|mapmode-x\| :xmap_l
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	147 :sm[ap] {lhs} \|mapmode-s\| :smap_l
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	148 :om[ap] {lhs} \|mapmode-o\| :omap_l
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	149 :map! {lhs} \|mapmode-ic\| :map_l!
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	150 :im[ap] {lhs} \|mapmode-i\| :imap_l
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	151 :lm[ap] {lhs} \|mapmode-l\| :lmap_l
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	152 :cm[ap] {lhs} \|mapmode-c\| :cmap_l
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	153 :tma[p] {lhs} \|mapmode-t\| :tmap_l
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	154 List the key mappings for the key sequences starting
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	155 with {lhs} in the modes where the map command applies.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	156
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	157 These commands are used to map a key or key sequence to a string of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	158 characters. You can use this to put command sequences under function keys,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	159 translate one key into another, etc. See \|:mkexrc\| for how to save and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	160 restore the current mappings.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	161
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	162 map-ambiguous
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	163 When two mappings start with the same sequence of characters, they are
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	164 ambiguous. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	165 :imap aa foo
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	166 :imap aaa bar
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	167 When Vim has read "aa", it will need to get another character to be able to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	168 decide if "aa" or "aaa" should be mapped. This means that after typing "aa"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	169 that mapping won't get expanded yet, Vim is waiting for another character.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	170 If you type a space, then "foo" will get inserted, plus the space. If you
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	171 type "a", then "bar" will get inserted.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	172
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	173 Trailing white space ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	174 map-trailing-white
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	175 This unmap command does NOT work: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	176 :map @@ foo
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	177 :unmap @@ \| print
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	178
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	179 Because it tries to unmap "@@ ", including the white space before the command
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	180 separator "\|". Other examples with trailing white space: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	181 unmap @@
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	182 unmap @@ # Vim9 script comment
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	183 unmap @@ " legacy script comment
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	184
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	185 An error will be issued, which is very hard to identify, because the ending
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	186 whitespace character in `unmap @@ ` is not visible.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	187
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	188 A generic solution is to put the command separator "\|" right after the mapped
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	189 keys. After that white space and a comment may follow: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	190
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	191 unmap @@\| # Vim9 script comment
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	192 unmap @@\| " legacy script comment
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	193
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	194
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	195 1.2 SPECIAL ARGUMENTS :map-arguments
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	196
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	197 "<buffer>", "<nowait>", "<silent>", "<special>", "<script>", "<expr>" and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	198 "<unique>" can be used in any order. They must appear right after the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	199 command, before any other arguments.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	200
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	201 :map-local :map-<buffer> :map-buffer
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	202 E224 E225
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	203 If the first argument to one of these commands is "<buffer>" the mapping will
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	204 be effective in the current buffer only. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	205 :map <buffer> ,w /[.,;]<CR>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	206 Then you can map ",w" to something else in another buffer: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	207 :map <buffer> ,w /[#&!]<CR>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	208 The local buffer mappings are used before the global ones. See <nowait> below
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	209 to make a short local mapping not taking effect when a longer global one
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	210 exists.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	211 The "<buffer>" argument can also be used to clear mappings: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	212 :unmap <buffer> ,w
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	213 :mapclear <buffer>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	214 Local mappings are also cleared when a buffer is deleted, but not when it is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	215 unloaded. Just like local option values.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	216 Also see \|map-precedence\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	217
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	218 :map-<nowait> :map-nowait
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	219 When defining a buffer-local mapping for "," there may be a global mapping
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	220 that starts with ",". Then you need to type another character for Vim to know
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	221 whether to use the "," mapping or the longer one. To avoid this add the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	222 <nowait> argument. Then the mapping will be used when it matches, Vim does
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	223 not wait for more characters to be typed. However, if the characters were
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	224 already typed they are used.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	225 Note that this works when the <nowait> mapping fully matches and is found
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	226 before any partial matches. This works when:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	227 - There is only one matching buffer-local mapping, since these are always
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	228 found before global mappings.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	229 - There is another buffer-local mapping that partly matches, but it is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	230 defined earlier (last defined mapping is found first).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	231
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	232 :map-<silent> :map-silent
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	233 To define a mapping which will not be echoed on the command line, add
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	234 "<silent>" as the first argument. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	235 :map <silent> ,h /Header<CR>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	236 The search string will not be echoed when using this mapping. Messages from
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	237 the executed command are still given though. To shut them up too, add a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	238 ":silent" in the executed command: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	239 :map <silent> ,h :exe ":silent normal /Header\r"<CR>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	240 Note that the effect of a command might also be silenced, e.g., when the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	241 mapping selects another entry for command line completion it won't be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	242 displayed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	243 Prompts will still be given, e.g., for inputdialog().
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	244 Using "<silent>" for an abbreviation is possible, but will cause redrawing of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	245 the command line to fail.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	246
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	247 :map-<special> :map-special
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	248 Define a mapping with <> notation for special keys, even though the "<" flag
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	249 may appear in 'cpoptions'. This is useful if the side effect of setting
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	250 'cpoptions' is not desired. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	251 :map <special> <F12> /Header<CR>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	252 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	253 :map-<script> :map-script
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	254 If the first argument to one of these commands is "<script>" and it is used to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	255 define a new mapping or abbreviation, the mapping will only remap characters
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	256 in the {rhs} using mappings that were defined local to a script, starting with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	257 "<SID>". This can be used to avoid that mappings from outside a script
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	258 interfere (e.g., when CTRL-V is remapped in mswin.vim), but do use other
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	259 mappings defined in the script.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	260 Note: ":map <script>" and ":noremap <script>" do the same thing. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	261 "<script>" overrules the command name. Using ":noremap <script>" is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	262 preferred, because it's clearer that remapping is (mostly) disabled.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	263
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	264 :map-<unique> :map-unique E226 E227
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	265 If the first argument to one of these commands is "<unique>" and it is used to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	266 define a new mapping or abbreviation, the command will fail if the mapping or
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	267 abbreviation already exists. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	268 :map <unique> ,w /[#&!]<CR>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	269 When defining a local mapping, there will also be a check if a global map
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	270 already exists which is equal.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	271 Example of what will fail: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	272 :map ,w /[#&!]<CR>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	273 :map <buffer> <unique> ,w /[.,;]<CR>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	274 If you want to map a key and then have it do what it was originally mapped to,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	275 have a look at \|maparg()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	276
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	277 :map-<expr> :map-expression
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	278 If the first argument to one of these commands is "<expr>" and it is used to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	279 define a new mapping or abbreviation, the argument is an expression. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	280 expression is evaluated to obtain the {rhs} that is used. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	281 :inoremap <expr> . <SID>InsertDot()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	282 The result of the s:InsertDot() function will be inserted. It could check the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	283 text before the cursor and start omni completion when some condition is met.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	284 Using a script-local function is preferred, to avoid polluting the global
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	285 namespace. Use <SID> in the RHS so that the script that the mapping was
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	286 defined in can be found.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	287
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	288 For abbreviations \|v:char\| is set to the character that was typed to trigger
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	289 the abbreviation. You can use this to decide how to expand the {lhs}. You
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	290 should not either insert or change the v:char.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	291
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	292 In case you want the mapping to not do anything, you can have the expression
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	293 evaluate to an empty string. If something changed that requires Vim to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	294 go through the main loop (e.g. to update the display), return "\<Ignore>".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	295 This is similar to "nothing" but makes Vim return from the loop that waits for
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	296 input. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	297 func s:OpenPopup()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	298 call popup_create(... arguments ...)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	299 return "\<Ignore>"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	300 endfunc
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	301 nnoremap <expr> <F3> <SID>OpenPopup()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	302
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	303 Keep in mind that the expression may be evaluated when looking for
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	304 typeahead, before the previous command has been executed. For example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	305 func StoreColumn()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	306 let g:column = col('.')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	307 return 'x'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	308 endfunc
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	309 nnoremap <expr> x StoreColumn()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	310 nmap ! f!x
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	311 You will notice that g:column has the value from before executing "f!",
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	312 because "x" is evaluated before "f!" is executed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	313 This can be solved by inserting <Ignore> before the character that is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	314 expression-mapped: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	315 nmap ! f!<Ignore>x
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	316
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	317 When defining a mapping in a \|Vim9\| script, the expression will be evaluated
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	318 in the context of that script. This means that script-local items can be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	319 accessed in the expression.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	320
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	321 Be very careful about side effects! The expression is evaluated while
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	322 obtaining characters, you may very well make the command dysfunctional.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	323 For this reason the following is blocked:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	324 - Changing the buffer text \|textlock\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	325 - Editing another buffer.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	326 - The \|:normal\| command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	327 - Moving the cursor is allowed, but it is restored afterwards.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	328 If you want the mapping to do any of these let the returned characters do
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	329 that, or use a \|<Cmd>\| mapping instead.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	330
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	331 You can use getchar(), it consumes typeahead if there is any. E.g., if you
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	332 have these mappings: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	333 inoremap <expr> <C-L> nr2char(getchar())
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	334 inoremap <expr> <C-L>x "foo"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	335 If you now type CTRL-L nothing happens yet, Vim needs the next character to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	336 decide what mapping to use. If you type 'x' the second mapping is used and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	337 "foo" is inserted. If you type any other key the first mapping is used,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	338 getchar() gets the typed key and returns it.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	339
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	340 Here is an example that inserts a list number that increases: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	341 let counter = 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	342 inoremap <expr> <C-L> ListItem()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	343 inoremap <expr> <C-R> ListReset()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	344
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	345 func ListItem()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	346 let g:counter += 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	347 return g:counter .. '. '
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	348 endfunc
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	349
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	350 func ListReset()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	351 let g:counter = 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	352 return ''
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	353 endfunc
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	354
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	355 CTRL-L inserts the next number, CTRL-R resets the count. CTRL-R returns an
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	356 empty string, so that nothing is inserted.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	357
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	358 Note that using 0x80 as a single byte before other text does not work, it will
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	359 be seen as a special key.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	360
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	361 <Cmd> :map-cmd
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	362 The special text <Cmd> begins a "command mapping", it executes the command
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	363 directly without changing modes. Where you might use ":...<CR>" in the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	364 {rhs} of a mapping, you can instead use "<Cmd>...<CR>".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	365 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	366 noremap x <Cmd>echo mode(1)<CR>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	367 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	368 This is more flexible than `:<C-U>` in Visual and Operator-pending mode, or
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	369 `<C-O>:` in Insert mode, because the commands are executed directly in the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	370 current mode, instead of always going to Normal mode. Visual mode is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	371 preserved, so tricks with \|gv\| are not needed. Commands can be invoked
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	372 directly in Command-line mode (which would otherwise require timer hacks).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	373 Example of using <Cmd> halfway Insert mode: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	374 nnoremap <F3> aText <Cmd>echo mode(1)<CR> Added<Esc>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	375
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	376 Unlike <expr> mappings, there are no special restrictions on the <Cmd>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	377 command: it is executed as if an (unrestricted) \|autocommand\| was invoked.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	378
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	379 <ScriptCmd>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	380 <ScriptCmd> is like <Cmd> but sets the context to the script the mapping was
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	381 defined in, for the duration of the command execution. This is especially
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	382 useful for \|Vim9\| script. It also works to access an import, which is useful
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	383 in a plugin using a, possibly autoloaded, script: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	384 vim9script
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	385 import autoload 'implementation.vim' as impl
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	386 nnoremap <F4> <ScriptCmd>impl.DoTheWork()<CR>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	387 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	388 No matter where <F4> is typed, the "impl" import will be found in the script
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	389 context of where the mapping was defined. When it's an autoload import, as in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	390 the example, the "implementation.vim" script will only be loaded once <F4> is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	391 typed, not when the mapping is defined.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	392
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	393 Without <ScriptCmd> using "s:impl" would result in "E121: Undefined variable".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	394
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	395 Note:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	396 - Because <Cmd> and <ScriptCmd> avoid mode-changes it does not trigger
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	397 \|CmdlineEnter\| and \|CmdlineLeave\| events, because no user interaction is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	398 expected.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	399 - For the same reason, \|keycodes\| like <C-R><C-W> are interpreted as plain,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	400 unmapped keys.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	401 - The command is not echo'ed, no need for <silent>.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	402 - The {rhs} is not subject to abbreviations nor to other mappings, even if the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	403 mapping is recursive.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	404 - In Visual mode you can use `line('v')` and `col('v')` to get one end of the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	405 Visual area, the cursor is at the other end.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	406
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	407 E1255 E1136
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	408 <Cmd> and <ScriptCmd> commands must terminate, that is, they must be followed
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	409 by <CR> in the {rhs} of the mapping definition. \|Command-line\| mode is never
34011 62d771d915fe runtime(doc): list of new/changed features in version9.txt Christian Brabandt <cb@256bit.org> parents: 32670 diff changeset	410 entered. To use a literal <CR> in the {rhs}, use \|<lt>\|.
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	411
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	412
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	413 1.3 MAPPING AND MODES :map-modes
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	414 mapmode-nvo mapmode-n mapmode-v mapmode-o
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	415
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	416 There are seven sets of mappings
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	417 - For Normal mode: When typing commands.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	418 - For Visual mode: When typing commands while the Visual area is highlighted.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	419 - For Select mode: like Visual mode but typing text replaces the selection.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	420 - For Operator-pending mode: When an operator is pending (after "d", "y", "c",
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	421 etc.). See below: \|omap-info\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	422 - For Insert mode. These are also used in Replace mode.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	423 - For Command-line mode: When entering a ":" or "/" command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	424 - For Terminal mode: When typing in a \|:terminal\| buffer.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	425
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	426 Special case: While typing a count for a command in Normal mode, mapping zero
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	427 is disabled. This makes it possible to map zero without making it impossible
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	428 to type a count with a zero.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	429
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	430 map-overview map-modes
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	431 Overview of which map command works in which mode. More details below.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	432 COMMANDS MODES ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	433 :map :noremap :unmap Normal, Visual, Select, Operator-pending
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	434 :nmap :nnoremap :nunmap Normal
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	435 :vmap :vnoremap :vunmap Visual and Select
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	436 :smap :snoremap :sunmap Select
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	437 :xmap :xnoremap :xunmap Visual
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	438 :omap :onoremap :ounmap Operator-pending
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	439 :map! :noremap! :unmap! Insert and Command-line
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	440 :imap :inoremap :iunmap Insert
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	441 :lmap :lnoremap :lunmap Insert, Command-line, Lang-Arg
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	442 :cmap :cnoremap :cunmap Command-line
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	443 :tmap :tnoremap :tunmap Terminal-Job
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	444
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	445 Same information in a table:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	446 map-table
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	447 Mode \| Norm \| Ins \| Cmd \| Vis \| Sel \| Opr \| Term \| Lang \| ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	448 Command +------+-----+-----+-----+-----+-----+------+------+ ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	449 [nore]map \| yes \| - \| - \| yes \| yes \| yes \| - \| - \|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	450 n[nore]map \| yes \| - \| - \| - \| - \| - \| - \| - \|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	451 [nore]map! \| - \| yes \| yes \| - \| - \| - \| - \| - \|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	452 i[nore]map \| - \| yes \| - \| - \| - \| - \| - \| - \|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	453 c[nore]map \| - \| - \| yes \| - \| - \| - \| - \| - \|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	454 v[nore]map \| - \| - \| - \| yes \| yes \| - \| - \| - \|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	455 x[nore]map \| - \| - \| - \| yes \| - \| - \| - \| - \|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	456 s[nore]map \| - \| - \| - \| - \| yes \| - \| - \| - \|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	457 o[nore]map \| - \| - \| - \| - \| - \| yes \| - \| - \|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	458 t[nore]map \| - \| - \| - \| - \| - \| - \| yes \| - \|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	459 l[nore]map \| - \| yes \| yes \| - \| - \| - \| - \| yes \|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	460
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	461
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	462 COMMANDS MODES ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	463 Normal Visual+Select Operator-pending ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	464 :map :noremap :unmap :mapclear yes yes yes
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	465 :nmap :nnoremap :nunmap :nmapclear yes - -
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	466 :vmap :vnoremap :vunmap :vmapclear - yes -
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	467 :omap :onoremap :ounmap :omapclear - - yes
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	468
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	469 :nunmap can also be used outside of a monastery.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	470 mapmode-x mapmode-s
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	471 Some commands work both in Visual and Select mode, some in only one. Note
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	472 that quite often "Visual" is mentioned where both Visual and Select mode
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	473 apply. \|Select-mode-mapping\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	474 NOTE: Mapping a printable character in Select mode may confuse the user. It's
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	475 better to explicitly use :xmap and :smap for printable characters. Or use
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	476 :sunmap after defining the mapping.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	477
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	478 COMMANDS MODES ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	479 Visual Select ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	480 :vmap :vnoremap :vunmap :vmapclear yes yes
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	481 :xmap :xnoremap :xunmap :xmapclear yes -
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	482 :smap :snoremap :sunmap :smapclear - yes
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	483
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	484 mapmode-ic mapmode-i mapmode-c mapmode-l
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	485 Some commands work both in Insert mode and Command-line mode, some not:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	486
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	487 COMMANDS MODES ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	488 Insert Command-line Lang-Arg ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	489 :map! :noremap! :unmap! :mapclear! yes yes -
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	490 :imap :inoremap :iunmap :imapclear yes - -
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	491 :cmap :cnoremap :cunmap :cmapclear - yes -
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	492 :lmap :lnoremap :lunmap :lmapclear yes* yes* yes*
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	493
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	494 * If 'iminsert' is 1, see \|language-mapping\| below.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	495
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	496 The original Vi did not have separate mappings for
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	497 Normal/Visual/Operator-pending mode and for Insert/Command-line mode.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	498 Therefore the ":map" and ":map!" commands enter and display mappings for
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	499 several modes. In Vim you can use the ":nmap", ":vmap", ":omap", ":cmap" and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	500 ":imap" commands to enter mappings for each mode separately.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	501
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	502 mapmode-t
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	503 The terminal mappings are used in a terminal window, when typing keys for the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	504 job running in the terminal. See \|terminal-typing\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	505
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	506 omap-info
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	507 Operator-pending mappings can be used to define a movement command that can be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	508 used with any operator. Simple example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	509 :omap { w
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	510 makes "y{" work like "yw" and "d{" like "dw".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	511
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	512 To ignore the starting cursor position and select different text, you can have
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	513 the omap start Visual mode to select the text to be operated upon. Example
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	514 that operates on a function name in the current line: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	515 onoremap <silent> F :<C-U>normal! 0f(hviw<CR>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	516 The CTRL-U (<C-U>) is used to remove the range that Vim may insert. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	517 Normal mode commands find the first '(' character and select the first word
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	518 before it. That usually is the function name.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	519
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	520 To enter a mapping for Normal and Visual mode, but not Operator-pending mode,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	521 first define it for all three modes, then unmap it for
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	522 Operator-pending mode: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	523 :map xx something-difficult
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	524 :ounmap xx
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	525
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	526 Likewise for a mapping for Visual and Operator-pending mode or Normal and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	527 Operator-pending mode.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	528
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	529 language-mapping
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	530 ":lmap" defines a mapping that applies to:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	531 - Insert mode
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	532 - Command-line mode
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	533 - when entering a search pattern
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	534 - the argument of the commands that accept a text character, such as "r" and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	535 "f"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	536 - for the input() line
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	537 Generally: Whenever a character is to be typed that is part of the text in the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	538 buffer, not a Vim command character. "Lang-Arg" isn't really another mode,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	539 it's just used here for this situation.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	540 The simplest way to load a set of related language mappings is by using the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	541 'keymap' option. See \|45.5\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	542 In Insert mode and in Command-line mode the mappings can be disabled with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	543 the CTRL-^ command \|i_CTRL-^\| \|c_CTRL-^\|. These commands change the value of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	544 the 'iminsert' option. When starting to enter a normal command line (not a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	545 search pattern) the mappings are disabled until a CTRL-^ is typed. The state
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	546 last used is remembered for Insert mode and Search patterns separately. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	547 state for Insert mode is also used when typing a character as an argument to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	548 command like "f" or "t".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	549 Language mappings will never be applied to already mapped characters. They
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	550 are only used for typed characters. This assumes that the language mapping
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	551 was already done when typing the mapping.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	552
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	553
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	554 1.4 LISTING MAPPINGS map-listing
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	555
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	556 When listing mappings the characters in the first two columns are:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	557
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	558 CHAR MODE ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	559 <Space> Normal, Visual, Select and Operator-pending
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	560 n Normal
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	561 v Visual and Select
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	562 s Select
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	563 x Visual
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	564 o Operator-pending
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	565 ! Insert and Command-line
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	566 i Insert
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	567 l ":lmap" mappings for Insert, Command-line and Lang-Arg
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	568 c Command-line
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	569 t Terminal-Job
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	570
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	571 Just before the {rhs} a special character can appear:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	572 * indicates that it is not remappable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	573 & indicates that only script-local mappings are remappable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	574 @ indicates a buffer-local mapping
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	575
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	576 Everything from the first non-blank after {lhs} up to the end of the line
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	577 (or '\|') is considered to be part of {rhs}. This allows the {rhs} to end
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	578 with a space.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	579
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	580 Note: When using mappings for Visual mode, you can use the "'<" mark, which
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	581 is the start of the last selected Visual area in the current buffer \|'<\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	582
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	583 The \|:filter\| command can be used to select what mappings to list. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	584 pattern is matched against the {lhs} and {rhs} in the raw form.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	585
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	586 While mappings are being listed, it is not possible to add or clear mappings,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	587 e.g. from a timer callback. E1309
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	588
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	589 :map-verbose
34049 7dcfd6c96ccc runtime(doc): Update Version9.txt for release 9.1 (#13804) Christian Brabandt <cb@256bit.org> parents: 34011 diff changeset	590 When 'verbose' is non-zero, the detected and used 'keyprotocol' value will be
7dcfd6c96ccc runtime(doc): Update Version9.txt for release 9.1 (#13804) Christian Brabandt <cb@256bit.org> parents: 34011 diff changeset	591 displayed in the first line. Also a key map will also display where it was
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	592 last defined. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	593
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	594 :verbose map <C-W>*
34049 7dcfd6c96ccc runtime(doc): Update Version9.txt for release 9.1 (#13804) Christian Brabandt <cb@256bit.org> parents: 34011 diff changeset	595 Kitty keyboard protocol: Cleared
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	596 n <C-W>* * <C-W><C-S>*
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	597 Last set from /home/abcd/.vimrc
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	598
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	599 See \|:verbose-cmd\| for more information.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	600
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	601
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	602 1.5 MAPPING SPECIAL KEYS :map-special-keys
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	603
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	604 There are three ways to map a special key:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	605 1. The Vi-compatible method: Map the key code. Often this is a sequence that
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	606 starts with <Esc>. To enter a mapping like this you type ":map " and then
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	607 you have to type CTRL-V before hitting the function key. Note that when
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	608 the key code for the key is in the termcap (the t_ options), it will
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	609 automatically be translated into the internal code and become the second
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	610 way of mapping (unless the 'k' flag is included in 'cpoptions').
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	611 2. The second method is to use the internal code for the function key. To
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	612 enter such a mapping type CTRL-K and then hit the function key, or use
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	613 the form "#1", "#2", .. "#9", "#0", "<Up>", "<S-Down>", "<S-F7>", etc.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	614 (see table of keys \|key-notation\|, all keys from <Up> can be used). The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	615 first ten function keys can be defined in two ways: Just the number, like
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	616 "#2", and with "<F>", like "<F2>". Both stand for function key 2. "#0"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	617 refers to function key 10, defined with option 't_f10', which may be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	618 function key zero on some keyboards. The <> form cannot be used when
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	619 'cpoptions' includes the '<' flag.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	620 3. Use the termcap entry, with the form <t_xx>, where "xx" is the name of the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	621 termcap entry. Any string entry can be used. For example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	622 :map <t_F3> G
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	623 < Maps function key 13 to "G". This does not work if 'cpoptions' includes
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	624 the '<' flag.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	625
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	626 The advantage of the second and third method is that the mapping will work on
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	627 different terminals without modification (the function key will be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	628 translated into the same internal code or the actual key code, no matter what
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	629 terminal you are using. The termcap must be correct for this to work, and you
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	630 must use the same mappings).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	631
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	632 DETAIL: Vim first checks if a sequence from the keyboard is mapped. If it
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	633 isn't the terminal key codes are tried (see \|terminal-options\|). If a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	634 terminal code is found it is replaced with the internal code. Then the check
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	635 for a mapping is done again (so you can map an internal code to something
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	636 else). What is written into the script file depends on what is recognized.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	637 If the terminal key code was recognized as a mapping the key code itself is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	638 written to the script file. If it was recognized as a terminal code the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	639 internal code is written to the script file.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	640
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	641
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	642 1.6 SPECIAL CHARACTERS :map-special-chars
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	643 map_backslash map-backslash
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	644 Note that only CTRL-V is mentioned here as a special character for mappings
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	645 and abbreviations. When 'cpoptions' does not contain 'B', a backslash can
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	646 also be used like CTRL-V. The <> notation can be fully used then \|<>\|. But
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	647 you cannot use "<C-V>" like CTRL-V to escape the special meaning of what
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	648 follows.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	649
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	650 To map a backslash, or use a backslash literally in the {rhs}, the special
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	651 sequence "<Bslash>" can be used. This avoids the need to double backslashes
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	652 when using nested mappings.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	653
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	654 map_CTRL-C map-CTRL-C
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	655 Using CTRL-C in the {lhs} is possible, but it will only work when Vim is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	656 waiting for a key, not when Vim is busy with something. When Vim is busy
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	657 CTRL-C interrupts/breaks the command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	658 When using the GUI version on MS-Windows CTRL-C can be mapped to allow a Copy
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	659 command to the clipboard. Use CTRL-Break to interrupt Vim.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	660
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	661 map_space_in_lhs map-space_in_lhs
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	662 To include a space in {lhs} precede it with a CTRL-V (type two CTRL-Vs for
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	663 each space).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	664 map_space_in_rhs map-space_in_rhs
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	665 If you want a {rhs} that starts with a space, use "<Space>". To be fully Vi
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	666 compatible (but unreadable) don't use the \|<>\| notation, precede {rhs} with a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	667 single CTRL-V (you have to type CTRL-V two times).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	668 map_empty_rhs map-empty-rhs
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	669 You can create an empty {rhs} by typing nothing after a single CTRL-V (you
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	670 have to type CTRL-V two times). Unfortunately, you cannot do this in a vimrc
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	671 file.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	672 <Nop>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	673 An easier way to get a mapping that doesn't produce anything, is to use
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	674 "<Nop>" for the {rhs}. This only works when the \|<>\| notation is enabled.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	675 For example, to make sure that function key 8 does nothing at all: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	676 :map <F8> <Nop>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	677 :map! <F8> <Nop>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	678 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	679 map-multibyte
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	680 It is possible to map multibyte characters, but only the whole character. You
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	681 cannot map the first byte only. This was done to prevent problems in this
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	682 scenario: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	683 :set encoding=latin1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	684 :imap <M-C> foo
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	685 :set encoding=utf-8
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	686 The mapping for <M-C> is defined with the latin1 encoding, resulting in a 0xc3
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	687 byte. If you type the character á (0xe1 <M-a>) in UTF-8 encoding this is the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	688 two bytes 0xc3 0xa1. You don't want the 0xc3 byte to be mapped then or
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	689 otherwise it would be impossible to type the á character.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	690
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	691 <Leader> mapleader
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	692 To define a mapping which uses the "g:mapleader" variable, the special string
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	693 "<Leader>" can be used. It is replaced with the string value of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	694 "g:mapleader". If "g:mapleader" is not set or empty, a backslash is used
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	695 instead. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	696 map <Leader>A oanother line<Esc>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	697 Works like: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	698 map \A oanother line<Esc>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	699 But after (legacy script): >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	700 let mapleader = ","
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	701 Or (Vim9 script): >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	702 g:mapleader = ","
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	703 It works like: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	704 map ,A oanother line<Esc>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	705
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	706 Note that the value of "g:mapleader" is used at the moment the mapping is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	707 defined. Changing "g:mapleader" after that has no effect for already defined
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	708 mappings.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	709
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	710 <LocalLeader> maplocalleader
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	711 <LocalLeader> is just like <Leader>, except that it uses "maplocalleader"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	712 instead of "mapleader". <LocalLeader> is to be used for mappings which are
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	713 local to a buffer. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	714 :map <buffer> <LocalLeader>A oanother line<Esc>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	715 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	716 In a global plugin <Leader> should be used and in a filetype plugin
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	717 <LocalLeader>. "mapleader" and "maplocalleader" can be equal. Although, if
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	718 you make them different, there is a smaller chance of mappings from global
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	719 plugins to clash with mappings for filetype plugins. For example, you could
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	720 keep "mapleader" at the default backslash, and set "maplocalleader" to an
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	721 underscore.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	722
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	723 map-<SID>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	724 In a script the special key name "<SID>" can be used to define a mapping
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	725 that's local to the script. See \|<SID>\| for details.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	726
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	727 <Plug>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	728 The special key name "<Plug>" can be used for an internal mapping, which is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	729 not to be matched with any key sequence. This is useful in plugins
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	730 \|using-<Plug>\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	731
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	732 <MouseMove>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	733 The special key name "<MouseMove>" can be used to handle mouse movement. It
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	734 needs to be enabled with 'mousemoveevent'. Currently only works in the GUI.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	735 The \|getmousepos()\| function can be used to obtain the mouse position.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	736
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	737 <Char> <Char->
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	738 To map a character by its decimal, octal or hexadecimal number the <Char>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	739 construct can be used:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	740 <Char-123> character 123
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	741 <Char-033> character 27
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	742 <Char-0x7f> character 127
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	743 <S-Char-114> character 114 ('r') shifted ('R')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	744 This is useful to specify a (multibyte) character in a 'keymap' file.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	745 Upper and lowercase differences are ignored.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	746
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	747 map-comments
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	748 It is not possible to put a comment after these commands, because the '"'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	749 character is considered to be part of the {lhs} or {rhs}. However, one can
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	750 use \|", since this starts a new, empty command with a comment.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	751
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	752 map_bar map-bar
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	753 Since the '\|' character is used to separate a map command from the next
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	754 command, you will have to do something special to include a '\|' in {rhs}.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	755 There are three methods:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	756 use works when example ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	757 <Bar> '<' is not in 'cpoptions' :map _l :!ls <Bar> more^M
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	758 \\| 'b' is not in 'cpoptions' :map _l :!ls \\| more^M
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	759 ^V\| always, in Vim and Vi :map _l :!ls ^V\| more^M
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	760
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	761 (here ^V stands for CTRL-V; to get one CTRL-V you have to type it twice; you
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	762 cannot use the <> notation "<C-V>" here).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	763
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	764 All three work when you use the default setting for 'cpoptions'.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	765
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	766 When 'b' is present in 'cpoptions', "\\|" will be recognized as a mapping
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	767 ending in a '\' and then another command. This is Vi compatible, but
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	768 illogical when compared to other commands.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	769
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	770 map_return map-return
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	771 When you have a mapping that contains an Ex command, you need to put a line
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	772 terminator after it to have it executed. The use of <CR> is recommended for
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	773 this (see \|<>\|). Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	774 :map _ls :!ls -l %:S<CR>:echo "the end"<CR>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	775
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	776 To avoid mapping of the characters you type in insert or Command-line mode,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	777 type a CTRL-V first. The mapping in Insert mode is disabled if the 'paste'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	778 option is on.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	779 map-error
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	780 Note that when an error is encountered (that causes an error message or might
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	781 cause a beep) the rest of the mapping is not executed. This is Vi-compatible.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	782
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	783 Note that the second character (argument) of the commands @zZtTfF[]rm'`"v
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	784 and CTRL-X is not mapped. This was done to be able to use all the named
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	785 registers and marks, even when the command with the same name has been
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	786 mapped.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	787
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	788
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	789 1.7 WHAT KEYS TO MAP map-which-keys
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	790
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	791 If you are going to map something, you will need to choose which key(s) to use
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	792 for the {lhs}. You will have to avoid keys that are used for Vim commands,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	793 otherwise you would not be able to use those commands anymore. Here are a few
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	794 suggestions:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	795 - Function keys <F2>, <F3>, etc.. Also the shifted function keys <S-F1>,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	796 <S-F2>, etc. Note that <F1> is already used for the help command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	797 - Any key with the Alt or Meta key pressed. Depending on your keyboard
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	798 accented characters may be used as well. \|:map-alt-keys\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	799 - Use the '_' or ',' character and then any other character. The "_" and ","
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	800 commands do exist in Vim (see \|_\| and \|,\|), but you probably never use them.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	801 - Use a key that is a synonym for another command. For example: CTRL-P and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	802 CTRL-N. Use an extra character to allow more mappings.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	803 - The key defined by <Leader> and one or more other keys. This is especially
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	804 useful in scripts. \|mapleader\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	805
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	806 See the file "index" for keys that are not used and thus can be mapped without
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	807 losing any builtin function. You can also use ":help {key}^D" to find out if
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	808 a key is used for some command. ({key} is the specific key you want to find
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	809 out about, ^D is CTRL-D).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	810
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	811
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	812 1.8 EXAMPLES map-examples
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	813
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	814 A few examples (given as you type them, for "<CR>" you type four characters;
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	815 the '<' flag must not be present in 'cpoptions' for this to work). >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	816
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	817 :map <F3> o#include
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	818 :map <M-g> /foo<CR>cwbar<Esc>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	819 :map _x d/END/e<CR>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	820 :map! qq quadrillion questions
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	821
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	822
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	823 Multiplying a count
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	824
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	825 When you type a count before triggering a mapping, it's like the count was
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	826 typed before the {lhs}. For example, with this mapping: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	827 :map <F4> 3w
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	828 Typing 2<F4> will result in "23w". Thus not moving 2 * 3 words but 23 words.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	829 If you want to multiply counts use the expression register: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	830 :map <F4> @='3w'<CR>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	831 The part between quotes is the expression being executed. \|@=\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	832
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	833
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	834 1.9 USING MAPPINGS map-typing
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	835
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	836 Vim will compare what you type with the start of a mapped sequence. If there
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	837 is an incomplete match, it will get more characters until there either is a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	838 complete match or until there is no match at all. Example: If you map! "qq",
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	839 the first 'q' will not appear on the screen until you type another
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	840 character. This is because Vim cannot know if the next character will be a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	841 'q' or not. If the 'timeout' option is on (which is the default) Vim will
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	842 only wait for one second (or as long as specified with the 'timeoutlen'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	843 option). After that it assumes that the 'q' is to be interpreted as such. If
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	844 you type slowly, or your system is slow, reset the 'timeout' option. Then you
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	845 might want to set the 'ttimeout' option.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	846
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	847 map-precedence
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	848 Buffer-local mappings (defined using \|:map-<buffer>\|) take precedence over
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	849 global mappings. When a buffer-local mapping is the same as a global mapping,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	850 Vim will use the buffer-local mapping. In addition, Vim will use a complete
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	851 mapping immediately if it was defined with <nowait>, even if a longer mapping
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	852 has the same prefix. For example, given the following two mappings: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	853 :map <buffer> <nowait> \a :echo "Local \a"<CR>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	854 :map \abc :echo "Global \abc"<CR>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	855 When typing \a the buffer-local mapping will be used immediately. Vim will
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	856 not wait for more characters to see if the user might be typing \abc.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	857
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	858 map-keys-fails
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	859 There are situations where key codes might not be recognized:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	860 - Vim can only read part of the key code. Mostly this is only the first
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	861 character. This happens on some Unix versions in an xterm.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	862 - The key code is after character(s) that are mapped. E.g., "<F1><F1>" or
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	863 "g<F1>".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	864
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	865 The result is that the key code is not recognized in this situation, and the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	866 mapping fails. There are two actions needed to avoid this problem:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	867
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	868 - Remove the 'K' flag from 'cpoptions'. This will make Vim wait for the rest
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	869 of the characters of the function key.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	870 - When using <F1> to <F4> the actual key code generated may correspond to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	871 <xF1> to <xF4>. There are mappings from <xF1> to <F1>, <xF2> to <F2>, etc.,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	872 but these are not recognized after another half a mapping. Make sure the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	873 key codes for <F1> to <F4> are correct: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	874 :set <F1>=<type CTRL-V><type F1>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	875 < Type the <F1> as four characters. The part after the "=" must be done with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	876 the actual keys, not the literal text.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	877 Another solution is to use the actual key code in the mapping for the second
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	878 special key: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	879 :map <F1><Esc>OP :echo "yes"<CR>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	880 Don't type a real <Esc>, Vim will recognize the key code and replace it with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	881 <F1> anyway.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	882
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	883 Another problem may be that when keeping ALT or Meta pressed the terminal
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	884 prepends ESC instead of setting the 8th bit. See \|:map-alt-keys\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	885
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	886 recursive_mapping
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	887 If you include the {lhs} in the {rhs} you have a recursive mapping. When
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	888 {lhs} is typed, it will be replaced with {rhs}. When the {lhs} which is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	889 included in {rhs} is encountered it will be replaced with {rhs}, and so on.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	890 This makes it possible to repeat a command an infinite number of times. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	891 only problem is that the only way to stop this is by causing an error. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	892 macros to solve a maze uses this, look there for an example. There is one
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	893 exception: If the {rhs} starts with {lhs}, the first character is not mapped
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	894 again (this is Vi compatible).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	895 For example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	896 :map ab abcd
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	897 will execute the "a" command and insert "bcd" in the text. The "ab" in the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	898 {rhs} will not be mapped again.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	899
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	900 If you want to exchange the meaning of two keys you should use the :noremap
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	901 command. For example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	902 :noremap k j
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	903 :noremap j k
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	904 This will exchange the cursor up and down commands.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	905
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	906 With the normal :map command, when the 'remap' option is on, mapping takes
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	907 place until the text is found not to be a part of a {lhs}. For example, if
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	908 you use: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	909 :map x y
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	910 :map y x
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	911 Vim will replace x with y, and then y with x, etc. When this has happened
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	912 'maxmapdepth' times (default 1000), Vim will give the error message
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	913 "recursive mapping".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	914
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	915 :map-undo
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	916 If you include an undo command inside a mapped sequence, this will bring the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	917 text back in the state before executing the macro. This is compatible with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	918 the original Vi, as long as there is only one undo command in the mapped
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	919 sequence (having two undo commands in a mapped sequence did not make sense
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	920 in the original Vi, you would get back the text before the first undo).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	921
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	922
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	923 1.10 MAPPING ALT-KEYS :map-alt-keys
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	924
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	925 For a readable mapping command the <A-k> form can be used. Note that <A-k>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	926 and <A-K> are different, the latter will use an upper case letter. Actually,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	927 <A-K> and <A-S-K> are the same. Instead of "A" you can use "M". If you have
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	928 an actual Meta modifier key, please see \|:map-meta-keys\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	929
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	930 In the GUI Vim handles the Alt key itself, thus mapping keys with ALT should
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	931 always work. But in a terminal Vim gets a sequence of bytes and has to figure
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	932 out whether ALT was pressed or not.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	933
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	934 If the terminal supports the modifyOtherKeys mode and it has been enabled,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	935 then Vim can recognize more key combinations, see \|modifyOtherKeys\| below.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	936 The Kitty keyboard protocol works in a similar way, see
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	937 \|kitty-keyboard-protocol\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	938
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	939 By default Vim assumes that pressing the ALT key sets the 8th bit of a typed
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	940 character. Most decent terminals can work that way, such as xterm, aterm and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	941 rxvt. If your <A-k> mappings don't work it might be that the terminal is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	942 prefixing the character with an ESC character. But you can just as well type
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	943 ESC before a character, thus Vim doesn't know what happened (except for
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	944 checking the delay between characters, which is not reliable).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	945
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	946 As of this writing, some mainstream terminals like gnome-terminal and konsole
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	947 use the ESC prefix. There doesn't appear a way to have them use the 8th bit
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	948 instead. Xterm should work well by default. Aterm and rxvt should work well
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	949 when started with the "--meta8" argument. You can also tweak resources like
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	950 "metaSendsEscape", "eightBitInput" and "eightBitOutput".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	951
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	952 On the Linux console, this behavior can be toggled with the "setmetamode"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	953 command. Bear in mind that not using an ESC prefix could get you in trouble
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	954 with other programs. You should make sure that bash has the "convert-meta"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	955 option set to "on" in order for your Meta keybindings to still work on it
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	956 (it's the default readline behavior, unless changed by specific system
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	957 configuration). For that, you can add the line: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	958
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	959 set convert-meta on
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	960
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	961 to your ~/.inputrc file. If you're creating the file, you might want to use: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	962
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	963 $include /etc/inputrc
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	964
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	965 as the first line, if that file exists on your system, to keep global options.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	966 This may cause a problem for entering special characters, such as the umlaut.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	967 Then you should use CTRL-V before that character.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	968
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	969 Bear in mind that convert-meta has been reported to have troubles when used in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	970 UTF-8 locales. On terminals like xterm, the "metaSendsEscape" resource can be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	971 toggled on the fly through the "Main Options" menu, by pressing Ctrl-LeftClick
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	972 on the terminal; that's a good last resource in case you want to send ESC when
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	973 using other applications but not when inside Vim.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	974
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	975
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	976 1.11 MAPPING META-KEYS :map-meta-keys
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	977
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	978 Mapping keys with the Meta modifier works very similar to using the Alt key.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	979 What key on your keyboard produces the Meta modifier depends on your keyboard
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	980 and configuration.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	981
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	982 Note that mapping <M-a> actually is for using the Alt key. That can be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	983 confusing! It cannot be changed, it would not be backwards compatible.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	984
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	985 For the Meta modifier the "T" character is used. For example, to map Meta-b
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	986 in Insert mode: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	987 :imap <T-b> terrible
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	988
34219 a0a4a774117b patch 9.1.0058: Cannot map Super Keys in GTK UI Christian Brabandt <cb@256bit.org> parents: 34082 diff changeset	989 1.12 MAPPING SUPER-KEYS or COMMAND-KEYS :map-super-keys :map-cmd-key
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	990
34219 a0a4a774117b patch 9.1.0058: Cannot map Super Keys in GTK UI Christian Brabandt <cb@256bit.org> parents: 34082 diff changeset	991 The Super modifier is available in GUI mode (when \|gui_running\| is 1) for
a0a4a774117b patch 9.1.0058: Cannot map Super Keys in GTK UI Christian Brabandt <cb@256bit.org> parents: 34082 diff changeset	992 GVim on Linux and MacVim on Mac OS. If you're on a Mac, this represents the
a0a4a774117b patch 9.1.0058: Cannot map Super Keys in GTK UI Christian Brabandt <cb@256bit.org> parents: 34082 diff changeset	993 Command key, on Linux with the GTK GUI it represents the Super key.
a0a4a774117b patch 9.1.0058: Cannot map Super Keys in GTK UI Christian Brabandt <cb@256bit.org> parents: 34082 diff changeset	994 The character "D" is used for the Super / Command modifier.
a0a4a774117b patch 9.1.0058: Cannot map Super Keys in GTK UI Christian Brabandt <cb@256bit.org> parents: 34082 diff changeset	995
a0a4a774117b patch 9.1.0058: Cannot map Super Keys in GTK UI Christian Brabandt <cb@256bit.org> parents: 34082 diff changeset	996 For example, to map Command-b in Insert mode: >
a0a4a774117b patch 9.1.0058: Cannot map Super Keys in GTK UI Christian Brabandt <cb@256bit.org> parents: 34082 diff changeset	997 :imap <D-b> barritone
a0a4a774117b patch 9.1.0058: Cannot map Super Keys in GTK UI Christian Brabandt <cb@256bit.org> parents: 34082 diff changeset	998
a0a4a774117b patch 9.1.0058: Cannot map Super Keys in GTK UI Christian Brabandt <cb@256bit.org> parents: 34082 diff changeset	999 1.13 MAPPING IN modifyOtherKeys mode modifyOtherKeys
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1000
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1001 Xterm and a few other terminals can be put in a mode where keys with modifiers
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1002 are sent with a special escape code. Vim recognizes these codes and can then
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1003 make a difference between CTRL-H and Backspace, even when Backspace sends the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1004 character 8. And many more special keys, such as Tab and CTRL-I, which cannot
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1005 be mapped separately otherwise.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1006
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1007 For xterm modifyOtherKeys is enabled in the builtin termcap entry. If this is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1008 not used you can enable modifyOtherKeys with these lines in your vimrc: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1009 let &t_TI = "\<Esc>[>4;2m"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1010 let &t_TE = "\<Esc>[>4;m"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1011
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1012 This sets modifyOtherKeys to level 2. Note that modifyOtherKeys level 1 does
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1013 not work. Some terminals do not support level 2 and then send key codes that
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1014 Vim will not be able to correctly recognize.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1015
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1016 In case the modifyOtherKeys mode causes problems you can disable it: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1017 let &t_TI = ""
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1018 let &t_TE = ""
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1019 It does not take effect immediately. To have this work without restarting Vim
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1020 execute a shell command, e.g.: `!ls` Or put the lines in your \|vimrc\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1021
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1022 When modifyOtherKeys is enabled you can map <C-[> and <C-S-{>: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1023 imap <C-[> [[[
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1024 imap <C-{> {{{
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1025 Without modifyOtherKeys <C-[> and <C-{> are indistinguishable from Esc.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1026 Note that <C-{> is used and not <C-S-[> or <C-S-{>. This works on most
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1027 keyboards. Similarly, <C-}> is used instead of <C-S-]> or <C-S-}> and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1028 <C-\|> instead of <C-S-\> or <C-S-\|>. Note that '\|' has a special meaning in a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1029 mapping, see \|map-bar\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1030
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1031 WARNING: if you map <C-[> you may very well break any key codes that start
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1032 with Esc. Make sure it comes AFTER other mappings.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1033
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1034 Starting with xterm version 377 Vim can detect the modifyOtherKeys state by
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1035 requesting it. For this the 't_RK' termcap entry is used. When the response
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1036 is found then Vim will know whether modifyOtherKeys level 2 is enabled, and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1037 handle mappings accordingly.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1038
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1039 Before version 377 Vim automatically detects if the modifyOtherKeys mode was
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1040 enabled when it spots an escape sequence that must have been created by it.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1041 To see if Vim detected such an escape sequence use `:verbose map`, the first
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1042 line will then show "Seen modifyOtherKeys: true" (possibly translated).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1043
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1044 This automatic detection depends on receiving an escape code starting with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1045 "<1b>[27;". This is the normal way xterm sends these key codes. However, if
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1046 the formatOtherKeys resource is set another form is used that is not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1047 recognized, therefore you must not set formatOtherKeys.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1048
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1049 A known side effect is that in Insert mode the raw escape sequence is inserted
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1050 after the CTRL-V key. This can be used to check whether modifyOtherKeys is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1051 enabled: In Insert mode type CTRL-SHIFT-V CTRL-V, if you get one byte then
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1052 modifyOtherKeys is off, if you get <1b>[27;5;118~ then it is on.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1053
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1054 Note that xterm up to version 376 has a bug that makes Shift-Esc send a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1055 regular Esc code, the Shift modifier is dropped.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1056
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1057 When the 'esckeys' option is off, then modifyOtherKeys will be disabled in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1058 Insert mode to avoid every key with a modifier causing Insert mode to end.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1059
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1060
34219 a0a4a774117b patch 9.1.0058: Cannot map Super Keys in GTK UI Christian Brabandt <cb@256bit.org> parents: 34082 diff changeset	1061 1.14 MAPPING WITH KITTY KEYBOARD PROTOCOL kitty-keyboard-protocol
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1062
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1063 If the value of 'term' contains "kitty" then Vim will send out an escape
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1064 sequence to enable the Kitty keyboard protocol. This can be changed with the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1065 'keyprotocol' option.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1066
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1067 Like modifyOtherKeys, this will make it possible to distinguish between more
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1068 keys with modifiers. Also, this protocol sends an escape sequence for the Esc
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1069 key, so that Vim does not need to use a timeout to know whether receiving an
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1070 Esc character means the Esc key was pressed or it's the start of an escape
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1071 sequence.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1072
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1073 Vim automatically detects if the Kitty keyboard protocol was enabled when it
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1074 spots the response to the status request (this should be part of the \|t_TI\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1075 termcap entry). To see if Vim detected such an escape sequence use: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1076 :verbose map
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1077 The first line will then show "Kitty keyboard protocol: {value}" (possibly
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1078 translated). The meaning of {value}:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1079 Unknown no status received yet
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1080 Off protocol is not used
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1081 On protocol is used
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1082 Disabled protocol was used but expected to have been disabled
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1083 by 't_TE'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1084 Cleared protocol expected to have been disabled by 't_TE',
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1085 previous state is unknown
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1086
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1087
34219 a0a4a774117b patch 9.1.0058: Cannot map Super Keys in GTK UI Christian Brabandt <cb@256bit.org> parents: 34082 diff changeset	1088 1.15 MAPPING AN OPERATOR :map-operator
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1089
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1090 An operator is used before a {motion} command. To define your own operator
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1091 you must create a mapping that first sets the 'operatorfunc' option and then
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1092 invoke the \|g@\| operator. After the user types the {motion} command the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1093 specified function will be called.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1094
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1095 g@ E774 E775
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1096 g@{motion} Call the function set by the 'operatorfunc' option.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1097 The '[ mark is positioned at the start of the text
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1098 moved over by {motion}, the '] mark on the last
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1099 character of the text.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1100 The function is called with one String argument:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1101 "line" {motion} was \|linewise\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1102 "char" {motion} was \|characterwise\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1103 "block" {motion} was \|blockwise-visual\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1104 The type can be forced, see \|forced-motion\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1105 {not available when compiled without the \|+eval\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1106 feature}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1107
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1108 Here is an example that counts the number of spaces with <F4>: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1109
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1110 nnoremap <expr> <F4> CountSpaces()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1111 xnoremap <expr> <F4> CountSpaces()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1112 " doubling <F4> works on a line
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1113 nnoremap <expr> <F4><F4> CountSpaces() .. '_'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1114
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1115 function CountSpaces(context = {}, type = '') abort
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1116 if a:type == ''
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1117 let context = #{
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1118 \ dot_command: v:false,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1119 \ extend_block: '',
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1120 \ virtualedit: [&l:virtualedit, &g:virtualedit],
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1121 \ }
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1122 let &operatorfunc = function('CountSpaces', [context])
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1123 set virtualedit=block
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1124 return 'g@'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1125 endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1126
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1127 let save = #{
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1128 \ clipboard: &clipboard,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1129 \ selection: &selection,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1130 \ virtualedit: [&l:virtualedit, &g:virtualedit],
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1131 \ register: getreginfo('"'),
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1132 \ visual_marks: [getpos("'<"), getpos("'>")],
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1133 \ }
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1134
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1135 try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1136 set clipboard= selection=inclusive virtualedit=
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1137 let commands = #{
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1138 \ line: "'[V']",
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1139 \ char: "`[v`]",
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1140 \ block: "`[\<C-V>`]",
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1141 \ }[a:type]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1142 let [_, _, col, off] = getpos("']")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1143 if off != 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1144 let vcol = getline("'[")->strpart(0, col + off)->strdisplaywidth()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1145 if vcol >= [line("'["), '$']->virtcol() - 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1146 let a:context.extend_block = '$'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1147 else
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1148 let a:context.extend_block = vcol .. '\|'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1149 endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1150 endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1151 if a:context.extend_block != ''
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1152 let commands ..= 'oO' .. a:context.extend_block
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1153 endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1154 let commands ..= 'y'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1155 execute 'silent noautocmd keepjumps normal! ' .. commands
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1156 echomsg getreg('"')->count(' ')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1157 finally
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1158 call setreg('"', save.register)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1159 call setpos("'<", save.visual_marks[0])
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1160 call setpos("'>", save.visual_marks[1])
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1161 let &clipboard = save.clipboard
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1162 let &selection = save.selection
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1163 let [&l:virtualedit, &g:virtualedit] = get(a:context.dot_command ? save : a:context, 'virtualedit')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1164 let a:context.dot_command = v:true
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1165 endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1166 endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1167
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1168 An <expr> mapping is used to be able to fetch any prefixed count and register.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1169 This also avoids using a command line, which would trigger CmdlineEnter and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1170 CmdlineLeave autocommands.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1171
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1172 Note that the 'selection' option is temporarily set to "inclusive" to be able
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1173 to yank exactly the right text by using Visual mode from the '[ to the ']
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1174 mark.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1175
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1176 Also note that the 'clipboard' option is temporarily emptied to avoid
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1177 clobbering the `"*` or `"+` registers, if its value contains the item `unnamed`
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1178 or `unnamedplus`.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1179
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1180 The `mode()` function will return the state as it will be after applying the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1181 operator.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1182
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1183 Here is an example for using a lambda function to create a normal-mode
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1184 operator to add quotes around text in the current line: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1185
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1186 nnoremap <F4> <Cmd>let &opfunc='{t ->
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1187 \ getline(".")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1188 \ ->split("\\zs")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1189 \ ->insert("\"", col("'']"))
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1190 \ ->insert("\"", col("''[") - 1)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1191 \ ->join("")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1192 \ ->setline(".")}'<CR>g@
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1193
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1194 ==============================================================================
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1195 2. Abbreviations abbreviations Abbreviations
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1196
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1197 Abbreviations are used in Insert mode, Replace mode and Command-line mode.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1198 If you enter a word that is an abbreviation, it is replaced with the word it
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1199 stands for. This can be used to save typing for often used long words. And
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1200 you can use it to automatically correct obvious spelling errors.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1201 Examples:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1202
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1203 :iab ms Microsoft
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1204 :iab tihs this
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1205
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1206 There are three types of abbreviations:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1207
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1208 full-id The "full-id" type consists entirely of keyword characters (letters
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1209 and characters from 'iskeyword' option). This is the most common
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1210 abbreviation.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1211
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1212 Examples: "foo", "g3", "-1"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1213
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1214 end-id The "end-id" type ends in a keyword character, but all the other
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1215 characters are not keyword characters.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1216
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1217 Examples: "#i", "..f", "$/7"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1218
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1219 non-id The "non-id" type ends in a non-keyword character, the other
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1220 characters may be of any type, excluding space and tab. {this type
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1221 is not supported by Vi}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1222
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1223 Examples: "def#", "4/7$"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1224
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1225 Examples of strings that cannot be abbreviations: "a.b", "#def", "a b", "_$r"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1226
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1227 An abbreviation is only recognized when you type a non-keyword character.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1228 This can also be the <Esc> that ends Insert mode or the <CR> that ends a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1229 command. The non-keyword character which ends the abbreviation is inserted
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1230 after the expanded abbreviation. An exception to this is the character <C-]>,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1231 which is used to expand an abbreviation without inserting any extra
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1232 characters.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1233
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1234 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1235 :ab hh hello
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1236 < "hh<Space>" is expanded to "hello<Space>"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1237 "hh<C-]>" is expanded to "hello"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1238
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1239 The characters before the cursor must match the abbreviation. Each type has
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1240 an additional rule:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1241
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1242 full-id In front of the match is a non-keyword character, or this is where
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1243 the line or insertion starts. Exception: When the abbreviation is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1244 only one character, it is not recognized if there is a non-keyword
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1245 character in front of it, other than a space or a tab. However, for
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1246 the command line "'<,'>" (or any other marks) is ignored, as if the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1247 command line starts after it.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1248
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1249 end-id In front of the match is a keyword character, or a space or a tab,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1250 or this is where the line or insertion starts.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1251
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1252 non-id In front of the match is a space, tab or the start of the line or
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1253 the insertion.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1254
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1255 Examples: ({CURSOR} is where you type a non-keyword character) >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1256 :ab foo four old otters
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1257 < " foo{CURSOR}" is expanded to " four old otters"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1258 " foobar{CURSOR}" is not expanded
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1259 "barfoo{CURSOR}" is not expanded
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1260 >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1261 :ab #i #include
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1262 < "#i{CURSOR}" is expanded to "#include"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1263 ">#i{CURSOR}" is not expanded
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1264 >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1265 :ab ;; <endofline>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1266 < "test;;" is not expanded
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1267 "test ;;" is expanded to "test <endofline>"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1268
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1269 To avoid the abbreviation in Insert mode: Type CTRL-V before the character
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1270 that would trigger the abbreviation. E.g. CTRL-V <Space>. Or type part of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1271 the abbreviation, exit insert mode with <Esc>, re-enter insert mode with "a"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1272 and type the rest.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1273
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1274 To avoid the abbreviation in Command-line mode: Type CTRL-V twice somewhere in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1275 the abbreviation to avoid it to be replaced. A CTRL-V in front of a normal
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1276 character is mostly ignored otherwise.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1277
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1278 It is possible to move the cursor after an abbreviation: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1279 :iab if if ()<Left>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1280 This does not work if 'cpoptions' includes the '<' flag. \|<>\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1281
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1282 You can even do more complicated things. For example, to consume the space
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1283 typed after an abbreviation: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1284 func Eatchar(pat)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1285 let c = nr2char(getchar(0))
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1286 return (c =~ a:pat) ? '' : c
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1287 endfunc
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1288 iabbr <silent> if if ()<Left><C-R>=Eatchar('\s')<CR>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1289
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1290 There are no default abbreviations.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1291
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1292 Abbreviations are never recursive. You can use ":ab f f-o-o" without any
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1293 problem. But abbreviations can be mapped. {some versions of Vi support
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1294 recursive abbreviations, for no apparent reason}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1295
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1296 Abbreviations are disabled if the 'paste' option is on.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1297
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1298 :abbreviate-local :abbreviate-<buffer>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1299 Just like mappings, abbreviations can be local to a buffer. This is mostly
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1300 used in a \|filetype-plugin\| file. Example for a C plugin file: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1301 :abb <buffer> FF for (i = 0; i < ; ++i)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1302 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1303 :ab :abbreviate
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1304 :ab[breviate] list all abbreviations. The character in the first
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1305 column indicates the mode where the abbreviation is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1306 used: 'i' for insert mode, 'c' for Command-line
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1307 mode, '!' for both. These are the same as for
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1308 mappings, see \|map-listing\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1309
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1310 :abbreviate-verbose
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1311 When 'verbose' is non-zero, listing an abbreviation will also display where it
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1312 was last defined. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1313
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1314 :verbose abbreviate
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1315 ! teh the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1316 Last set from /home/abcd/vim/abbr.vim
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1317
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1318 See \|:verbose-cmd\| for more information.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1319
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1320 :ab[breviate] {lhs} list the abbreviations that start with {lhs}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1321 You may need to insert a CTRL-V (type it twice) to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1322 avoid that a typed {lhs} is expanded, since
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1323 command-line abbreviations apply here.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1324
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1325 :ab[breviate] [<expr>] [<buffer>] {lhs} {rhs}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1326 add abbreviation for {lhs} to {rhs}. If {lhs} already
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1327 existed it is replaced with the new {rhs}. {rhs} may
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1328 contain spaces.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1329 See \|:map-<expr>\| for the optional <expr> argument.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1330 See \|:map-<buffer>\| for the optional <buffer> argument.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1331
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1332 :una :unabbreviate
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1333 :una[bbreviate] [<buffer>] {lhs}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1334 Remove abbreviation for {lhs} from the list. If none
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1335 is found, remove abbreviations in which {lhs} matches
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1336 with the {rhs}. This is done so that you can even
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1337 remove abbreviations after expansion. To avoid
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1338 expansion insert a CTRL-V (type it twice).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1339
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1340 :norea :noreabbrev
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1341 :norea[bbrev] [<expr>] [<buffer>] [lhs] [rhs]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1342 Same as ":ab", but no remapping for this {rhs}.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1343
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1344 :ca :cab :cabbrev
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1345 :ca[bbrev] [<expr>] [<buffer>] [lhs] [rhs]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1346 Same as ":ab", but for Command-line mode only.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1347
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1348 :cuna :cunabbrev
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1349 :cuna[bbrev] [<buffer>] {lhs}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1350 Same as ":una", but for Command-line mode only.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1351
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1352 :cnorea :cnoreabbrev
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1353 :cnorea[bbrev] [<expr>] [<buffer>] [lhs] [rhs]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1354 same as ":ab", but for Command-line mode only and no
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1355 remapping for this {rhs}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1356
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1357 :ia :iabbrev
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1358 :ia[bbrev] [<expr>] [<buffer>] [lhs] [rhs]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1359 Same as ":ab", but for Insert mode only.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1360
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1361 :iuna :iunabbrev
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1362 :iuna[bbrev] [<buffer>] {lhs}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1363 Same as ":una", but for insert mode only.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1364
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1365 :inorea :inoreabbrev
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1366 :inorea[bbrev] [<expr>] [<buffer>] [lhs] [rhs]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1367 Same as ":ab", but for Insert mode only and no
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1368 remapping for this {rhs}.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1369
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1370 :abc :abclear
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1371 :abc[lear] [<buffer>] Remove all abbreviations.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1372
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1373 :iabc :iabclear
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1374 :iabc[lear] [<buffer>] Remove all abbreviations for Insert mode.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1375
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1376 :cabc :cabclear
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1377 :cabc[lear] [<buffer>] Remove all abbreviations for Command-line mode.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1378
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1379 using_CTRL-V
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1380 It is possible to use special characters in the rhs of an abbreviation.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1381 CTRL-V has to be used to avoid the special meaning of most non printable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1382 characters. How many CTRL-Vs need to be typed depends on how you enter the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1383 abbreviation. This also applies to mappings. Let's use an example here.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1384
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1385 Suppose you want to abbreviate "esc" to enter an <Esc> character. When you
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1386 type the ":ab" command in Vim, you have to enter this: (here ^V is a CTRL-V
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1387 and ^[ is <Esc>)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1388
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1389 You type: ab esc ^V^V^V^V^V^[
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1390
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1391 All keyboard input is subjected to ^V quote interpretation, so
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1392 the first, third, and fifth ^V characters simply allow the second,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1393 and fourth ^Vs, and the ^[, to be entered into the command-line.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1394
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1395 You see: ab esc ^V^V^[
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1396
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1397 The command-line contains two actual ^Vs before the ^[. This is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1398 how it should appear in your .exrc file, if you choose to go that
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1399 route. The first ^V is there to quote the second ^V; the :ab
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1400 command uses ^V as its own quote character, so you can include quoted
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1401 whitespace or the \| character in the abbreviation. The :ab command
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1402 doesn't do anything special with the ^[ character, so it doesn't need
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1403 to be quoted. (Although quoting isn't harmful; that's why typing 7
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1404 [but not 8!] ^Vs works.)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1405
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1406 Stored as: esc ^V^[
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1407
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1408 After parsing, the abbreviation's short form ("esc") and long form
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1409 (the two characters "^V^[") are stored in the abbreviation table.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1410 If you give the :ab command with no arguments, this is how the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1411 abbreviation will be displayed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1412
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1413 Later, when the abbreviation is expanded because the user typed in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1414 the word "esc", the long form is subjected to the same type of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1415 ^V interpretation as keyboard input. So the ^V protects the ^[
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1416 character from being interpreted as the "exit Insert mode" character.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1417 Instead, the ^[ is inserted into the text.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1418
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1419 Expands to: ^[
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1420
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1421 [example given by Steve Kirkendall]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1422
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1423 ==============================================================================
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1424 3. Local mappings and functions script-local
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1425
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1426 When using several Vim script files, there is the danger that mappings and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1427 functions used in one script use the same name as in other scripts. To avoid
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1428 this, they can be made local to the script.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1429
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1430 <SID> <SNR> E81
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1431 The string "<SID>" can be used in a mapping or menu. This requires that the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1432 '<' flag is not present in 'cpoptions'. This is useful if you have a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1433 script-local function that you want to call from a mapping in the same script.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1434 When executing the map command, Vim will replace "<SID>" with the special
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1435 key code <SNR>, followed by a number that's unique for the script, and an
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1436 underscore. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1437 :map <SID>Add
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1438 would define a mapping "<SNR>23_Add".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1439
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1440 When defining a function in a script, "s:" can be prepended to the name to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1441 make it local to the script (in \|Vim9\| script functions without a prefix are
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1442 local to the script). But when a mapping is executed from outside of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1443 the script, it doesn't know in which script the function was defined. To
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1444 avoid this problem, use "<SID>" instead of "s:". The same translation is done
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1445 as for mappings. This makes it possible to define a call to the function in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1446 a mapping.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1447
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1448 When a local function is executed, it runs in the context of the script it was
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1449 defined in. This means that new functions and mappings it defines can also
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1450 use "s:" or "<SID>" and it will use the same unique number as when the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1451 function itself was defined. Also, the "s:var" local script variables can be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1452 used.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1453
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1454 When executing an autocommand or a user command, it will run in the context of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1455 the script it was defined in. This makes it possible that the command calls a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1456 local function or uses a local mapping.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1457
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1458 In case the value is used in a context where <SID> cannot be correctly
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1459 expanded, use the expand() function: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1460 let &includexpr = expand('<SID>') .. 'My_includeexpr()'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1461
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1462 Otherwise, using "<SID>" outside of a script context is an error.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1463
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1464 If you need to get the script number to use in a complicated script, you can
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1465 use this function: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1466 func s:ScriptNumber()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1467 return matchstr(expand('<SID>'), '<SNR>\zs\d\+\ze_')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1468 endfunc
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1469
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1470 The "<SNR>" will be shown when listing functions and mappings. This is useful
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1471 to find out what they are defined to.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1472
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1473 The \|:scriptnames\| command can be used to see which scripts have been sourced
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1474 and what their <SNR> number is.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1475
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1476 This is all {not available when compiled without the \|+eval\| feature}.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1477
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1478 ==============================================================================
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1479 4. User-defined commands user-commands
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1480
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1481 It is possible to define your own Ex commands. A user-defined command can act
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1482 just like a built-in command (it can have a range or arguments, arguments can
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1483 be completed as filenames or buffer names, etc), except that when the command
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1484 is executed, it is transformed into a normal Ex command and then executed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1485
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1486 For starters: See section \|40.2\| in the user manual.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1487
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1488 E183 E841 user-cmd-ambiguous
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1489 All user defined commands must start with an uppercase letter, to avoid
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1490 confusion with builtin commands. Exceptions are these builtin commands:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1491 :Next
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1492 :X
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1493 They cannot be used for a user defined command. ":Print" is also an existing
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1494 command, but it is deprecated and can be overruled.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1495
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1496 The other characters of the user command can be uppercase letters, lowercase
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1497 letters or digits. When using digits, note that other commands that take a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1498 numeric argument may become ambiguous. For example, the command ":Cc2" could
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1499 be the user command ":Cc2" without an argument, or the command ":Cc" with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1500 argument "2". It is advised to put a space between the command name and the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1501 argument to avoid these problems.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1502
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1503 When using a user-defined command, the command can be abbreviated. However, if
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1504 an abbreviation is not unique, an error will be issued. Furthermore, a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1505 built-in command will always take precedence.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1506
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1507 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1508 :command Rename ...
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1509 :command Renumber ...
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1510 :Rena " Means "Rename"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1511 :Renu " Means "Renumber"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1512 :Ren " Error - ambiguous
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1513 :command Paste ...
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1514 :P " The built-in :Print
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1515
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1516 It is recommended that full names for user-defined commands are used in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1517 scripts.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1518
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1519 :com[mand] :com :command
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1520 List all user-defined commands. When listing commands,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1521 the characters in the first columns are:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1522 ! Command has the -bang attribute
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1523 " Command has the -register attribute
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1524 \| Command has the -bar attribute
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1525 b Command is local to current buffer
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1526 (see below for details on attributes)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1527 The list can be filtered on command name with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1528 \|:filter\|, e.g., to list all commands with "Pyth" in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1529 the name: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1530 filter Pyth command
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1531
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1532 :com[mand] {cmd} List the user-defined commands that start with {cmd}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1533
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1534 :command-verbose
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1535 When 'verbose' is non-zero, listing a command will also display where it was
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1536 last defined and any completion argument. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1537
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1538 :verbose command TOhtml
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1539 < Name Args Range Complete Definition ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1540 TOhtml 0 % :call Convert2HTML(<line1>, <line2>) ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1541 Last set from /usr/share/vim/vim-7.0/plugin/tohtml.vim ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1542
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1543 See \|:verbose-cmd\| for more information.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1544
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1545 E174 E182
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1546 :com[mand][!] [{attr}...] {cmd} {repl}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1547 Define a user command. The name of the command is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1548 {cmd} and its replacement text is {repl}. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1549 command's attributes (see below) are {attr}. If the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1550 command already exists, an error is reported, unless a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1551 ! is specified, in which case the command is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1552 redefined. There is one exception: When sourcing a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1553 script again, a command that was previously defined in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1554 that script will be silently replaced.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1555
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1556
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1557 :delc[ommand] {cmd} :delc :delcommand E184
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1558 Delete the user-defined command {cmd}.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1559 This is not allowed while listing commands, e.g. from
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1560 a timer. E1311
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1561
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1562 :delc[ommand] -buffer {cmd} E1237
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1563 Delete the user-defined command {cmd} that was defined
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1564 for the current buffer.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1565
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1566 :comc[lear] :comc :comclear
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1567 Delete all user-defined commands.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1568
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1569
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1570 Command attributes ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1571 command-attributes
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1572 User-defined commands are treated by Vim just like any other Ex commands. They
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1573 can have arguments, or have a range specified. Arguments are subject to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1574 completion as filenames, buffers, etc. Exactly how this works depends upon the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1575 command's attributes, which are specified when the command is defined.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1576
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1577 When defining a user command in a script, it will be able to call functions
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1578 local to the script and use mappings local to the script. When the user
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1579 invokes the user command, it will run in the context of the script it was
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1580 defined in. This matters if \|<SID>\| is used in a command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1581
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1582 There are a number of attributes, split into four categories: argument
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1583 handling, completion behavior, range handling, and special cases. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1584 attributes are described below, by category.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1585
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1586
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1587 Argument handling ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1588 E175 E176 :command-nargs
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1589 By default, a user defined command will take no arguments (and an error is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1590 reported if any are supplied). However, it is possible to specify that the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1591 command can take arguments, using the -nargs attribute. Valid cases are:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1592
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1593 -nargs=0 No arguments are allowed (the default)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1594 -nargs=1 Exactly one argument is required, it includes spaces
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1595 -nargs=* Any number of arguments are allowed (0, 1, or many),
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1596 separated by white space
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1597 -nargs=? 0 or 1 arguments are allowed
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1598 -nargs=+ Arguments must be supplied, but any number are allowed
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1599
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1600 Arguments are considered to be separated by (unescaped) spaces or tabs in this
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1601 context, except when there is one argument, then the white space is part of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1602 the argument.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1603
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1604 Note that arguments are used as text, not as expressions. Specifically,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1605 "s:var" will use the script-local variable in the script where the command was
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1606 defined, not where it is invoked! Example:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1607 script1.vim: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1608 :let s:error = "None"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1609 :command -nargs=1 Error echoerr <args>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1610 < script2.vim: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1611 :source script1.vim
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1612 :let s:error = "Wrong!"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1613 :Error s:error
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1614 Executing script2.vim will result in "None" being echoed. Not what you
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1615 intended! Calling a function may be an alternative.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1616
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1617
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1618 Completion behavior ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1619 :command-completion E179 E180 E181
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1620 :command-complete
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1621 By default, the arguments of user defined commands do not undergo completion.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1622 However, by specifying one or the other of the following attributes, argument
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1623 completion can be enabled:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1624
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1625 -complete=arglist file names in argument list
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1626 -complete=augroup autocmd groups
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1627 -complete=buffer buffer names
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1628 -complete=behave :behave suboptions
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1629 -complete=color color schemes
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1630 -complete=command Ex command (and arguments)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1631 -complete=compiler compilers
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1632 -complete=cscope \|:cscope\| suboptions
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1633 -complete=dir directory names
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1634 -complete=environment environment variable names
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1635 -complete=event autocommand events
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1636 -complete=expression Vim expression
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1637 -complete=file file and directory names
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1638 -complete=file_in_path file and directory names in \|'path'\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1639 -complete=filetype filetype names \|'filetype'\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1640 -complete=function function name
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1641 -complete=help help subjects
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1642 -complete=highlight highlight groups
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1643 -complete=history :history suboptions
34082 a197265a2e07 patch 9.1.0010: Keymap completion is not available Christian Brabandt <cb@256bit.org> parents: 34057 diff changeset	1644 -complete=keymap keyboard mappings
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1645 -complete=locale locale names (as output of locale -a)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1646 -complete=mapclear buffer argument
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1647 -complete=mapping mapping name
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1648 -complete=menu menus
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1649 -complete=messages \|:messages\| suboptions
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1650 -complete=option options
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1651 -complete=packadd optional package \|pack-add\| names
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1652 -complete=shellcmd Shell command
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1653 -complete=sign \|:sign\| suboptions
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1654 -complete=syntax syntax file names \|'syntax'\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1655 -complete=syntime \|:syntime\| suboptions
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1656 -complete=tag tags
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1657 -complete=tag_listfiles tags, file names are shown when CTRL-D is hit
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1658 -complete=user user names
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1659 -complete=var user variables
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1660 -complete=custom,{func} custom completion, defined via {func}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1661 -complete=customlist,{func} custom completion, defined via {func}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1662
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1663 If you specify completion while there is nothing to complete (-nargs=0, the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1664 default) then you get error E1208 .
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1665 Note: That some completion methods might expand environment variables.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1666
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1667
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1668 Custom completion ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1669 :command-completion-custom
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1670 :command-completion-customlist E467 E468
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1671 It is possible to define customized completion schemes via the "custom,{func}"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1672 or the "customlist,{func}" completion argument. The {func} part should be a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1673 function with the following signature: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1674
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1675 :function {func}(ArgLead, CmdLine, CursorPos)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1676
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1677 The function need not use all these arguments. The function should provide the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1678 completion candidates as the return value.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1679
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1680 For the "custom" argument, the function should return the completion
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1681 candidates one per line in a newline separated string.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1682 E1303
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1683 For the "customlist" argument, the function should return the completion
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1684 candidates as a Vim List. Non-string items in the list are ignored.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1685
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1686 The function arguments are:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1687 ArgLead the leading portion of the argument currently being
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1688 completed on
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1689 CmdLine the entire command line
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1690 CursorPos the cursor position in it (byte index)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1691 The function may use these for determining context. For the "custom"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1692 argument, it is not necessary to filter candidates against the (implicit
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1693 pattern in) ArgLead. Vim will filter the candidates with its regexp engine
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1694 after function return, and this is probably more efficient in most cases. If
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1695 'wildoptions' contains "fuzzy", then the candidates will be filtered using
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1696 \|fuzzy-matching\|. For the "customlist" argument, Vim will not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1697 filter the returned completion candidates and the user supplied function
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1698 should filter the candidates.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1699
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1700 The following example lists user names to a Finger command >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1701 :com -complete=custom,ListUsers -nargs=1 Finger !finger <args>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1702 :fun ListUsers(A,L,P)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1703 : return system("cut -d: -f1 /etc/passwd")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1704 :endfun
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1705
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1706 The following example completes filenames from the directories specified in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1707 the 'path' option: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1708 :com -nargs=1 -bang -complete=customlist,EditFileComplete
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1709 \ EditFile edit<bang> <args>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1710 :fun EditFileComplete(A,L,P)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1711 : return split(globpath(&path, a:A), "\n")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1712 :endfun
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1713 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1714 This example does not work for file names with spaces!
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1715
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1716
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1717 Range handling ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1718 E177 E178 :command-range :command-count
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1719 By default, user-defined commands do not accept a line number range. However,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1720 it is possible to specify that the command does take a range (the -range
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1721 attribute), or that it takes an arbitrary count value, either in the line
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1722 number position (-range=N, like the \|:split\| command) or as a "count"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1723 argument (-count=N, like the \|:Next\| command). The count will then be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1724 available in the argument with \|<count>\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1725
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1726 Possible attributes are:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1727
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1728 -range Range allowed, default is current line
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1729 -range=% Range allowed, default is whole file (1,$)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1730 -range=N A count (default N) which is specified in the line
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1731 number position (like \|:split\|); allows for zero line
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1732 number.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1733 -count=N A count (default N) which is specified either in the line
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1734 number position, or as an initial argument (like \|:Next\|).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1735 -count Acts like -count=0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1736
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1737 Note that -range=N and -count=N are mutually exclusive - only one should be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1738 specified.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1739
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1740 :command-addr
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1741 It is possible that the special characters in the range like ., $ or % which
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1742 by default correspond to the current line, last line and the whole buffer,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1743 relate to arguments, (loaded) buffers, windows or tab pages.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1744
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1745 Possible values are (second column is the short name used in listing):
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1746 -addr=lines Range of lines (this is the default for -range)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1747 -addr=arguments arg Range for arguments
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1748 -addr=buffers buf Range for buffers (also not loaded buffers)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1749 -addr=loaded_buffers load Range for loaded buffers
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1750 -addr=windows win Range for windows
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1751 -addr=tabs tab Range for tab pages
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1752 -addr=quickfix qf Range for quickfix entries
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1753 -addr=other ? Other kind of range; can use ".", "$" and "%"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1754 as with "lines" (this is the default for
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1755 -count)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1756
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1757
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1758 Special cases ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1759 :command-bang :command-bar
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1760 :command-register :command-buffer
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1761 :command-keepscript
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1762 There are some special cases as well:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1763
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1764 -bang The command can take a ! modifier (like :q or :w)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1765 -bar The command can be followed by a "\|" and another command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1766 A "\|" inside the command argument is not allowed then.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1767 Also checks for a " to start a comment.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1768 -register The first argument to the command can be an optional
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1769 register name (like :del, :put, :yank).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1770 -buffer The command will only be available in the current buffer.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1771 -keepscript Do not use the location of where the user command was
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1772 defined for verbose messages, use the location of where
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1773 the user command was invoked.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1774
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1775 In the cases of the -count and -register attributes, if the optional argument
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1776 is supplied, it is removed from the argument list and is available to the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1777 replacement text separately.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1778 Note that these arguments can be abbreviated, but that is a deprecated
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1779 feature. Use the full name for new scripts.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1780
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1781
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1782 Replacement text ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1783 :command-repl
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1784 The {repl} argument is normally one long string, possibly with "\|" separated
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1785 commands. A special case is when the argument is "{", then the following
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1786 lines, up to a line starting with "}" are used and \|Vim9\| syntax applies.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1787 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1788 :command MyCommand {
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1789 echo 'hello'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1790 g:calledMyCommand = true
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1791 }
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1792 < E1231
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1793 There must be white space before the "{". No nesting is supported, inline
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1794 functions cannot be used. Commands where a "\|" may appear in the argument,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1795 such as commands with an expression argument, cannot be followed by a "\|" and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1796 another command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1797
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1798 If the command is defined in Vim9 script (a script that starts with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1799 `:vim9script` and in a `:def` function) then {repl} will be executed as in Vim9
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1800 script. Thus this depends on where the command is defined, not where it is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1801 used.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1802
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1803 The replacement text {repl} for a user defined command is scanned for special
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1804 escape sequences, using <...> notation. Escape sequences are replaced with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1805 values from the entered command line, and all other text is copied unchanged.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1806 The resulting string is executed as an Ex command. To avoid the replacement
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1807 use <lt> in place of the initial <. Thus to include "<bang>" literally use
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1808 "<lt>bang>".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1809
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1810 The valid escape sequences are
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1811
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1812 <line1>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1813 <line1> The starting line of the command range.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1814 <line2>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1815 <line2> The final line of the command range.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1816 <range>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1817 <range> The number of items in the command range: 0, 1 or 2
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1818 <count>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1819 <count> Any count supplied (as described for the '-range'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1820 and '-count' attributes).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1821 <bang>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1822 <bang> (See the '-bang' attribute) Expands to a ! if the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1823 command was executed with a ! modifier, otherwise
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1824 expands to nothing.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1825 <mods> <q-mods> :command-modifiers
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1826 <mods> The command modifiers, if specified. Otherwise, expands to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1827 nothing. Supported modifiers are \|:aboveleft\|, \|:belowright\|,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1828 \|:botright\|, \|:browse\|, \|:confirm\|, \|:hide\|, \|:horizontal\|,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1829 \|:keepalt\|, \|:keepjumps\|, \|:keepmarks\|, \|:keeppatterns\|,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1830 \|:leftabove\|, \|:lockmarks\|, \|:noautocmd\|, \|:noswapfile\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1831 \|:rightbelow\|, \|:sandbox\|, \|:silent\|, \|:tab\|, \|:topleft\|,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1832 \|:unsilent\|, \|:verbose\|, and \|:vertical\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1833 Note that \|:filter\| is not supported.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1834 Examples: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1835 command! -nargs=+ -complete=file MyEdit
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1836 \ for f in expand(<q-args>, 0, 1) \|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1837 \ exe '<mods> split ' .. f \|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1838 \ endfor
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1839
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1840 function! SpecialEdit(files, mods)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1841 for f in expand(a:files, 0, 1)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1842 exe a:mods .. ' split ' .. f
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1843 endfor
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1844 endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1845 command! -nargs=+ -complete=file Sedit
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1846 \ call SpecialEdit(<q-args>, <q-mods>)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1847 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1848 <reg> <register>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1849 <reg> (See the '-register' attribute) The optional register,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1850 if specified. Otherwise, expands to nothing. <register>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1851 is a synonym for this.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1852 <args>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1853 <args> The command arguments, exactly as supplied (but as
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1854 noted above, any count or register can consume some
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1855 of the arguments, which are then not part of <args>).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1856 <lt> A single '<' (Less-Than) character. This is needed if you
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1857 want to get a literal copy of one of these escape sequences
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1858 into the expansion - for example, to get <bang>, use
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1859 <lt>bang>.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1860
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1861 <q-args>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1862 If the first two characters of an escape sequence are "q-" (for example,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1863 <q-args>) then the value is quoted in such a way as to make it a valid value
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1864 for use in an expression. This uses the argument as one single value.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1865 When there is no argument <q-args> is an empty string. See the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1866 \|q-args-example\| below.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1867 <f-args>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1868 To allow commands to pass their arguments on to a user-defined function, there
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1869 is a special form <f-args> ("function args"). This splits the command
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1870 arguments at spaces and tabs, quotes each argument individually, and the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1871 <f-args> sequence is replaced by the comma-separated list of quoted arguments.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1872 See the Mycmd example below. If no arguments are given <f-args> is removed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1873 To embed whitespace into an argument of <f-args>, prepend a backslash.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1874 <f-args> replaces every pair of backslashes (\\) with one backslash. A
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1875 backslash followed by a character other than white space or a backslash
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1876 remains unmodified. Also see \|f-args-example\| below. Overview:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1877
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1878 command <f-args> ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1879 XX ab 'ab'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1880 XX a\b 'a\b'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1881 XX a\ b 'a b'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1882 XX a\ b 'a ', 'b'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1883 XX a\\b 'a\b'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1884 XX a\\ b 'a\', 'b'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1885 XX a\\\b 'a\\b'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1886 XX a\\\ b 'a\ b'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1887 XX a\\\\b 'a\\b'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1888 XX a\\\\ b 'a\\', 'b'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1889 XX [nothing]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1890
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1891
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1892 Note that if the "no arguments" situation is to be handled, you have to make
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1893 sure that the function can be called without arguments. For a compiled
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1894 function you might want to use variable arguments, see
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1895 \|vim9-variable-arguments\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1896
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1897 Examples for user commands: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1898
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1899 " Delete everything after here to the end
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1900 :com Ddel +,$d
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1901
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1902 " Rename the current buffer
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1903 :com -nargs=1 -bang -complete=file Ren f <args>\|w<bang>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1904
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1905 " Replace a range with the contents of a file
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1906 " (Enter this all as one line)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1907 :com -range -nargs=1 -complete=file
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1908 Replace <line1>-pu_\|<line1>,<line2>d\|r <args>\|<line1>d
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1909
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1910 " Count the number of lines in the range
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1911 :com! -range -nargs=0 Lines echo <line2> - <line1> + 1 "lines"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1912
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1913 < f-args-example
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1914 Call a user function (example of <f-args>) >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1915 :com -nargs=* Mycmd call Myfunc(<f-args>)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1916
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1917 When executed as: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1918 :Mycmd arg1 arg2
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1919 This will invoke: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1920 :call Myfunc("arg1","arg2")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1921
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1922 < q-args-example
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1923 A more substantial example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1924 :function Allargs(command)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1925 : let i = 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1926 : while i < argc()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1927 : if filereadable(argv(i))
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1928 : execute "e " .. argv(i)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1929 : execute a:command
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1930 : endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1931 : let i = i + 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1932 : endwhile
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1933 :endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1934 :command -nargs=+ -complete=command Allargs call Allargs(<q-args>)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1935
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1936 The command Allargs takes any Vim command(s) as argument and executes it on all
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1937 files in the argument list. Usage example (note use of the "e" flag to ignore
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1938 errors and the "update" command to write modified buffers): >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1939 :Allargs %s/foo/bar/ge\|update
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1940 This will invoke: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1941 :call Allargs("%s/foo/bar/ge\|update")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1942 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1943
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1944 vim:tw=78:ts=8:noet:ft=help:norl:

Mercurial > vim

annotate runtime/doc/map.txt @ 34219:a0a4a774117b v9.1.0058