patch 8.2.4861: it is not easy to restore saved mappingsv8.2.4861

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

1 files changed, 29 insertions, 5 deletions

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index beeb736491..12fb509a78 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -5310,6 +5310,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()|.
@@ -5380,9 +5381,18 @@ mapnew({expr1}, {expr2})					*mapnew()*
 
 
 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*
+mapset({dict})
+		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 insure 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: >
@@ -5391,8 +5401,22 @@ 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: >
+			vim9script
+			var save_maps = maplist()->filter(
+						(_, m) => m.lhs == 'K')
+			nnoremap K somethingelse
+			cnoremap K somethingelse2
+			# ...
+			unmap K
+			for d in save_maps
+			    mapset(d)
+			endfor
 
 
 match({expr}, {pat} [, {start} [, {count}]])			*match()*