patch 8.0.0893: cannot get the scroll count of a terminal window

Problem:    Cannot get the scroll count of a terminal window.
Solution:   Add term_getscrolled().

runtime/doc/eval.txt

@@ -2373,6 +2373,7 @@ term_getattr({attr}, {what})	Number	get the value of attribute {what}
 term_getcursor({buf})		List	get the cursor position of a terminal
 term_getjob({buf})		Job	get the job associated with a terminal
 term_getline({buf}, {row})	String	get a line of text from a terminal
+term_getscrolled({buf})		Number	get the scroll count of a terminal
 term_getsize({buf})		List	get the size of a terminal
 term_getstatus({buf})		String	get the status of a terminal
 term_gettitle({buf})		String	get the title of a terminal
@@ -2984,6 +2985,11 @@ ch_logfile({fname} [, {mode}])					*ch_logfile()*
 		The file is flushed after every message, on Unix you can use
 		"tail -f" to see what is going on in real time.
 
+		This function is not available in the |sandbox|.
+		NOTE: the channel communication is stored in the file, be
+		aware that this may contain confidential and privacy sensitive
+		information, e.g. a password you type in a terminal window.
+
 
 ch_open({address} [, {options}])				*ch_open()*
 		Open a channel to {address}.  See |channel|.
@@ -7948,6 +7954,18 @@ term_getline({buf}, {row})				*term_getline()*
 		returned.
 		{only available when compiled with the |+terminal| feature}
 
+term_getscrolled({buf})					*term_getscrolled()*
+		Return the number of lines that scrolled to above the top of
+		terminal {buf}.  This is the offset between the row number
+		used for |term_getline()| and |getline()|, so that: >
+			term_getline(buf, N)
+<		is equal to: >
+			`getline(N + term_getscrolled(buf))
+<		(if that line exists).
+
+		{buf} is used as with |term_getsize()|.
+		{only available when compiled with the |+terminal| feature}
+
 term_getsize({buf})					*term_getsize()*
 		Get the size of terminal {buf}. Returns a list with two
 		numbers: [rows, cols].  This is the size of the terminal, not

src/evalfunc.c

@@ -835,6 +835,7 @@ static struct fst
     {"term_getcursor",	1, 1, f_term_getcursor},
     {"term_getjob",	1, 1, f_term_getjob},
     {"term_getline",	2, 2, f_term_getline},
+    {"term_getscrolled", 1, 1, f_term_getscrolled},
     {"term_getsize",	1, 1, f_term_getsize},
     {"term_getstatus",	1, 1, f_term_getstatus},
     {"term_gettitle",	1, 1, f_term_gettitle},

src/proto/terminal.pro

@@ -21,6 +21,7 @@ void f_term_getattr(typval_T *argvars, typval_T *rettv);
 void f_term_getcursor(typval_T *argvars, typval_T *rettv);
 void f_term_getjob(typval_T *argvars, typval_T *rettv);
 void f_term_getline(typval_T *argvars, typval_T *rettv);
+void f_term_getscrolled(typval_T *argvars, typval_T *rettv);
 void f_term_getsize(typval_T *argvars, typval_T *rettv);
 void f_term_getstatus(typval_T *argvars, typval_T *rettv);
 void f_term_gettitle(typval_T *argvars, typval_T *rettv);

src/terminal.c

@@ -40,14 +40,15 @@
  *   - Need an option or argument to drop the window+buffer right away, to be
  *     used for a shell or Vim. 'termfinish'; "close", "open" (open window when
  *     job finishes).
+ *     patch by Yasuhiro: #1950
  * - add option values to the command:
  *      :term <24x80> <close> vim notes.txt
+ *   or use:
+ *      :term ++24x80 ++close vim notes.txt
  * - support different cursor shapes, colors and attributes
  * - make term_getcursor() return type (none/block/bar/underline) and
  *   attributes (color, blink, etc.)
  * - MS-Windows: no redraw for 'updatetime'  #1915
- * - term_getline() and term_scrape() don't work once the job exited. Use the
- *   buffer and scrollback, remembering the topline from when the job exited.
  * - To set BS correctly, check get_stty(); Pass the fd of the pty.
  *   For the GUI fill termios with default values, perhaps like pangoterm:
  *   http://bazaar.launchpad.net/~leonerd/pangoterm/trunk/view/head:/main.c#L134
@@ -2025,6 +2026,19 @@ f_term_getline(typval_T *argvars, typval_T *rettv)
     }
 }
 
+/*
+ * "term_getscrolled(buf)" function
+ */
+    void
+f_term_getscrolled(typval_T *argvars, typval_T *rettv)
+{
+    buf_T	*buf = term_get_buf(argvars);
+
+    if (buf == NULL)
+	return;
+    rettv->vval.v_number = buf->b_term->tl_scrollback_scrolled;
+}
+
 /*
  * "term_getsize(buf)" function
  */

src/testdir/test_terminal.vim

@@ -227,9 +227,13 @@ func Test_terminal_scroll()
     sleep 100m
   endif
 
+  let scrolled = term_getscrolled(buf)
   call assert_equal('1', getline(1))
+  call assert_equal('1', term_getline(buf, 1 - scrolled))
   call assert_equal('49', getline(49))
+  call assert_equal('49', term_getline(buf, 49 - scrolled))
   call assert_equal('200', getline(200))
+  call assert_equal('200', term_getline(buf, 200 - scrolled))
 
   exe buf . 'bwipe'
   call delete('Xtext')

src/version.c

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