blob: 35a5548f2c942846055b3b786e60714e7cc5e27a [file] [log] [blame]
Bram Moolenaar016188f2022-06-06 20:52:59 +01001*channel.txt* For Vim version 8.2. Last change: 2022 Jun 04
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
7 Inter-process communication *channel*
8
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01009Vim uses channels to communicate with other processes.
Bram Moolenaar269f5952016-07-15 22:54:41 +020010A channel uses a socket or pipes. *socket-interface*
Bram Moolenaar38a55632016-02-15 22:07:32 +010011Jobs can be used to start processes and communicate with them.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010012The Netbeans interface also uses a channel. |netbeans|
13
Bram Moolenaar38a55632016-02-15 22:07:32 +0100141. Overview |job-channel-overview|
152. Channel demo |channel-demo|
163. Opening a channel |channel-open|
174. Using a JSON or JS channel |channel-use|
185. Channel commands |channel-commands|
196. Using a RAW or NL channel |channel-raw|
207. More channel functions |channel-more|
Bram Moolenaar54775062019-07-31 21:07:14 +0200218. Channel functions details |channel-functions-details|
Bram Moolenaared997ad2019-07-21 16:42:00 +0200229. Starting a job with a channel |job-start|
2310. Starting a job without a channel |job-start-nochannel|
2411. Job functions |job-functions-details|
2512. Job options |job-options|
2613. Controlling a job |job-control|
2714. Using a prompt buffer |prompt-buffer|
Yegappan Lakshmanan3b470ae2022-04-16 10:41:27 +01002815. Language Server Protocol |language-server-protocol|
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010029
Bram Moolenaar38a55632016-02-15 22:07:32 +010030{only when compiled with the |+channel| feature for channel stuff}
Bram Moolenaarf37506f2016-08-31 22:22:10 +020031 You can check this with: `has('channel')`
Bram Moolenaar38a55632016-02-15 22:07:32 +010032{only when compiled with the |+job| feature for job stuff}
Bram Moolenaarf37506f2016-08-31 22:22:10 +020033 You can check this with: `has('job')`
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010034
35==============================================================================
Bram Moolenaar38a55632016-02-15 22:07:32 +0100361. Overview *job-channel-overview*
37
38There are four main types of jobs:
Bram Moolenaar50ba5262016-09-22 22:33:02 +0200391. A daemon, serving several Vim instances.
Bram Moolenaar38a55632016-02-15 22:07:32 +010040 Vim connects to it with a socket.
412. One job working with one Vim instance, asynchronously.
42 Uses a socket or pipes.
433. A job performing some work for a short time, asynchronously.
44 Uses a socket or pipes.
454. Running a filter, synchronously.
46 Uses pipes.
47
Bram Moolenaar77cdfd12016-03-12 12:57:59 +010048For when using sockets See |job-start|, |job-start-nochannel| and
49|channel-open|. For 2 and 3, one or more jobs using pipes, see |job-start|.
Bram Moolenaar38a55632016-02-15 22:07:32 +010050For 4 use the ":{range}!cmd" command, see |filter|.
51
52Over the socket and pipes these protocols are available:
53RAW nothing known, Vim cannot tell where a message ends
54NL every message ends in a NL (newline) character
55JSON JSON encoding |json_encode()|
56JS JavaScript style JSON-like encoding |js_encode()|
Yegappan Lakshmanan9247a222022-03-30 10:16:05 +010057LSP Language Server Protocol encoding |language-server-protocol|
Bram Moolenaar38a55632016-02-15 22:07:32 +010058
59Common combination are:
60- Using a job connected through pipes in NL mode. E.g., to run a style
61 checker and receive errors and warnings.
Bram Moolenaar7dda86f2018-04-20 22:36:41 +020062- Using a daemon, connecting over a socket in JSON mode. E.g. to lookup
Bram Moolenaar09521312016-08-12 22:54:35 +020063 cross-references in a database.
Bram Moolenaar38a55632016-02-15 22:07:32 +010064
65==============================================================================
Bram Moolenaar26852122016-05-24 20:02:38 +0200662. Channel demo *channel-demo* *demoserver.py*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010067
68This requires Python. The demo program can be found in
69$VIMRUNTIME/tools/demoserver.py
70Run it in one terminal. We will call this T1.
71
72Run Vim in another terminal. Connect to the demo server with: >
Bram Moolenaar38a55632016-02-15 22:07:32 +010073 let channel = ch_open('localhost:8765')
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010074
75In T1 you should see:
76 === socket opened === ~
77
78You can now send a message to the server: >
Bram Moolenaar8b1862a2016-02-27 19:21:24 +010079 echo ch_evalexpr(channel, 'hello!')
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010080
81The message is received in T1 and a response is sent back to Vim.
82You can see the raw messages in T1. What Vim sends is:
83 [1,"hello!"] ~
84And the response is:
85 [1,"got it"] ~
86The number will increase every time you send a message.
87
88The server can send a command to Vim. Type this on T1 (literally, including
Bram Moolenaarfb1f6262016-01-31 20:24:32 +010089the quotes):
90 ["ex","echo 'hi there'"] ~
91And you should see the message in Vim. You can move the cursor a word forward:
92 ["normal","w"] ~
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010093
94To handle asynchronous communication a callback needs to be used: >
Bram Moolenaar38a55632016-02-15 22:07:32 +010095 func MyHandler(channel, msg)
Bram Moolenaarc51cf032022-02-26 12:25:45 +000096 echo "from the handler: " .. a:msg
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010097 endfunc
Bram Moolenaar02e83b42016-02-21 20:10:26 +010098 call ch_sendexpr(channel, 'hello!', {'callback': "MyHandler"})
Bram Moolenaar38a55632016-02-15 22:07:32 +010099Vim will not wait for a response. Now the server can send the response later
100and MyHandler will be invoked.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100101
102Instead of giving a callback with every send call, it can also be specified
103when opening the channel: >
Bram Moolenaar38a55632016-02-15 22:07:32 +0100104 call ch_close(channel)
105 let channel = ch_open('localhost:8765', {'callback': "MyHandler"})
Bram Moolenaar47003982021-12-05 21:54:04 +0000106 call ch_sendexpr(channel, 'hello channel!')
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100107
Bram Moolenaar328da0d2016-03-04 22:22:32 +0100108When trying out channels it's useful to see what is going on. You can tell
109Vim to write lines in log file: >
110 call ch_logfile('channellog', 'w')
111See |ch_logfile()|.
112
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100113==============================================================================
Bram Moolenaar38a55632016-02-15 22:07:32 +01001143. Opening a channel *channel-open*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100115
Bram Moolenaar681baaf2016-02-04 20:57:07 +0100116To open a channel: >
Bram Moolenaar38a55632016-02-15 22:07:32 +0100117 let channel = ch_open({address} [, {options}])
Bram Moolenaar02e83b42016-02-21 20:10:26 +0100118 if ch_status(channel) == "open"
119 " use the channel
Bram Moolenaar38a55632016-02-15 22:07:32 +0100120
121Use |ch_status()| to see if the channel could be opened.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100122
LemonBoycc766a82022-04-04 15:46:58 +0100123 *channel-address*
124{address} can be a domain name or an IP address, followed by a port number, or
125a Unix-domain socket path prefixed by "unix:". E.g. >
126 www.example.com:80 " domain + port
127 127.0.0.1:1234 " IPv4 + port
128 [2001:db8::1]:8765 " IPv6 + port
129 unix:/tmp/my-socket " Unix-domain socket path
Bram Moolenaarbfe13cc2020-04-12 17:53:12 +0200130
Bram Moolenaar4f3f6682016-03-26 23:01:59 +0100131{options} is a dictionary with optional entries: *channel-open-options*
Bram Moolenaar4d919d72016-02-05 22:36:41 +0100132
133"mode" can be: *channel-mode*
134 "json" - Use JSON, see below; most convenient way. Default.
Bram Moolenaar910b8aa2016-02-16 21:03:07 +0100135 "js" - Use JS (JavaScript) encoding, more efficient than JSON.
Bram Moolenaar38a55632016-02-15 22:07:32 +0100136 "nl" - Use messages that end in a NL character
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100137 "raw" - Use raw messages
Yegappan Lakshmanan9247a222022-03-30 10:16:05 +0100138 "lsp" - Use language server protocol encoding
Bram Moolenaard6c2f052016-03-14 23:22:59 +0100139 *channel-callback* *E921*
Bram Moolenaar38a55632016-02-15 22:07:32 +0100140"callback" A function that is called when a message is received that is
Bram Moolenaar47003982021-12-05 21:54:04 +0000141 not handled otherwise (e.g. a JSON message with ID zero). It
142 gets two arguments: the channel and the received message.
143 Example: >
Bram Moolenaar38a55632016-02-15 22:07:32 +0100144 func Handle(channel, msg)
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000145 echo 'Received: ' .. a:msg
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100146 endfunc
Bram Moolenaar38a55632016-02-15 22:07:32 +0100147 let channel = ch_open("localhost:8765", {"callback": "Handle"})
148<
Yegappan Lakshmanan9247a222022-03-30 10:16:05 +0100149 When "mode" is "json" or "js" or "lsp" the "msg" argument is
150 the body of the received message, converted to Vim types.
Bram Moolenaar02e83b42016-02-21 20:10:26 +0100151 When "mode" is "nl" the "msg" argument is one message,
152 excluding the NL.
153 When "mode" is "raw" the "msg" argument is the whole message
154 as a string.
Bram Moolenaare18c0b32016-03-20 21:08:34 +0100155
156 For all callbacks: Use |function()| to bind it to arguments
Bram Moolenaar4f3f6682016-03-26 23:01:59 +0100157 and/or a Dictionary. Or use the form "dict.function" to bind
158 the Dictionary.
Bram Moolenaar06d2d382016-05-20 17:24:11 +0200159
160 Callbacks are only called at a "safe" moment, usually when Vim
161 is waiting for the user to type a character. Vim does not use
162 multi-threading.
163
Bram Moolenaard6c2f052016-03-14 23:22:59 +0100164 *close_cb*
165"close_cb" A function that is called when the channel gets closed, other
Bram Moolenaar38a55632016-02-15 22:07:32 +0100166 than by calling ch_close(). It should be defined like this: >
167 func MyCloseHandler(channel)
Bram Moolenaar06d2d382016-05-20 17:24:11 +0200168< Vim will invoke callbacks that handle data before invoking
169 close_cb, thus when this function is called no more data will
Bram Moolenaar68e65602019-05-26 21:33:31 +0200170 be passed to the callbacks. However, if a callback causes Vim
171 to check for messages, the close_cb may be invoked while still
172 in the callback. The plugin must handle this somehow, it can
173 be useful to know that no more data is coming.
Yegappan Lakshmanan9247a222022-03-30 10:16:05 +0100174 If it is not known if there is a message to be read, use a
175 try/catch block: >
176 try
177 let msg = ch_readraw(a:channel)
178 catch
179 let msg = 'no message'
180 endtry
181 try
182 let err = ch_readraw(a:channel, #{part: 'err'})
183 catch
184 let err = 'no error'
185 endtry
186< *channel-drop*
Bram Moolenaar958dc692016-12-01 15:34:12 +0100187"drop" Specifies when to drop messages:
188 "auto" When there is no callback to handle a message.
189 The "close_cb" is also considered for this.
190 "never" All messages will be kept.
191
Bram Moolenaar0b146882018-09-06 16:27:24 +0200192 *channel-noblock*
193"noblock" Same effect as |job-noblock|. Only matters for writing.
194
Bram Moolenaar06d2d382016-05-20 17:24:11 +0200195 *waittime*
Bram Moolenaar38a55632016-02-15 22:07:32 +0100196"waittime" The time to wait for the connection to be made in
Bram Moolenaarf3913272016-02-25 00:00:01 +0100197 milliseconds. A negative number waits forever.
198
199 The default is zero, don't wait, which is useful if a local
200 server is supposed to be running already. On Unix Vim
201 actually uses a 1 msec timeout, that is required on many
202 systems. Use a larger value for a remote server, e.g. 10
203 msec at least.
Bram Moolenaar4f3f6682016-03-26 23:01:59 +0100204 *channel-timeout*
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100205"timeout" The time to wait for a request when blocking, E.g. when using
Bram Moolenaar8b1862a2016-02-27 19:21:24 +0100206 ch_evalexpr(). In milliseconds. The default is 2000 (2
Bram Moolenaar38a55632016-02-15 22:07:32 +0100207 seconds).
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100208
Bram Moolenaar595e64e2016-02-07 19:19:53 +0100209When "mode" is "json" or "js" the "callback" is optional. When omitted it is
210only possible to receive a message after sending one.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100211
Bram Moolenaar02e83b42016-02-21 20:10:26 +0100212To change the channel options after opening it use |ch_setoptions()|. The
213arguments are similar to what is passed to |ch_open()|, but "waittime" cannot
214be given, since that only applies to opening the channel.
Bram Moolenaar4d919d72016-02-05 22:36:41 +0100215
Bram Moolenaar02e83b42016-02-21 20:10:26 +0100216For example, the handler can be added or changed: >
Bram Moolenaar38a55632016-02-15 22:07:32 +0100217 call ch_setoptions(channel, {'callback': callback})
218When "callback" is empty (zero or an empty string) the handler is removed.
219
Bram Moolenaar328da0d2016-03-04 22:22:32 +0100220After a callback has been invoked Vim will update the screen and put the
221cursor back where it belongs. Thus the callback should not need to do
222`:redraw`.
223
Bram Moolenaar38a55632016-02-15 22:07:32 +0100224The timeout can be changed: >
225 call ch_setoptions(channel, {'timeout': msec})
226<
Bram Moolenaar02e83b42016-02-21 20:10:26 +0100227 *channel-close* *E906*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100228Once done with the channel, disconnect it like this: >
Bram Moolenaar38a55632016-02-15 22:07:32 +0100229 call ch_close(channel)
230When a socket is used this will close the socket for both directions. When
231pipes are used (stdin/stdout/stderr) they are all closed. This might not be
232what you want! Stopping the job with job_stop() might be better.
Bram Moolenaar187db502016-02-27 14:44:26 +0100233All readahead is discarded, callbacks will no longer be invoked.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100234
Bram Moolenaar4f3f6682016-03-26 23:01:59 +0100235Note that a channel is closed in three stages:
236 - The I/O ends, log message: "Closing channel". There can still be queued
237 messages to read or callbacks to invoke.
238 - The readahead is cleared, log message: "Clearing channel". Some variables
239 may still reference the channel.
240 - The channel is freed, log message: "Freeing channel".
241
Bram Moolenaarcbebd482016-02-07 23:02:56 +0100242When the channel can't be opened you will get an error message. There is a
243difference between MS-Windows and Unix: On Unix when the port doesn't exist
244ch_open() fails quickly. On MS-Windows "waittime" applies.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +0200245*E898* *E901* *E902*
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100246
247If there is an error reading or writing a channel it will be closed.
Bram Moolenaar664f3cf2019-12-07 16:03:51 +0100248*E630* *E631*
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100249
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100250==============================================================================
Bram Moolenaar38a55632016-02-15 22:07:32 +01002514. Using a JSON or JS channel *channel-use*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100252
Bram Moolenaar910b8aa2016-02-16 21:03:07 +0100253If mode is JSON then a message can be sent synchronously like this: >
Bram Moolenaar8b1862a2016-02-27 19:21:24 +0100254 let response = ch_evalexpr(channel, {expr})
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100255This awaits a response from the other side.
256
Bram Moolenaar910b8aa2016-02-16 21:03:07 +0100257When mode is JS this works the same, except that the messages use
Bram Moolenaar38a55632016-02-15 22:07:32 +0100258JavaScript encoding. See |js_encode()| for the difference.
Bram Moolenaar595e64e2016-02-07 19:19:53 +0100259
Bram Moolenaar02e83b42016-02-21 20:10:26 +0100260To send a message, without handling a response or letting the channel callback
261handle the response: >
Bram Moolenaar8b1862a2016-02-27 19:21:24 +0100262 call ch_sendexpr(channel, {expr})
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100263
264To send a message and letting the response handled by a specific function,
265asynchronously: >
Bram Moolenaar02e83b42016-02-21 20:10:26 +0100266 call ch_sendexpr(channel, {expr}, {'callback': Handler})
Bram Moolenaar38a55632016-02-15 22:07:32 +0100267
268Vim will match the response with the request using the message ID. Once the
269response is received the callback will be invoked. Further responses with the
270same ID will be ignored. If your server sends back multiple responses you
271need to send them with ID zero, they will be passed to the channel callback.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100272
273The {expr} is converted to JSON and wrapped in an array. An example of the
274message that the receiver will get when {expr} is the string "hello":
275 [12,"hello"] ~
276
277The format of the JSON sent is:
278 [{number},{expr}]
279
280In which {number} is different every time. It must be used in the response
281(if any):
282
283 [{number},{response}]
284
285This way Vim knows which sent message matches with which received message and
286can call the right handler. Also when the messages arrive out of order.
287
Bram Moolenaarf1f07922016-08-26 17:58:53 +0200288A newline character is terminating the JSON text. This can be used to
289separate the read text. For example, in Python:
290 splitidx = read_text.find('\n')
291 message = read_text[:splitidx]
292 rest = read_text[splitidx + 1:]
293
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100294The sender must always send valid JSON to Vim. Vim can check for the end of
295the message by parsing the JSON. It will only accept the message if the end
Bram Moolenaarf1f07922016-08-26 17:58:53 +0200296was received. A newline after the message is optional.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100297
298When the process wants to send a message to Vim without first receiving a
299message, it must use the number zero:
300 [0,{response}]
301
302Then channel handler will then get {response} converted to Vim types. If the
303channel does not have a handler the message is dropped.
304
Bram Moolenaar8b1862a2016-02-27 19:21:24 +0100305It is also possible to use ch_sendraw() and ch_evalraw() on a JSON or JS
306channel. The caller is then completely responsible for correct encoding and
307decoding.
Bram Moolenaarcbebd482016-02-07 23:02:56 +0100308
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100309==============================================================================
Bram Moolenaar38a55632016-02-15 22:07:32 +01003105. Channel commands *channel-commands*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100311
Bram Moolenaar910b8aa2016-02-16 21:03:07 +0100312With a JSON channel the process can send commands to Vim that will be
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100313handled by Vim internally, it does not require a handler for the channel.
314
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100315Possible commands are: *E903* *E904* *E905*
Bram Moolenaar220adb12016-09-12 12:17:26 +0200316 ["redraw", {forced}]
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100317 ["ex", {Ex command}]
318 ["normal", {Normal mode command}]
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100319 ["expr", {expression}, {number}]
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100320 ["expr", {expression}]
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100321 ["call", {func name}, {argument list}, {number}]
322 ["call", {func name}, {argument list}]
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100323
324With all of these: Be careful what these commands do! You can easily
325interfere with what the user is doing. To avoid trouble use |mode()| to check
326that the editor is in the expected state. E.g., to send keys that must be
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100327inserted as text, not executed as a command:
328 ["ex","if mode() == 'i' | call feedkeys('ClassName') | endif"] ~
329
330Errors in these commands are normally not reported to avoid them messing up
331the display. If you do want to see them, set the 'verbose' option to 3 or
332higher.
333
334
335Command "redraw" ~
336
Bram Moolenaar63b74a82019-03-24 15:09:13 +0100337The other commands do not explicitly update the screen, so that you can send a
338sequence of commands without the cursor moving around. A redraw can happen as
339a side effect of some commands. You must end with the "redraw" command to
340show any changed text and show the cursor where it belongs.
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100341
342The argument is normally an empty string:
343 ["redraw", ""] ~
344To first clear the screen pass "force":
345 ["redraw", "force"] ~
346
347
348Command "ex" ~
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100349
350The "ex" command is executed as any Ex command. There is no response for
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100351completion or error. You could use functions in an |autoload| script:
352 ["ex","call myscript#MyFunc(arg)"]
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100353
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100354You can also use "call |feedkeys()|" to insert any key sequence.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100355
Bram Moolenaar4f3f6682016-03-26 23:01:59 +0100356When there is an error a message is written to the channel log, if it exists,
357and v:errmsg is set to the error.
358
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100359
360Command "normal" ~
361
Bram Moolenaar681baaf2016-02-04 20:57:07 +0100362The "normal" command is executed like with ":normal!", commands are not
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100363mapped. Example to open the folds under the cursor:
364 ["normal" "zO"]
365
366
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100367Command "expr" with response ~
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100368
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100369The "expr" command can be used to get the result of an expression. For
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100370example, to get the number of lines in the current buffer:
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100371 ["expr","line('$')", -2] ~
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100372
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100373It will send back the result of the expression:
Bram Moolenaare0fa3742016-02-20 15:47:01 +0100374 [-2, "last line"] ~
375The format is:
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100376 [{number}, {result}]
Bram Moolenaar187db502016-02-27 14:44:26 +0100377
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100378Here {number} is the same as what was in the request. Use a negative number
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100379to avoid confusion with message that Vim sends. Use a different number on
380every request to be able to match the request with the response.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100381
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100382{result} is the result of the evaluation and is JSON encoded. If the
Bram Moolenaar595e64e2016-02-07 19:19:53 +0100383evaluation fails or the result can't be encoded in JSON it is the string
384"ERROR".
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100385
386
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100387Command "expr" without a response ~
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100388
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100389This command is similar to "expr" above, but does not send back any response.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100390Example:
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100391 ["expr","setline('$', ['one', 'two', 'three'])"] ~
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100392There is no third argument in the request.
393
394
395Command "call" ~
396
397This is similar to "expr", but instead of passing the whole expression as a
398string this passes the name of a function and a list of arguments. This
399avoids the conversion of the arguments to a string and escaping and
400concatenating them. Example:
401 ["call", "line", ["$"], -2] ~
402
403Leave out the fourth argument if no response is to be sent:
404 ["call", "setline", ["$", ["one", "two", "three"]]] ~
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100405
406==============================================================================
Bram Moolenaar38a55632016-02-15 22:07:32 +01004076. Using a RAW or NL channel *channel-raw*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100408
Bram Moolenaarc0514bf2016-11-17 14:50:09 +0100409If mode is RAW or NL then a message can be sent like this: >
Bram Moolenaar8b1862a2016-02-27 19:21:24 +0100410 let response = ch_evalraw(channel, {string})
Bram Moolenaar910b8aa2016-02-16 21:03:07 +0100411
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100412The {string} is sent as-is. The response will be what can be read from the
413channel right away. Since Vim doesn't know how to recognize the end of the
Bram Moolenaar38a55632016-02-15 22:07:32 +0100414message you need to take care of it yourself. The timeout applies for reading
415the first byte, after that it will not wait for anything more.
416
Bram Moolenaar910b8aa2016-02-16 21:03:07 +0100417If mode is "nl" you can send a message in a similar way. You are expected
Bram Moolenaar38a55632016-02-15 22:07:32 +0100418to put in the NL after each message. Thus you can also send several messages
419ending in a NL at once. The response will be the text up to and including the
420first NL. This can also be just the NL for an empty response.
421If no NL was read before the channel timeout an empty string is returned.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100422
423To send a message, without expecting a response: >
Bram Moolenaar8b1862a2016-02-27 19:21:24 +0100424 call ch_sendraw(channel, {string})
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100425The process can send back a response, the channel handler will be called with
426it.
427
Yegappan Lakshmanan3b470ae2022-04-16 10:41:27 +0100428 *channel-onetime-callback*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100429To send a message and letting the response handled by a specific function,
430asynchronously: >
Bram Moolenaar8b1862a2016-02-27 19:21:24 +0100431 call ch_sendraw(channel, {string}, {'callback': 'MyHandler'})
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100432
Bram Moolenaar38a55632016-02-15 22:07:32 +0100433This {string} can also be JSON, use |json_encode()| to create it and
434|json_decode()| to handle a received JSON message.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100435
Bram Moolenaar8b1862a2016-02-27 19:21:24 +0100436It is not possible to use |ch_evalexpr()| or |ch_sendexpr()| on a raw channel.
Bram Moolenaarcbebd482016-02-07 23:02:56 +0100437
Bram Moolenaar818078d2016-08-27 21:58:42 +0200438A String in Vim cannot contain NUL bytes. To send or receive NUL bytes read
439or write from a buffer. See |in_io-buffer| and |out_io-buffer|.
440
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100441==============================================================================
Bram Moolenaar38a55632016-02-15 22:07:32 +01004427. More channel functions *channel-more*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100443
Bram Moolenaar38a55632016-02-15 22:07:32 +0100444To obtain the status of a channel: ch_status(channel). The possible results
445are:
446 "fail" Failed to open the channel.
447 "open" The channel can be used.
Bram Moolenaar06481422016-04-30 15:13:38 +0200448 "buffered" The channel was closed but there is data to read.
Bram Moolenaar38a55632016-02-15 22:07:32 +0100449 "closed" The channel was closed.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100450
Bram Moolenaar187db502016-02-27 14:44:26 +0100451To obtain the job associated with a channel: ch_getjob(channel)
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100452
Bram Moolenaar38a55632016-02-15 22:07:32 +0100453To read one message from a channel: >
454 let output = ch_read(channel)
455This uses the channel timeout. To read without a timeout, just get any
456message that is available: >
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100457 let output = ch_read(channel, {'timeout': 0})
Bram Moolenaar38a55632016-02-15 22:07:32 +0100458When no message was available then the result is v:none for a JSON or JS mode
Bram Moolenaar4b785f62016-11-29 21:54:44 +0100459channels, an empty string for a RAW or NL channel. You can use |ch_canread()|
460to check if there is something to read.
461
Bram Moolenaar05aafed2017-08-11 19:12:11 +0200462Note that when there is no callback, messages are dropped. To avoid that add
463a close callback to the channel.
Bram Moolenaar38a55632016-02-15 22:07:32 +0100464
Yegappan Lakshmanan9247a222022-03-30 10:16:05 +0100465To read all normal output from a RAW channel that is available: >
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100466 let output = ch_readraw(channel)
Bram Moolenaar38a55632016-02-15 22:07:32 +0100467To read the error output: >
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100468 let output = ch_readraw(channel, {"part": "err"})
Bram Moolenaar38a55632016-02-15 22:07:32 +0100469
Bram Moolenaar4f3f6682016-03-26 23:01:59 +0100470ch_read() and ch_readraw() use the channel timeout. When there is nothing to
471read within that time an empty string is returned. To specify a different
472timeout in msec use the "timeout" option:
473 {"timeout": 123} ~
474To read from the error output use the "part" option:
475 {"part": "err"} ~
476To read a message with a specific ID, on a JS or JSON channel:
477 {"id": 99} ~
478When no ID is specified or the ID is -1, the first message is returned. This
479overrules any callback waiting for this message.
480
481For a RAW channel this returns whatever is available, since Vim does not know
482where a message ends.
483For a NL channel this returns one message.
484For a JS or JSON channel this returns one decoded message.
485This includes any sequence number.
486
Bram Moolenaar38a55632016-02-15 22:07:32 +0100487==============================================================================
Bram Moolenaar54775062019-07-31 21:07:14 +02004888. Channel functions details *channel-functions-details*
Bram Moolenaared997ad2019-07-21 16:42:00 +0200489
490ch_canread({handle}) *ch_canread()*
491 Return non-zero when there is something to read from {handle}.
492 {handle} can be a Channel or a Job that has a Channel.
493
494 This is useful to read from a channel at a convenient time,
495 e.g. from a timer.
496
497 Note that messages are dropped when the channel does not have
498 a callback. Add a close callback to avoid that.
499
Bram Moolenaar570497a2019-08-22 22:55:13 +0200500 Can also be used as a |method|: >
501 GetChannel()->ch_canread()
Bram Moolenaared997ad2019-07-21 16:42:00 +0200502
503ch_close({handle}) *ch_close()*
504 Close {handle}. See |channel-close|.
505 {handle} can be a Channel or a Job that has a Channel.
506 A close callback is not invoked.
507
Bram Moolenaar570497a2019-08-22 22:55:13 +0200508 Can also be used as a |method|: >
509 GetChannel()->ch_close()
Bram Moolenaared997ad2019-07-21 16:42:00 +0200510
511ch_close_in({handle}) *ch_close_in()*
512 Close the "in" part of {handle}. See |channel-close-in|.
513 {handle} can be a Channel or a Job that has a Channel.
514 A close callback is not invoked.
515
Bram Moolenaar570497a2019-08-22 22:55:13 +0200516 Can also be used as a |method|: >
517 GetChannel()->ch_close_in()
518
Bram Moolenaared997ad2019-07-21 16:42:00 +0200519
520ch_evalexpr({handle}, {expr} [, {options}]) *ch_evalexpr()*
521 Send {expr} over {handle}. The {expr} is encoded
522 according to the type of channel. The function cannot be used
523 with a raw channel. See |channel-use|.
524 {handle} can be a Channel or a Job that has a Channel.
Yegappan Lakshmanan9247a222022-03-30 10:16:05 +0100525 When using the "lsp" channel mode, {expr} must be a |Dict|.
Bram Moolenaared997ad2019-07-21 16:42:00 +0200526 *E917*
527 {options} must be a Dictionary. It must not have a "callback"
528 entry. It can have a "timeout" entry to specify the timeout
529 for this specific request.
530
531 ch_evalexpr() waits for a response and returns the decoded
532 expression. When there is an error or timeout it returns an
Yegappan Lakshmanane0805b82022-04-16 15:18:23 +0100533 empty |String| or, when using the "lsp" channel mode, returns an
534 empty |Dict|.
Bram Moolenaared997ad2019-07-21 16:42:00 +0200535
Bram Moolenaar8fe10002019-09-11 22:56:44 +0200536 Note that while waiting for the response, Vim handles other
537 messages. You need to make sure this doesn't cause trouble.
538
Bram Moolenaar570497a2019-08-22 22:55:13 +0200539 Can also be used as a |method|: >
540 GetChannel()->ch_evalexpr(expr)
541
Bram Moolenaared997ad2019-07-21 16:42:00 +0200542
543ch_evalraw({handle}, {string} [, {options}]) *ch_evalraw()*
544 Send {string} over {handle}.
545 {handle} can be a Channel or a Job that has a Channel.
546
547 Works like |ch_evalexpr()|, but does not encode the request or
548 decode the response. The caller is responsible for the
549 correct contents. Also does not add a newline for a channel
550 in NL mode, the caller must do that. The NL in the response
551 is removed.
552 Note that Vim does not know when the text received on a raw
553 channel is complete, it may only return the first part and you
554 need to use |ch_readraw()| to fetch the rest.
555 See |channel-use|.
556
Bram Moolenaar570497a2019-08-22 22:55:13 +0200557 Can also be used as a |method|: >
558 GetChannel()->ch_evalraw(rawstring)
Bram Moolenaared997ad2019-07-21 16:42:00 +0200559
560ch_getbufnr({handle}, {what}) *ch_getbufnr()*
Bram Moolenaar6aa57292021-08-14 21:25:52 +0200561 Get the buffer number that {handle} is using for String {what}.
Bram Moolenaared997ad2019-07-21 16:42:00 +0200562 {handle} can be a Channel or a Job that has a Channel.
563 {what} can be "err" for stderr, "out" for stdout or empty for
564 socket output.
565 Returns -1 when there is no buffer.
566
Bram Moolenaar570497a2019-08-22 22:55:13 +0200567 Can also be used as a |method|: >
568 GetChannel()->ch_getbufnr(what)
Bram Moolenaared997ad2019-07-21 16:42:00 +0200569
570ch_getjob({channel}) *ch_getjob()*
571 Get the Job associated with {channel}.
572 If there is no job calling |job_status()| on the returned Job
573 will result in "fail".
574
Bram Moolenaar570497a2019-08-22 22:55:13 +0200575 Can also be used as a |method|: >
576 GetChannel()->ch_getjob()
577
Bram Moolenaared997ad2019-07-21 16:42:00 +0200578
579ch_info({handle}) *ch_info()*
580 Returns a Dictionary with information about {handle}. The
581 items are:
582 "id" number of the channel
583 "status" "open", "buffered" or "closed", like
584 ch_status()
585 When opened with ch_open():
586 "hostname" the hostname of the address
587 "port" the port of the address
LemonBoycc766a82022-04-04 15:46:58 +0100588 "path" the path of the Unix-domain socket
Bram Moolenaared997ad2019-07-21 16:42:00 +0200589 "sock_status" "open" or "closed"
590 "sock_mode" "NL", "RAW", "JSON" or "JS"
591 "sock_io" "socket"
592 "sock_timeout" timeout in msec
LemonBoycc766a82022-04-04 15:46:58 +0100593
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +0100594 Note that "path" is only present for Unix-domain sockets, for
LemonBoycc766a82022-04-04 15:46:58 +0100595 regular ones "hostname" and "port" are present instead.
596
Bram Moolenaared997ad2019-07-21 16:42:00 +0200597 When opened with job_start():
598 "out_status" "open", "buffered" or "closed"
599 "out_mode" "NL", "RAW", "JSON" or "JS"
600 "out_io" "null", "pipe", "file" or "buffer"
601 "out_timeout" timeout in msec
602 "err_status" "open", "buffered" or "closed"
603 "err_mode" "NL", "RAW", "JSON" or "JS"
604 "err_io" "out", "null", "pipe", "file" or "buffer"
605 "err_timeout" timeout in msec
606 "in_status" "open" or "closed"
Yegappan Lakshmanan9247a222022-03-30 10:16:05 +0100607 "in_mode" "NL", "RAW", "JSON", "JS" or "LSP"
Bram Moolenaared997ad2019-07-21 16:42:00 +0200608 "in_io" "null", "pipe", "file" or "buffer"
609 "in_timeout" timeout in msec
610
Bram Moolenaar570497a2019-08-22 22:55:13 +0200611 Can also be used as a |method|: >
612 GetChannel()->ch_info()
613
Bram Moolenaared997ad2019-07-21 16:42:00 +0200614
615ch_log({msg} [, {handle}]) *ch_log()*
Bram Moolenaar6aa57292021-08-14 21:25:52 +0200616 Write String {msg} in the channel log file, if it was opened
617 with |ch_logfile()|.
Bram Moolenaared997ad2019-07-21 16:42:00 +0200618 When {handle} is passed the channel number is used for the
619 message.
620 {handle} can be a Channel or a Job that has a Channel. The
621 Channel must be open for the channel number to be used.
622
Bram Moolenaar570497a2019-08-22 22:55:13 +0200623 Can also be used as a |method|: >
624 'did something'->ch_log()
625
Bram Moolenaared997ad2019-07-21 16:42:00 +0200626
627ch_logfile({fname} [, {mode}]) *ch_logfile()*
628 Start logging channel activity to {fname}.
629 When {fname} is an empty string: stop logging.
630
Bram Moolenaar1d97db32022-06-04 22:15:54 +0100631 When {mode} is omitted or contains "a" or is "o" then append
632 to the file.
633 When {mode} contains "w" and not "a" start with an empty file.
634 When {mode} contains "o" then log all terminal output.
635 Otherwise only some interesting terminal output is logged.
Bram Moolenaared997ad2019-07-21 16:42:00 +0200636
637 Use |ch_log()| to write log messages. The file is flushed
638 after every message, on Unix you can use "tail -f" to see what
639 is going on in real time.
640
Bram Moolenaar077cc7a2020-09-04 16:35:35 +0200641 To enable the log very early, to see what is received from a
Bram Moolenaar1d97db32022-06-04 22:15:54 +0100642 terminal during startup, use |--log| (this uses mode "ao"): >
Bram Moolenaarc9a9a0a2022-04-12 15:09:23 +0100643 vim --log logfile
Bram Moolenaar077cc7a2020-09-04 16:35:35 +0200644<
Bram Moolenaared997ad2019-07-21 16:42:00 +0200645 This function is not available in the |sandbox|.
646 NOTE: the channel communication is stored in the file, be
647 aware that this may contain confidential and privacy sensitive
648 information, e.g. a password you type in a terminal window.
649
Bram Moolenaar570497a2019-08-22 22:55:13 +0200650 Can also be used as a |method|: >
651 'logfile'->ch_logfile('w')
652
Bram Moolenaared997ad2019-07-21 16:42:00 +0200653
654ch_open({address} [, {options}]) *ch_open()*
655 Open a channel to {address}. See |channel|.
656 Returns a Channel. Use |ch_status()| to check for failure.
657
LemonBoycc766a82022-04-04 15:46:58 +0100658 {address} is a String, see |channel-address| for the possible
659 accepted forms.
Bram Moolenaarbfe13cc2020-04-12 17:53:12 +0200660
Bram Moolenaared997ad2019-07-21 16:42:00 +0200661 If {options} is given it must be a |Dictionary|.
662 See |channel-open-options|.
663
Bram Moolenaar570497a2019-08-22 22:55:13 +0200664 Can also be used as a |method|: >
665 GetAddress()->ch_open()
666
Bram Moolenaared997ad2019-07-21 16:42:00 +0200667
668ch_read({handle} [, {options}]) *ch_read()*
669 Read from {handle} and return the received message.
670 {handle} can be a Channel or a Job that has a Channel.
671 For a NL channel this waits for a NL to arrive, except when
672 there is nothing more to read (channel was closed).
673 See |channel-more|.
674
Bram Moolenaar570497a2019-08-22 22:55:13 +0200675 Can also be used as a |method|: >
676 GetChannel()->ch_read()
677
Bram Moolenaared997ad2019-07-21 16:42:00 +0200678
679ch_readblob({handle} [, {options}]) *ch_readblob()*
680 Like ch_read() but reads binary data and returns a |Blob|.
681 See |channel-more|.
682
Bram Moolenaar570497a2019-08-22 22:55:13 +0200683 Can also be used as a |method|: >
684 GetChannel()->ch_readblob()
685
Bram Moolenaared997ad2019-07-21 16:42:00 +0200686
687ch_readraw({handle} [, {options}]) *ch_readraw()*
688 Like ch_read() but for a JS and JSON channel does not decode
689 the message. For a NL channel it does not block waiting for
690 the NL to arrive, but otherwise works like ch_read().
691 See |channel-more|.
692
Bram Moolenaar570497a2019-08-22 22:55:13 +0200693 Can also be used as a |method|: >
694 GetChannel()->ch_readraw()
695
Bram Moolenaared997ad2019-07-21 16:42:00 +0200696
697ch_sendexpr({handle}, {expr} [, {options}]) *ch_sendexpr()*
698 Send {expr} over {handle}. The {expr} is encoded
699 according to the type of channel. The function cannot be used
700 with a raw channel.
701 See |channel-use|. *E912*
702 {handle} can be a Channel or a Job that has a Channel.
Yegappan Lakshmanan9247a222022-03-30 10:16:05 +0100703 When using the "lsp" channel mode, {expr} must be a |Dict|.
Bram Moolenaared997ad2019-07-21 16:42:00 +0200704
Yegappan Lakshmanan3b470ae2022-04-16 10:41:27 +0100705 If the channel mode is "lsp", then returns a Dict. Otherwise
706 returns an empty String. If the "callback" item is present in
707 {options}, then the returned Dict contains the ID of the
708 request message. The ID can be used to send a cancellation
Yegappan Lakshmanane0805b82022-04-16 15:18:23 +0100709 request to the LSP server (if needed). Returns an empty Dict
710 on error.
Yegappan Lakshmanan3b470ae2022-04-16 10:41:27 +0100711
712 If a response message is not expected for {expr}, then don't
713 specify the "callback" item in {options}.
714
Bram Moolenaar570497a2019-08-22 22:55:13 +0200715 Can also be used as a |method|: >
716 GetChannel()->ch_sendexpr(expr)
717
Bram Moolenaared997ad2019-07-21 16:42:00 +0200718
719ch_sendraw({handle}, {expr} [, {options}]) *ch_sendraw()*
720 Send |String| or |Blob| {expr} over {handle}.
721 Works like |ch_sendexpr()|, but does not encode the request or
722 decode the response. The caller is responsible for the
723 correct contents. Also does not add a newline for a channel
724 in NL mode, the caller must do that. The NL in the response
725 is removed.
726 See |channel-use|.
727
Bram Moolenaar570497a2019-08-22 22:55:13 +0200728 Can also be used as a |method|: >
729 GetChannel()->ch_sendraw(rawexpr)
730
Bram Moolenaared997ad2019-07-21 16:42:00 +0200731
732ch_setoptions({handle}, {options}) *ch_setoptions()*
733 Set options on {handle}:
734 "callback" the channel callback
735 "timeout" default read timeout in msec
736 "mode" mode for the whole channel
737 See |ch_open()| for more explanation.
738 {handle} can be a Channel or a Job that has a Channel.
739
740 Note that changing the mode may cause queued messages to be
741 lost.
742
743 These options cannot be changed:
744 "waittime" only applies to |ch_open()|
745
Bram Moolenaar570497a2019-08-22 22:55:13 +0200746 Can also be used as a |method|: >
747 GetChannel()->ch_setoptions(options)
748
Bram Moolenaared997ad2019-07-21 16:42:00 +0200749
750ch_status({handle} [, {options}]) *ch_status()*
751 Return the status of {handle}:
752 "fail" failed to open the channel
753 "open" channel can be used
754 "buffered" channel can be read, not written to
755 "closed" channel can not be used
756 {handle} can be a Channel or a Job that has a Channel.
757 "buffered" is used when the channel was closed but there is
758 still data that can be obtained with |ch_read()|.
759
760 If {options} is given it can contain a "part" entry to specify
761 the part of the channel to return the status for: "out" or
762 "err". For example, to get the error status: >
763 ch_status(job, {"part": "err"})
764<
Bram Moolenaar570497a2019-08-22 22:55:13 +0200765 Can also be used as a |method|: >
766 GetChannel()->ch_status()
Bram Moolenaared997ad2019-07-21 16:42:00 +0200767
768==============================================================================
7699. Starting a job with a channel *job-start* *job*
Bram Moolenaar38a55632016-02-15 22:07:32 +0100770
771To start a job and open a channel for stdin/stdout/stderr: >
772 let job = job_start(command, {options})
773
774You can get the channel with: >
775 let channel = job_getchannel(job)
776
777The channel will use NL mode. If you want another mode it's best to specify
778this in {options}. When changing the mode later some text may have already
779been received and not parsed correctly.
780
781If the command produces a line of output that you want to deal with, specify
782a handler for stdout: >
Bram Moolenaard6c2f052016-03-14 23:22:59 +0100783 let job = job_start(command, {"out_cb": "MyHandler"})
Bram Moolenaar38a55632016-02-15 22:07:32 +0100784The function will be called with the channel and a message. You would define
785it like this: >
786 func MyHandler(channel, msg)
787
Bram Moolenaar02e83b42016-02-21 20:10:26 +0100788Without the handler you need to read the output with |ch_read()| or
Bram Moolenaar06481422016-04-30 15:13:38 +0200789|ch_readraw()|. You can do this in the close callback, see |read-in-close-cb|.
Bram Moolenaar38a55632016-02-15 22:07:32 +0100790
Bram Moolenaar1ccd8ff2017-08-11 19:50:37 +0200791Note that if the job exits before you read the output, the output may be lost.
792This depends on the system (on Unix this happens because closing the write end
793of a pipe causes the read end to get EOF). To avoid this make the job sleep
794for a short while before it exits.
795
Bram Moolenaard6c2f052016-03-14 23:22:59 +0100796The handler defined for "out_cb" will not receive stderr. If you want to
797handle that separately, add an "err_cb" handler: >
798 let job = job_start(command, {"out_cb": "MyHandler",
799 \ "err_cb": "ErrHandler"})
Bram Moolenaar38a55632016-02-15 22:07:32 +0100800
Bram Moolenaar02e83b42016-02-21 20:10:26 +0100801If you want to handle both stderr and stdout with one handler use the
802"callback" option: >
Bram Moolenaar664f3cf2019-12-07 16:03:51 +0100803 let job = job_start(command, {"callback": "MyHandler"})
Bram Moolenaar02e83b42016-02-21 20:10:26 +0100804
Bram Moolenaar3ec574f2017-06-13 18:12:01 +0200805Depending on the system, starting a job can put Vim in the background, the
806started job gets the focus. To avoid that, use the `foreground()` function.
807This might not always work when called early, put in the callback handler or
808use a timer to call it after the job has started.
809
Bram Moolenaar8b1862a2016-02-27 19:21:24 +0100810You can send a message to the command with ch_evalraw(). If the channel is in
811JSON or JS mode you can use ch_evalexpr().
Bram Moolenaar38a55632016-02-15 22:07:32 +0100812
813There are several options you can use, see |job-options|.
Bram Moolenaar187db502016-02-27 14:44:26 +0100814For example, to start a job and write its output in buffer "dummy": >
815 let logjob = job_start("tail -f /tmp/log",
Bram Moolenaard6c2f052016-03-14 23:22:59 +0100816 \ {'out_io': 'buffer', 'out_name': 'dummy'})
Bram Moolenaar187db502016-02-27 14:44:26 +0100817 sbuf dummy
Bram Moolenaar38a55632016-02-15 22:07:32 +0100818
Bram Moolenaar5f148ec2016-03-07 22:59:26 +0100819
820Job input from a buffer ~
Bram Moolenaar818078d2016-08-27 21:58:42 +0200821 *in_io-buffer*
Bram Moolenaar328da0d2016-03-04 22:22:32 +0100822To run a job that reads from a buffer: >
823 let job = job_start({command},
Bram Moolenaard6c2f052016-03-14 23:22:59 +0100824 \ {'in_io': 'buffer', 'in_name': 'mybuffer'})
Bram Moolenaar328da0d2016-03-04 22:22:32 +0100825<
826 *E915* *E918*
827The buffer is found by name, similar to |bufnr()|. The buffer must exist and
828be loaded when job_start() is called.
829
Bram Moolenaard6c2f052016-03-14 23:22:59 +0100830By default this reads the whole buffer. This can be changed with the "in_top"
831and "in_bot" options.
Bram Moolenaar328da0d2016-03-04 22:22:32 +0100832
Bram Moolenaard6c2f052016-03-14 23:22:59 +0100833A special mode is when "in_top" is set to zero and "in_bot" is not set: Every
Bram Moolenaar74675a62017-07-15 13:53:23 +0200834time a line is added to the buffer, the last-but-one line will be sent to the
Bram Moolenaar5f148ec2016-03-07 22:59:26 +0100835job stdin. This allows for editing the last line and sending it when pressing
836Enter.
Bram Moolenaar0874a832016-09-01 15:11:51 +0200837 *channel-close-in*
838When not using the special mode the pipe or socket will be closed after the
839last line has been written. This signals the reading end that the input
840finished. You can also use |ch_close_in()| to close it sooner.
Bram Moolenaar328da0d2016-03-04 22:22:32 +0100841
Bram Moolenaar063b9d12016-07-09 20:21:48 +0200842NUL bytes in the text will be passed to the job (internally Vim stores these
843as NL bytes).
844
Bram Moolenaar06481422016-04-30 15:13:38 +0200845
846Reading job output in the close callback ~
847 *read-in-close-cb*
848If the job can take some time and you don't need intermediate results, you can
849add a close callback and read the output there: >
850
851 func! CloseHandler(channel)
Bram Moolenaar2ec618c2016-10-01 14:47:05 +0200852 while ch_status(a:channel, {'part': 'out'}) == 'buffered'
Bram Moolenaar06481422016-04-30 15:13:38 +0200853 echomsg ch_read(a:channel)
854 endwhile
855 endfunc
856 let job = job_start(command, {'close_cb': 'CloseHandler'})
857
858You will want to do something more useful than "echomsg".
859
Bram Moolenaar38a55632016-02-15 22:07:32 +0100860==============================================================================
Bram Moolenaared997ad2019-07-21 16:42:00 +020086110. Starting a job without a channel *job-start-nochannel*
Bram Moolenaar38a55632016-02-15 22:07:32 +0100862
863To start another process without creating a channel: >
Bram Moolenaar328da0d2016-03-04 22:22:32 +0100864 let job = job_start(command,
Bram Moolenaar51628222016-12-01 23:03:28 +0100865 \ {"in_io": "null", "out_io": "null", "err_io": "null"})
Bram Moolenaar38a55632016-02-15 22:07:32 +0100866
867This starts {command} in the background, Vim does not wait for it to finish.
868
Bram Moolenaar38a55632016-02-15 22:07:32 +0100869When Vim sees that neither stdin, stdout or stderr are connected, no channel
870will be created. Often you will want to include redirection in the command to
871avoid it getting stuck.
872
873There are several options you can use, see |job-options|.
874
Bram Moolenaar77cdfd12016-03-12 12:57:59 +0100875 *job-start-if-needed*
876To start a job only when connecting to an address does not work, do something
877like this: >
Bram Moolenaar38a55632016-02-15 22:07:32 +0100878 let channel = ch_open(address, {"waittime": 0})
879 if ch_status(channel) == "fail"
880 let job = job_start(command)
881 let channel = ch_open(address, {"waittime": 1000})
Bram Moolenaar38a55632016-02-15 22:07:32 +0100882 endif
Bram Moolenaar77cdfd12016-03-12 12:57:59 +0100883
884Note that the waittime for ch_open() gives the job one second to make the port
885available.
Bram Moolenaar38a55632016-02-15 22:07:32 +0100886
887==============================================================================
Bram Moolenaared997ad2019-07-21 16:42:00 +020088811. Job functions *job-functions-details*
889
890job_getchannel({job}) *job_getchannel()*
891 Get the channel handle that {job} is using.
892 To check if the job has no channel: >
Yegappan Lakshmanan1a71d312021-07-15 12:49:58 +0200893 if string(job_getchannel(job)) == 'channel fail'
Bram Moolenaared997ad2019-07-21 16:42:00 +0200894<
Bram Moolenaar570497a2019-08-22 22:55:13 +0200895 Can also be used as a |method|: >
896 GetJob()->job_getchannel()
Bram Moolenaared997ad2019-07-21 16:42:00 +0200897
898job_info([{job}]) *job_info()*
899 Returns a Dictionary with information about {job}:
900 "status" what |job_status()| returns
901 "channel" what |job_getchannel()| returns
902 "cmd" List of command arguments used to start the job
903 "process" process ID
904 "tty_in" terminal input name, empty when none
905 "tty_out" terminal output name, empty when none
906 "exitval" only valid when "status" is "dead"
907 "exit_cb" function to be called on exit
908 "stoponexit" |job-stoponexit|
909
910 Only in Unix:
911 "termsig" the signal which terminated the process
912 (See |job_stop()| for the values)
913 only valid when "status" is "dead"
914
915 Only in MS-Windows:
916 "tty_type" Type of virtual console in use.
917 Values are "winpty" or "conpty".
918 See 'termwintype'.
919
920 Without any arguments, returns a List with all Job objects.
921
Bram Moolenaar570497a2019-08-22 22:55:13 +0200922 Can also be used as a |method|: >
923 GetJob()->job_info()
924
Bram Moolenaared997ad2019-07-21 16:42:00 +0200925
926job_setoptions({job}, {options}) *job_setoptions()*
927 Change options for {job}. Supported are:
928 "stoponexit" |job-stoponexit|
929 "exit_cb" |job-exit_cb|
930
Bram Moolenaar570497a2019-08-22 22:55:13 +0200931 Can also be used as a |method|: >
932 GetJob()->job_setoptions(options)
933
Bram Moolenaared997ad2019-07-21 16:42:00 +0200934
935job_start({command} [, {options}]) *job_start()*
936 Start a job and return a Job object. Unlike |system()| and
937 |:!cmd| this does not wait for the job to finish.
938 To start a job in a terminal window see |term_start()|.
939
940 If the job fails to start then |job_status()| on the returned
941 Job object results in "fail" and none of the callbacks will be
942 invoked.
943
944 {command} can be a String. This works best on MS-Windows. On
945 Unix it is split up in white-separated parts to be passed to
946 execvp(). Arguments in double quotes can contain white space.
947
948 {command} can be a List, where the first item is the executable
949 and further items are the arguments. All items are converted
950 to String. This works best on Unix.
951
952 On MS-Windows, job_start() makes a GUI application hidden. If
953 want to show it, Use |:!start| instead.
954
955 The command is executed directly, not through a shell, the
956 'shell' option is not used. To use the shell: >
957 let job = job_start(["/bin/sh", "-c", "echo hello"])
958< Or: >
959 let job = job_start('/bin/sh -c "echo hello"')
960< Note that this will start two processes, the shell and the
961 command it executes. If you don't want this use the "exec"
962 shell command.
963
964 On Unix $PATH is used to search for the executable only when
965 the command does not contain a slash.
966
967 The job will use the same terminal as Vim. If it reads from
968 stdin the job and Vim will be fighting over input, that
969 doesn't work. Redirect stdin and stdout to avoid problems: >
970 let job = job_start(['sh', '-c', "myserver </dev/null >/dev/null"])
971<
972 The returned Job object can be used to get the status with
973 |job_status()| and stop the job with |job_stop()|.
974
975 Note that the job object will be deleted if there are no
976 references to it. This closes the stdin and stderr, which may
977 cause the job to fail with an error. To avoid this keep a
978 reference to the job. Thus instead of: >
979 call job_start('my-command')
980< use: >
981 let myjob = job_start('my-command')
982< and unlet "myjob" once the job is not needed or is past the
983 point where it would fail (e.g. when it prints a message on
984 startup). Keep in mind that variables local to a function
985 will cease to exist if the function returns. Use a
986 script-local variable if needed: >
987 let s:myjob = job_start('my-command')
988<
989 {options} must be a Dictionary. It can contain many optional
990 items, see |job-options|.
991
Bram Moolenaar570497a2019-08-22 22:55:13 +0200992 Can also be used as a |method|: >
993 BuildCommand()->job_start()
994
Bram Moolenaared997ad2019-07-21 16:42:00 +0200995
996job_status({job}) *job_status()* *E916*
997 Returns a String with the status of {job}:
998 "run" job is running
999 "fail" job failed to start
1000 "dead" job died or was stopped after running
1001
1002 On Unix a non-existing command results in "dead" instead of
1003 "fail", because a fork happens before the failure can be
1004 detected.
1005
Bram Moolenaarcb80aa22020-10-26 21:12:46 +01001006 If in Vim9 script a variable is declared with type "job" but
1007 never assigned to, passing that variable to job_status()
1008 returns "fail".
1009
Bram Moolenaared997ad2019-07-21 16:42:00 +02001010 If an exit callback was set with the "exit_cb" option and the
1011 job is now detected to be "dead" the callback will be invoked.
1012
1013 For more information see |job_info()|.
1014
Bram Moolenaar570497a2019-08-22 22:55:13 +02001015 Can also be used as a |method|: >
1016 GetJob()->job_status()
1017
Bram Moolenaared997ad2019-07-21 16:42:00 +02001018
1019job_stop({job} [, {how}]) *job_stop()*
1020 Stop the {job}. This can also be used to signal the job.
1021
1022 When {how} is omitted or is "term" the job will be terminated.
1023 For Unix SIGTERM is sent. On MS-Windows the job will be
1024 terminated forcedly (there is no "gentle" way).
1025 This goes to the process group, thus children may also be
1026 affected.
1027
1028 Effect for Unix:
1029 "term" SIGTERM (default)
1030 "hup" SIGHUP
1031 "quit" SIGQUIT
1032 "int" SIGINT
1033 "kill" SIGKILL (strongest way to stop)
1034 number signal with that number
1035
1036 Effect for MS-Windows:
1037 "term" terminate process forcedly (default)
1038 "hup" CTRL_BREAK
1039 "quit" CTRL_BREAK
1040 "int" CTRL_C
1041 "kill" terminate process forcedly
1042 Others CTRL_BREAK
1043
1044 On Unix the signal is sent to the process group. This means
1045 that when the job is "sh -c command" it affects both the shell
1046 and the command.
1047
1048 The result is a Number: 1 if the operation could be executed,
1049 0 if "how" is not supported on the system.
1050 Note that even when the operation was executed, whether the
1051 job was actually stopped needs to be checked with
1052 |job_status()|.
1053
1054 If the status of the job is "dead", the signal will not be
1055 sent. This is to avoid to stop the wrong job (esp. on Unix,
1056 where process numbers are recycled).
1057
1058 When using "kill" Vim will assume the job will die and close
1059 the channel.
1060
Bram Moolenaar570497a2019-08-22 22:55:13 +02001061 Can also be used as a |method|: >
1062 GetJob()->job_stop()
1063
Bram Moolenaared997ad2019-07-21 16:42:00 +02001064
1065==============================================================================
106612. Job options *job-options*
Bram Moolenaar38a55632016-02-15 22:07:32 +01001067
1068The {options} argument in job_start() is a dictionary. All entries are
Bram Moolenaar02e83b42016-02-21 20:10:26 +01001069optional. Some options can be used after the job has started, using
1070job_setoptions(job, {options}). Many options can be used with the channel
1071related to the job, using ch_setoptions(channel, {options}).
1072See |job_setoptions()| and |ch_setoptions()|.
Bram Moolenaar38a55632016-02-15 22:07:32 +01001073
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01001074 *in_mode* *out_mode* *err_mode*
1075"in_mode" mode specifically for stdin, only when using pipes
1076"out_mode" mode specifically for stdout, only when using pipes
1077"err_mode" mode specifically for stderr, only when using pipes
1078 See |channel-mode| for the values.
1079
1080 Note: when setting "mode" the part specific mode is
1081 overwritten. Therefore set "mode" first and the part
1082 specific mode later.
1083
1084 Note: when writing to a file or buffer and when
1085 reading from a buffer NL mode is used by default.
1086
Bram Moolenaar0b146882018-09-06 16:27:24 +02001087 *job-noblock*
1088"noblock": 1 When writing use a non-blocking write call. This
1089 avoids getting stuck if Vim should handle other
1090 messages in between, e.g. when a job sends back data
1091 to Vim. It implies that when `ch_sendraw()` returns
1092 not all data may have been written yet.
1093 This option was added in patch 8.1.0350, test with: >
1094 if has("patch-8.1.350")
1095 let options['noblock'] = 1
1096 endif
1097<
Bram Moolenaardecb14d2016-02-20 23:32:02 +01001098 *job-callback*
1099"callback": handler Callback for something to read on any part of the
1100 channel.
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01001101 *job-out_cb* *out_cb*
Bram Moolenaard6c2f052016-03-14 23:22:59 +01001102"out_cb": handler Callback for when there is something to read on
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01001103 stdout. Only for when the channel uses pipes. When
1104 "out_cb" wasn't set the channel callback is used.
Bram Moolenaar269f5952016-07-15 22:54:41 +02001105 The two arguments are the channel and the message.
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01001106
1107 *job-err_cb* *err_cb*
Bram Moolenaard6c2f052016-03-14 23:22:59 +01001108"err_cb": handler Callback for when there is something to read on
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01001109 stderr. Only for when the channel uses pipes. When
1110 "err_cb" wasn't set the channel callback is used.
Bram Moolenaar269f5952016-07-15 22:54:41 +02001111 The two arguments are the channel and the message.
Bram Moolenaard6c2f052016-03-14 23:22:59 +01001112 *job-close_cb*
1113"close_cb": handler Callback for when the channel is closed. Same as
Bram Moolenaar82af8712016-06-04 20:20:29 +02001114 "close_cb" on |ch_open()|, see |close_cb|.
Bram Moolenaarbc2eada2017-01-02 21:27:47 +01001115 *job-drop*
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +02001116"drop": when Specifies when to drop messages. Same as "drop" on
Bram Moolenaar51628222016-12-01 23:03:28 +01001117 |ch_open()|, see |channel-drop|. For "auto" the
1118 exit_cb is not considered.
Bram Moolenaarbc2eada2017-01-02 21:27:47 +01001119 *job-exit_cb*
Bram Moolenaard6c2f052016-03-14 23:22:59 +01001120"exit_cb": handler Callback for when the job ends. The arguments are the
Bram Moolenaar38a55632016-02-15 22:07:32 +01001121 job and the exit status.
Bram Moolenaarb4ada792016-10-30 21:55:26 +01001122 Vim checks up to 10 times per second for jobs that
1123 ended. The check can also be triggered by calling
1124 |job_status()|, which may then invoke the exit_cb
1125 handler.
Bram Moolenaar06d2d382016-05-20 17:24:11 +02001126 Note that data can be buffered, callbacks may still be
1127 called after the process ends.
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01001128 *job-timeout*
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +02001129"timeout": time The time to wait for a request when blocking, E.g.
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01001130 when using ch_evalexpr(). In milliseconds. The
1131 default is 2000 (2 seconds).
1132 *out_timeout* *err_timeout*
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +02001133"out_timeout": time Timeout for stdout. Only when using pipes.
1134"err_timeout": time Timeout for stderr. Only when using pipes.
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01001135 Note: when setting "timeout" the part specific mode is
1136 overwritten. Therefore set "timeout" first and the
1137 part specific mode later.
1138
Bram Moolenaar02e83b42016-02-21 20:10:26 +01001139 *job-stoponexit*
1140"stoponexit": {signal} Send {signal} to the job when Vim exits. See
1141 |job_stop()| for possible values.
1142"stoponexit": "" Do not stop the job when Vim exits.
1143 The default is "term".
1144
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01001145 *job-term*
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +02001146"term": "open" Start a terminal in a new window and connect the job
1147 stdin/stdout/stderr to it. Similar to using
1148 `:terminal`.
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01001149 NOTE: Not implemented yet!
Bram Moolenaar38a55632016-02-15 22:07:32 +01001150
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01001151"channel": {channel} Use an existing channel instead of creating a new one.
1152 The parts of the channel that get used for the new job
1153 will be disconnected from what they were used before.
Bram Moolenaar51628222016-12-01 23:03:28 +01001154 If the channel was still used by another job this may
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01001155 cause I/O errors.
1156 Existing callbacks and other settings remain.
1157
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +02001158"pty": 1 Use a pty (pseudo-tty) instead of a pipe when
1159 possible. This is most useful in combination with a
1160 terminal window, see |terminal|.
1161 {only on Unix and Unix-like systems}
1162
Bram Moolenaard6c2f052016-03-14 23:22:59 +01001163 *job-in_io* *in_top* *in_bot* *in_name* *in_buf*
1164"in_io": "null" disconnect stdin (read from /dev/null)
1165"in_io": "pipe" stdin is connected to the channel (default)
1166"in_io": "file" stdin reads from a file
1167"in_io": "buffer" stdin reads from a buffer
1168"in_top": number when using "buffer": first line to send (default: 1)
1169"in_bot": number when using "buffer": last line to send (default: last)
1170"in_name": "/path/file" the name of the file or buffer to read from
1171"in_buf": number the number of the buffer to read from
Bram Moolenaar38a55632016-02-15 22:07:32 +01001172
Bram Moolenaard6c2f052016-03-14 23:22:59 +01001173 *job-out_io* *out_name* *out_buf*
1174"out_io": "null" disconnect stdout (goes to /dev/null)
1175"out_io": "pipe" stdout is connected to the channel (default)
1176"out_io": "file" stdout writes to a file
Bram Moolenaar51628222016-12-01 23:03:28 +01001177"out_io": "buffer" stdout appends to a buffer (see below)
Bram Moolenaard6c2f052016-03-14 23:22:59 +01001178"out_name": "/path/file" the name of the file or buffer to write to
1179"out_buf": number the number of the buffer to write to
Bram Moolenaar9f5842e2016-05-29 16:17:08 +02001180"out_modifiable": 0 when writing to a buffer, 'modifiable' will be off
1181 (see below)
Bram Moolenaar169ebb02016-09-07 23:32:23 +02001182"out_msg": 0 when writing to a new buffer, the first line will be
1183 set to "Reading from channel output..."
Bram Moolenaar38a55632016-02-15 22:07:32 +01001184
Bram Moolenaard6c2f052016-03-14 23:22:59 +01001185 *job-err_io* *err_name* *err_buf*
1186"err_io": "out" stderr messages to go to stdout
1187"err_io": "null" disconnect stderr (goes to /dev/null)
1188"err_io": "pipe" stderr is connected to the channel (default)
1189"err_io": "file" stderr writes to a file
Bram Moolenaar51628222016-12-01 23:03:28 +01001190"err_io": "buffer" stderr appends to a buffer (see below)
Bram Moolenaard6c2f052016-03-14 23:22:59 +01001191"err_name": "/path/file" the name of the file or buffer to write to
1192"err_buf": number the number of the buffer to write to
Bram Moolenaar9f5842e2016-05-29 16:17:08 +02001193"err_modifiable": 0 when writing to a buffer, 'modifiable' will be off
1194 (see below)
Bram Moolenaar169ebb02016-09-07 23:32:23 +02001195"err_msg": 0 when writing to a new buffer, the first line will be
1196 set to "Reading from channel error..."
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01001197
Bram Moolenaar7db8f6f2016-03-29 23:12:46 +02001198"block_write": number only for testing: pretend every other write to stdin
1199 will block
1200
Bram Moolenaar05aafed2017-08-11 19:12:11 +02001201"env": dict environment variables for the new process
1202"cwd": "/path/to/dir" current working directory for the new process;
1203 if the directory does not exist an error is given
1204
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01001205
1206Writing to a buffer ~
Bram Moolenaar818078d2016-08-27 21:58:42 +02001207 *out_io-buffer*
Bram Moolenaard6c2f052016-03-14 23:22:59 +01001208When the out_io or err_io mode is "buffer" and there is a callback, the text
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01001209is appended to the buffer before invoking the callback.
1210
1211When a buffer is used both for input and output, the output lines are put
1212above the last line, since the last line is what is written to the channel
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01001213input. Otherwise lines are appended below the last line.
Bram Moolenaarc7f0ebc2016-02-27 21:10:09 +01001214
Bram Moolenaar328da0d2016-03-04 22:22:32 +01001215When using JS or JSON mode with "buffer", only messages with zero or negative
1216ID will be added to the buffer, after decoding + encoding. Messages with a
1217positive number will be handled by a callback, commands are handled as usual.
1218
Bram Moolenaar82af8712016-06-04 20:20:29 +02001219The name of the buffer from "out_name" or "err_name" is compared the full name
1220of existing buffers, also after expanding the name for the current directory.
1221E.g., when a buffer was created with ":edit somename" and the buffer name is
1222"somename" it will use that buffer.
1223
1224If there is no matching buffer a new buffer is created. Use an empty name to
1225always create a new buffer. |ch_getbufnr()| can then be used to get the
1226buffer number.
Bram Moolenaarc7f0ebc2016-02-27 21:10:09 +01001227
1228For a new buffer 'buftype' is set to "nofile" and 'bufhidden' to "hide". If
1229you prefer other settings, create the buffer first and pass the buffer number.
Bram Moolenaar169ebb02016-09-07 23:32:23 +02001230 *out_modifiable* *err_modifiable*
Bram Moolenaar9f5842e2016-05-29 16:17:08 +02001231The "out_modifiable" and "err_modifiable" options can be used to set the
1232'modifiable' option off, or write to a buffer that has 'modifiable' off. That
1233means that lines will be appended to the buffer, but the user can't easily
1234change the buffer.
Bram Moolenaar169ebb02016-09-07 23:32:23 +02001235 *out_msg* *err_msg*
1236The "out_msg" option can be used to specify whether a new buffer will have the
1237first line set to "Reading from channel output...". The default is to add the
1238message. "err_msg" does the same for channel error.
1239
Bram Moolenaar9f5842e2016-05-29 16:17:08 +02001240When an existing buffer is to be written where 'modifiable' is off and the
1241"out_modifiable" or "err_modifiable" options is not zero, an error is given
1242and the buffer will not be written to.
1243
Bram Moolenaar187db502016-02-27 14:44:26 +01001244When the buffer written to is displayed in a window and the cursor is in the
1245first column of the last line, the cursor will be moved to the newly added
1246line and the window is scrolled up to show the cursor if needed.
1247
Bram Moolenaar063b9d12016-07-09 20:21:48 +02001248Undo is synced for every added line. NUL bytes are accepted (internally Vim
1249stores these as NL bytes).
Bram Moolenaar38a55632016-02-15 22:07:32 +01001250
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01001251
1252Writing to a file ~
Bram Moolenaard6c2f052016-03-14 23:22:59 +01001253 *E920*
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01001254The file is created with permissions 600 (read-write for the user, not
1255accessible for others). Use |setfperm()| to change this.
1256
1257If the file already exists it is truncated.
1258
Bram Moolenaar38a55632016-02-15 22:07:32 +01001259==============================================================================
Bram Moolenaared997ad2019-07-21 16:42:00 +0200126013. Controlling a job *job-control*
Bram Moolenaar38a55632016-02-15 22:07:32 +01001261
1262To get the status of a job: >
1263 echo job_status(job)
1264
1265To make a job stop running: >
1266 job_stop(job)
1267
1268This is the normal way to end a job. On Unix it sends a SIGTERM to the job.
1269It is possible to use other ways to stop the job, or even send arbitrary
1270signals. E.g. to force a job to stop, "kill it": >
1271 job_stop(job, "kill")
1272
1273For more options see |job_stop()|.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01001274
Bram Moolenaarf2732452018-06-03 14:47:35 +02001275==============================================================================
Bram Moolenaared997ad2019-07-21 16:42:00 +0200127614. Using a prompt buffer *prompt-buffer*
Bram Moolenaarf2732452018-06-03 14:47:35 +02001277
1278If you want to type input for the job in a Vim window you have a few options:
1279- Use a normal buffer and handle all possible commands yourself.
1280 This will be complicated, since there are so many possible commands.
1281- Use a terminal window. This works well if what you type goes directly to
1282 the job and the job output is directly displayed in the window.
1283 See |terminal-window|.
Bram Moolenaaracc22402020-06-07 21:07:18 +02001284- Use a window with a prompt buffer. This works well when entering a line for
1285 the job in Vim while displaying (possibly filtered) output from the job.
Bram Moolenaarf2732452018-06-03 14:47:35 +02001286
1287A prompt buffer is created by setting 'buftype' to "prompt". You would
1288normally only do that in a newly created buffer.
1289
1290The user can edit and enter one line of text at the very last line of the
1291buffer. When pressing Enter in the prompt line the callback set with
1292|prompt_setcallback()| is invoked. It would normally send the line to a job.
1293Another callback would receive the output from the job and display it in the
1294buffer, below the prompt (and above the next prompt).
1295
1296Only the text in the last line, after the prompt, is editable. The rest of the
1297buffer is not modifiable with Normal mode commands. It can be modified by
1298calling functions, such as |append()|. Using other commands may mess up the
1299buffer.
1300
1301After setting 'buftype' to "prompt" Vim does not automatically start Insert
1302mode, use `:startinsert` if you want to enter Insert mode, so that the user
1303can start typing a line.
1304
Bram Moolenaar077cc7a2020-09-04 16:35:35 +02001305The text of the prompt can be set with the |prompt_setprompt()| function. If
1306no prompt is set with |prompt_setprompt()|, "% " is used. You can get the
1307effective prompt text for a buffer, with |prompt_getprompt()|.
Bram Moolenaarf2732452018-06-03 14:47:35 +02001308
1309The user can go to Normal mode and navigate through the buffer. This can be
Bram Moolenaar7ff78462020-07-10 22:00:53 +02001310useful to see older output or copy text.
Bram Moolenaarf2732452018-06-03 14:47:35 +02001311
Bram Moolenaard2f3a8b2018-06-19 14:35:59 +02001312The CTRL-W key can be used to start a window command, such as CTRL-W w to
1313switch to the next window. This also works in Insert mode (use Shift-CTRL-W
1314to delete a word). When leaving the window Insert mode will be stopped. When
1315coming back to the prompt window Insert mode will be restored.
1316
Bram Moolenaarf2732452018-06-03 14:47:35 +02001317Any command that starts Insert mode, such as "a", "i", "A" and "I", will move
Bram Moolenaard2f3a8b2018-06-19 14:35:59 +02001318the cursor to the last line. "A" will move to the end of the line, "I" to the
1319start of the line.
Bram Moolenaarf2732452018-06-03 14:47:35 +02001320
Bram Moolenaaracc22402020-06-07 21:07:18 +02001321Here is an example for Unix. It starts a shell in the background and prompts
1322for the next shell command. Output from the shell is displayed above the
1323prompt. >
1324
1325 " Create a channel log so we can see what happens.
1326 call ch_logfile('logfile', 'w')
1327
Bram Moolenaar1588bc82022-03-08 21:35:07 +00001328 " Function handling a line of text that has been typed.
Bram Moolenaaracc22402020-06-07 21:07:18 +02001329 func TextEntered(text)
1330 " Send the text to a shell with Enter appended.
1331 call ch_sendraw(g:shell_job, a:text .. "\n")
1332 endfunc
Bram Moolenaarcb80aa22020-10-26 21:12:46 +01001333
Bram Moolenaar1588bc82022-03-08 21:35:07 +00001334 " Function handling output from the shell: Add it above the prompt.
Bram Moolenaaracc22402020-06-07 21:07:18 +02001335 func GotOutput(channel, msg)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001336 call append(line("$") - 1, "- " .. a:msg)
Bram Moolenaaracc22402020-06-07 21:07:18 +02001337 endfunc
1338
Bram Moolenaar1588bc82022-03-08 21:35:07 +00001339 " Function handling the shell exits: close the window.
Bram Moolenaaracc22402020-06-07 21:07:18 +02001340 func JobExit(job, status)
1341 quit!
1342 endfunc
1343
1344 " Start a shell in the background.
1345 let shell_job = job_start(["/bin/sh"], #{
1346 \ out_cb: function('GotOutput'),
1347 \ err_cb: function('GotOutput'),
1348 \ exit_cb: function('JobExit'),
1349 \ })
Bram Moolenaaracc22402020-06-07 21:07:18 +02001350
1351 new
1352 set buftype=prompt
1353 let buf = bufnr('')
1354 call prompt_setcallback(buf, function("TextEntered"))
1355 eval prompt_setprompt(buf, "shell command: ")
1356
1357 " start accepting shell commands
1358 startinsert
1359<
Bram Moolenaar1588bc82022-03-08 21:35:07 +00001360The same in |Vim9| script: >
1361
1362 vim9script
1363
1364 # Create a channel log so we can see what happens.
1365 ch_logfile('logfile', 'w')
1366
1367 var shell_job: job
1368
1369 # Function handling a line of text that has been typed.
1370 def TextEntered(text: string)
1371 # Send the text to a shell with Enter appended.
1372 ch_sendraw(shell_job, text .. "\n")
1373 enddef
1374
1375 # Function handling output from the shell: Add it above the prompt.
1376 def GotOutput(channel: channel, msg: string)
1377 append(line("$") - 1, "- " .. msg)
1378 enddef
1379
1380 # Function handling the shell exits: close the window.
1381 def JobExit(job: job, status: number)
1382 quit!
1383 enddef
1384
1385 # Start a shell in the background.
1386 shell_job = job_start(["/bin/sh"], {
1387 out_cb: GotOutput,
1388 err_cb: GotOutput,
1389 exit_cb: JobExit,
1390 })
1391
1392 new
1393 set buftype=prompt
1394 var buf = bufnr('')
1395 prompt_setcallback(buf, TextEntered)
1396 prompt_setprompt(buf, "shell command: ")
1397
1398 # start accepting shell commands
1399 startinsert
Bram Moolenaaracc22402020-06-07 21:07:18 +02001400
Yegappan Lakshmanan9247a222022-03-30 10:16:05 +01001401==============================================================================
Yegappan Lakshmanan3b470ae2022-04-16 10:41:27 +0100140215. Language Server Protocol *language-server-protocol*
Yegappan Lakshmanan9247a222022-03-30 10:16:05 +01001403
1404The language server protocol specification is available at:
1405
1406 https://microsoft.github.io/language-server-protocol/specification
1407
1408Each LSP protocol message starts with a simple HTTP header followed by the
1409payload encoded in JSON-RPC format. This is described in:
1410
1411 https://www.jsonrpc.org/specification
1412
Yegappan Lakshmanane0805b82022-04-16 15:18:23 +01001413To encode and send a LSP request/notification message in a Vim |Dict| into a
1414LSP JSON-RPC message and to receive and decode a LSP JSON-RPC
1415response/notification message into a Vim |Dict|, connect to the LSP server
1416with the |channel-mode| set to "lsp".
1417
1418For messages received on a channel with |channel-mode| set to "lsp", Vim will
1419process the HTTP header and decode the JSON-RPC payload into a Vim |Dict| type
1420and call the |channel-callback| function or the specified
1421|channel-onetime-callback| function. When sending messages on a channel using
1422the |ch_evalexpr()| or |ch_sendexpr()| functions, Vim will add the HTTP header
1423and encode the Vim expression into JSON. Refer to |json_encode()| and
1424|json_decode()| for more information about how Vim encodes and decodes the
1425builtin types into JSON.
Yegappan Lakshmanan9247a222022-03-30 10:16:05 +01001426
1427To open a channel using the 'lsp' mode, set the 'mode' item in the |ch_open()|
1428{options} argument to 'lsp'. Example: >
1429
1430 let ch = ch_open(..., #{mode: 'lsp'})
1431
1432To open a channel using the 'lsp' mode with a job, set the 'in_mode' and
1433'out_mode' items in the |job_start()| {options} argument to 'lsp'. Example: >
1434
Yegappan Lakshmanane0805b82022-04-16 15:18:23 +01001435 let cmd = ['clangd', '--background-index', '--clang-tidy']
1436 let opts = {}
1437 let opts.in_mode = 'lsp'
1438 let opts.out_mode = 'lsp'
Yegappan Lakshmanan03cca292022-04-18 14:07:46 +01001439 let opts.err_mode = 'nl'
Yegappan Lakshmanane0805b82022-04-16 15:18:23 +01001440 let opts.out_cb = function('LspOutCallback')
1441 let opts.err_cb = function('LspErrCallback')
1442 let opts.exit_cb = function('LspExitCallback')
1443 let job = job_start(cmd, opts)
Yegappan Lakshmanan9247a222022-03-30 10:16:05 +01001444
Yegappan Lakshmanan03cca292022-04-18 14:07:46 +01001445Note that if a job outputs LSP messages on stdout and non-LSP messages on
1446stderr, then the channel-callback function should handle both the message
1447formats appropriately or you should use a separate callback function for
1448"out_cb" and "err_cb" to handle them as shown above.
1449
Yegappan Lakshmanan3b470ae2022-04-16 10:41:27 +01001450To synchronously send a JSON-RPC request to the server, use the
1451|ch_evalexpr()| function. This function will wait and return the decoded
1452response message from the server. You can use either the |channel-timeout| or
Yegappan Lakshmanan9247a222022-03-30 10:16:05 +01001453the 'timeout' field in the {options} argument to control the response wait
Yegappan Lakshmanane0805b82022-04-16 15:18:23 +01001454time. If the request times out, then an empty |Dict| is returned. Example: >
Yegappan Lakshmanan9247a222022-03-30 10:16:05 +01001455
1456 let req = {}
1457 let req.method = 'textDocument/definition'
1458 let req.params = {}
1459 let req.params.textDocument = #{uri: 'a.c'}
1460 let req.params.position = #{line: 10, character: 3}
Yegappan Lakshmanane0805b82022-04-16 15:18:23 +01001461 let defs = ch_evalexpr(ch, req, #{timeout: 100})
1462 if defs->empty()
1463 ... <handle failure>
1464 endif
Yegappan Lakshmanan9247a222022-03-30 10:16:05 +01001465
1466Note that in the request message the 'id' field should not be specified. If it
1467is specified, then Vim will overwrite the value with an internally generated
1468identifier. Vim currently supports only a number type for the 'id' field.
Yegappan Lakshmanan3b470ae2022-04-16 10:41:27 +01001469The callback function will be invoked for both a successful and a failed RPC
Yegappan Lakshmanane0805b82022-04-16 15:18:23 +01001470request.
Yegappan Lakshmanan9247a222022-03-30 10:16:05 +01001471
1472To send a JSON-RPC request to the server and asynchronously process the
Yegappan Lakshmanane0805b82022-04-16 15:18:23 +01001473response, use the |ch_sendexpr()| function and supply a callback function. If
1474the "id" field is present in the request message, then Vim will overwrite it
1475with an internally generated number. This function returns a Dict with the
1476identifier used for the message. This can be used to send cancellation
1477request to the LSP server (if needed). Example: >
Yegappan Lakshmanan9247a222022-03-30 10:16:05 +01001478
1479 let req = {}
1480 let req.method = 'textDocument/hover'
Yegappan Lakshmanan3b470ae2022-04-16 10:41:27 +01001481 let req.id = 200
Yegappan Lakshmanan9247a222022-03-30 10:16:05 +01001482 let req.params = {}
1483 let req.params.textDocument = #{uri: 'a.c'}
1484 let req.params.position = #{line: 10, character: 3}
Yegappan Lakshmanane0805b82022-04-16 15:18:23 +01001485 let resp = ch_sendexpr(ch, req, #{callback: 'HoverFunc'})
Yegappan Lakshmanan9247a222022-03-30 10:16:05 +01001486
Yegappan Lakshmanane0805b82022-04-16 15:18:23 +01001487To cancel an outstanding asynchronous LSP request sent to the server using the
Bram Moolenaard592deb2022-06-17 15:42:40 +01001488|ch_sendexpr()| function, send a cancellation message to the server using the
Yegappan Lakshmanane0805b82022-04-16 15:18:23 +01001489|ch_sendexpr()| function with the ID returned by the |ch_sendexpr()| function
1490for the request. Example: >
Yegappan Lakshmanan3b470ae2022-04-16 10:41:27 +01001491
1492 " send a completion request
1493 let req = {}
1494 let req.method = 'textDocument/completion'
1495 let req.params = {}
1496 let req.params.textDocument = #{uri: 'a.c'}
1497 let req.params.position = #{line: 10, character: 3}
Yegappan Lakshmanane0805b82022-04-16 15:18:23 +01001498 let reqstatus = ch_sendexpr(ch, req, #{callback: 'LspComplete'})
Yegappan Lakshmanan3b470ae2022-04-16 10:41:27 +01001499 " send a cancellation notification
1500 let notif = {}
1501 let notif.method = '$/cancelRequest'
1502 let notif.id = reqstatus.id
1503 call ch_sendexpr(ch, notif)
1504
Yegappan Lakshmanan9247a222022-03-30 10:16:05 +01001505To send a JSON-RPC notification message to the server, use the |ch_sendexpr()|
Yegappan Lakshmanan3b470ae2022-04-16 10:41:27 +01001506function. As the server will not send a response message to the notification,
1507don't specify the "callback" item. Example: >
Yegappan Lakshmanan9247a222022-03-30 10:16:05 +01001508
1509 call ch_sendexpr(ch, #{method: 'initialized'})
1510
1511To respond to a JSON-RPC request message from the server, use the
1512|ch_sendexpr()| function. In the response message, copy the 'id' field value
1513from the server request message. Example: >
1514
1515 let resp = {}
1516 let resp.id = req.id
1517 let resp.result = 1
1518 call ch_sendexpr(ch, resp)
1519
1520The JSON-RPC notification messages from the server are delivered through the
1521|channel-callback| function.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01001522
Yegappan Lakshmanan3b470ae2022-04-16 10:41:27 +01001523Depending on the use case, you can use the ch_evalexpr(), ch_sendexpr() and
1524ch_sendraw() functions on the same channel.
1525
1526A LSP request message has the following format (expressed as a Vim Dict). The
1527"params" field is optional: >
1528
1529 {
1530 "jsonrpc": "2.0",
1531 "id": <number>,
1532 "method": <string>,
1533 "params": <list|dict>
1534 }
1535
Bram Moolenaard592deb2022-06-17 15:42:40 +01001536A LSP response message has the following format (expressed as a Vim Dict). The
Yegappan Lakshmanan3b470ae2022-04-16 10:41:27 +01001537"result" and "error" fields are optional: >
1538
1539 {
1540 "jsonrpc": "2.0",
1541 "id": <number>,
1542 "result": <vim type>
1543 "error": <dict>
1544 }
1545
1546A LSP notification message has the following format (expressed as a Vim Dict).
1547The "params" field is optional: >
1548
1549 {
1550 "jsonrpc": "2.0",
1551 "method": <string>,
1552 "params": <list|dict>
1553 }
1554
1555Depending on the use case, you can use the ch_evalexpr(), ch_sendexpr() and
1556ch_sendraw() functions on the same channel.
1557
1558A LSP request message has the following format (expressed as a Vim Dict). The
1559"params" field is optional: >
1560
1561 {
1562 "jsonrpc": "2.0",
1563 "id": <number>,
1564 "method": <string>,
1565 "params": <list|dict>
1566 }
1567
Bram Moolenaard592deb2022-06-17 15:42:40 +01001568A LSP response message has the following format (expressed as a Vim Dict). The
Yegappan Lakshmanan3b470ae2022-04-16 10:41:27 +01001569"result" and "error" fields are optional: >
1570
1571 {
1572 "jsonrpc": "2.0",
1573 "id": <number>,
1574 "result": <vim type>
1575 "error": <dict>
1576 }
1577
1578A LSP notification message has the following format (expressed as a Vim Dict).
1579The "params" field is optional: >
1580
1581 {
1582 "jsonrpc": "2.0",
1583 "method": <string>,
1584 "params": <list|dict>
1585 }
1586
Bram Moolenaar91f84f62018-07-29 15:07:52 +02001587 vim:tw=78:ts=8:noet:ft=help:norl: