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>

Author: 2 people

runtime/doc/builtin.txt

@@ -279,6 +279,7 @@ getregionpos({pos1}, {pos2} [, {opts}])
 				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 @@ getscriptinfo([{opts}])					*getscriptinfo()*
 		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

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 @@ variables for each buffer.  Use local buffer variables instead |b:var|.
 
 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:event		Dictionary containing information about the current
 <
 					*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 @@ v:sizeofpointer	Number of bytes in a pointer.  Depends on how Vim was compiled.
 		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:this_session	Full filename of the last loaded or saved session file.  See
 					*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 @@ 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: >
 

runtime/doc/tags

@@ -7908,6 +7908,7 @@ getscript-history	pi_getscript.txt	/*getscript-history*
 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 @@ sqrt()	builtin.txt	/*sqrt()*
 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:shell_error	eval.txt	/*v:shell_error*
 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*

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 @@ Various:					*various-functions*
 	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

runtime/doc/version9.txt

@@ -41623,6 +41623,8 @@ Changed~
   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 @@ Functions: ~
 |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

src/dict.c

@@ -531,6 +531,29 @@ dict_add_callback(dict_T *d, char *key, callback_T *cb)
     return OK;
 }
 
+/*
+ * Add a function entry to dictionary "d".
+ * Returns FAIL when out of memory and when key already exists.
+ */
+    int
+dict_add_func(dict_T *d, char *key, ufunc_T *fp)
+{
+    dictitem_T	*item;
+
+    item = dictitem_alloc((char_u *)key);
+    if (item == NULL)
+	return FAIL;
+    item->di_tv.v_type = VAR_FUNC;
+    item->di_tv.vval.v_string = vim_strsave(fp->uf_name);
+    if (dict_add(d, item) == FAIL)
+    {
+	dictitem_free(item);
+	return FAIL;
+    }
+    func_ref(item->di_tv.vval.v_string);
+    return OK;
+}
+
 /*
  * Initializes "iter" for iterating over dictionary items with
  * dict_iterate_next().

src/evalfunc.c

@@ -2170,6 +2170,8 @@ static funcentry_T global_functions[] =
 			ret_string,	    f_getregtype},
     {"getscriptinfo",	0, 1, 0,	    arg1_dict_any,
 			ret_list_dict_any,  f_getscriptinfo},
+    {"getstacktrace",	0, 0, 0,	    NULL,
+			ret_list_dict_any,  f_getstacktrace},
     {"gettabinfo",	0, 1, FEARG_1,	    arg1_number,
 			ret_list_dict_any,  f_gettabinfo},
     {"gettabvar",	2, 3, FEARG_1,	    arg3_number_string_any,

src/evalvars.c

@@ -160,7 +160,8 @@ static struct vimvar
     {VV_NAME("python3_version",	 VAR_NUMBER), NULL, VV_RO},
     {VV_NAME("t_typealias",	 VAR_NUMBER), NULL, VV_RO},
     {VV_NAME("t_enum",		 VAR_NUMBER), NULL, VV_RO},
-    {VV_NAME("t_enumvalue",	 VAR_NUMBER), NULL, VV_RO}
+    {VV_NAME("t_enumvalue",	 VAR_NUMBER), NULL, VV_RO},
+    {VV_NAME("stacktrace",	 VAR_LIST), &t_list_string, VV_RO},
 };
 
 // shorthand

src/ex_eval.c

@@ -562,6 +562,10 @@ throw_exception(void *value, except_type_T type, char_u *cmdname)
 	excp->throw_lnum = SOURCING_LNUM;
     }
 
+    excp->stacktrace = stacktrace_create();
+    if (excp->stacktrace != NULL)
+	excp->stacktrace->lv_refcount = 1;
+
     if (p_verbose >= 13 || debug_break_level > 0)
     {
 	int	save_msg_silent = msg_silent;
@@ -647,6 +651,7 @@ discard_exception(except_T *excp, int was_finished)
     if (excp->type == ET_ERROR)
 	free_msglist(excp->messages);
     vim_free(excp->throw_name);
+    list_unref(excp->stacktrace);
     vim_free(excp);
 }
 
@@ -671,6 +676,7 @@ catch_exception(except_T *excp)
     excp->caught = caught_stack;
     caught_stack = excp;
     set_vim_var_string(VV_EXCEPTION, (char_u *)excp->value, -1);
+    set_vim_var_list(VV_STACKTRACE, excp->stacktrace);
     if (*excp->throw_name != NUL)
     {
 	if (excp->throw_lnum != 0)
@@ -721,6 +727,7 @@ finish_exception(except_T *excp)
     if (caught_stack != NULL)
     {
 	set_vim_var_string(VV_EXCEPTION, (char_u *)caught_stack->value, -1);
+	set_vim_var_list(VV_STACKTRACE, caught_stack->stacktrace);
 	if (*caught_stack->throw_name != NUL)
 	{
 	    if (caught_stack->throw_lnum != 0)
@@ -741,6 +748,7 @@ finish_exception(except_T *excp)
     {
 	set_vim_var_string(VV_EXCEPTION, NULL, -1);
 	set_vim_var_string(VV_THROWPOINT, NULL, -1);
+	set_vim_var_list(VV_STACKTRACE, NULL);
     }
 
     // Discard the exception, but use the finish message for 'verbose'.

src/proto/dict.pro

@@ -22,6 +22,7 @@ int dict_add_string_len(dict_T *d, char *key, char_u *str, int len);
 int dict_add_list(dict_T *d, char *key, list_T *list);
 int dict_add_tv(dict_T *d, char *key, typval_T *tv);
 int dict_add_callback(dict_T *d, char *key, callback_T *cb);
+int dict_add_func(dict_T *d, char *key, ufunc_T *fp);
 void dict_iterate_start(typval_T *var, dict_iterator_T *iter);
 char_u *dict_iterate_next(dict_iterator_T *iter, typval_T **tv_result);
 int dict_add_dict(dict_T *d, char *key, dict_T *dict);