vim-patch:8.1.2341: not so easy to interrupt a script programatically

Problem:    Not so easy to interrupt a script programatically.
Solution:   Add the interrupt() function. (Yasuhiro Matsumoto, closes vim/vim#2834)
67a2deb9cb

runtime/doc/eval.txt

@@ -2224,6 +2224,7 @@ inputsecret({prompt} [, {text}])
 				String  like input() but hiding the text
 insert({list}, {item} [, {idx}])
 				List	insert {item} in {list} [before {idx}]
+interrupt()			none	interrupt script execution
 invert({expr})			Number  bitwise invert
 isdirectory({directory})	Number	|TRUE| if {directory} is a directory
 isinf({expr})			Number	determine if {expr} is infinity value
@@ -5412,6 +5413,19 @@ insert({list}, {item} [, {idx}])			*insert()*
 		Note that when {item} is a |List| it is inserted as a single
 		item.  Use |extend()| to concatenate |Lists|.
 
+interrupt()						*interrupt()*
+		Interrupt script execution.  It works more or less like the
+		user typing CTRL-C, most commands won't execute and control
+		returns to the user.  This is useful to abort execution
+		from lower down, e.g. in an autocommand.  Example: >
+		:function s:check_typoname(file)
+		:   if fnamemodify(a:file, ':t') == '['
+		:       echomsg 'Maybe typo'
+		:       call interrupt()
+		:   endif
+		:endfunction
+		:au BufWritePre * call s:check_typoname(expand('<amatch>'))
+
 invert({expr})						*invert()*
 		Bitwise invert.  The argument is converted to a number.  A
 		List, Dict or Float argument causes an error.  Example: >

src/nvim/eval.lua

@@ -191,6 +191,7 @@ return {
     inputsave={},
     inputsecret={args={1, 2}},
     insert={args={2, 3}},
+    interrupt={args=0},
     invert={args=1},
     isdirectory={args=1},
     isinf={args=1},

src/nvim/eval/funcs.c

@@ -4717,6 +4717,14 @@ static void f_insert(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
+// "interrupt()" function
+static void f_interrupt(typval_T *argvars FUNC_ATTR_UNUSED,
+                        typval_T *rettv FUNC_ATTR_UNUSED,
+                        FunPtr fptr FUNC_ATTR_UNUSED)
+{
+  got_int = true;
+}
+
 /*
  * "invert(expr)" function
  */

src/nvim/ex_eval.c

@@ -87,17 +87,16 @@
  */
 static int cause_abort = FALSE;
 
-/*
+// Return true when immediately aborting on error, or when an interrupt
- * Return TRUE when immediately aborting on error, or when an interrupt
+// occurred or an exception was thrown but not caught.  Use for ":{range}call"
- * occurred or an exception was thrown but not caught.  Use for ":{range}call"
+// to check whether an aborted function that does not handle a range itself
- * to check whether an aborted function that does not handle a range itself
+// should be called again for the next line in the range.  Also used for
- * should be called again for the next line in the range.  Also used for
+// cancelling expression evaluation after a function call caused an immediate
- * cancelling expression evaluation after a function call caused an immediate
+// abort.  Note that the first emsg() call temporarily resets "force_abort"
- * abort.  Note that the first emsg() call temporarily resets "force_abort"
+// until the throw point for error messages has been reached.  That is, during
- * until the throw point for error messages has been reached.  That is, during
+// cancellation of an expression evaluation after an aborting function call or
- * cancellation of an expression evaluation after an aborting function call or
+// due to a parsing error, aborting() always returns the same value.
- * due to a parsing error, aborting() always returns the same value.
+// "got_int" is also set by calling interrupt().
- */
 int aborting(void)
 {
   return (did_emsg && force_abort) || got_int || current_exception;

src/nvim/testdir/test_interrupt.vim

@@ -0,0 +1,27 @@
+" Test behavior of interrupt()
+
+let s:bufwritepre_called = 0
+let s:bufwritepost_called = 0
+
+func s:bufwritepre()
+  let s:bufwritepre_called = 1
+  call interrupt()
+endfunction
+
+func s:bufwritepost()
+  let s:bufwritepost_called = 1
+endfunction
+
+func Test_interrupt()
+  new Xfile
+  let n = 0
+  try
+    au BufWritePre Xfile call s:bufwritepre()
+    au BufWritePost Xfile call s:bufwritepost()
+    w!
+  catch /^Vim:Interrupt$/
+  endtry
+  call assert_equal(1, s:bufwritepre_called)
+  call assert_equal(0, s:bufwritepost_called)
+  call assert_equal(0, filereadable('Xfile'))
+endfunc