1- *channel.txt* For Vim version 7.4. Last change: 2016 Feb 16
1+ *channel.txt* For Vim version 7.4. Last change: 2016 Feb 20
22
33
44 VIM REFERENCE MANUAL by Bram Moolenaar
@@ -121,6 +121,13 @@ Use |ch_status()| to see if the channel could be opened.
121121 "nl" - Use messages that end in a NL character
122122 "raw" - Use raw messages
123123
124+ "in-mode" mode specifically for stdin, only when using pipes
125+ "out-mode" mode specifically for stdout, only when using pipes
126+ "err-mode" mode specifically for stderr, only when using pipes
127+ Note: when setting "mode" the part specific mode is
128+ overwritten. Therefore set "mode" first and the part specific
129+ mode later.
130+
124131 *channel-callback*
125132"callback" A function that is called when a message is received that is
126133 not handled otherwise. It gets two arguments: the channel
@@ -130,9 +137,13 @@ Use |ch_status()| to see if the channel could be opened.
130137 endfunc
131138 let channel = ch_open("localhost:8765", {"callback": "Handle"})
132139<
133- TODO:
140+ "out-cb" A function like "callback" but used for stdout. Only for when
141+ the channel uses pipes. When "out-cb" wasn't set the channel
142+ callback is used.
143+
134144"err-cb" A function like "callback" but used for stderr. Only for when
135- the channel uses pipes.
145+ the channel uses pipes. When "err-cb" wasn't set the channel
146+ callback is used.
136147
137148 TODO:
138149"close-cb" A function that is called when the channel gets closed, other
@@ -144,18 +155,23 @@ Use |ch_status()| to see if the channel could be opened.
144155 useful if the server is supposed to be running already. A
145156 negative number waits forever.
146157
147- "timeout" The time to wait for a request when blocking, using
148- ch_sendexpr(). Again in milliseconds. The default is 2000 (2
158+ "timeout" The time to wait for a request when blocking, E.g. when using
159+ ch_sendexpr(). In milliseconds. The default is 2000 (2
149160 seconds).
150161
162+ "out-timeout" Timeout for stdout. Only when using pipes.
163+ "err-timeout" Timeout for stderr. Only when using pipes.
164+ Note: when setting "timeout" the part specific mode is
165+ overwritten. Therefore set "timeout" first and the part
166+ specific mode later.
167+
151168When "mode" is "json" or "js" the "msg" argument is the body of the received
152169message, converted to Vim types.
153170When "mode" is "raw" the "msg" argument is the whole message as a string.
154171
155172When "mode" is "json" or "js" the "callback" is optional. When omitted it is
156173only possible to receive a message after sending one.
157174
158- TODO:
159175To change the channel options after opening it use ch_setoptions(). The
160176arguments are similar to what is passed to ch_open(), but "waittime" cannot be
161177given, since that only applies to opening the channel.
@@ -233,8 +249,8 @@ message, it must use the number zero:
233249Then channel handler will then get {response} converted to Vim types. If the
234250channel does not have a handler the message is dropped.
235251
236- On read error or ch_close() the string "DETACH" is sent, if still possible.
237- The channel will then be inactive.
252+ On read error or ch_close(), when using a socket, the string "DETACH" is sent,
253+ if still possible. The channel will then be inactive.
238254
239255It is also possible to use ch_sendraw() on a JSON or JS channel. The caller
240256is then completely responsible for correct encoding and decoding.
@@ -249,8 +265,10 @@ Possible commands are: *E903* *E904* *E905*
249265 ["redraw" {forced} ]
250266 ["ex", {Ex command}]
251267 ["normal", {Normal mode command}]
252- ["eval ", {expression} , {number} ]
268+ ["expr ", {expression} , {number} ]
253269 ["expr", {expression} ]
270+ ["call", {func name}, {argument list}, {number} ]
271+ ["call", {func name}, {argument list}]
254272
255273With all of these: Be careful what these commands do! You can easily
256274interfere with what the user is doing. To avoid trouble use | mode() | to check
@@ -291,27 +309,44 @@ mapped. Example to open the folds under the cursor:
291309 ["normal" "zO"]
292310
293311
294- Command "eval" ~
312+ Command "expr" with response ~
295313
296- The "eval " command an be used to get the result of an expression. For
314+ The "expr " command can be used to get the result of an expression. For
297315example, to get the number of lines in the current buffer:
298- ["eval ","line('$')"] ~
316+ ["expr ","line('$')", -2 ] ~
299317
300- it will send back the result of the expression:
318+ It will send back the result of the expression:
319+ [-2, "last line"] ~
320+ The format is:
301321 [{number} , {result} ]
322+ *E915*
302323Here {number} is the same as what was in the request. Use a negative number
303- to avoid confusion with message that Vim sends.
324+ to avoid confusion with message that Vim sends. Use a different number on
325+ every request to be able to match the request with the response.
304326
305327{result} is the result of the evaluation and is JSON encoded. If the
306328evaluation fails or the result can't be encoded in JSON it is the string
307329"ERROR".
308330
309331
310- Command "expr" ~
332+ Command "expr" without a response ~
311333
312- The "expr" command is similar to "eval" , but does not send back any response.
334+ This command is similar to "expr" above , but does not send back any response.
313335Example:
314336 ["expr","setline('$', ['one', 'two', 'three'])"] ~
337+ There is no third argument in the request.
338+
339+
340+ Command "call" ~
341+
342+ This is similar to "expr", but instead of passing the whole expression as a
343+ string this passes the name of a function and a list of arguments. This
344+ avoids the conversion of the arguments to a string and escaping and
345+ concatenating them. Example:
346+ ["call", "line", ["$"], -2] ~
347+
348+ Leave out the fourth argument if no response is to be sent:
349+ ["call", "setline", ["$", ["one", "two", "three"]]] ~
315350
316351==============================================================================
3173526. Using a RAW or NL channel *channel-raw*
@@ -356,20 +391,18 @@ are:
356391TODO:
357392To objain the job associated with a channel: ch_getjob(channel)
358393
359- TODO:
360394To read one message from a channel: >
361395 let output = ch_read(channel)
362396
363397message that is available: >
364- let output = ch_read(channel, 0 )
398+ let output = ch_read(channel, {'timeout': 0} )
365399
366400channels, an empty string for a RAW or NL channel.
367401
368- To read all output from a RAW or NL channel that is available: >
369- let output = ch_readall (channel)
402+ To read all output from a RAW channel that is available: >
403+ let output = ch_readraw (channel)
370404>
371- let output = ch_readall(channel, "err")
372-
405+ let output = ch_readraw(channel, {"part": "err"})
373406
374407==============================================================================
3754088. Starting a job with a channel *job-start* *job*
@@ -450,13 +483,15 @@ This gives the job some time to make the port available.
450483The {options} argument in job_start() is a dictionary. All entries are
451484optional. The same options can be used with job_setoptions(job, {options} ).
452485
453- TODO: *job-out-cb*
454- "callback": handler
486+ *job-callback*
487+ "callback": handler Callback for something to read on any part of the
488+ channel.
489+ *job-out-cb*
455490"out-cb": handler Callback for when there is something to read on
456491 stdout.
457- TODO: *job-err-cb*
492+ *job-err-cb*
458493"err-cb": handler Callback for when there is something to read on
459- stderr. Defaults to the same callback as "out-cb".
494+ stderr.
460495TODO: *job-close-cb*
461496"close-cb": handler Callback for when the channel is closed. Same as
462497 "close-cb" on ch_open().
0 commit comments