vim-patch:8.2.4861: it is not easy to restore saved mappings

Problem:    It is not easy to restore saved mappings.
Solution:   Make mapset() accept a dict argument. (Ernie Rael, closes vim/vim#10295)

https://github.com/vim/vim/commit/51d04d16f21e19d6eded98f9530d84089102f925

Co-authored-by: Ernie Rael <errael@raelity.com>

4 files changed, 60 insertions, 19 deletions

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 5d21b405df..1eb173af58 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -4185,6 +4185,7 @@ maparg({name} [, {mode} [, {abbr} [, {dict}]]])                       *maparg()*
 		  "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|.
 
 		The dictionary can be used to restore a mapping with
 		|mapset()|.
@@ -4246,9 +4247,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
@@ -4257,8 +4266,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/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index 3293b71977..dea2e476b6 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -5046,6 +5046,7 @@ function vim.fn.map(expr1, expr2) end
 ---   "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|.
 ---
 --- The dictionary can be used to restore a mapping with
 --- |mapset()|.
@@ -5124,9 +5125,17 @@ function vim.fn.maplist() 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
@@ -5135,12 +5144,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