patch 9.1.0984: exception handling can be improved
Problem: exception handling can be improved
Solution: add v:stacktrace and getstacktrace()
closes: #16360
Co-authored-by: Naruhiko Nishino <naru123456789@gmail.com>
Signed-off-by: ichizok <gclient.gaap@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>
diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 48ba03b..d7ed732 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -279,6 +279,7 @@
List get a list of positions for a region
getregtype([{regname}]) String type of a register
getscriptinfo([{opts}]) List list of sourced scripts
+getstacktrace() List get current stack trace of Vim scripts
gettabinfo([{expr}]) List list of tab pages
gettabvar({nr}, {varname} [, {def}])
any variable {varname} in tab {nr} or {def}
@@ -4997,6 +4998,21 @@
Return type: list<dict<any>>
+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 type: list<dict<any>>
+
+
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 af5b3a9..2348cdd 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -1,4 +1,4 @@
-*eval.txt* For Vim version 9.1. Last change: 2024 Dec 23
+*eval.txt* For Vim version 9.1. Last change: 2025 Jan 02
VIM REFERENCE MANUAL by Bram Moolenaar
@@ -1953,7 +1953,8 @@
PREDEFINED VIM VARIABLES *vim-variable* *v:var* *v:*
*E963* *E1063*
-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.
*v:argv* *argv-variable*
v:argv The command line arguments Vim was invoked with. This is a
@@ -2172,7 +2173,8 @@
<
*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: >
:try
: throw "oops"
@@ -2548,6 +2550,12 @@
This is only useful for deciding whether a test will give the
expected result.
+ *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. It's allowed to set this variable.
@@ -2676,7 +2684,7 @@
*v:throwpoint* *throwpoint-variable*
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: >
:try
: throw "oops"
@@ -3856,7 +3864,8 @@
: 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/tags b/runtime/doc/tags
index 6458224..a299679 100644
--- a/runtime/doc/tags
+++ b/runtime/doc/tags
@@ -7908,6 +7908,7 @@
getscript-plugins pi_getscript.txt /*getscript-plugins*
getscript-start pi_getscript.txt /*getscript-start*
getscriptinfo() builtin.txt /*getscriptinfo()*
+getstacktrace() builtin.txt /*getstacktrace()*
gettabinfo() builtin.txt /*gettabinfo()*
gettabvar() builtin.txt /*gettabvar()*
gettabwinvar() builtin.txt /*gettabwinvar()*
@@ -10218,6 +10219,7 @@
squirrel.vim syntax.txt /*squirrel.vim*
srand() builtin.txt /*srand()*
sscanf eval.txt /*sscanf*
+stacktrace-variable eval.txt /*stacktrace-variable*
standard-plugin usr_05.txt /*standard-plugin*
standard-plugin-list help.txt /*standard-plugin-list*
standout syntax.txt /*standout*
@@ -11038,6 +11040,7 @@
v:sizeofint eval.txt /*v:sizeofint*
v:sizeoflong eval.txt /*v:sizeoflong*
v:sizeofpointer eval.txt /*v:sizeofpointer*
+v:stacktrace eval.txt /*v:stacktrace*
v:statusmsg eval.txt /*v:statusmsg*
v:swapchoice eval.txt /*v:swapchoice*
v:swapcommand eval.txt /*v:swapcommand*
diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt
index fdb9934..ded30e3 100644
--- a/runtime/doc/usr_41.txt
+++ b/runtime/doc/usr_41.txt
@@ -1,4 +1,4 @@
-*usr_41.txt* For Vim version 9.1. Last change: 2024 Dec 30
+*usr_41.txt* For Vim version 9.1. Last change: 2025 Jan 02
VIM USER MANUAL - by Bram Moolenaar
@@ -1399,7 +1399,8 @@
eventhandler() check if invoked by an event handler
getcellpixels() get List of cell pixel size
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
getimstatus() check if IME status is active
interrupt() interrupt script execution
windowsversion() get MS-Windows version
diff --git a/runtime/doc/version9.txt b/runtime/doc/version9.txt
index cfb472d..bcb0b78 100644
--- a/runtime/doc/version9.txt
+++ b/runtime/doc/version9.txt
@@ -41623,6 +41623,8 @@
for the ghostty terminal emulator (using kitty protocol)
- |complete_info()| returns the list of matches shown in the poppu menu via
the "matches" key
+- |v:stacktrace| The stack trace of the exception most recently caught and
+ not finished
*added-9.2*
Added ~
@@ -41642,6 +41644,7 @@
|getcmdprompt()| get prompt for input()/confirm()
|getregion()| get a region of text from a buffer
|getregionpos()| get a list of positions for a region
+|getstacktrace()| get current stack trace of Vim scripts
|id()| get unique identifier for a Dict, List, Object,
Channel or Blob variable
|matchbufline()| all the matches of a pattern in a buffer