Mercurial > vim

comparison runtime/doc/channel.txt @ 7967:45ea5ebf3a98 v7.4.1279

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
commit https://github.com/vim/vim/commit/595e64e259faefb330866852e1b9f6168544572a Author: Bram Moolenaar <Bram@vim.org> Date: Sun Feb 7 19:19:53 2016 +0100 patch 7.4.1279 Problem: jsonencode() is not producing strict JSON. Solution: Add jsencode() and jsdecode(). Make jsonencode() and jsondecode() strict.
author Christian Brabandt <cb@256bit.org>
date Sun, 07 Feb 2016 19:30:05 +0100
parents b74549818500
children 78106b0f2c56
comparison
equal deleted inserted replaced
7966:79c5a86fcdfe 7967:45ea5ebf3a98
1 *channel.txt* For Vim version 7.4. Last change: 2016 Feb 06 1 *channel.txt* For Vim version 7.4. Last change: 2016 Feb 07
2 2
3 3
4 VIM REFERENCE MANUAL by Bram Moolenaar 4 VIM REFERENCE MANUAL by Bram Moolenaar
5 5
6 6
14 Vim current supports up to 10 simultaneous channels. 14 Vim current supports up to 10 simultaneous channels.
15 The Netbeans interface also uses a channel. |netbeans| 15 The Netbeans interface also uses a channel. |netbeans|
16 16
17 1. Demo |channel-demo| 17 1. Demo |channel-demo|
18 2. Opening a channel |channel-open| 18 2. Opening a channel |channel-open|
19 3. Using a JSON channel |channel-use| 19 3. Using a JSON or JS channel |channel-use|
20 4. Vim commands |channel-commands| 20 4. Vim commands |channel-commands|
21 5. Using a raw channel |channel-use| 21 5. Using a raw channel |channel-use|
22 6. Job control |job-control| 22 6. Job control |job-control|
23 23
24 {Vi does not have any of these features} 24 {Vi does not have any of these features}
75 75
76 {argdict} is a dictionary with optional entries: 76 {argdict} is a dictionary with optional entries:
77 77
78 "mode" can be: *channel-mode* 78 "mode" can be: *channel-mode*
79 "json" - Use JSON, see below; most convenient way. Default. 79 "json" - Use JSON, see below; most convenient way. Default.
80 "js" - Use JavaScript encoding, more efficient than JSON.
80 "raw" - Use raw messages 81 "raw" - Use raw messages
81 82
82 *channel-callback* 83 *channel-callback*
83 "callback" is a function that is called when a message is received that is not 84 "callback" is a function that is called when a message is received that is not
84 handled otherwise. It gets two arguments: the channel handle and the received 85 handled otherwise. It gets two arguments: the channel handle and the received
85 message. Example: > 86 message. Example: >
86 func Handle(handle, msg) 87 func Handle(handle, msg)
87 echo 'Received: ' . a:msg 88 echo 'Received: ' . a:msg
88 endfunc 89 endfunc
89 let handle = ch_open("localhost:8765", 'json', "Handle") 90 let handle = ch_open("localhost:8765", {"callback": "Handle"})
90 91
91 "waittime" is the time to wait for the connection to be made in milliseconds. 92 "waittime" is the time to wait for the connection to be made in milliseconds.
92 The default is zero, don't wait, which is useful if the server is supposed to 93 The default is zero, don't wait, which is useful if the server is supposed to
93 be running already. A negative number waits forever. 94 be running already. A negative number waits forever.
94 95
95 "timeout" is the time to wait for a request when blocking, using 96 "timeout" is the time to wait for a request when blocking, using
96 ch_sendexpr(). Again in milliseconds. The default is 2000 (2 seconds). 97 ch_sendexpr(). Again in milliseconds. The default is 2000 (2 seconds).
97 98
98 When "mode" is "json" the "msg" argument is the body of the received message, 99 When "mode" is "json" or "js" the "msg" argument is the body of the received
99 converted to Vim types. 100 message, converted to Vim types.
100 When "mode" is "raw" the "msg" argument is the whole message as a string. 101 When "mode" is "raw" the "msg" argument is the whole message as a string.
101 102
102 When "mode" is "json" the "callback" is optional. When omitted it is only 103 When "mode" is "json" or "js" the "callback" is optional. When omitted it is
103 possible to receive a message after sending one. 104 only possible to receive a message after sending one.
104 105
105 The handler can be added or changed later: > 106 The handler can be added or changed later: >
106 call ch_setcallback(handle, {callback}) 107 call ch_setcallback(handle, {callback})
107 When "callback" is empty (zero or an empty string) the handler is removed. 108 When "callback" is empty (zero or an empty string) the handler is removed.
108 NOT IMPLEMENTED YET 109 NOT IMPLEMENTED YET
121 122
122 If there is an error reading or writing a channel it will be closed. 123 If there is an error reading or writing a channel it will be closed.
123 *E896* *E630* *E631* 124 *E896* *E630* *E631*
124 125
125 ============================================================================== 126 ==============================================================================
126 3. Using a JSON channel *channel-use* 127 3. Using a JSON or JS channel *channel-use*
127 128
128 If {mode} is "json" then a message can be sent synchronously like this: > 129 If {mode} is "json" then a message can be sent synchronously like this: >
129 let response = ch_sendexpr(handle, {expr}) 130 let response = ch_sendexpr(handle, {expr})
130 This awaits a response from the other side. 131 This awaits a response from the other side.
132
133 When {mode} is "js" this works the same, except that the messages use
134 JavaScript encoding. See |jsencode()| for the difference.
131 135
132 To send a message, without handling a response: > 136 To send a message, without handling a response: >
133 call ch_sendexpr(handle, {expr}, 0) 137 call ch_sendexpr(handle, {expr}, 0)
134 138
135 To send a message and letting the response handled by a specific function, 139 To send a message and letting the response handled by a specific function,
229 [{number}, {result}] 233 [{number}, {result}]
230 Here {number} is the same as what was in the request. Use a negative number 234 Here {number} is the same as what was in the request. Use a negative number
231 to avoid confusion with message that Vim sends. 235 to avoid confusion with message that Vim sends.
232 236
233 {result} is the result of the evaluation and is JSON encoded. If the 237 {result} is the result of the evaluation and is JSON encoded. If the
234 evaluation fails it is the string "ERROR". 238 evaluation fails or the result can't be encoded in JSON it is the string
239 "ERROR".
235 240
236 241
237 Command "expr" ~ 242 Command "expr" ~
238 243
239 The "expr" command is similar to "eval", but does not send back any response. 244 The "expr" command is similar to "eval", but does not send back any response.