vim-patch:9.1.0984: exception handling can be improved

Problem:  exception handling can be improved
Solution: add v:stacktrace and getstacktrace()

closes: vim/vim#16360

https://github.com/vim/vim/commit/663d18d6102f40d14e36096ec590445e61026ed6

Co-authored-by: ichizok <gclient.gaap@gmail.com>
Co-authored-by: Naruhiko Nishino <naru123456789@gmail.com>

6 files changed, 55 insertions, 7 deletions

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index f321c880a4..70c7a7b802 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -4182,6 +4182,21 @@ getscriptinfo([{opts}])                                        *getscriptinfo()*
                 Return: ~
                   (`vim.fn.getscriptinfo.ret[]`)
 
+getstacktrace()                                                *getstacktrace()*
+		Returns the current stack trace of Vim scripts.
+		Stack trace is a |List|, of which each item is a |Dictionary|
+		with the following items:
+		    funcref	The funcref if the stack is at the function,
+				otherwise this item is not exist.
+		    event	The string of the event description if the
+				stack is at autocmd event, otherwise this item
+				is not exist.
+		    lnum	The line number of the script on the stack.
+		    filepath	The file path of the script on the stack.
+
+                Return: ~
+                  (`table[]`)
+
 gettabinfo([{tabnr}])                                             *gettabinfo()*
 		If {tabnr} is not specified, then information about all the
 		tab pages is returned as a |List|. Each List item is a
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index e0c45503cc..60238bc90d 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -2848,7 +2848,8 @@ in the variable |v:exception|: >
 	:    echo "Number thrown.  Value is" v:exception
 
 You may also be interested where an exception was thrown.  This is stored in
-|v:throwpoint|.  Note that "v:exception" and "v:throwpoint" are valid for the
+|v:throwpoint|.  And you can obtain the stack trace from |v:stacktrace|.
+Note that "v:exception", "v:stacktrace" and "v:throwpoint" are valid for the
 exception most recently caught as long it is not finished.
    Example: >
 
diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt
index 3202a70b76..f958491ccf 100644
--- a/runtime/doc/usr_41.txt
+++ b/runtime/doc/usr_41.txt
@@ -1103,7 +1103,8 @@ Various:					*various-functions*
 	did_filetype()		check if a FileType autocommand was used
 	eventhandler()		check if invoked by an event handler
 	getpid()		get process ID of Vim
-	getscriptinfo()		get list of sourced vim scripts
+	getscriptinfo()		get list of sourced Vim scripts
+	getstacktrace()		get current stack trace of Vim scripts
 
 	libcall()		call a function in an external library
 	libcallnr()		idem, returning a number
diff --git a/runtime/doc/vvars.txt b/runtime/doc/vvars.txt
index 32f3b96269..0ebb54e38a 100644
--- a/runtime/doc/vvars.txt
+++ b/runtime/doc/vvars.txt
@@ -6,7 +6,8 @@
 
 Predefined variables                                             *vvars*
 
-Some variables can be set by the user, but the type cannot be changed.
+Most variables are read-only, when a variable can be set by the user, it will
+be mentioned at the variable description below. The type cannot be changed.
 
                                        Type |gO| to see the table of contents.
 
@@ -195,7 +196,8 @@ v:event
 				*v:exception* *exception-variable*
 v:exception
 		The value of the exception most recently caught and not
-		finished.  See also |v:throwpoint| and |throw-variables|.
+		finished.  See also |v:stacktrace|, |v:throwpoint|, and
+		|throw-variables|.
 		Example: >vim
 		  try
 		    throw "oops"
@@ -586,6 +588,13 @@ v:shell_error
 		  endif
 <
 
+				*v:stacktrace* *stacktrace-variable*
+v:stacktrace
+		The stack trace of the exception most recently caught and
+		not finished.  Refer to |getstacktrace()| for the structure of
+		stack trace.  See also |v:exception|, |v:throwpoint|, and
+		|throw-variables|.
+
 				*v:statusmsg* *statusmsg-variable*
 v:statusmsg
 		Last given status message.
@@ -679,7 +688,7 @@ v:this_session
 v:throwpoint
 		The point where the exception most recently caught and not
 		finished was thrown.  Not set when commands are typed.  See
-		also |v:exception| and |throw-variables|.
+		also |v:exception|, |v:stacktrace|, and |throw-variables|.
 		Example: >vim
 		  try
 		    throw "oops"
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index 6662fca84f..3de8b9951c 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -3770,6 +3770,20 @@ function vim.fn.getregtype(regname) end
 --- @return vim.fn.getscriptinfo.ret[]
 function vim.fn.getscriptinfo(opts) end
 
+--- Returns the current stack trace of Vim scripts.
+--- Stack trace is a |List|, of which each item is a |Dictionary|
+--- with the following items:
+---     funcref  The funcref if the stack is at the function,
+---     otherwise this item is not exist.
+---     event  The string of the event description if the
+---     stack is at autocmd event, otherwise this item
+---     is not exist.
+---     lnum  The line number of the script on the stack.
+---     filepath  The file path of the script on the stack.
+---
+--- @return table[]
+function vim.fn.getstacktrace() end
+
 --- If {tabnr} is not specified, then information about all the
 --- tab pages is returned as a |List|. Each List item is a
 --- |Dictionary|.  Otherwise, {tabnr} specifies the tab page
diff --git a/runtime/lua/vim/_meta/vvars.lua b/runtime/lua/vim/_meta/vvars.lua
index 445da4e02f..c1b8695bbf 100644
--- a/runtime/lua/vim/_meta/vvars.lua
+++ b/runtime/lua/vim/_meta/vvars.lua
@@ -203,7 +203,8 @@ vim.v.errors = ...
 vim.v.event = ...
 
 --- The value of the exception most recently caught and not
---- finished.  See also `v:throwpoint` and `throw-variables`.
+--- finished.  See also `v:stacktrace`, `v:throwpoint`, and
+--- `throw-variables`.
 --- Example:
 ---
 --- ```vim
@@ -616,6 +617,13 @@ vim.v.servername = ...
 --- @type integer
 vim.v.shell_error = ...
 
+--- The stack trace of the exception most recently caught and
+--- not finished.  Refer to `getstacktrace()` for the structure of
+--- stack trace.  See also `v:exception`, `v:throwpoint`, and
+--- `throw-variables`.
+--- @type table[]
+vim.v.stacktrace = ...
+
 --- Last given status message.
 --- Modifiable (can be set).
 --- @type string
@@ -718,7 +726,7 @@ vim.v.this_session = ...
 
 --- The point where the exception most recently caught and not
 --- finished was thrown.  Not set when commands are typed.  See
---- also `v:exception` and `throw-variables`.
+--- also `v:exception`, `v:stacktrace`, and `throw-variables`.
 --- Example:
 ---
 --- ```vim