diff options
author | Bram Moolenaar <Bram@vim.org> | 2016-02-27 19:21:24 +0100 |
---|---|---|
committer | Bram Moolenaar <Bram@vim.org> | 2016-02-27 19:21:24 +0100 |
commit | 8b1862a31639becadcbbca5dc2eaa92db73e8e5f (patch) | |
tree | 32ce5d730c990033e18518441cf654fca6a9a673 /runtime | |
parent | b6ff81188d27fae774d9ad2dfb498f596d697d4b (diff) |
patch 7.4.1435v7.4.1435
Problem: It is confusing that ch_sendexpr() and ch_sendraw() wait for a
response.
Solution: Add ch_evalexpr() and ch_evalraw().
Diffstat (limited to 'runtime')
-rw-r--r-- | runtime/doc/channel.txt | 29 | ||||
-rw-r--r-- | runtime/doc/eval.txt | 45 |
2 files changed, 49 insertions, 25 deletions
diff --git a/runtime/doc/channel.txt b/runtime/doc/channel.txt index 1e6eaf5f64..4571258a41 100644 --- a/runtime/doc/channel.txt +++ b/runtime/doc/channel.txt @@ -1,4 +1,4 @@ -*channel.txt* For Vim version 7.4. Last change: 2016 Feb 23 +*channel.txt* For Vim version 7.4. Last change: 2016 Feb 27 VIM REFERENCE MANUAL by Bram Moolenaar @@ -74,7 +74,7 @@ In T1 you should see: === socket opened === ~ You can now send a message to the server: > - echo ch_sendexpr(channel, 'hello!') + echo ch_evalexpr(channel, 'hello!') The message is received in T1 and a response is sent back to Vim. You can see the raw messages in T1. What Vim sends is: @@ -101,7 +101,7 @@ Instead of giving a callback with every send call, it can also be specified when opening the channel: > call ch_close(channel) let channel = ch_open('localhost:8765', {'callback': "MyHandler"}) - call ch_sendexpr(channel, 'hello!', {'callback': 0}) + call ch_sendexpr(channel, 'hello!') ============================================================================== 3. Opening a channel *channel-open* @@ -171,7 +171,7 @@ Use |ch_status()| to see if the channel could be opened. msec at least. "timeout" The time to wait for a request when blocking, E.g. when using - ch_sendexpr(). In milliseconds. The default is 2000 (2 + ch_evalexpr(). In milliseconds. The default is 2000 (2 seconds). *out-timeout* *err-timeout* "out-timeout" Timeout for stdout. Only when using pipes. @@ -214,7 +214,7 @@ If there is an error reading or writing a channel it will be closed. 4. Using a JSON or JS channel *channel-use* If mode is JSON then a message can be sent synchronously like this: > - let response = ch_sendexpr(channel, {expr}) + let response = ch_evalexpr(channel, {expr}) This awaits a response from the other side. When mode is JS this works the same, except that the messages use @@ -222,7 +222,7 @@ JavaScript encoding. See |js_encode()| for the difference. To send a message, without handling a response or letting the channel callback handle the response: > - call ch_sendexpr(channel, {expr}, {'callback': 0}) + call ch_sendexpr(channel, {expr}) To send a message and letting the response handled by a specific function, asynchronously: > @@ -263,8 +263,9 @@ On read error or ch_close(), when using a socket, the string "DETACH" is sent, if still possible. The channel will then be inactive. For a JSON and JS mode channel quotes are used around DETACH, otherwise there are no quotes. -It is also possible to use ch_sendraw() on a JSON or JS channel. The caller -is then completely responsible for correct encoding and decoding. +It is also possible to use ch_sendraw() and ch_evalraw() on a JSON or JS +channel. The caller is then completely responsible for correct encoding and +decoding. ============================================================================== 5. Channel commands *channel-commands* @@ -363,7 +364,7 @@ Leave out the fourth argument if no response is to be sent: 6. Using a RAW or NL channel *channel-raw* If mode is RAW or NL then a message can be send like this: > - let response = ch_sendraw(channel, {string}) + let response = ch_evalraw(channel, {string}) The {string} is sent as-is. The response will be what can be read from the channel right away. Since Vim doesn't know how to recognize the end of the @@ -377,18 +378,18 @@ first NL. This can also be just the NL for an empty response. If no NL was read before the channel timeout an empty string is returned. To send a message, without expecting a response: > - call ch_sendraw(channel, {string}, 0) + call ch_sendraw(channel, {string}) The process can send back a response, the channel handler will be called with it. To send a message and letting the response handled by a specific function, asynchronously: > - call ch_sendraw(channel, {string}, {callback}) + call ch_sendraw(channel, {string}, {'callback': 'MyHandler'}) This {string} can also be JSON, use |json_encode()| to create it and |json_decode()| to handle a received JSON message. -It is not possible to use |ch_sendexpr()| on a raw channel. +It is not possible to use |ch_evalexpr()| or |ch_sendexpr()| on a raw channel. ============================================================================== 7. More channel functions *channel-more* @@ -447,8 +448,8 @@ If you want to handle both stderr and stdout with one handler use the "callback" option: > let job = job_start(command, {"callback": "MyHandler"}) -You can send a message to the command with ch_sendraw(). If the channel is in -JSON or JS mode you can use ch_sendexpr(). +You can send a message to the command with ch_evalraw(). If the channel is in +JSON or JS mode you can use ch_evalexpr(). There are several options you can use, see |job-options|. For example, to start a job and write its output in buffer "dummy": > diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 1a1da6e093..6a41c5fe63 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -1818,6 +1818,10 @@ call( {func}, {arglist} [, {dict}]) any call {func} with arguments {arglist} ceil( {expr}) Float round {expr} up ch_close( {channel}) none close {channel} +ch_evalexpr( {channel}, {expr} [, {options}]) + any evaluate {expr} on JSON {channel} +ch_evalraw( {channel}, {string} [, {options}]) + any evaluate {string} on raw {channel} ch_getjob( {channel}) Job get the Job of {channel} ch_log( {msg} [, {channel}]) none write {msg} in the channel log file ch_logfile( {fname} [, {mode}]) none start logging channel activity @@ -2692,6 +2696,31 @@ ch_close({channel}) *ch_close()* Close {channel}. See |channel-close|. {only available when compiled with the |+channel| feature} +ch_evalexpr({channel}, {expr} [, {options}]) *ch_evalexpr()* + Send {expr} over {channel}. The {expr} is encoded + according to the type of channel. The function cannot be used + with a raw channel. See |channel-use|. *E912* + *E917* + {options} must be a Dictionary. It must not have a "callback" + entry. + + ch_evalexpr() waits for a response and returns the decoded + expression. When there is an error or timeout it returns an + empty string. + + {only available when compiled with the |+channel| feature} + +ch_evalraw({channel}, {string} [, {options}]) *ch_evalraw()* + Send {string} over {channel}. + Works like |ch_evalexpr()|, but does not encode the request or + decode the response. The caller is responsible for the + correct contents. Also does not add a newline for a channel + in NL mode, the caller must do that. The NL in the response + is removed. + See |channel-use|. + + {only available when compiled with the |+channel| feature} + ch_getjob({channel}) *ch_getjob()* Get the Job associated with {channel}. If there is no job calling |job_status()| on the returned Job @@ -2769,16 +2798,11 @@ ch_sendexpr({channel}, {expr} [, {options}]) *ch_sendexpr()* according to the type of channel. The function cannot be used with a raw channel. See |channel-use|. *E912* - {options} must be a Dictionary. - When "callback" is a Funcref or the name of a function, - ch_sendexpr() returns immediately. The callback is invoked - when the response is received. See |channel-callback|. - - Without "callback" ch_sendexpr() waits for a response and - returns the decoded expression. When there is an error or - timeout it returns an empty string. - - When "callback" is zero no response is expected. + {options} must be a Dictionary. The "callback" item is a + Funcref or the name of a function it is invoked when the + response is received. See |channel-callback|. + Without "callback" the channel handler is invoked, otherwise + any received message is dropped. {only available when compiled with the |+channel| feature} @@ -7391,7 +7415,6 @@ scrollbind Compiled with 'scrollbind' support. showcmd Compiled with 'showcmd' support. signs Compiled with |:sign| support. smartindent Compiled with 'smartindent' support. -sniff Compiled with SNiFF interface support. spell Compiled with spell checking support |spell|. startuptime Compiled with |--startuptime| support. statusline Compiled with support for 'statusline', 'rulerformat' |