Merge pull request #25951 from zeertzjq/vim-8.2.4140

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

3 files changed, 69 insertions, 8 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