patch 8.2.4932: not easy to filter the output of maplist()v8.2.4932

Problem:    Not easy to filter the output of maplist().
Solution:   Add mode_bits to the dictionary. (Ernie Rael, closes #10356)

1 files changed, 26 insertions, 0 deletions

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index f6da0cfd8..60fe91f1d 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -5331,6 +5331,10 @@ maparg({name} [, {mode} [, {abbr} [, {dict}]]])			*maparg()*
 		  "nowait"   Do not wait for other, longer mappings.
 			     (|:map-<nowait>|).
 		  "abbr"     True if this is an abbreviation |abbreviations|.
+		  "mode_bits" Vim's internal binary representation of "mode".
+			     |mapset()| ignores this; only "mode" is used.
+			     See |maplist()| for usage examples. The values
+			     are from src/vim.h and may change in the future.
 
 		The dictionary can be used to restore a mapping with
 		|mapset()|.
@@ -5391,6 +5395,28 @@ maplist([{abbr}])					*maplist()*
 			vim9script
 			echo maplist()->filter(
 				(_, m) => match(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: >
+			vim9script
+			var saved_maps = []
+			for m in maplist()
+			    if and(m.mode_bits, 0x19) != 0
+				saved_maps->add(m)
+			    endif
+			endfor
+			echo saved_maps->mapnew((_, m) => m.lhs)
+<		The values of the mode_bits are defined in Vim's src/vim.h
+		file and they can be discovered at runtime using
+		|:map-commands| and "maplist()". Example: >
+			vim9script
+			omap xyzzy <Nop>
+			var 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()*