Mercurial > vim

comparison runtime/doc/channel.txt @ 8285:e05e28dcb590 v7.4.1435

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f Author: Bram Moolenaar <Bram@vim.org> Date: Sat Feb 27 19:21:24 2016 +0100 patch 7.4.1435 Problem: It is confusing that ch_sendexpr() and ch_sendraw() wait for a response. Solution: Add ch_evalexpr() and ch_evalraw().
author Christian Brabandt <cb@256bit.org>
date Sat, 27 Feb 2016 19:30:04 +0100
parents 108d30ed34ba
children ac0c43e7af20
comparison
equal deleted inserted replaced
8284:ded553b5751a 8285:e05e28dcb590
1 *channel.txt* For Vim version 7.4. Last change: 2016 Feb 23 1 *channel.txt* For Vim version 7.4. Last change: 2016 Feb 27
2 2
3 3
4 VIM REFERENCE MANUAL by Bram Moolenaar 4 VIM REFERENCE MANUAL by Bram Moolenaar
5 5
6 6
72 72
73 In T1 you should see: 73 In T1 you should see:
74 === socket opened === ~ 74 === socket opened === ~
75 75
76 You can now send a message to the server: > 76 You can now send a message to the server: >
77 echo ch_sendexpr(channel, 'hello!') 77 echo ch_evalexpr(channel, 'hello!')
78 78
79 The message is received in T1 and a response is sent back to Vim. 79 The message is received in T1 and a response is sent back to Vim.
80 You can see the raw messages in T1. What Vim sends is: 80 You can see the raw messages in T1. What Vim sends is:
81 [1,"hello!"] ~ 81 [1,"hello!"] ~
82 And the response is: 82 And the response is:
99 99
100 Instead of giving a callback with every send call, it can also be specified 100 Instead of giving a callback with every send call, it can also be specified
101 when opening the channel: > 101 when opening the channel: >
102 call ch_close(channel) 102 call ch_close(channel)
103 let channel = ch_open('localhost:8765', {'callback': "MyHandler"}) 103 let channel = ch_open('localhost:8765', {'callback': "MyHandler"})
104 call ch_sendexpr(channel, 'hello!', {'callback': 0}) 104 call ch_sendexpr(channel, 'hello!')
105 105
106 ============================================================================== 106 ==============================================================================
107 3. Opening a channel *channel-open* 107 3. Opening a channel *channel-open*
108 108
109 To open a channel: > 109 To open a channel: >
169 actually uses a 1 msec timeout, that is required on many 169 actually uses a 1 msec timeout, that is required on many
170 systems. Use a larger value for a remote server, e.g. 10 170 systems. Use a larger value for a remote server, e.g. 10
171 msec at least. 171 msec at least.
172 172
173 "timeout" The time to wait for a request when blocking, E.g. when using 173 "timeout" The time to wait for a request when blocking, E.g. when using
174 ch_sendexpr(). In milliseconds. The default is 2000 (2 174 ch_evalexpr(). In milliseconds. The default is 2000 (2
175 seconds). 175 seconds).
176 *out-timeout* *err-timeout* 176 *out-timeout* *err-timeout*
177 "out-timeout" Timeout for stdout. Only when using pipes. 177 "out-timeout" Timeout for stdout. Only when using pipes.
178 "err-timeout" Timeout for stderr. Only when using pipes. 178 "err-timeout" Timeout for stderr. Only when using pipes.
179 Note: when setting "timeout" the part specific mode is 179 Note: when setting "timeout" the part specific mode is
212 212
213 ============================================================================== 213 ==============================================================================
214 4. Using a JSON or JS channel *channel-use* 214 4. Using a JSON or JS channel *channel-use*
215 215
216 If mode is JSON then a message can be sent synchronously like this: > 216 If mode is JSON then a message can be sent synchronously like this: >
217 let response = ch_sendexpr(channel, {expr}) 217 let response = ch_evalexpr(channel, {expr})
218 This awaits a response from the other side. 218 This awaits a response from the other side.
219 219
220 When mode is JS this works the same, except that the messages use 220 When mode is JS this works the same, except that the messages use
221 JavaScript encoding. See |js_encode()| for the difference. 221 JavaScript encoding. See |js_encode()| for the difference.
222 222
223 To send a message, without handling a response or letting the channel callback 223 To send a message, without handling a response or letting the channel callback
224 handle the response: > 224 handle the response: >
225 call ch_sendexpr(channel, {expr}, {'callback': 0}) 225 call ch_sendexpr(channel, {expr})
226 226
227 To send a message and letting the response handled by a specific function, 227 To send a message and letting the response handled by a specific function,
228 asynchronously: > 228 asynchronously: >
229 call ch_sendexpr(channel, {expr}, {'callback': Handler}) 229 call ch_sendexpr(channel, {expr}, {'callback': Handler})
230 230
261 261
262 On read error or ch_close(), when using a socket, the string "DETACH" is sent, 262 On read error or ch_close(), when using a socket, the string "DETACH" is sent,
263 if still possible. The channel will then be inactive. For a JSON and JS mode 263 if still possible. The channel will then be inactive. For a JSON and JS mode
264 channel quotes are used around DETACH, otherwise there are no quotes. 264 channel quotes are used around DETACH, otherwise there are no quotes.
265 265
266 It is also possible to use ch_sendraw() on a JSON or JS channel. The caller 266 It is also possible to use ch_sendraw() and ch_evalraw() on a JSON or JS
267 is then completely responsible for correct encoding and decoding. 267 channel. The caller is then completely responsible for correct encoding and
268 decoding.
268 269
269 ============================================================================== 270 ==============================================================================
270 5. Channel commands *channel-commands* 271 5. Channel commands *channel-commands*
271 272
272 With a JSON channel the process can send commands to Vim that will be 273 With a JSON channel the process can send commands to Vim that will be
361 362
362 ============================================================================== 363 ==============================================================================
363 6. Using a RAW or NL channel *channel-raw* 364 6. Using a RAW or NL channel *channel-raw*
364 365
365 If mode is RAW or NL then a message can be send like this: > 366 If mode is RAW or NL then a message can be send like this: >
366 let response = ch_sendraw(channel, {string}) 367 let response = ch_evalraw(channel, {string})
367 368
368 The {string} is sent as-is. The response will be what can be read from the 369 The {string} is sent as-is. The response will be what can be read from the
369 channel right away. Since Vim doesn't know how to recognize the end of the 370 channel right away. Since Vim doesn't know how to recognize the end of the
370 message you need to take care of it yourself. The timeout applies for reading 371 message you need to take care of it yourself. The timeout applies for reading
371 the first byte, after that it will not wait for anything more. 372 the first byte, after that it will not wait for anything more.
375 ending in a NL at once. The response will be the text up to and including the 376 ending in a NL at once. The response will be the text up to and including the
376 first NL. This can also be just the NL for an empty response. 377 first NL. This can also be just the NL for an empty response.
377 If no NL was read before the channel timeout an empty string is returned. 378 If no NL was read before the channel timeout an empty string is returned.
378 379
379 To send a message, without expecting a response: > 380 To send a message, without expecting a response: >
380 call ch_sendraw(channel, {string}, 0) 381 call ch_sendraw(channel, {string})
381 The process can send back a response, the channel handler will be called with 382 The process can send back a response, the channel handler will be called with
382 it. 383 it.
383 384
384 To send a message and letting the response handled by a specific function, 385 To send a message and letting the response handled by a specific function,
385 asynchronously: > 386 asynchronously: >
386 call ch_sendraw(channel, {string}, {callback}) 387 call ch_sendraw(channel, {string}, {'callback': 'MyHandler'})
387 388
388 This {string} can also be JSON, use |json_encode()| to create it and 389 This {string} can also be JSON, use |json_encode()| to create it and
389 |json_decode()| to handle a received JSON message. 390 |json_decode()| to handle a received JSON message.
390 391
391 It is not possible to use |ch_sendexpr()| on a raw channel. 392 It is not possible to use |ch_evalexpr()| or |ch_sendexpr()| on a raw channel.
392 393
393 ============================================================================== 394 ==============================================================================
394 7. More channel functions *channel-more* 395 7. More channel functions *channel-more*
395 396
396 To obtain the status of a channel: ch_status(channel). The possible results 397 To obtain the status of a channel: ch_status(channel). The possible results
445 446
446 If you want to handle both stderr and stdout with one handler use the 447 If you want to handle both stderr and stdout with one handler use the
447 "callback" option: > 448 "callback" option: >
448 let job = job_start(command, {"callback": "MyHandler"}) 449 let job = job_start(command, {"callback": "MyHandler"})
449 450
450 You can send a message to the command with ch_sendraw(). If the channel is in 451 You can send a message to the command with ch_evalraw(). If the channel is in
451 JSON or JS mode you can use ch_sendexpr(). 452 JSON or JS mode you can use ch_evalexpr().
452 453
453 There are several options you can use, see |job-options|. 454 There are several options you can use, see |job-options|.
454 For example, to start a job and write its output in buffer "dummy": > 455 For example, to start a job and write its output in buffer "dummy": >
455 let logjob = job_start("tail -f /tmp/log", 456 let logjob = job_start("tail -f /tmp/log",
456 \ {'out-io': 'buffer', 'out-name': 'dummy'}) 457 \ {'out-io': 'buffer', 'out-name': 'dummy'})