From 187db50d0499aecf4cfd42fb4db0a1bebf61c8cd Mon Sep 17 00:00:00 2001 From: Bram Moolenaar Date: Sat, 27 Feb 2016 14:44:26 +0100 Subject: 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. --- runtime/doc/channel.txt | 66 ++++++++++++++++++++++++++++++++----------------- 1 file changed, 44 insertions(+), 22 deletions(-) (limited to 'runtime/doc/channel.txt') diff --git a/runtime/doc/channel.txt b/runtime/doc/channel.txt index 0f329648a3..1e6eaf5f64 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* -- cgit v1.2.3