Merge pull request #25951 from zeertzjq/vim-8.2.4140

vim-patch:8.2.{4140,4820,4825,4861,4932}

5 files changed, 143 insertions, 23 deletions

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 35c94d6c74..bc4d1f30c9 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -4133,7 +4133,8 @@ maparg({name} [, {mode} [, {abbr} [, {dict}]]])                       *maparg()*
 		When {dict} is omitted or zero: Return the rhs of mapping
 		{name} in mode {mode}.  The returned String has special
 		characters translated like in the output of the ":map" command
-		listing.
+		listing. When {dict} is TRUE a dictionary is returned, see
+		below. To get a list of all mappings see |maplist()|.
 
 		When there is no mapping for {name}, an empty String is
 		returned if {dict} is FALSE, otherwise returns an empty Dict.
@@ -4161,7 +4162,7 @@ maparg({name} [, {mode} [, {abbr} [, {dict}]]])                       *maparg()*
 
 		When {dict} is there and it is |TRUE| return a dictionary
 		containing all the information of the mapping with the
-		following items:
+		following items:			*mapping-dict*
 		  "lhs"	     The {lhs} of the mapping as it would be typed
 		  "lhsraw"   The {lhs} of the mapping as raw bytes
 		  "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate
@@ -4180,9 +4181,16 @@ maparg({name} [, {mode} [, {abbr} [, {dict}]]])                       *maparg()*
 				     (|mapmode-ic|)
 		  "sid"	     The script local ID, used for <sid> mappings
 			     (|<SID>|).  Negative for special contexts.
+		  "scriptversion"  The version of the script, always 1.
 		  "lnum"     The line number in "sid", zero if unknown.
 		  "nowait"   Do not wait for other, longer mappings.
 			     (|:map-<nowait>|).
+		  "abbr"     True if this is an |abbreviation|.
+		  "mode_bits" Nvim's internal binary representation of "mode".
+			     |mapset()| ignores this; only "mode" is used.
+			     See |maplist()| for usage examples. The values
+			     are from src/nvim/vim.h and may change in the
+			     future.
 
 		The dictionary can be used to restore a mapping with
 		|mapset()|.
@@ -4226,6 +4234,37 @@ mapcheck({name} [, {mode} [, {abbr}]])                              *mapcheck()*
 <		This avoids adding the "_vv" mapping when there already is a
 		mapping for "_v" or for "_vvv".
 
+maplist([{abbr}])                                                    *maplist()*
+		Returns a |List| of all mappings.  Each List item is a |Dict|,
+		the same as what is returned by |maparg()|, see
+		|mapping-dict|.  When {abbr} is there and it is |TRUE| use
+		abbreviations instead of mappings.
+
+		Example to show all mappings with "MultiMatch" in rhs: >vim
+			echo maplist()->filter({_, m ->
+				\ match(get(m, 'rhs', ''), 'MultiMatch') >= 0
+				\ })
+<		It can be tricky to find mappings for particular |:map-modes|.
+		|mapping-dict|'s "mode_bits" can simplify this. For example,
+		the mode_bits for Normal, Insert or Command-line modes are
+		0x19. To find all the mappings available in those modes you
+		can do: >vim
+			let saved_maps = []
+			for m in maplist()
+			    if and(m.mode_bits, 0x19) != 0
+				eval saved_maps->add(m)
+			    endif
+			endfor
+			echo saved_maps->mapnew({_, m -> m.lhs})
+<		The values of the mode_bits are defined in Nvim's
+		src/nvim/vim.h file and they can be discovered at runtime
+		using |:map-commands| and "maplist()". Example: >vim
+			omap xyzzy <Nop>
+			let op_bit = maplist()->filter(
+			    \ {_, m -> m.lhs == 'xyzzy'})[0].mode_bits
+			ounmap xyzzy
+			echo printf("Operator-pending mode bit: 0x%x", op_bit)
+
 mapnew({expr1}, {expr2})                                              *mapnew()*
 		Like |map()| but instead of replacing items in {expr1} a new
 		List or Dictionary is created and returned.  {expr1} remains
@@ -4233,9 +4272,17 @@ mapnew({expr1}, {expr2})                                              *mapnew()*
 		don't want that use |deepcopy()| first.
 
 mapset({mode}, {abbr}, {dict})                                        *mapset()*
-		Restore a mapping from a dictionary returned by |maparg()|.
-		{mode} and {abbr} should be the same as for the call to
-		|maparg()|. *E460*
+		Restore a mapping from a dictionary, possibly returned by
+		|maparg()| or |maplist()|.  A buffer mapping, when dict.buffer
+		is true, is set on the current buffer; it is up to the caller
+		to ensure that the intended buffer is the current buffer. This
+		feature allows copying mappings from one buffer to another.
+		The dict.mode value may restore a single mapping that covers
+		more than one mode, like with mode values of '!', ' ', "nox",
+		or 'v'. *E1276*
+
+		In the first form, {mode} and {abbr} should be the same as
+		for the call to |maparg()|. *E460*
 		{mode} is used to define the mode in which the mapping is set,
 		not the "mode" entry in {dict}.
 		Example for saving and restoring a mapping: >vim
@@ -4244,8 +4291,21 @@ mapset({mode}, {abbr}, {dict})                                        *mapset()*
 			" ...
 			call mapset('n', 0, save_map)
 <		Note that if you are going to replace a map in several modes,
-		e.g. with `:map!`, you need to save the mapping for all of
-		them, since they can differ.
+		e.g. with `:map!`, you need to save/restore the mapping for
+		all of them, when they might differ.
+
+		In the second form, with {dict} as the only argument, mode
+		and abbr are taken from the dict.
+		Example: >vim
+			let save_maps = maplist()->filter(
+						\ {_, m -> m.lhs == 'K'})
+			nnoremap K somethingelse
+			cnoremap K somethingelse2
+			" ...
+			unmap K
+			for d in save_maps
+			    call mapset(d)
+			endfor
 
 match({expr}, {pat} [, {start} [, {count}]])                           *match()*
 		When {expr} is a |List| then this returns the index of the
diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt
index 56e58baad8..6f61259af0 100644
--- a/runtime/doc/map.txt
+++ b/runtime/doc/map.txt
@@ -955,7 +955,7 @@ operator to add quotes around text in the current line: >
 				\ ->setline(".")}'<CR>g@
 
 ==============================================================================
-2. Abbreviations			*abbreviations* *Abbreviations*
+2. Abbreviations		*abbreviation* *abbreviations* *Abbreviations*
 
 Abbreviations are used in Insert mode, Replace mode and Command-line mode.
 If you enter a word that is an abbreviation, it is replaced with the word it
diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt
index c8b31b2d5b..e206a804f4 100644
--- a/runtime/doc/usr_41.txt
+++ b/runtime/doc/usr_41.txt
@@ -1015,6 +1015,7 @@ Mappings and Menus:			    *mapping-functions*
 	hasmapto()		check if a mapping exists
 	mapcheck()		check if a matching mapping exists
 	maparg()		get rhs of a mapping
+	maplist()		get list of all mappings
 	mapset()		restore a mapping
 	menu_info()		get information about a menu item
 	wildmenumode()		check if the wildmode is active
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index 0563f9dd5f..d1e676ef70 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -4994,7 +4994,8 @@ function vim.fn.map(expr1, expr2) end
 --- When {dict} is omitted or zero: Return the rhs of mapping
 --- {name} in mode {mode}.  The returned String has special
 --- characters translated like in the output of the ":map" command
---- listing.
+--- listing. When {dict} is TRUE a dictionary is returned, see
+--- below. To get a list of all mappings see |maplist()|.
 ---
 --- When there is no mapping for {name}, an empty String is
 --- returned if {dict} is FALSE, otherwise returns an empty Dict.
@@ -5022,7 +5023,7 @@ function vim.fn.map(expr1, expr2) end
 ---
 --- When {dict} is there and it is |TRUE| return a dictionary
 --- containing all the information of the mapping with the
---- following items:
+--- following items:      *mapping-dict*
 ---   "lhs"       The {lhs} of the mapping as it would be typed
 ---   "lhsraw"   The {lhs} of the mapping as raw bytes
 ---   "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate
@@ -5041,9 +5042,16 @@ function vim.fn.map(expr1, expr2) end
 ---          (|mapmode-ic|)
 ---   "sid"       The script local ID, used for <sid> mappings
 ---        (|<SID>|).  Negative for special contexts.
+---   "scriptversion"  The version of the script, always 1.
 ---   "lnum"     The line number in "sid", zero if unknown.
 ---   "nowait"   Do not wait for other, longer mappings.
 ---        (|:map-<nowait>|).
+---   "abbr"     True if this is an |abbreviation|.
+---   "mode_bits" Nvim's internal binary representation of "mode".
+---        |mapset()| ignores this; only "mode" is used.
+---        See |maplist()| for usage examples. The values
+---        are from src/nvim/vim.h and may change in the
+---        future.
 ---
 --- The dictionary can be used to restore a mapping with
 --- |mapset()|.
@@ -5099,6 +5107,39 @@ function vim.fn.maparg(name, mode, abbr, dict) end
 --- @return any
 function vim.fn.mapcheck(name, mode, abbr) end
 
+--- Returns a |List| of all mappings.  Each List item is a |Dict|,
+--- the same as what is returned by |maparg()|, see
+--- |mapping-dict|.  When {abbr} is there and it is |TRUE| use
+--- abbreviations instead of mappings.
+---
+--- Example to show all mappings with "MultiMatch" in rhs: >vim
+---   echo maplist()->filter({_, m ->
+---     \ match(get(m, 'rhs', ''), 'MultiMatch') >= 0
+---     \ })
+--- <It can be tricky to find mappings for particular |:map-modes|.
+--- |mapping-dict|'s "mode_bits" can simplify this. For example,
+--- the mode_bits for Normal, Insert or Command-line modes are
+--- 0x19. To find all the mappings available in those modes you
+--- can do: >vim
+---   let saved_maps = []
+---   for m in maplist()
+---       if and(m.mode_bits, 0x19) != 0
+---     eval saved_maps->add(m)
+---       endif
+---   endfor
+---   echo saved_maps->mapnew({_, m -> m.lhs})
+--- <The values of the mode_bits are defined in Nvim's
+--- src/nvim/vim.h file and they can be discovered at runtime
+--- using |:map-commands| and "maplist()". Example: >vim
+---   omap xyzzy <Nop>
+---   let op_bit = maplist()->filter(
+---       \ {_, m -> m.lhs == 'xyzzy'})[0].mode_bits
+---   ounmap xyzzy
+---   echo printf("Operator-pending mode bit: 0x%x", op_bit)
+---
+--- @return any
+function vim.fn.maplist() end
+
 --- Like |map()| but instead of replacing items in {expr1} a new
 --- List or Dictionary is created and returned.  {expr1} remains
 --- unchanged.  Items can still be changed by {expr2}, if you
@@ -5109,9 +5150,17 @@ function vim.fn.mapcheck(name, mode, abbr) end
 --- @return any
 function vim.fn.mapnew(expr1, expr2) end
 
---- Restore a mapping from a dictionary returned by |maparg()|.
---- {mode} and {abbr} should be the same as for the call to
---- |maparg()|. *E460*
+--- Restore a mapping from a dictionary, possibly returned by
+--- |maparg()| or |maplist()|.  A buffer mapping, when dict.buffer
+--- is true, is set on the current buffer; it is up to the caller
+--- to ensure that the intended buffer is the current buffer. This
+--- feature allows copying mappings from one buffer to another.
+--- The dict.mode value may restore a single mapping that covers
+--- more than one mode, like with mode values of '!', ' ', "nox",
+--- or 'v'. *E1276*
+---
+--- In the first form, {mode} and {abbr} should be the same as
+--- for the call to |maparg()|. *E460*
 --- {mode} is used to define the mode in which the mapping is set,
 --- not the "mode" entry in {dict}.
 --- Example for saving and restoring a mapping: >vim
@@ -5120,12 +5169,25 @@ function vim.fn.mapnew(expr1, expr2) end
 ---   " ...
 ---   call mapset('n', 0, save_map)
 --- <Note that if you are going to replace a map in several modes,
---- e.g. with `:map!`, you need to save the mapping for all of
---- them, since they can differ.
+--- e.g. with `:map!`, you need to save/restore the mapping for
+--- all of them, when they might differ.
+---
+--- In the second form, with {dict} as the only argument, mode
+--- and abbr are taken from the dict.
+--- Example: >vim
+---   let save_maps = maplist()->filter(
+---         \ {_, m -> m.lhs == 'K'})
+---   nnoremap K somethingelse
+---   cnoremap K somethingelse2
+---   " ...
+---   unmap K
+---   for d in save_maps
+---       call mapset(d)
+---   endfor
 ---
 --- @param mode string
---- @param abbr any
---- @param dict any
+--- @param abbr? any
+--- @param dict? any
 --- @return any
 function vim.fn.mapset(mode, abbr, dict) end
 
diff --git a/runtime/pack/dist/opt/termdebug/plugin/termdebug.vim b/runtime/pack/dist/opt/termdebug/plugin/termdebug.vim
index 73fbc8c922..8beca8ffb3 100644
--- a/runtime/pack/dist/opt/termdebug/plugin/termdebug.vim
+++ b/runtime/pack/dist/opt/termdebug/plugin/termdebug.vim
@@ -1116,8 +1116,7 @@ func s:DeleteCommands()
   if exists('s:k_map_saved')
     if !empty(s:k_map_saved) && !s:k_map_saved.buffer
       nunmap K
-      " call mapset(s:k_map_saved)
-      call mapset('n', 0, s:k_map_saved)
+      call mapset(s:k_map_saved)
     elseif empty(s:k_map_saved)
       nunmap K
     endif
@@ -1126,8 +1125,7 @@ func s:DeleteCommands()
   if exists('s:plus_map_saved')
     if !empty(s:plus_map_saved) && !s:plus_map_saved.buffer
       nunmap +
-      " call mapset(s:plus_map_saved)
-      call mapset('n', 0, s:plus_map_saved)
+      call mapset(s:plus_map_saved)
     elseif empty(s:plus_map_saved)
       nunmap +
     endif
@@ -1136,8 +1134,7 @@ func s:DeleteCommands()
   if exists('s:minus_map_saved')
     if !empty(s:minus_map_saved) && !s:minus_map_saved.buffer
       nunmap -
-      " call mapset(s:minus_map_saved)
-      call mapset('n', 0, s:minus_map_saved)
+      call mapset(s:minus_map_saved)
     elseif empty(s:minus_map_saved)
       nunmap -
     endif