patch 8.1.0027: difficult to make a plugin that feeds a line to a jobv8.1.0027

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

4 files changed, 136 insertions, 9 deletions

diff --git a/runtime/doc/channel.txt b/runtime/doc/channel.txt
index 9cc2be37ad..bffb3e2833 100644
--- a/runtime/doc/channel.txt
+++ b/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:
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index e243ba3788..7d214c11aa 100644
--- a/runtime/doc/eval.txt
+++ b/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|.
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 422f100285..d37fa641a4 100644
--- a/runtime/doc/options.txt
+++ b/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.
diff --git a/runtime/doc/todo.txt b/runtime/doc/todo.txt
index 2029c35ee1..dbd293526b 100644
--- a/runtime/doc/todo.txt
+++ b/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,9 +75,15 @@ 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)
@@ -81,6 +91,22 @@ Errors found with random data:
 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!"
@@ -88,16 +114,27 @@ modified buffers
   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)