patch 8.1.0027: difficult to make a plugin that feeds a line to a job

Problem:    Difficult to make a plugin that feeds a line to a job.
Solution:   Add the nitial code for the "prompt" buftype.

runtime/doc/channel.txt

@@ -22,6 +22,7 @@ The Netbeans interface also uses a channel. |netbeans|
 9. Starting a job without a channel	|job-start-nochannel|
 10. Job options				|job-options|
 11. Controlling a job			|job-control|
+12. Using a prompt buffer		|prompt-buffer|
 
 {Vi does not have any of these features}
 {only when compiled with the |+channel| feature for channel stuff}
@@ -770,5 +771,43 @@ signals.  E.g. to force a job to stop, "kill it": >
 
 For more options see |job_stop()|.
 
+==============================================================================
+12. Using a prompt buffer				*prompt-buffer*
+
+If you want to type input for the job in a Vim window you have a few options:
+- Use a normal buffer and handle all possible commands yourself.
+  This will be complicated, since there are so many possible commands.
+- Use a terminal window.  This works well if what you type goes directly to
+  the job and the job output is directly displayed in the window.
+  See |terminal-window|.
+- Use a prompt window. This works well when entering a line for the job in Vim
+  while displaying (possibly filtered) output from the job.
+
+A prompt buffer is created by setting 'buftype' to "prompt". You would
+normally only do that in a newly created buffer.
+
+The user can edit and enter one line of text at the very last line of the
+buffer.  When pressing Enter in the prompt line the callback set with
+|prompt_setcallback()| is invoked.  It would normally send the line to a job.
+Another callback would receive the output from the job and display it in the
+buffer, below the prompt (and above the next prompt).
+
+Only the text in the last line, after the prompt, is editable. The rest of the
+buffer is not modifiable with Normal mode commands.  It can be modified by
+calling functions, such as |append()|.  Using other commands may mess up the
+buffer.
+
+After setting 'buftype' to "prompt" Vim does not automatically start Insert
+mode, use `:startinsert` if you want to enter Insert mode, so that the user
+can start typing a line.
+
+The text of the prompt can be set with the |prompt_setprompt()| function.
+
+The user can go to Normal mode and navigate through the buffer.  This can be
+useful see older output or copy text.
+
+Any command that starts Insert mode, such as "a", "i", "A" and "I", will move
+the cursor to the last line, after the prompt.
+
 
  vim:tw=78:ts=8:ft=help:norl:

runtime/doc/eval.txt

@@ -2294,6 +2294,9 @@ perleval({expr})		any	evaluate |Perl| expression
 pow({x}, {y})			Float	{x} to the power of {y}
 prevnonblank({lnum})		Number	line nr of non-blank line <= {lnum}
 printf({fmt}, {expr1}...)	String	format text
+prompt_addtext({buf}, {expr})	none	add text to a prompt buffer
+prompt_setprompt({buf}, {text}) none	set prompt text
+prompt_setcallback({buf}, {expr}) none	set prompt callback function
 pumvisible()			Number	whether popup menu is visible
 pyeval({expr})			any	evaluate |Python| expression
 py3eval({expr})			any	evaluate |python3| expression
@@ -2302,7 +2305,7 @@ range({expr} [, {max} [, {stride}]])
 				List	items from {expr} to {max}
 readfile({fname} [, {binary} [, {max}]])
 				List	get list of lines from file {fname}
-reg_executing()			Number	get the executing register name
+reg_executing()			String	get the executing register name
 reg_recording()			String	get the recording register name
 reltime([{start} [, {end}]])	List	get time value
 reltimefloat({time})		Float	turn the time value into a Float
@@ -4650,7 +4653,7 @@ getline({lnum} [, {end}])
 		from the current buffer.  Example: >
 			getline(1)
 <		When {lnum} is a String that doesn't start with a
-		digit, line() is called to translate the String into a Number.
+		digit, |line()| is called to translate the String into a Number.
 		To get the line under the cursor: >
 			getline(".")
 <		When {lnum} is smaller than 1 or bigger than the number of
@@ -6475,6 +6478,42 @@ printf({fmt}, {expr1} ...)				*printf()*
 		arguments an error is given.  Up to 18 arguments can be used.
 
 
+prompt_setprompt({buf}, {text})				*prompt_setprompt()*
+		Set prompt for buffer {buf} to {text}.  You most likely want
+		{text} to end in a space.
+		The result is only visible if {buf} has 'buftype' set to
+		"prompt".  Example: >
+			call prompt_setprompt(bufnr(''), 'command: ')
+
+
+prompt_setcallback({buf}, {expr})			*prompt_setcallback()*
+		Set prompt callback for buffer {buf} to {expr}.  This has only
+		effect if {buf} has 'buftype' set to "prompt".
+		The callback is invoked when pressing Enter.  The current
+		buffer will always be the prompt buffer.  A new line for a
+		prompt is added before invoking the callback, thus the prompt
+		for which the callback was invoked will be in the last but one
+		line.
+		If the callback wants to add text to the buffer, it must
+		insert it above the last line, since that is where the current
+		prompt is.  This can also be done asynchronously.
+		The callback is invoked with one argument, which is the text
+		that was entered at the prompt.  This can be an empty string
+		if the user only typed Enter.
+		Example: >
+		   call prompt_setcallback(bufnr(''), function('s:TextEntered'))
+		   func s:TextEntered(text)
+		     if a:text == 'exit' || a:text == 'quit'
+		       stopinsert
+		       close
+		     else
+		       call append(line('$') - 1, 'Entered: "' . a:text . '"')
+		       " Reset 'modified' to allow the buffer to be closed.
+		       set nomodified
+		     endif
+		   endfunc
+
+
 pumvisible()						*pumvisible()*
 		Returns non-zero when the popup menu is visible, zero
 		otherwise.  See |ins-completion-menu|.

runtime/doc/options.txt

@@ -1394,6 +1394,9 @@ A jump table for the options with a short description can be found at |Q_op|.
 			manually)
 	  terminal	buffer for a |terminal| (you are not supposed to set
 			this manually)
+	  prompt	buffer where only the last line can be edited, meant
+			to be used by a plugin, see |prompt-buffer|
+			{only when compiled with the |+channel| feature}
 
 	This option is used together with 'bufhidden' and 'swapfile' to
 	specify special kinds of buffers.   See |special-buffers|.
@@ -4264,7 +4267,8 @@ A jump table for the options with a short description can be found at |Q_op|.
 'imactivatefunc' 'imaf'	string (default "")
 			global
 			{not in Vi}
-			{only available when compiled with |+mbyte|}
+			{only available when compiled with the |+multi_byte|
+			feature}
 	This option specifies a function that will be called to
 	activate or deactivate the Input Method.
 	It is not used in the GUI.
@@ -4316,7 +4320,8 @@ A jump table for the options with a short description can be found at |Q_op|.
 'imcmdline' 'imc'	boolean (default off)
 			global
 			{not in Vi}
-			{only available when compiled with |+mbyte|}
+			{only available when compiled with the |+multi_byte|
+			feature}
 	When set the Input Method is always on when starting to edit a command
 	line, unless entering a search pattern (see 'imsearch' for that).
 	Setting this option is useful when your input method allows entering
@@ -4327,7 +4332,8 @@ A jump table for the options with a short description can be found at |Q_op|.
 'imdisable' 'imd'	boolean (default off, on for some systems (SGI))
 			global
 			{not in Vi}
-			{only available when compiled with |+mbyte|}
+			{only available when compiled with the |+multi_byte|
+			feature}
 	When set the Input Method is never used.  This is useful to disable
 	the IM when it doesn't work properly.
 	Currently this option is on by default for SGI/IRIX machines.  This
@@ -4380,7 +4386,8 @@ A jump table for the options with a short description can be found at |Q_op|.
 'imstatusfunc' 'imsf'	string (default "")
 			global
 			{not in Vi}
-			{only available when compiled with |+mbyte|}
+			{only available when compiled with the |+multi_byte|
+			feature}
 	This option specifies a function that is called to obtain the status
 	of Input Method.  It must return a positive number when IME is active.
 	It is not used in the GUI.

runtime/doc/todo.txt

@@ -38,6 +38,10 @@ browser use: https://github.com/vim/vim/issues/1234
 							*known-bugs*
 -------------------- Known bugs and current work -----------------------
 
+Prompt buffer:
+- Add a command line history.
+- delay next prompt until plugin gives OK?
+
 Terminal emulator window:
 - Win32: Termdebug doesn't work, because gdb does not support mi2 on a tty.
   This plugin: https://github.com/cpiger/NeoDebug  runs gdb as a job,
@@ -71,33 +75,66 @@ Crash when mixing matchadd and substitute()? (Max Christian Pohle, 2018 May
 On Win32 when not in the console and t_Co >= 256, allow using 'tgc'.
 (Nobuhiro Takasaki, #2833)  Also check t_Co.
 
-balloon_show() does not work properly in the terminal. (Ben Jackson, 2017 Dec
-20, #2481)
-Also see #2352, want better control over balloon, perhaps set the position.
+Patch to fix arguments of :edit. (Dominique Pelle, 2018 May 28 #2966)
+
+Ptch to update html syntax. (Jorge Maldonado Ventura, #2974)
+
+Patch to fix that restoring window doesn't work when 'winheight' is large.
+(Darrell Nash, 2018 May 30, #2971)  Doesn't work?  Issue #2970
+
+Patch to add completion to :unlet for environment vars. (Jason Franklin, 2018
+May 30) Last update.
 
 Errors found with random data:
     heap-buffer-overflow in alist_add (#2472)
 
 More warnings from static analysis:
 https://lgtm.com/projects/g/vim/vim/alerts/?mode=list
 
+Patch to make "is" and "as" work bettter. (Jason Franklin, 2018 May 19)
+
+Patch to add tests for user and language completion. (Dominique Pelle, 2018
+Jun 2, #2978)
+
+Using ":file" in quickfix window during an autocommand doesn't work. 
+(Jason Franklin, 2018 May 23) Allow for using it when there is no argument.
+
+Pull request #2967: Allow white space in sign text. (Ben Jackson)
+
+Patch for xterm and vt320 builtin termcap. (Kouichi Iwamoto, 2018 May 31,
+#2973)
+
+Patch to add more testing for :cd command. (Dominique Pelle, 2018 May 30,
+#2972)
+
 Script generated by :mksession does not work well if there are windows with
 modified buffers
   change "silent only" into "silent only!"
   change "edit fname" of first buffer to "hide edit fname"
   skip "badd fname" if "fname" is already in the buffer list
   remove remark about unloading buffers from documentation
 
+Patch to make :help work for tags with a ?. (Hirohito Higashi, 2018 May 28)
+
 Compiler warnings (geeknik, 2017 Oct 26):
 - signed integer overflow in do_sub() (#2249)
 - signed integer overflow in get_address() (#2248)
 - signed integer overflow in getdecchrs() (#2254)
 - undefined left shift in get_string_tv() (#2250)
 
+Patch for more quickfix refactoring. (Yegappan Lakshmanan, #2950)
+
 Tests failing for "make testgui" with GTK:
 - Test_setbufvar_options()
 - Test_exit_callback_interval()
 
+Make balloon_show() work outside of 'balloonexpr'?  Users expect it to work:
+#2948. (related to #1512?)
+On Win32 it stops showing, because showState is already ShS_SHOWING.
+balloon_show() does not work properly in the terminal. (Ben Jackson, 2017 Dec
+20, #2481)
+Also see #2352, want better control over balloon, perhaps set the position.
+
 Try out background make plugin: 
   https://github.com/AndrewVos/vim-make-background
 or asyncmake: 
@@ -112,6 +149,8 @@ used for git temp files.
 
 Cursor in wrong position when line wraps. (#2540)
 
+Patch for Lua support. (Kazunobu Kuriyama, 2018 May 26)
+
 Add an option similar to 'lazyredraw' to skip redrawing while executing a
 script or function.
 
@@ -141,6 +180,9 @@ How to test that it works well for all Vim users?
 
 Alternative manpager.vim. (Enno, 2018 Jan 5, #2529)
 
+Patch to use NGETTEXT() in many more places. (Sergey Alyoshin, 2018 May 25)
+Updated ptach May 27.
+
 Does setting 'cursorline' cause syntax highlighting to slow down?  Perhaps is
 mess up the cache?  (Mike Lee Williams, 2018 Jan 27, #2539)
 Also: 'foldtext' is evaluated too often. (Daniel Hahler, #2773)

src/Makefile

@@ -2252,6 +2252,7 @@ test_arglist \
 	test_popup \
 	test_preview \
 	test_profile \
+	test_prompt_buffer \
 	test_put \
 	test_python2 \
 	test_python3 \

src/buffer.c

@@ -851,6 +851,10 @@ free_buffer(buf_T *buf)
 #ifdef FEAT_TERMINAL
     free_terminal(buf);
 #endif
+#ifdef FEAT_JOB_CHANNEL
+    vim_free(buf->b_prompt_text);
+    free_callback(buf->b_prompt_callback, buf->b_prompt_partial);
+#endif
 
     buf_hashtab_remove(buf);
 
@@ -5633,6 +5637,15 @@ bt_help(buf_T *buf)
     return buf != NULL && buf->b_help;
 }
 
+/*
+ * Return TRUE if "buf" is a prompt buffer.
+ */
+    int
+bt_prompt(buf_T *buf)
+{
+    return buf != NULL && buf->b_p_bt[0] == 'p';
+}
+
 /*
  * Return TRUE if "buf" is a "nofile", "acwrite" or "terminal" buffer.
  * This means the buffer name is not a file name.
@@ -5642,7 +5655,8 @@ bt_nofile(buf_T *buf)
 {
     return buf != NULL && ((buf->b_p_bt[0] == 'n' && buf->b_p_bt[2] == 'f')
 	    || buf->b_p_bt[0] == 'a'
-	    || buf->b_p_bt[0] == 't');
+	    || buf->b_p_bt[0] == 't'
+	    || buf->b_p_bt[0] == 'p');
 }
 
 /*
@@ -5651,7 +5665,9 @@ bt_nofile(buf_T *buf)
     int
 bt_dontwrite(buf_T *buf)
 {
-    return buf != NULL && (buf->b_p_bt[0] == 'n' || buf->b_p_bt[0] == 't');
+    return buf != NULL && (buf->b_p_bt[0] == 'n'
+	         || buf->b_p_bt[0] == 't'
+	         || buf->b_p_bt[0] == 'p');
 }
 
     int

src/channel.c

@@ -5836,4 +5836,38 @@ job_stop(job_T *job, typval_T *argvars, char *type)
     return 1;
 }
 
+    void
+invoke_prompt_callback(void)
+{
+    typval_T	rettv;
+    int		dummy;
+    typval_T	argv[2];
+    char_u	*text;
+    char_u	*prompt;
+    linenr_T	lnum = curbuf->b_ml.ml_line_count;
+
+    // Add a new line for the prompt before invoking the callback, so that
+    // text can always be inserted above the last line.
+    ml_append(lnum, (char_u  *)"", 0, FALSE);
+    curwin->w_cursor.lnum = lnum + 1;
+    curwin->w_cursor.col = 0;
+
+    if (curbuf->b_prompt_callback == NULL)
+	return;
+    text = ml_get(lnum);
+    prompt = prompt_text();
+    if (STRLEN(text) >= STRLEN(prompt))
+	text += STRLEN(prompt);
+    argv[0].v_type = VAR_STRING;
+    argv[0].vval.v_string = vim_strsave(text);
+    argv[1].v_type = VAR_UNKNOWN;
+
+    call_func(curbuf->b_prompt_callback,
+	      (int)STRLEN(curbuf->b_prompt_callback),
+	      &rettv, 1, argv, NULL, 0L, 0L, &dummy, TRUE,
+	      curbuf->b_prompt_partial, NULL);
+    clear_tv(&argv[0]);
+    clear_tv(&rettv);
+}
+
 #endif /* FEAT_JOB_CHANNEL */

src/diff.c

@@ -2141,6 +2141,13 @@ nv_diffgetput(int put, long count)
     exarg_T	ea;
     char_u	buf[30];
 
+#ifdef FEAT_JOB_CHANNEL
+    if (bt_prompt(curbuf))
+    {
+	vim_beep(BO_OPER);
+	return;
+    }
+#endif
     if (count == 0)
 	ea.arg = (char_u *)"";
     else