diff options
Diffstat (limited to '')
| -rw-r--r-- | runtime/doc/channel.txt | 833 |
1 files changed, 833 insertions, 0 deletions
diff --git a/runtime/doc/channel.txt b/runtime/doc/channel.txt new file mode 100644 index 0000000..fd08cd4 --- /dev/null +++ b/runtime/doc/channel.txt @@ -0,0 +1,833 @@ +*channel.txt* For Vim version 8.1. Last change: 2018 Apr 18 + + + VIM REFERENCE MANUAL by Bram Moolenaar + + + Inter-process communication *channel* + +Vim uses channels to communicate with other processes. +A channel uses a socket or pipes. *socket-interface* +Jobs can be used to start processes and communicate with them. +The Netbeans interface also uses a channel. |netbeans| + +1. Overview |job-channel-overview| +2. Channel demo |channel-demo| +3. Opening a channel |channel-open| +4. Using a JSON or JS channel |channel-use| +5. Channel commands |channel-commands| +6. Using a RAW or NL channel |channel-raw| +7. More channel functions |channel-more| +8. Starting a job with a channel |job-start| +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} + You can check this with: `has('channel')` +{only when compiled with the |+job| feature for job stuff} + You can check this with: `has('job')` + +============================================================================== +1. Overview *job-channel-overview* + +There are four main types of jobs: +1. A daemon, serving several Vim instances. + Vim connects to it with a socket. +2. One job working with one Vim instance, asynchronously. + Uses a socket or pipes. +3. A job performing some work for a short time, asynchronously. + Uses a socket or pipes. +4. Running a filter, synchronously. + Uses pipes. + +For when using sockets See |job-start|, |job-start-nochannel| and +|channel-open|. For 2 and 3, one or more jobs using pipes, see |job-start|. +For 4 use the ":{range}!cmd" command, see |filter|. + +Over the socket and pipes these protocols are available: +RAW nothing known, Vim cannot tell where a message ends +NL every message ends in a NL (newline) character +JSON JSON encoding |json_encode()| +JS JavaScript style JSON-like encoding |js_encode()| + +Common combination are: +- Using a job connected through pipes in NL mode. E.g., to run a style + checker and receive errors and warnings. +- Using a daemon, connecting over a socket in JSON mode. E.g. to lookup + cross-references in a database. + +============================================================================== +2. Channel demo *channel-demo* *demoserver.py* + +This requires Python. The demo program can be found in +$VIMRUNTIME/tools/demoserver.py +Run it in one terminal. We will call this T1. + +Run Vim in another terminal. Connect to the demo server with: > + let channel = ch_open('localhost:8765') + +In T1 you should see: + === socket opened === ~ + +You can now send a message to the server: > + echo ch_evalexpr(channel, 'hello!') + +The message is received in T1 and a response is sent back to Vim. +You can see the raw messages in T1. What Vim sends is: + [1,"hello!"] ~ +And the response is: + [1,"got it"] ~ +The number will increase every time you send a message. + +The server can send a command to Vim. Type this on T1 (literally, including +the quotes): + ["ex","echo 'hi there'"] ~ +And you should see the message in Vim. You can move the cursor a word forward: + ["normal","w"] ~ + +To handle asynchronous communication a callback needs to be used: > + func MyHandler(channel, msg) + echo "from the handler: " . a:msg + endfunc + call ch_sendexpr(channel, 'hello!', {'callback': "MyHandler"}) +Vim will not wait for a response. Now the server can send the response later +and MyHandler will be invoked. + +Instead of giving a callback with every send call, it can also be specified +when opening the channel: > + call ch_close(channel) + let channel = ch_open('localhost:8765', {'callback': "MyHandler"}) + call ch_sendexpr(channel, 'hello!') + +When trying out channels it's useful to see what is going on. You can tell +Vim to write lines in log file: > + call ch_logfile('channellog', 'w') +See |ch_logfile()|. + +============================================================================== +3. Opening a channel *channel-open* + +To open a channel: > + let channel = ch_open({address} [, {options}]) + if ch_status(channel) == "open" + " use the channel + +Use |ch_status()| to see if the channel could be opened. + +{address} has the form "hostname:port". E.g., "localhost:8765". + +{options} is a dictionary with optional entries: *channel-open-options* + +"mode" can be: *channel-mode* + "json" - Use JSON, see below; most convenient way. Default. + "js" - Use JS (JavaScript) encoding, more efficient than JSON. + "nl" - Use messages that end in a NL character + "raw" - Use raw messages + *channel-callback* *E921* +"callback" A function that is called when a message is received that is + not handled otherwise. It gets two arguments: the channel + and the received message. Example: > + func Handle(channel, msg) + echo 'Received: ' . a:msg + endfunc + let channel = ch_open("localhost:8765", {"callback": "Handle"}) +< + When "mode" is "json" or "js" the "msg" argument is the body + of the received message, converted to Vim types. + When "mode" is "nl" the "msg" argument is one message, + excluding the NL. + When "mode" is "raw" the "msg" argument is the whole message + as a string. + + For all callbacks: Use |function()| to bind it to arguments + and/or a Dictionary. Or use the form "dict.function" to bind + the Dictionary. + + Callbacks are only called at a "safe" moment, usually when Vim + is waiting for the user to type a character. Vim does not use + multi-threading. + + *close_cb* +"close_cb" A function that is called when the channel gets closed, other + than by calling ch_close(). It should be defined like this: > + func MyCloseHandler(channel) +< Vim will invoke callbacks that handle data before invoking + close_cb, thus when this function is called no more data will + be passed to the callbacks. + *channel-drop* +"drop" Specifies when to drop messages: + "auto" When there is no callback to handle a message. + The "close_cb" is also considered for this. + "never" All messages will be kept. + + *channel-noblock* +"noblock" Same effect as |job-noblock|. Only matters for writing. + + *waittime* +"waittime" The time to wait for the connection to be made in + milliseconds. A negative number waits forever. + + The default is zero, don't wait, which is useful if a local + server is supposed to be running already. On Unix Vim + actually uses a 1 msec timeout, that is required on many + systems. Use a larger value for a remote server, e.g. 10 + msec at least. + *channel-timeout* +"timeout" The time to wait for a request when blocking, E.g. when using + ch_evalexpr(). In milliseconds. The default is 2000 (2 + seconds). + +When "mode" is "json" or "js" the "callback" is optional. When omitted it is +only possible to receive a message after sending one. + +To change the channel options after opening it use |ch_setoptions()|. The +arguments are similar to what is passed to |ch_open()|, but "waittime" cannot +be given, since that only applies to opening the channel. + +For example, the handler can be added or changed: > + call ch_setoptions(channel, {'callback': callback}) +When "callback" is empty (zero or an empty string) the handler is removed. + +After a callback has been invoked Vim will update the screen and put the +cursor back where it belongs. Thus the callback should not need to do +`:redraw`. + +The timeout can be changed: > + call ch_setoptions(channel, {'timeout': msec}) +< + *channel-close* *E906* +Once done with the channel, disconnect it like this: > + call ch_close(channel) +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. + +Note that a channel is closed in three stages: + - The I/O ends, log message: "Closing channel". There can still be queued + messages to read or callbacks to invoke. + - The readahead is cleared, log message: "Clearing channel". Some variables + may still reference the channel. + - The channel is freed, log message: "Freeing channel". + +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 +ch_open() fails quickly. On MS-Windows "waittime" applies. +*E898* *E901* *E902* + +If there is an error reading or writing a channel it will be closed. +*E630* *E631* + +============================================================================== +4. Using a JSON or JS channel *channel-use* + +If mode is JSON then a message can be sent synchronously like this: > + let response = ch_evalexpr(channel, {expr}) +This awaits a response from the other side. + +When mode is JS this works the same, except that the messages use +JavaScript encoding. See |js_encode()| for the difference. + +To send a message, without handling a response or letting the channel callback +handle the response: > + call ch_sendexpr(channel, {expr}) + +To send a message and letting the response handled by a specific function, +asynchronously: > + call ch_sendexpr(channel, {expr}, {'callback': Handler}) + +Vim will match the response with the request using the message ID. Once the +response is received the callback will be invoked. Further responses with the +same ID will be ignored. If your server sends back multiple responses you +need to send them with ID zero, they will be passed to the channel callback. + +The {expr} is converted to JSON and wrapped in an array. An example of the +message that the receiver will get when {expr} is the string "hello": + [12,"hello"] ~ + +The format of the JSON sent is: + [{number},{expr}] + +In which {number} is different every time. It must be used in the response +(if any): + + [{number},{response}] + +This way Vim knows which sent message matches with which received message and +can call the right handler. Also when the messages arrive out of order. + +A newline character is terminating the JSON text. This can be used to +separate the read text. For example, in Python: + splitidx = read_text.find('\n') + message = read_text[:splitidx] + rest = read_text[splitidx + 1:] + +The sender must always send valid JSON to Vim. Vim can check for the end of +the message by parsing the JSON. It will only accept the message if the end +was received. A newline after the message is optional. + +When the process wants to send a message to Vim without first receiving a +message, it must use the number zero: + [0,{response}] + +Then channel handler will then get {response} converted to Vim types. If the +channel does not have a handler the message is dropped. + +It is also possible to use ch_sendraw() and ch_evalraw() on a JSON or JS +channel. The caller is then completely responsible for correct encoding and +decoding. + +============================================================================== +5. Channel commands *channel-commands* + +With a JSON channel the process can send commands to Vim that will be +handled by Vim internally, it does not require a handler for the channel. + +Possible commands are: *E903* *E904* *E905* + ["redraw", {forced}] + ["ex", {Ex command}] + ["normal", {Normal mode command}] + ["expr", {expression}, {number}] + ["expr", {expression}] + ["call", {func name}, {argument list}, {number}] + ["call", {func name}, {argument list}] + +With all of these: Be careful what these commands do! You can easily +interfere with what the user is doing. To avoid trouble use |mode()| to check +that the editor is in the expected state. E.g., to send keys that must be +inserted as text, not executed as a command: + ["ex","if mode() == 'i' | call feedkeys('ClassName') | endif"] ~ + +Errors in these commands are normally not reported to avoid them messing up +the display. If you do want to see them, set the 'verbose' option to 3 or +higher. + + +Command "redraw" ~ + +The other commands do not update the screen, so that you can send a sequence +of commands without the cursor moving around. You must end with the "redraw" +command to show any changed text and show the cursor where it belongs. + +The argument is normally an empty string: + ["redraw", ""] ~ +To first clear the screen pass "force": + ["redraw", "force"] ~ + + +Command "ex" ~ + +The "ex" command is executed as any Ex command. There is no response for +completion or error. You could use functions in an |autoload| script: + ["ex","call myscript#MyFunc(arg)"] + +You can also use "call |feedkeys()|" to insert any key sequence. + +When there is an error a message is written to the channel log, if it exists, +and v:errmsg is set to the error. + + +Command "normal" ~ + +The "normal" command is executed like with ":normal!", commands are not +mapped. Example to open the folds under the cursor: + ["normal" "zO"] + + +Command "expr" with response ~ + +The "expr" command can be used to get the result of an expression. For +example, to get the number of lines in the current buffer: + ["expr","line('$')", -2] ~ + +It will send back the result of the expression: + [-2, "last line"] ~ +The format is: + [{number}, {result}] + +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. + +{result} is the result of the evaluation and is JSON encoded. If the +evaluation fails or the result can't be encoded in JSON it is the string +"ERROR". + + +Command "expr" without a response ~ + +This command is similar to "expr" above, but does not send back any response. +Example: + ["expr","setline('$', ['one', 'two', 'three'])"] ~ +There is no third argument in the request. + + +Command "call" ~ + +This is similar to "expr", but instead of passing the whole expression as a +string this passes the name of a function and a list of arguments. This +avoids the conversion of the arguments to a string and escaping and +concatenating them. Example: + ["call", "line", ["$"], -2] ~ + +Leave out the fourth argument if no response is to be sent: + ["call", "setline", ["$", ["one", "two", "three"]]] ~ + +============================================================================== +6. Using a RAW or NL channel *channel-raw* + +If mode is RAW or NL then a message can be sent like this: > + let response = ch_evalraw(channel, {string}) + +The {string} is sent as-is. The response will be what can be read from the +channel right away. Since Vim doesn't know how to recognize the end of the +message you need to take care of it yourself. The timeout applies for reading +the first byte, after that it will not wait for anything more. + +If mode is "nl" you can send a message in a similar way. You are expected +to put in the NL after each message. Thus you can also send several messages +ending in a NL at once. The response will be the text up to and including the +first NL. This can also be just the NL for an empty response. +If no NL was read before the channel timeout an empty string is returned. + +To send a message, without expecting a response: > + call ch_sendraw(channel, {string}) +The process can send back a response, the channel handler will be called with +it. + +To send a message and letting the response handled by a specific function, +asynchronously: > + call ch_sendraw(channel, {string}, {'callback': 'MyHandler'}) + +This {string} can also be JSON, use |json_encode()| to create it and +|json_decode()| to handle a received JSON message. + +It is not possible to use |ch_evalexpr()| or |ch_sendexpr()| on a raw channel. + +A String in Vim cannot contain NUL bytes. To send or receive NUL bytes read +or write from a buffer. See |in_io-buffer| and |out_io-buffer|. + +============================================================================== +7. More channel functions *channel-more* + +To obtain the status of a channel: ch_status(channel). The possible results +are: + "fail" Failed to open the channel. + "open" The channel can be used. + "buffered" The channel was closed but there is data to read. + "closed" The channel was closed. + +To obtain the job associated with a channel: ch_getjob(channel) + +To read one message from a channel: > + let output = ch_read(channel) +This uses the channel timeout. To read without a timeout, just get any +message that is available: > + let output = ch_read(channel, {'timeout': 0}) +When no message was available then the result is v:none for a JSON or JS mode +channels, an empty string for a RAW or NL channel. You can use |ch_canread()| +to check if there is something to read. + +Note that when there is no callback, messages are dropped. To avoid that add +a close callback to the channel. + +To read all output from a RAW channel that is available: > + let output = ch_readraw(channel) +To read the error output: > + let output = ch_readraw(channel, {"part": "err"}) + +ch_read() and ch_readraw() use the channel timeout. When there is nothing to +read within that time an empty string is returned. To specify a different +timeout in msec use the "timeout" option: + {"timeout": 123} ~ +To read from the error output use the "part" option: + {"part": "err"} ~ +To read a message with a specific ID, on a JS or JSON channel: + {"id": 99} ~ +When no ID is specified or the ID is -1, the first message is returned. This +overrules any callback waiting for this message. + +For a RAW channel this returns whatever is available, since Vim does not know +where a message ends. +For a NL channel this returns one message. +For a JS or JSON channel this returns one decoded message. +This includes any sequence number. + +============================================================================== +8. Starting a job with a channel *job-start* *job* + +To start a job and open a channel for stdin/stdout/stderr: > + let job = job_start(command, {options}) + +You can get the channel with: > + let channel = job_getchannel(job) + +The channel will use NL mode. If you want another mode it's best to specify +this in {options}. When changing the mode later some text may have already +been received and not parsed correctly. + +If the command produces a line of output that you want to deal with, specify +a handler for stdout: > + let job = job_start(command, {"out_cb": "MyHandler"}) +The function will be called with the channel and a message. You would define +it like this: > + func MyHandler(channel, msg) + +Without the handler you need to read the output with |ch_read()| or +|ch_readraw()|. You can do this in the close callback, see |read-in-close-cb|. + +Note that if the job exits before you read the output, the output may be lost. +This depends on the system (on Unix this happens because closing the write end +of a pipe causes the read end to get EOF). To avoid this make the job sleep +for a short while before it exits. + +The handler defined for "out_cb" will not receive stderr. If you want to +handle that separately, add an "err_cb" handler: > + let job = job_start(command, {"out_cb": "MyHandler", + \ "err_cb": "ErrHandler"}) + +If you want to handle both stderr and stdout with one handler use the +"callback" option: > + let job = job_start(command, {"callback": "MyHandler"}) + +Depending on the system, starting a job can put Vim in the background, the +started job gets the focus. To avoid that, use the `foreground()` function. +This might not always work when called early, put in the callback handler or +use a timer to call it after the job has started. + +You can send a message to the command with ch_evalraw(). If the channel is in +JSON or JS mode you can use ch_evalexpr(). + +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 + + +Job input from a buffer ~ + *in_io-buffer* +To run a job that reads from a buffer: > + let job = job_start({command}, + \ {'in_io': 'buffer', 'in_name': 'mybuffer'}) +< + *E915* *E918* +The buffer is found by name, similar to |bufnr()|. The buffer must exist and +be loaded when job_start() is called. + +By default this reads the whole buffer. This can be changed with the "in_top" +and "in_bot" options. + +A special mode is when "in_top" is set to zero and "in_bot" is not set: Every +time a line is added to the buffer, the last-but-one line will be sent to the +job stdin. This allows for editing the last line and sending it when pressing +Enter. + *channel-close-in* +When not using the special mode the pipe or socket will be closed after the +last line has been written. This signals the reading end that the input +finished. You can also use |ch_close_in()| to close it sooner. + +NUL bytes in the text will be passed to the job (internally Vim stores these +as NL bytes). + + +Reading job output in the close callback ~ + *read-in-close-cb* +If the job can take some time and you don't need intermediate results, you can +add a close callback and read the output there: > + + func! CloseHandler(channel) + while ch_status(a:channel, {'part': 'out'}) == 'buffered' + echomsg ch_read(a:channel) + endwhile + endfunc + let job = job_start(command, {'close_cb': 'CloseHandler'}) + +You will want to do something more useful than "echomsg". + +============================================================================== +9. Starting a job without a channel *job-start-nochannel* + +To start another process without creating a channel: > + let job = job_start(command, + \ {"in_io": "null", "out_io": "null", "err_io": "null"}) + +This starts {command} in the background, Vim does not wait for it to finish. + +When Vim sees that neither stdin, stdout or stderr are connected, no channel +will be created. Often you will want to include redirection in the command to +avoid it getting stuck. + +There are several options you can use, see |job-options|. + + *job-start-if-needed* +To start a job only when connecting to an address does not work, do something +like this: > + let channel = ch_open(address, {"waittime": 0}) + if ch_status(channel) == "fail" + let job = job_start(command) + let channel = ch_open(address, {"waittime": 1000}) + endif + +Note that the waittime for ch_open() gives the job one second to make the port +available. + +============================================================================== +10. Job options *job-options* + +The {options} argument in job_start() is a dictionary. All entries are +optional. Some options can be used after the job has started, using +job_setoptions(job, {options}). Many options can be used with the channel +related to the job, using ch_setoptions(channel, {options}). +See |job_setoptions()| and |ch_setoptions()|. + + *in_mode* *out_mode* *err_mode* +"in_mode" mode specifically for stdin, only when using pipes +"out_mode" mode specifically for stdout, only when using pipes +"err_mode" mode specifically for stderr, only when using pipes + See |channel-mode| for the values. + + Note: when setting "mode" the part specific mode is + overwritten. Therefore set "mode" first and the part + specific mode later. + + Note: when writing to a file or buffer and when + reading from a buffer NL mode is used by default. + + *job-noblock* +"noblock": 1 When writing use a non-blocking write call. This + avoids getting stuck if Vim should handle other + messages in between, e.g. when a job sends back data + to Vim. It implies that when `ch_sendraw()` returns + not all data may have been written yet. + This option was added in patch 8.1.0350, test with: > + if has("patch-8.1.350") + let options['noblock'] = 1 + endif +< + *job-callback* +"callback": handler Callback for something to read on any part of the + channel. + *job-out_cb* *out_cb* +"out_cb": handler Callback for when there is something to read on + stdout. Only for when the channel uses pipes. When + "out_cb" wasn't set the channel callback is used. + The two arguments are the channel and the message. + + *job-err_cb* *err_cb* +"err_cb": handler Callback for when there is something to read on + stderr. Only for when the channel uses pipes. When + "err_cb" wasn't set the channel callback is used. + The two arguments are the channel and the message. + *job-close_cb* +"close_cb": handler Callback for when the channel is closed. Same as + "close_cb" on |ch_open()|, see |close_cb|. + *job-drop* +"drop": when Specifies when to drop messages. Same as "drop" on + |ch_open()|, see |channel-drop|. For "auto" the + exit_cb is not considered. + *job-exit_cb* +"exit_cb": handler Callback for when the job ends. The arguments are the + job and the exit status. + Vim checks up to 10 times per second for jobs that + ended. The check can also be triggered by calling + |job_status()|, which may then invoke the exit_cb + handler. + Note that data can be buffered, callbacks may still be + called after the process ends. + *job-timeout* +"timeout": time The time to wait for a request when blocking, E.g. + when using ch_evalexpr(). In milliseconds. The + default is 2000 (2 seconds). + *out_timeout* *err_timeout* +"out_timeout": time Timeout for stdout. Only when using pipes. +"err_timeout": time Timeout for stderr. Only when using pipes. + Note: when setting "timeout" the part specific mode is + overwritten. Therefore set "timeout" first and the + part specific mode later. + + *job-stoponexit* +"stoponexit": {signal} Send {signal} to the job when Vim exits. See + |job_stop()| for possible values. +"stoponexit": "" Do not stop the job when Vim exits. + The default is "term". + + *job-term* +"term": "open" Start a terminal in a new window and connect the job + stdin/stdout/stderr to it. Similar to using + `:terminal`. + NOTE: Not implemented yet! + +"channel": {channel} Use an existing channel instead of creating a new one. + The parts of the channel that get used for the new job + will be disconnected from what they were used before. + If the channel was still used by another job this may + cause I/O errors. + Existing callbacks and other settings remain. + +"pty": 1 Use a pty (pseudo-tty) instead of a pipe when + possible. This is most useful in combination with a + terminal window, see |terminal|. + {only on Unix and Unix-like systems} + + *job-in_io* *in_top* *in_bot* *in_name* *in_buf* +"in_io": "null" disconnect stdin (read from /dev/null) +"in_io": "pipe" stdin is connected to the channel (default) +"in_io": "file" stdin reads from a file +"in_io": "buffer" stdin reads from a buffer +"in_top": number when using "buffer": first line to send (default: 1) +"in_bot": number when using "buffer": last line to send (default: last) +"in_name": "/path/file" the name of the file or buffer to read from +"in_buf": number the number of the buffer to read from + + *job-out_io* *out_name* *out_buf* +"out_io": "null" disconnect stdout (goes to /dev/null) +"out_io": "pipe" stdout is connected to the channel (default) +"out_io": "file" stdout writes to a file +"out_io": "buffer" stdout appends to a buffer (see below) +"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 +"out_modifiable": 0 when writing to a buffer, 'modifiable' will be off + (see below) +"out_msg": 0 when writing to a new buffer, the first line will be + set to "Reading from channel output..." + + *job-err_io* *err_name* *err_buf* +"err_io": "out" stderr messages to go to stdout +"err_io": "null" disconnect stderr (goes to /dev/null) +"err_io": "pipe" stderr is connected to the channel (default) +"err_io": "file" stderr writes to a file +"err_io": "buffer" stderr appends to a buffer (see below) +"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 +"err_modifiable": 0 when writing to a buffer, 'modifiable' will be off + (see below) +"err_msg": 0 when writing to a new buffer, the first line will be + set to "Reading from channel error..." + +"block_write": number only for testing: pretend every other write to stdin + will block + +"env": dict environment variables for the new process +"cwd": "/path/to/dir" current working directory for the new process; + if the directory does not exist an error is given + + +Writing to a buffer ~ + *out_io-buffer* +When the out_io or err_io mode is "buffer" and there is a callback, the text +is appended to the buffer before invoking the callback. + +When a buffer is used both for input and output, the output lines are put +above the last line, since the last line is what is written to the channel +input. Otherwise lines are appended below the last line. + +When using JS or JSON mode with "buffer", only messages with zero or negative +ID will be added to the buffer, after decoding + encoding. Messages with a +positive number will be handled by a callback, commands are handled as usual. + +The name of the buffer from "out_name" or "err_name" is compared the full name +of existing buffers, also after expanding the name for the current directory. +E.g., when a buffer was created with ":edit somename" and the buffer name is +"somename" it will use that buffer. + +If there is no matching buffer a new buffer is created. Use an empty name to +always create a new buffer. |ch_getbufnr()| can then be used to get the +buffer number. + +For a new buffer 'buftype' is set to "nofile" and 'bufhidden' to "hide". If +you prefer other settings, create the buffer first and pass the buffer number. + *out_modifiable* *err_modifiable* +The "out_modifiable" and "err_modifiable" options can be used to set the +'modifiable' option off, or write to a buffer that has 'modifiable' off. That +means that lines will be appended to the buffer, but the user can't easily +change the buffer. + *out_msg* *err_msg* +The "out_msg" option can be used to specify whether a new buffer will have the +first line set to "Reading from channel output...". The default is to add the +message. "err_msg" does the same for channel error. + +When an existing buffer is to be written where 'modifiable' is off and the +"out_modifiable" or "err_modifiable" options is not zero, an error is given +and the buffer will not be written to. + +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. NUL bytes are accepted (internally Vim +stores these as NL bytes). + + +Writing to a file ~ + *E920* +The file is created with permissions 600 (read-write for the user, not +accessible for others). Use |setfperm()| to change this. + +If the file already exists it is truncated. + +============================================================================== +11. Controlling a job *job-control* + +To get the status of a job: > + echo job_status(job) + +To make a job stop running: > + job_stop(job) + +This is the normal way to end a job. On Unix it sends a SIGTERM to the job. +It is possible to use other ways to stop the job, or even send arbitrary +signals. E.g. to force a job to stop, "kill it": > + job_stop(job, "kill") + +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. + +The CTRL-W key can be used to start a window command, such as CTRL-W w to +switch to the next window. This also works in Insert mode (use Shift-CTRL-W +to delete a word). When leaving the window Insert mode will be stopped. When +coming back to the prompt window Insert mode will be restored. + +Any command that starts Insert mode, such as "a", "i", "A" and "I", will move +the cursor to the last line. "A" will move to the end of the line, "I" to the +start of the line. + + + vim:tw=78:ts=8:noet:ft=help:norl: |