patch 8.2.2128: there is no way to do something on CTRL-Z

Problem:    There is no way to do something on CTRL-Z.
Solution:   Add VimSuspend and VimResume autocommand events. (closes #7450)

runtime/doc/autocmd.txt

@@ -306,6 +306,9 @@ Name			triggered by ~
 |VimLeavePre|		before exiting Vim, before writing the viminfo file
 |VimLeave|		before exiting Vim, after writing the viminfo file
 
+|VimSuspend|		when suspending Vim
+|VimResume|		when Vim is resumed after being suspended
+
 	Terminal
 |TerminalOpen|		after a terminal buffer was created
 |TerminalWinOpen|	after a terminal buffer was created in a new window
@@ -1231,6 +1234,17 @@ VimLeavePre			Before exiting Vim, just before writing the
 VimResized			After the Vim window was resized, thus 'lines'
 				and/or 'columns' changed.  Not when starting
 				up though.
+							*VimResume*
+VimResume			When the Vim instance is resumed after being
+				suspended and |VimSuspend| was triggered.
+				Useful for triggering |:checktime| and ensure
+				the buffers content did not change while Vim
+				was suspended: >
+	:autocmd VimResume * checktime
+<							*VimSuspend*
+VimSuspend			When the Vim instance is suspended.  Only when
+				CTRL-Z was typed inside Vim, not when the
+				SIGSTOP or SIGTSTP signal was sent to Vim.
 							*WinEnter*
 WinEnter			After entering another window.  Not done for
 				the first window, when Vim has just started.

src/autocmd.c

@@ -191,6 +191,8 @@ static struct event_name
     {"WinLeave",	EVENT_WINLEAVE},
     {"VimResized",	EVENT_VIMRESIZED},
     {"TextYankPost",	EVENT_TEXTYANKPOST},
+    {"VimSuspend",	EVENT_VIMSUSPEND},
+    {"VimResume",	EVENT_VIMRESUME},
     {NULL,		(event_T)0}
 };
 

src/ex_docmd.c

@@ -5864,6 +5864,7 @@ ex_stop(exarg_T *eap)
     {
 	if (!eap->forceit)
 	    autowrite_all();
+	apply_autocmds(EVENT_VIMSUSPEND, NULL, NULL, FALSE, NULL);
 	windgoto((int)Rows - 1, 0);
 	out_char('\n');
 	out_flush();
@@ -5881,6 +5882,7 @@ ex_stop(exarg_T *eap)
 	scroll_start();		// scroll screen before redrawing
 	redraw_later_clear();
 	shell_resized();	// may have resized window
+	apply_autocmds(EVENT_VIMRESUME, NULL, NULL, FALSE, NULL);
     }
 }
 

src/normal.c

@@ -5787,7 +5787,7 @@ nv_suspend(cmdarg_T *cap)
     clearop(cap->oap);
     if (VIsual_active)
 	end_visual_mode();		// stop Visual mode
-    do_cmdline_cmd((char_u *)"st");
+    do_cmdline_cmd((char_u *)"stop");
 }
 
 /*

src/testdir/test_suspend.vim

@@ -61,4 +61,48 @@ func Test_suspend()
   call delete('Xfoo')
 endfunc
 
+func Test_suspend_autocmd()
+  CheckFeature terminal
+  CheckExecutable /bin/sh
+
+  let buf = term_start('/bin/sh', #{term_rows: 6})
+  " Wait for shell prompt.
+  call WaitForAssert({-> assert_match('[$#] $', term_getline(buf, '.'))})
+
+  call term_sendkeys(buf, v:progpath
+        \               . " --clean -X"
+        \               . " -c 'set nu'"
+        \               . " -c 'let g:count = 0'"
+        \               . " -c 'au VimSuspend * let g:count += 1'"
+        \               . " -c 'au VimResume * let g:count += 1'"
+        \               . " -c 'call setline(1, \"foo\")'"
+        \               . " Xfoo\<CR>")
+  " Cursor in terminal buffer should be on first line in spawned vim.
+  call WaitForAssert({-> assert_equal('  1 foo', term_getline(buf, '.'))})
+
+  for suspend_cmd in [":suspend\<CR>",
+        \             ":stop\<CR>",
+        \             ":suspend!\<CR>",
+        \             ":stop!\<CR>",
+        \             "\<C-Z>"]
+    " Suspend and wait for shell prompt.  Then "fg" will restore Vim.
+    call term_sendkeys(buf, suspend_cmd)
+    call CheckSuspended(buf, 0)
+  endfor
+
+  call term_sendkeys(buf, ":echo g:count\<CR>")
+  call TermWait(buf)
+  call WaitForAssert({-> assert_match('^10', term_getline(buf, 6))})
+
+  " Quit gracefully to dump coverage information.
+  call term_sendkeys(buf, ":qall!\<CR>")
+  call TermWait(buf)
+  " Wait until Vim actually exited and shell shows a prompt
+  call WaitForAssert({-> assert_match('[$#] $', term_getline(buf, '.'))})
+  call StopShellInTerminal(buf)
+
+  exe buf . 'bwipe!'
+  call delete('Xfoo')
+endfunc
+
 " vim: shiftwidth=2 sts=2 expandtab

src/version.c

@@ -750,6 +750,8 @@ static char *(features[]) =
 
 static int included_patches[] =
 {   /* Add new patch number below this line */
+/**/
+    2128,
 /**/
     2127,
 /**/

src/vim.h

@@ -1344,6 +1344,8 @@ enum auto_event
     EVENT_WINENTER,		// after entering a window
     EVENT_WINLEAVE,		// before leaving a window
     EVENT_WINNEW,		// when entering a new window
+    EVENT_VIMSUSPEND,		// before Vim is suspended
+    EVENT_VIMRESUME,		// after Vim is resumed
 
     NUM_EVENTS			// MUST be the last one
 };