Merge pull request #24816 from zeertzjq/vim-8.1.2044

vim-patch:8.1.{2044,2046,2047,2048,2053,2066,2067,2068,2069,2099},8.2.4299: SafeState, state()

1 files changed, 29 insertions, 0 deletions

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 92cedbdc80..2ce66d8cc2 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -4753,6 +4753,7 @@ mode([expr])                                                            *mode()*
 		If [expr] is supplied and it evaluates to a non-zero Number or
 		a non-empty String (|non-zero-arg|), then the full mode is
 		returned, otherwise only the first letter is returned.
+		Also see |state()|.
 
 		   n	    Normal
 		   no	    Operator-pending
@@ -7368,6 +7369,34 @@ srand([{expr}])                                                        *srand()*
 			echo rand(seed)
 <
 
+state([{what}])                                                        *state()*
+		Return a string which contains characters indicating the
+		current state.  Mostly useful in callbacks that want to do
+		work that may not always be safe.  Roughly this works like:
+		- callback uses state() to check if work is safe to do.
+		  If yes, then do it right away.
+		  Otherwise add to work queue and add SafeState autocommand.
+		- When SafeState is triggered, check with state() if the work
+		  can be done now, and if yes remove it from the queue and
+		  execute.
+		Also see |mode()|.
+
+		When {what} is given only characters in this string will be
+		added.  E.g, this checks if the screen has scrolled: >vim
+			if state('s') != ''
+
+		These characters indicate the state, generally indicating that
+		something is busy:
+		    m  halfway a mapping, :normal command, feedkeys() or
+		       stuffed command
+		    o  operator pending or waiting for a command argument
+		    a  Insert mode autocomplete active
+		    x  executing an autocommand
+		    S  not triggering SafeState
+		    c  callback invoked, including timer (repeats for
+		       recursiveness up to "ccc")
+		    s  screen has scrolled for messages
+
 stdioopen({opts})                                                  *stdioopen()*
 		With |--headless| this opens stdin and stdout as a |channel|.
 		May be called only once. See |channel-stdio|. stderr is not