patch 7.4.1426

Problem:    The "out-io" option for jobs is not implemented yet.
Solution:   Implement the "buffer" value: append job output to a buffer.

1 files changed, 44 insertions, 22 deletions

diff --git a/runtime/doc/channel.txt b/runtime/doc/channel.txt
index 0f329648a..1e6eaf5f6 100644
--- a/runtime/doc/channel.txt
+++ b/runtime/doc/channel.txt
@@ -130,6 +130,8 @@ Use |ch_status()| to see if the channel could be opened.
 		overwritten.  Therefore set "mode" first and the part specific
 		mode later.
 
+		Note: when writing to a file or buffer NL mode is always used.
+
 							*channel-callback*
 "callback"	A function that is called when a message is received that is
 		not handled otherwise.  It gets two arguments: the channel
@@ -198,6 +200,7 @@ Once done with the channel, disconnect it like this: >
 When a socket is used this will close the socket for both directions.  When
 pipes are used (stdin/stdout/stderr) they are all closed.  This might not be
 what you want!  Stopping the job with job_stop() might be better.
+All readahead is discarded, callbacks will no longer be invoked.
 
 When the channel can't be opened you will get an error message.  There is a
 difference between MS-Windows and Unix: On Unix when the port doesn't exist
@@ -327,7 +330,7 @@ It will send back the result of the expression:
 	[-2, "last line"] ~
 The format is:
 	[{number}, {result}]
-							*E915*
+
 Here {number} is the same as what was in the request.  Use a negative number
 to avoid confusion with message that Vim sends.  Use a different number on
 every request to be able to match the request with the response.
@@ -397,7 +400,7 @@ are:
 	"closed"	The channel was closed.
 
 TODO:
-To objain the job associated with a channel: ch_getjob(channel)
+To obtain the job associated with a channel: ch_getjob(channel)
 
 To read one message from a channel: >
 	let output = ch_read(channel)
@@ -448,10 +451,13 @@ You can send a message to the command with ch_sendraw().  If the channel is in
 JSON or JS mode you can use ch_sendexpr().
 
 There are several options you can use, see |job-options|.
+For example, to start a job and write its output in buffer "dummy": >
+	let logjob = job_start("tail -f /tmp/log",
+			     \ {'out-io': 'buffer', 'out-name': 'dummy'})
+	sbuf dummy
 
 TODO:
 To run a job and read its output once it is done: >
-
 	let job = job_start({command}, {'exit-cb': 'MyHandler'})
 	func MyHandler(job, status)
 	  let channel = job_getchannel()
@@ -508,7 +514,7 @@ See |job_setoptions()| and |ch_setoptions()|.
 						*job-err-cb*
 "err-cb": handler	Callback for when there is something to read on
 			stderr.
-TODO:						*job-close-cb*
+						*job-close-cb*
 "close-cb": handler	Callback for when the channel is closed.  Same as
 			"close-cb" on ch_open().
 						*job-exit-cb*
@@ -527,28 +533,44 @@ TODO:						*job-term*
 "term": "open"		Start a terminal and connect the job
 			stdin/stdout/stderr to it.
 
-TODO:						*job-in-io*
-"in-io": "null"		disconnect stdin
+						*job-in-io*
+"in-io": "null"		disconnect stdin  TODO
 "in-io": "pipe"		stdin is connected to the channel (default)
-"in-io": "file"		stdin reads from a file
-"in-file": "/path/file"	the file to read from
+"in-io": "file"		stdin reads from a file  TODO
+"in-io": "buffer"	stdin reads from a buffer  TODO
+"in-name": "/path/file"	the name of he file or buffer to read from
+"in-buf": number	the number of the buffer to read from  TODO
 
-TODO:						*job-out-io*
-"out-io": "null"	disconnect stdout
+						*job-out-io*
+"out-io": "null"	disconnect stdout  TODO
 "out-io": "pipe"	stdout is connected to the channel (default)
-"out-io": "file"	stdout writes to a file
-"out-file": "/path/file" the file to write to
+"out-io": "file"	stdout writes to a file  TODO
 "out-io": "buffer" 	stdout appends to a buffer
-"out-buffer": "name" 	buffer to append to
-
-TODO:						*job-err-io*
-"err-io": "out"		same type as stdout (default)
-"err-io": "null"	disconnect stderr
-"err-io": "pipe"	stderr is connected to the channel
-"err-io": "file"	stderr writes to a file
-"err-file": "/path/file" the file to write to
-"err-io": "buffer" 	stderr appends to a buffer
-"err-buffer": "name" 	buffer to append to
+"out-name": "/path/file" the name of the file or buffer to write to
+"out-buf": number	the number of the buffer to write to  TODO
+
+						*job-err-io*
+"err-io": "out"		same as stdout  TODO
+"err-io": "null"	disconnect stderr  TODO
+"err-io": "pipe"	stderr is connected to the channel (default)
+"err-io": "file"	stderr writes to a file  TODO
+"err-io": "buffer" 	stderr appends to a buffer  TODO
+"err-name": "/path/file" the name of the file or buffer to write to
+"err-buf": number	the number of the buffer to write to  TODO
+
+When the IO mode is "buffer" and there is a callback, the text is appended to
+the buffer before invoking the callback.
+							*E915*
+The name of the buffer is compared the full name of existing buffers.  If
+there is a match that buffer is used.  Otherwise a new buffer is created,
+where 'buftype' is set to "nofile" and 'bufhidden' to "hide".  If you prefer
+other settings, create the buffer first and pass the buffer number.
+
+When the buffer written to is displayed in a window and the cursor is in the
+first column of the last line, the cursor will be moved to the newly added
+line and the window is scrolled up to show the cursor if needed.
+
+Undo is synced for every added line.
 
 ==============================================================================
 11. Controlling a job					*job-control*