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, 32 insertions, 0 deletions

diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index 300210b296..70d1aa4a79 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -5713,6 +5713,7 @@ function vim.fn.mkdir(name, flags, prot) end
 --- 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
@@ -8744,6 +8745,37 @@ function vim.fn.sqrt(expr) end
 --- @return any
 function vim.fn.srand(expr) end
 
+--- 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
+---
+--- @param what? string
+--- @return any
+function vim.fn.state(what) end
+
 --- With |--headless| this opens stdin and stdout as a |channel|.
 --- May be called only once. See |channel-stdio|. stderr is not
 --- handled by this function, see |v:stderr|.