blob: 23687505150192173da48a426e1b3f6e35c78173 [file] [log] [blame]
Bram Moolenaar595e64e2016-02-07 19:19:53 +01001*channel.txt* For Vim version 7.4. Last change: 2016 Feb 07
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
7 Inter-process communication *channel*
8
9DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT
10
11Vim uses channels to communicate with other processes.
12A channel uses a socket. *socket-interface*
13
Bram Moolenaar681baaf2016-02-04 20:57:07 +010014Vim current supports up to 10 simultaneous channels.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010015The Netbeans interface also uses a channel. |netbeans|
16
171. Demo |channel-demo|
182. Opening a channel |channel-open|
Bram Moolenaar595e64e2016-02-07 19:19:53 +0100193. Using a JSON or JS channel |channel-use|
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100204. Vim commands |channel-commands|
215. Using a raw channel |channel-use|
226. Job control |job-control|
23
24{Vi does not have any of these features}
25{only available when compiled with the |+channel| feature}
26
27==============================================================================
281. Demo *channel-demo*
29
30This requires Python. The demo program can be found in
31$VIMRUNTIME/tools/demoserver.py
32Run it in one terminal. We will call this T1.
33
34Run Vim in another terminal. Connect to the demo server with: >
Bram Moolenaar4d919d72016-02-05 22:36:41 +010035 let handle = ch_open('localhost:8765')
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010036
37In T1 you should see:
38 === socket opened === ~
39
40You can now send a message to the server: >
Bram Moolenaar681baaf2016-02-04 20:57:07 +010041 echo ch_sendexpr(handle, 'hello!')
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010042
43The message is received in T1 and a response is sent back to Vim.
44You can see the raw messages in T1. What Vim sends is:
45 [1,"hello!"] ~
46And the response is:
47 [1,"got it"] ~
48The number will increase every time you send a message.
49
50The server can send a command to Vim. Type this on T1 (literally, including
Bram Moolenaarfb1f6262016-01-31 20:24:32 +010051the quotes):
52 ["ex","echo 'hi there'"] ~
53And you should see the message in Vim. You can move the cursor a word forward:
54 ["normal","w"] ~
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010055
56To handle asynchronous communication a callback needs to be used: >
57 func MyHandler(handle, msg)
58 echo "from the handler: " . a:msg
59 endfunc
Bram Moolenaar681baaf2016-02-04 20:57:07 +010060 call ch_sendexpr(handle, 'hello!', "MyHandler")
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010061
62Instead of giving a callback with every send call, it can also be specified
63when opening the channel: >
Bram Moolenaar681baaf2016-02-04 20:57:07 +010064 call ch_close(handle)
Bram Moolenaar4d919d72016-02-05 22:36:41 +010065 let handle = ch_open('localhost:8765', {'callback': "MyHandler"})
Bram Moolenaar681baaf2016-02-04 20:57:07 +010066 call ch_sendexpr(handle, 'hello!', 0)
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010067
68==============================================================================
692. Opening a channel *channel-open*
70
Bram Moolenaar681baaf2016-02-04 20:57:07 +010071To open a channel: >
Bram Moolenaar4d919d72016-02-05 22:36:41 +010072 let handle = ch_open({address} [, {argdict}])
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010073
74{address} has the form "hostname:port". E.g., "localhost:8765".
75
Bram Moolenaar4d919d72016-02-05 22:36:41 +010076{argdict} is a dictionary with optional entries:
77
78"mode" can be: *channel-mode*
79 "json" - Use JSON, see below; most convenient way. Default.
Bram Moolenaar595e64e2016-02-07 19:19:53 +010080 "js" - Use JavaScript encoding, more efficient than JSON.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010081 "raw" - Use raw messages
82
83 *channel-callback*
Bram Moolenaar4d919d72016-02-05 22:36:41 +010084"callback" is a function that is called when a message is received that is not
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010085handled otherwise. It gets two arguments: the channel handle and the received
86message. Example: >
87 func Handle(handle, msg)
88 echo 'Received: ' . a:msg
89 endfunc
Bram Moolenaar595e64e2016-02-07 19:19:53 +010090 let handle = ch_open("localhost:8765", {"callback": "Handle"})
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010091
Bram Moolenaar4d919d72016-02-05 22:36:41 +010092"waittime" is the time to wait for the connection to be made in milliseconds.
93The default is zero, don't wait, which is useful if the server is supposed to
94be running already. A negative number waits forever.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010095
Bram Moolenaar4d919d72016-02-05 22:36:41 +010096"timeout" is the time to wait for a request when blocking, using
Bram Moolenaar835dc632016-02-07 14:27:38 +010097ch_sendexpr(). Again in milliseconds. The default is 2000 (2 seconds).
Bram Moolenaar4d919d72016-02-05 22:36:41 +010098
Bram Moolenaar595e64e2016-02-07 19:19:53 +010099When "mode" is "json" or "js" the "msg" argument is the body of the received
100message, converted to Vim types.
Bram Moolenaar4d919d72016-02-05 22:36:41 +0100101When "mode" is "raw" the "msg" argument is the whole message as a string.
102
Bram Moolenaar595e64e2016-02-07 19:19:53 +0100103When "mode" is "json" or "js" the "callback" is optional. When omitted it is
104only possible to receive a message after sending one.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100105
106The handler can be added or changed later: >
Bram Moolenaar681baaf2016-02-04 20:57:07 +0100107 call ch_setcallback(handle, {callback})
Bram Moolenaar835dc632016-02-07 14:27:38 +0100108When "callback" is empty (zero or an empty string) the handler is removed.
Bram Moolenaar4d919d72016-02-05 22:36:41 +0100109NOT IMPLEMENTED YET
110
111The timeout can be changed later: >
112 call ch_settimeout(handle, {msec})
113NOT IMPLEMENTED YET
Bram Moolenaar835dc632016-02-07 14:27:38 +0100114 *E906*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100115Once done with the channel, disconnect it like this: >
Bram Moolenaar681baaf2016-02-04 20:57:07 +0100116 call ch_close(handle)
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100117
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100118Currently up to 10 channels can be in use at the same time. *E897*
119
Bram Moolenaarcbebd482016-02-07 23:02:56 +0100120When the channel can't be opened you will get an error message. There is a
121difference between MS-Windows and Unix: On Unix when the port doesn't exist
122ch_open() fails quickly. On MS-Windows "waittime" applies.
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100123*E898* *E899* *E900* *E901* *E902*
124
125If there is an error reading or writing a channel it will be closed.
126*E896* *E630* *E631*
127
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100128==============================================================================
Bram Moolenaar595e64e2016-02-07 19:19:53 +01001293. Using a JSON or JS channel *channel-use*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100130
131If {mode} is "json" then a message can be sent synchronously like this: >
Bram Moolenaar681baaf2016-02-04 20:57:07 +0100132 let response = ch_sendexpr(handle, {expr})
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100133This awaits a response from the other side.
134
Bram Moolenaar595e64e2016-02-07 19:19:53 +0100135When {mode} is "js" this works the same, except that the messages use
136JavaScript encoding. See |jsencode()| for the difference.
137
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100138To send a message, without handling a response: >
Bram Moolenaar681baaf2016-02-04 20:57:07 +0100139 call ch_sendexpr(handle, {expr}, 0)
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100140
141To send a message and letting the response handled by a specific function,
142asynchronously: >
Bram Moolenaar681baaf2016-02-04 20:57:07 +0100143 call ch_sendexpr(handle, {expr}, {callback})
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100144
145The {expr} is converted to JSON and wrapped in an array. An example of the
146message that the receiver will get when {expr} is the string "hello":
147 [12,"hello"] ~
148
149The format of the JSON sent is:
150 [{number},{expr}]
151
152In which {number} is different every time. It must be used in the response
153(if any):
154
155 [{number},{response}]
156
157This way Vim knows which sent message matches with which received message and
158can call the right handler. Also when the messages arrive out of order.
159
160The sender must always send valid JSON to Vim. Vim can check for the end of
161the message by parsing the JSON. It will only accept the message if the end
162was received.
163
164When the process wants to send a message to Vim without first receiving a
165message, it must use the number zero:
166 [0,{response}]
167
168Then channel handler will then get {response} converted to Vim types. If the
169channel does not have a handler the message is dropped.
170
Bram Moolenaar681baaf2016-02-04 20:57:07 +0100171On read error or ch_close() the string "DETACH" is sent, if still possible.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100172The channel will then be inactive.
173
Bram Moolenaarcbebd482016-02-07 23:02:56 +0100174It is also possible to use ch_sendraw() on a JSON or JS channel. The caller
175is then completely responsible for correct encoding and decoding.
176
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100177==============================================================================
1784. Vim commands *channel-commands*
179
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100180PARTLY IMPLEMENTED: only "ex" and "normal" work
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100181
182With a "json" channel the process can send commands to Vim that will be
183handled by Vim internally, it does not require a handler for the channel.
184
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100185Possible commands are: *E903* *E904* *E905*
186 ["redraw" {forced}]
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100187 ["ex", {Ex command}]
188 ["normal", {Normal mode command}]
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100189 ["eval", {expression}, {number}]
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100190 ["expr", {expression}]
191
192With all of these: Be careful what these commands do! You can easily
193interfere with what the user is doing. To avoid trouble use |mode()| to check
194that the editor is in the expected state. E.g., to send keys that must be
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100195inserted as text, not executed as a command:
196 ["ex","if mode() == 'i' | call feedkeys('ClassName') | endif"] ~
197
198Errors in these commands are normally not reported to avoid them messing up
199the display. If you do want to see them, set the 'verbose' option to 3 or
200higher.
201
202
203Command "redraw" ~
204
205The other commands do not update the screen, so that you can send a sequence
206of commands without the cursor moving around. You must end with the "redraw"
207command to show any changed text and show the cursor where it belongs.
208
209The argument is normally an empty string:
210 ["redraw", ""] ~
211To first clear the screen pass "force":
212 ["redraw", "force"] ~
213
214
215Command "ex" ~
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100216
217The "ex" command is executed as any Ex command. There is no response for
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100218completion or error. You could use functions in an |autoload| script:
219 ["ex","call myscript#MyFunc(arg)"]
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100220
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100221You can also use "call |feedkeys()|" to insert any key sequence.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100222
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100223
224Command "normal" ~
225
Bram Moolenaar681baaf2016-02-04 20:57:07 +0100226The "normal" command is executed like with ":normal!", commands are not
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100227mapped. Example to open the folds under the cursor:
228 ["normal" "zO"]
229
230
231Command "eval" ~
232
233The "eval" command an be used to get the result of an expression. For
234example, to get the number of lines in the current buffer:
235 ["eval","line('$')"] ~
236
237it will send back the result of the expression:
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100238 [{number}, {result}]
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100239Here {number} is the same as what was in the request. Use a negative number
240to avoid confusion with message that Vim sends.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100241
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100242{result} is the result of the evaluation and is JSON encoded. If the
Bram Moolenaar595e64e2016-02-07 19:19:53 +0100243evaluation fails or the result can't be encoded in JSON it is the string
244"ERROR".
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100245
246
247Command "expr" ~
248
249The "expr" command is similar to "eval", but does not send back any response.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100250Example:
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100251 ["expr","setline('$', ['one', 'two', 'three'])"] ~
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100252
253==============================================================================
2545. Using a raw channel *channel-raw*
255
256If {mode} is "raw" then a message can be send like this: >
Bram Moolenaar681baaf2016-02-04 20:57:07 +0100257 let response = ch_sendraw(handle, {string})
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100258The {string} is sent as-is. The response will be what can be read from the
259channel right away. Since Vim doesn't know how to recognize the end of the
260message you need to take care of it yourself.
261
262To send a message, without expecting a response: >
Bram Moolenaar681baaf2016-02-04 20:57:07 +0100263 call ch_sendraw(handle, {string}, 0)
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100264The process can send back a response, the channel handler will be called with
265it.
266
267To send a message and letting the response handled by a specific function,
268asynchronously: >
Bram Moolenaar681baaf2016-02-04 20:57:07 +0100269 call ch_sendraw(handle, {string}, {callback})
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100270
271This {string} can also be JSON, use |jsonencode()| to create it and
272|jsondecode()| to handle a received JSON message.
273
Bram Moolenaarcbebd482016-02-07 23:02:56 +0100274It is not possible to use |ch_sendexpr()| on a raw channel.
275
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100276==============================================================================
2776. Job control *job-control*
278
279NOT IMPLEMENTED YET
280
281To start another process: >
282 call startjob({command})
283
284This does not wait for {command} to exit.
285
286TODO:
287
288 let handle = startjob({command}, 's') # uses stdin/stdout
289 let handle = startjob({command}, '', {address}) # uses socket
290 let handle = startjob({command}, 'd', {address}) # start if connect fails
291
292
293 vim:tw=78:ts=8:ft=help:norl: