Bram Moolenaar | ed997ad | 2019-07-21 16:42:00 +0200 | [diff] [blame] | 1 | *channel.txt* For Vim version 8.1. Last change: 2019 Jul 21 |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 2 | |
| 3 | |
| 4 | VIM REFERENCE MANUAL by Bram Moolenaar |
| 5 | |
| 6 | |
| 7 | Inter-process communication *channel* |
| 8 | |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 9 | Vim uses channels to communicate with other processes. |
Bram Moolenaar | 269f595 | 2016-07-15 22:54:41 +0200 | [diff] [blame] | 10 | A channel uses a socket or pipes. *socket-interface* |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 11 | Jobs can be used to start processes and communicate with them. |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 12 | The Netbeans interface also uses a channel. |netbeans| |
| 13 | |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 14 | 1. Overview |job-channel-overview| |
| 15 | 2. Channel demo |channel-demo| |
| 16 | 3. Opening a channel |channel-open| |
| 17 | 4. Using a JSON or JS channel |channel-use| |
| 18 | 5. Channel commands |channel-commands| |
| 19 | 6. Using a RAW or NL channel |channel-raw| |
| 20 | 7. More channel functions |channel-more| |
Bram Moolenaar | ed997ad | 2019-07-21 16:42:00 +0200 | [diff] [blame] | 21 | 8. channel functions details |channel-functions-details| |
| 22 | 9. Starting a job with a channel |job-start| |
| 23 | 10. Starting a job without a channel |job-start-nochannel| |
| 24 | 11. Job functions |job-functions-details| |
| 25 | 12. Job options |job-options| |
| 26 | 13. Controlling a job |job-control| |
| 27 | 14. Using a prompt buffer |prompt-buffer| |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 28 | |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 29 | {only when compiled with the |+channel| feature for channel stuff} |
Bram Moolenaar | f37506f | 2016-08-31 22:22:10 +0200 | [diff] [blame] | 30 | You can check this with: `has('channel')` |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 31 | {only when compiled with the |+job| feature for job stuff} |
Bram Moolenaar | f37506f | 2016-08-31 22:22:10 +0200 | [diff] [blame] | 32 | You can check this with: `has('job')` |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 33 | |
| 34 | ============================================================================== |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 35 | 1. Overview *job-channel-overview* |
| 36 | |
| 37 | There are four main types of jobs: |
Bram Moolenaar | 50ba526 | 2016-09-22 22:33:02 +0200 | [diff] [blame] | 38 | 1. A daemon, serving several Vim instances. |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 39 | Vim connects to it with a socket. |
| 40 | 2. One job working with one Vim instance, asynchronously. |
| 41 | Uses a socket or pipes. |
| 42 | 3. A job performing some work for a short time, asynchronously. |
| 43 | Uses a socket or pipes. |
| 44 | 4. Running a filter, synchronously. |
| 45 | Uses pipes. |
| 46 | |
Bram Moolenaar | 77cdfd1 | 2016-03-12 12:57:59 +0100 | [diff] [blame] | 47 | For when using sockets See |job-start|, |job-start-nochannel| and |
| 48 | |channel-open|. For 2 and 3, one or more jobs using pipes, see |job-start|. |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 49 | For 4 use the ":{range}!cmd" command, see |filter|. |
| 50 | |
| 51 | Over the socket and pipes these protocols are available: |
| 52 | RAW nothing known, Vim cannot tell where a message ends |
| 53 | NL every message ends in a NL (newline) character |
| 54 | JSON JSON encoding |json_encode()| |
| 55 | JS JavaScript style JSON-like encoding |js_encode()| |
| 56 | |
| 57 | Common combination are: |
| 58 | - Using a job connected through pipes in NL mode. E.g., to run a style |
| 59 | checker and receive errors and warnings. |
Bram Moolenaar | 7dda86f | 2018-04-20 22:36:41 +0200 | [diff] [blame] | 60 | - Using a daemon, connecting over a socket in JSON mode. E.g. to lookup |
Bram Moolenaar | 0952131 | 2016-08-12 22:54:35 +0200 | [diff] [blame] | 61 | cross-references in a database. |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 62 | |
| 63 | ============================================================================== |
Bram Moolenaar | 2685212 | 2016-05-24 20:02:38 +0200 | [diff] [blame] | 64 | 2. Channel demo *channel-demo* *demoserver.py* |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 65 | |
| 66 | This requires Python. The demo program can be found in |
| 67 | $VIMRUNTIME/tools/demoserver.py |
| 68 | Run it in one terminal. We will call this T1. |
| 69 | |
| 70 | Run Vim in another terminal. Connect to the demo server with: > |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 71 | let channel = ch_open('localhost:8765') |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 72 | |
| 73 | In T1 you should see: |
| 74 | === socket opened === ~ |
| 75 | |
| 76 | You can now send a message to the server: > |
Bram Moolenaar | 8b1862a | 2016-02-27 19:21:24 +0100 | [diff] [blame] | 77 | echo ch_evalexpr(channel, 'hello!') |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 78 | |
| 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: |
| 81 | [1,"hello!"] ~ |
| 82 | And the response is: |
| 83 | [1,"got it"] ~ |
| 84 | The number will increase every time you send a message. |
| 85 | |
| 86 | The server can send a command to Vim. Type this on T1 (literally, including |
Bram Moolenaar | fb1f626 | 2016-01-31 20:24:32 +0100 | [diff] [blame] | 87 | the quotes): |
| 88 | ["ex","echo 'hi there'"] ~ |
| 89 | And you should see the message in Vim. You can move the cursor a word forward: |
| 90 | ["normal","w"] ~ |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 91 | |
| 92 | To handle asynchronous communication a callback needs to be used: > |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 93 | func MyHandler(channel, msg) |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 94 | echo "from the handler: " . a:msg |
| 95 | endfunc |
Bram Moolenaar | 02e83b4 | 2016-02-21 20:10:26 +0100 | [diff] [blame] | 96 | call ch_sendexpr(channel, 'hello!', {'callback': "MyHandler"}) |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 97 | Vim will not wait for a response. Now the server can send the response later |
| 98 | and MyHandler will be invoked. |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 99 | |
| 100 | Instead of giving a callback with every send call, it can also be specified |
| 101 | when opening the channel: > |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 102 | call ch_close(channel) |
| 103 | let channel = ch_open('localhost:8765', {'callback': "MyHandler"}) |
Bram Moolenaar | 8b1862a | 2016-02-27 19:21:24 +0100 | [diff] [blame] | 104 | call ch_sendexpr(channel, 'hello!') |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 105 | |
Bram Moolenaar | 328da0d | 2016-03-04 22:22:32 +0100 | [diff] [blame] | 106 | When trying out channels it's useful to see what is going on. You can tell |
| 107 | Vim to write lines in log file: > |
| 108 | call ch_logfile('channellog', 'w') |
| 109 | See |ch_logfile()|. |
| 110 | |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 111 | ============================================================================== |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 112 | 3. Opening a channel *channel-open* |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 113 | |
Bram Moolenaar | 681baaf | 2016-02-04 20:57:07 +0100 | [diff] [blame] | 114 | To open a channel: > |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 115 | let channel = ch_open({address} [, {options}]) |
Bram Moolenaar | 02e83b4 | 2016-02-21 20:10:26 +0100 | [diff] [blame] | 116 | if ch_status(channel) == "open" |
| 117 | " use the channel |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 118 | |
| 119 | Use |ch_status()| to see if the channel could be opened. |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 120 | |
| 121 | {address} has the form "hostname:port". E.g., "localhost:8765". |
| 122 | |
Bram Moolenaar | 4f3f668 | 2016-03-26 23:01:59 +0100 | [diff] [blame] | 123 | {options} is a dictionary with optional entries: *channel-open-options* |
Bram Moolenaar | 4d919d7 | 2016-02-05 22:36:41 +0100 | [diff] [blame] | 124 | |
| 125 | "mode" can be: *channel-mode* |
| 126 | "json" - Use JSON, see below; most convenient way. Default. |
Bram Moolenaar | 910b8aa | 2016-02-16 21:03:07 +0100 | [diff] [blame] | 127 | "js" - Use JS (JavaScript) encoding, more efficient than JSON. |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 128 | "nl" - Use messages that end in a NL character |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 129 | "raw" - Use raw messages |
Bram Moolenaar | d6c2f05 | 2016-03-14 23:22:59 +0100 | [diff] [blame] | 130 | *channel-callback* *E921* |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 131 | "callback" A function that is called when a message is received that is |
| 132 | not handled otherwise. It gets two arguments: the channel |
Bram Moolenaar | 02e83b4 | 2016-02-21 20:10:26 +0100 | [diff] [blame] | 133 | and the received message. Example: > |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 134 | func Handle(channel, msg) |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 135 | echo 'Received: ' . a:msg |
| 136 | endfunc |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 137 | let channel = ch_open("localhost:8765", {"callback": "Handle"}) |
| 138 | < |
Bram Moolenaar | 02e83b4 | 2016-02-21 20:10:26 +0100 | [diff] [blame] | 139 | When "mode" is "json" or "js" the "msg" argument is the body |
| 140 | of the received message, converted to Vim types. |
| 141 | When "mode" is "nl" the "msg" argument is one message, |
| 142 | excluding the NL. |
| 143 | When "mode" is "raw" the "msg" argument is the whole message |
| 144 | as a string. |
Bram Moolenaar | e18c0b3 | 2016-03-20 21:08:34 +0100 | [diff] [blame] | 145 | |
| 146 | For all callbacks: Use |function()| to bind it to arguments |
Bram Moolenaar | 4f3f668 | 2016-03-26 23:01:59 +0100 | [diff] [blame] | 147 | and/or a Dictionary. Or use the form "dict.function" to bind |
| 148 | the Dictionary. |
Bram Moolenaar | 06d2d38 | 2016-05-20 17:24:11 +0200 | [diff] [blame] | 149 | |
| 150 | Callbacks are only called at a "safe" moment, usually when Vim |
| 151 | is waiting for the user to type a character. Vim does not use |
| 152 | multi-threading. |
| 153 | |
Bram Moolenaar | d6c2f05 | 2016-03-14 23:22:59 +0100 | [diff] [blame] | 154 | *close_cb* |
| 155 | "close_cb" A function that is called when the channel gets closed, other |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 156 | than by calling ch_close(). It should be defined like this: > |
| 157 | func MyCloseHandler(channel) |
Bram Moolenaar | 06d2d38 | 2016-05-20 17:24:11 +0200 | [diff] [blame] | 158 | < Vim will invoke callbacks that handle data before invoking |
| 159 | close_cb, thus when this function is called no more data will |
Bram Moolenaar | 68e6560 | 2019-05-26 21:33:31 +0200 | [diff] [blame] | 160 | be passed to the callbacks. However, if a callback causes Vim |
| 161 | to check for messages, the close_cb may be invoked while still |
| 162 | in the callback. The plugin must handle this somehow, it can |
| 163 | be useful to know that no more data is coming. |
Bram Moolenaar | 958dc69 | 2016-12-01 15:34:12 +0100 | [diff] [blame] | 164 | *channel-drop* |
| 165 | "drop" Specifies when to drop messages: |
| 166 | "auto" When there is no callback to handle a message. |
| 167 | The "close_cb" is also considered for this. |
| 168 | "never" All messages will be kept. |
| 169 | |
Bram Moolenaar | 0b14688 | 2018-09-06 16:27:24 +0200 | [diff] [blame] | 170 | *channel-noblock* |
| 171 | "noblock" Same effect as |job-noblock|. Only matters for writing. |
| 172 | |
Bram Moolenaar | 06d2d38 | 2016-05-20 17:24:11 +0200 | [diff] [blame] | 173 | *waittime* |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 174 | "waittime" The time to wait for the connection to be made in |
Bram Moolenaar | f391327 | 2016-02-25 00:00:01 +0100 | [diff] [blame] | 175 | milliseconds. A negative number waits forever. |
| 176 | |
| 177 | The default is zero, don't wait, which is useful if a local |
| 178 | server is supposed to be running already. On Unix Vim |
| 179 | actually uses a 1 msec timeout, that is required on many |
| 180 | systems. Use a larger value for a remote server, e.g. 10 |
| 181 | msec at least. |
Bram Moolenaar | 4f3f668 | 2016-03-26 23:01:59 +0100 | [diff] [blame] | 182 | *channel-timeout* |
Bram Moolenaar | decb14d | 2016-02-20 23:32:02 +0100 | [diff] [blame] | 183 | "timeout" The time to wait for a request when blocking, E.g. when using |
Bram Moolenaar | 8b1862a | 2016-02-27 19:21:24 +0100 | [diff] [blame] | 184 | ch_evalexpr(). In milliseconds. The default is 2000 (2 |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 185 | seconds). |
Bram Moolenaar | decb14d | 2016-02-20 23:32:02 +0100 | [diff] [blame] | 186 | |
Bram Moolenaar | 595e64e | 2016-02-07 19:19:53 +0100 | [diff] [blame] | 187 | When "mode" is "json" or "js" the "callback" is optional. When omitted it is |
| 188 | only possible to receive a message after sending one. |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 189 | |
Bram Moolenaar | 02e83b4 | 2016-02-21 20:10:26 +0100 | [diff] [blame] | 190 | To change the channel options after opening it use |ch_setoptions()|. The |
| 191 | arguments are similar to what is passed to |ch_open()|, but "waittime" cannot |
| 192 | be given, since that only applies to opening the channel. |
Bram Moolenaar | 4d919d7 | 2016-02-05 22:36:41 +0100 | [diff] [blame] | 193 | |
Bram Moolenaar | 02e83b4 | 2016-02-21 20:10:26 +0100 | [diff] [blame] | 194 | For example, the handler can be added or changed: > |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 195 | call ch_setoptions(channel, {'callback': callback}) |
| 196 | When "callback" is empty (zero or an empty string) the handler is removed. |
| 197 | |
Bram Moolenaar | 328da0d | 2016-03-04 22:22:32 +0100 | [diff] [blame] | 198 | After a callback has been invoked Vim will update the screen and put the |
| 199 | cursor back where it belongs. Thus the callback should not need to do |
| 200 | `:redraw`. |
| 201 | |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 202 | The timeout can be changed: > |
| 203 | call ch_setoptions(channel, {'timeout': msec}) |
| 204 | < |
Bram Moolenaar | 02e83b4 | 2016-02-21 20:10:26 +0100 | [diff] [blame] | 205 | *channel-close* *E906* |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 206 | Once done with the channel, disconnect it like this: > |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 207 | call ch_close(channel) |
| 208 | When a socket is used this will close the socket for both directions. When |
| 209 | pipes are used (stdin/stdout/stderr) they are all closed. This might not be |
| 210 | what you want! Stopping the job with job_stop() might be better. |
Bram Moolenaar | 187db50 | 2016-02-27 14:44:26 +0100 | [diff] [blame] | 211 | All readahead is discarded, callbacks will no longer be invoked. |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 212 | |
Bram Moolenaar | 4f3f668 | 2016-03-26 23:01:59 +0100 | [diff] [blame] | 213 | Note that a channel is closed in three stages: |
| 214 | - The I/O ends, log message: "Closing channel". There can still be queued |
| 215 | messages to read or callbacks to invoke. |
| 216 | - The readahead is cleared, log message: "Clearing channel". Some variables |
| 217 | may still reference the channel. |
| 218 | - The channel is freed, log message: "Freeing channel". |
| 219 | |
Bram Moolenaar | cbebd48 | 2016-02-07 23:02:56 +0100 | [diff] [blame] | 220 | When the channel can't be opened you will get an error message. There is a |
| 221 | difference between MS-Windows and Unix: On Unix when the port doesn't exist |
| 222 | ch_open() fails quickly. On MS-Windows "waittime" applies. |
Bram Moolenaar | aa3b15d | 2016-04-21 08:53:19 +0200 | [diff] [blame] | 223 | *E898* *E901* *E902* |
Bram Moolenaar | fb1f626 | 2016-01-31 20:24:32 +0100 | [diff] [blame] | 224 | |
| 225 | If there is an error reading or writing a channel it will be closed. |
Bram Moolenaar | aa3b15d | 2016-04-21 08:53:19 +0200 | [diff] [blame] | 226 | *E630* *E631* |
Bram Moolenaar | fb1f626 | 2016-01-31 20:24:32 +0100 | [diff] [blame] | 227 | |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 228 | ============================================================================== |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 229 | 4. Using a JSON or JS channel *channel-use* |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 230 | |
Bram Moolenaar | 910b8aa | 2016-02-16 21:03:07 +0100 | [diff] [blame] | 231 | If mode is JSON then a message can be sent synchronously like this: > |
Bram Moolenaar | 8b1862a | 2016-02-27 19:21:24 +0100 | [diff] [blame] | 232 | let response = ch_evalexpr(channel, {expr}) |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 233 | This awaits a response from the other side. |
| 234 | |
Bram Moolenaar | 910b8aa | 2016-02-16 21:03:07 +0100 | [diff] [blame] | 235 | When mode is JS this works the same, except that the messages use |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 236 | JavaScript encoding. See |js_encode()| for the difference. |
Bram Moolenaar | 595e64e | 2016-02-07 19:19:53 +0100 | [diff] [blame] | 237 | |
Bram Moolenaar | 02e83b4 | 2016-02-21 20:10:26 +0100 | [diff] [blame] | 238 | To send a message, without handling a response or letting the channel callback |
| 239 | handle the response: > |
Bram Moolenaar | 8b1862a | 2016-02-27 19:21:24 +0100 | [diff] [blame] | 240 | call ch_sendexpr(channel, {expr}) |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 241 | |
| 242 | To send a message and letting the response handled by a specific function, |
| 243 | asynchronously: > |
Bram Moolenaar | 02e83b4 | 2016-02-21 20:10:26 +0100 | [diff] [blame] | 244 | call ch_sendexpr(channel, {expr}, {'callback': Handler}) |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 245 | |
| 246 | Vim will match the response with the request using the message ID. Once the |
| 247 | response is received the callback will be invoked. Further responses with the |
| 248 | same ID will be ignored. If your server sends back multiple responses you |
| 249 | need to send them with ID zero, they will be passed to the channel callback. |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 250 | |
| 251 | The {expr} is converted to JSON and wrapped in an array. An example of the |
| 252 | message that the receiver will get when {expr} is the string "hello": |
| 253 | [12,"hello"] ~ |
| 254 | |
| 255 | The format of the JSON sent is: |
| 256 | [{number},{expr}] |
| 257 | |
| 258 | In which {number} is different every time. It must be used in the response |
| 259 | (if any): |
| 260 | |
| 261 | [{number},{response}] |
| 262 | |
| 263 | This way Vim knows which sent message matches with which received message and |
| 264 | can call the right handler. Also when the messages arrive out of order. |
| 265 | |
Bram Moolenaar | f1f0792 | 2016-08-26 17:58:53 +0200 | [diff] [blame] | 266 | A newline character is terminating the JSON text. This can be used to |
| 267 | separate the read text. For example, in Python: |
| 268 | splitidx = read_text.find('\n') |
| 269 | message = read_text[:splitidx] |
| 270 | rest = read_text[splitidx + 1:] |
| 271 | |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 272 | The sender must always send valid JSON to Vim. Vim can check for the end of |
| 273 | the message by parsing the JSON. It will only accept the message if the end |
Bram Moolenaar | f1f0792 | 2016-08-26 17:58:53 +0200 | [diff] [blame] | 274 | was received. A newline after the message is optional. |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 275 | |
| 276 | When the process wants to send a message to Vim without first receiving a |
| 277 | message, it must use the number zero: |
| 278 | [0,{response}] |
| 279 | |
| 280 | Then channel handler will then get {response} converted to Vim types. If the |
| 281 | channel does not have a handler the message is dropped. |
| 282 | |
Bram Moolenaar | 8b1862a | 2016-02-27 19:21:24 +0100 | [diff] [blame] | 283 | It is also possible to use ch_sendraw() and ch_evalraw() on a JSON or JS |
| 284 | channel. The caller is then completely responsible for correct encoding and |
| 285 | decoding. |
Bram Moolenaar | cbebd48 | 2016-02-07 23:02:56 +0100 | [diff] [blame] | 286 | |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 287 | ============================================================================== |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 288 | 5. Channel commands *channel-commands* |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 289 | |
Bram Moolenaar | 910b8aa | 2016-02-16 21:03:07 +0100 | [diff] [blame] | 290 | With a JSON channel the process can send commands to Vim that will be |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 291 | handled by Vim internally, it does not require a handler for the channel. |
| 292 | |
Bram Moolenaar | fb1f626 | 2016-01-31 20:24:32 +0100 | [diff] [blame] | 293 | Possible commands are: *E903* *E904* *E905* |
Bram Moolenaar | 220adb1 | 2016-09-12 12:17:26 +0200 | [diff] [blame] | 294 | ["redraw", {forced}] |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 295 | ["ex", {Ex command}] |
| 296 | ["normal", {Normal mode command}] |
Bram Moolenaar | decb14d | 2016-02-20 23:32:02 +0100 | [diff] [blame] | 297 | ["expr", {expression}, {number}] |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 298 | ["expr", {expression}] |
Bram Moolenaar | decb14d | 2016-02-20 23:32:02 +0100 | [diff] [blame] | 299 | ["call", {func name}, {argument list}, {number}] |
| 300 | ["call", {func name}, {argument list}] |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 301 | |
| 302 | With all of these: Be careful what these commands do! You can easily |
| 303 | interfere with what the user is doing. To avoid trouble use |mode()| to check |
| 304 | that the editor is in the expected state. E.g., to send keys that must be |
Bram Moolenaar | fb1f626 | 2016-01-31 20:24:32 +0100 | [diff] [blame] | 305 | inserted as text, not executed as a command: |
| 306 | ["ex","if mode() == 'i' | call feedkeys('ClassName') | endif"] ~ |
| 307 | |
| 308 | Errors in these commands are normally not reported to avoid them messing up |
| 309 | the display. If you do want to see them, set the 'verbose' option to 3 or |
| 310 | higher. |
| 311 | |
| 312 | |
| 313 | Command "redraw" ~ |
| 314 | |
Bram Moolenaar | 63b74a8 | 2019-03-24 15:09:13 +0100 | [diff] [blame] | 315 | The other commands do not explicitly update the screen, so that you can send a |
| 316 | sequence of commands without the cursor moving around. A redraw can happen as |
| 317 | a side effect of some commands. You must end with the "redraw" command to |
| 318 | show any changed text and show the cursor where it belongs. |
Bram Moolenaar | fb1f626 | 2016-01-31 20:24:32 +0100 | [diff] [blame] | 319 | |
| 320 | The argument is normally an empty string: |
| 321 | ["redraw", ""] ~ |
| 322 | To first clear the screen pass "force": |
| 323 | ["redraw", "force"] ~ |
| 324 | |
| 325 | |
| 326 | Command "ex" ~ |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 327 | |
| 328 | The "ex" command is executed as any Ex command. There is no response for |
Bram Moolenaar | fb1f626 | 2016-01-31 20:24:32 +0100 | [diff] [blame] | 329 | completion or error. You could use functions in an |autoload| script: |
| 330 | ["ex","call myscript#MyFunc(arg)"] |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 331 | |
Bram Moolenaar | fb1f626 | 2016-01-31 20:24:32 +0100 | [diff] [blame] | 332 | You can also use "call |feedkeys()|" to insert any key sequence. |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 333 | |
Bram Moolenaar | 4f3f668 | 2016-03-26 23:01:59 +0100 | [diff] [blame] | 334 | When there is an error a message is written to the channel log, if it exists, |
| 335 | and v:errmsg is set to the error. |
| 336 | |
Bram Moolenaar | fb1f626 | 2016-01-31 20:24:32 +0100 | [diff] [blame] | 337 | |
| 338 | Command "normal" ~ |
| 339 | |
Bram Moolenaar | 681baaf | 2016-02-04 20:57:07 +0100 | [diff] [blame] | 340 | The "normal" command is executed like with ":normal!", commands are not |
Bram Moolenaar | fb1f626 | 2016-01-31 20:24:32 +0100 | [diff] [blame] | 341 | mapped. Example to open the folds under the cursor: |
| 342 | ["normal" "zO"] |
| 343 | |
| 344 | |
Bram Moolenaar | decb14d | 2016-02-20 23:32:02 +0100 | [diff] [blame] | 345 | Command "expr" with response ~ |
Bram Moolenaar | fb1f626 | 2016-01-31 20:24:32 +0100 | [diff] [blame] | 346 | |
Bram Moolenaar | decb14d | 2016-02-20 23:32:02 +0100 | [diff] [blame] | 347 | The "expr" command can be used to get the result of an expression. For |
Bram Moolenaar | fb1f626 | 2016-01-31 20:24:32 +0100 | [diff] [blame] | 348 | example, to get the number of lines in the current buffer: |
Bram Moolenaar | decb14d | 2016-02-20 23:32:02 +0100 | [diff] [blame] | 349 | ["expr","line('$')", -2] ~ |
Bram Moolenaar | fb1f626 | 2016-01-31 20:24:32 +0100 | [diff] [blame] | 350 | |
Bram Moolenaar | decb14d | 2016-02-20 23:32:02 +0100 | [diff] [blame] | 351 | It will send back the result of the expression: |
Bram Moolenaar | e0fa374 | 2016-02-20 15:47:01 +0100 | [diff] [blame] | 352 | [-2, "last line"] ~ |
| 353 | The format is: |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 354 | [{number}, {result}] |
Bram Moolenaar | 187db50 | 2016-02-27 14:44:26 +0100 | [diff] [blame] | 355 | |
Bram Moolenaar | fb1f626 | 2016-01-31 20:24:32 +0100 | [diff] [blame] | 356 | Here {number} is the same as what was in the request. Use a negative number |
Bram Moolenaar | decb14d | 2016-02-20 23:32:02 +0100 | [diff] [blame] | 357 | to avoid confusion with message that Vim sends. Use a different number on |
| 358 | every request to be able to match the request with the response. |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 359 | |
Bram Moolenaar | fb1f626 | 2016-01-31 20:24:32 +0100 | [diff] [blame] | 360 | {result} is the result of the evaluation and is JSON encoded. If the |
Bram Moolenaar | 595e64e | 2016-02-07 19:19:53 +0100 | [diff] [blame] | 361 | evaluation fails or the result can't be encoded in JSON it is the string |
| 362 | "ERROR". |
Bram Moolenaar | fb1f626 | 2016-01-31 20:24:32 +0100 | [diff] [blame] | 363 | |
| 364 | |
Bram Moolenaar | decb14d | 2016-02-20 23:32:02 +0100 | [diff] [blame] | 365 | Command "expr" without a response ~ |
Bram Moolenaar | fb1f626 | 2016-01-31 20:24:32 +0100 | [diff] [blame] | 366 | |
Bram Moolenaar | decb14d | 2016-02-20 23:32:02 +0100 | [diff] [blame] | 367 | This command is similar to "expr" above, but does not send back any response. |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 368 | Example: |
Bram Moolenaar | fb1f626 | 2016-01-31 20:24:32 +0100 | [diff] [blame] | 369 | ["expr","setline('$', ['one', 'two', 'three'])"] ~ |
Bram Moolenaar | decb14d | 2016-02-20 23:32:02 +0100 | [diff] [blame] | 370 | There is no third argument in the request. |
| 371 | |
| 372 | |
| 373 | Command "call" ~ |
| 374 | |
| 375 | This is similar to "expr", but instead of passing the whole expression as a |
| 376 | string this passes the name of a function and a list of arguments. This |
| 377 | avoids the conversion of the arguments to a string and escaping and |
| 378 | concatenating them. Example: |
| 379 | ["call", "line", ["$"], -2] ~ |
| 380 | |
| 381 | Leave out the fourth argument if no response is to be sent: |
| 382 | ["call", "setline", ["$", ["one", "two", "three"]]] ~ |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 383 | |
| 384 | ============================================================================== |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 385 | 6. Using a RAW or NL channel *channel-raw* |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 386 | |
Bram Moolenaar | c0514bf | 2016-11-17 14:50:09 +0100 | [diff] [blame] | 387 | If mode is RAW or NL then a message can be sent like this: > |
Bram Moolenaar | 8b1862a | 2016-02-27 19:21:24 +0100 | [diff] [blame] | 388 | let response = ch_evalraw(channel, {string}) |
Bram Moolenaar | 910b8aa | 2016-02-16 21:03:07 +0100 | [diff] [blame] | 389 | |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 390 | The {string} is sent as-is. The response will be what can be read from the |
| 391 | channel right away. Since Vim doesn't know how to recognize the end of the |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 392 | message you need to take care of it yourself. The timeout applies for reading |
| 393 | the first byte, after that it will not wait for anything more. |
| 394 | |
Bram Moolenaar | 910b8aa | 2016-02-16 21:03:07 +0100 | [diff] [blame] | 395 | If mode is "nl" you can send a message in a similar way. You are expected |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 396 | to put in the NL after each message. Thus you can also send several messages |
| 397 | ending in a NL at once. The response will be the text up to and including the |
| 398 | first NL. This can also be just the NL for an empty response. |
| 399 | If no NL was read before the channel timeout an empty string is returned. |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 400 | |
| 401 | To send a message, without expecting a response: > |
Bram Moolenaar | 8b1862a | 2016-02-27 19:21:24 +0100 | [diff] [blame] | 402 | call ch_sendraw(channel, {string}) |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 403 | The process can send back a response, the channel handler will be called with |
| 404 | it. |
| 405 | |
| 406 | To send a message and letting the response handled by a specific function, |
| 407 | asynchronously: > |
Bram Moolenaar | 8b1862a | 2016-02-27 19:21:24 +0100 | [diff] [blame] | 408 | call ch_sendraw(channel, {string}, {'callback': 'MyHandler'}) |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 409 | |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 410 | This {string} can also be JSON, use |json_encode()| to create it and |
| 411 | |json_decode()| to handle a received JSON message. |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 412 | |
Bram Moolenaar | 8b1862a | 2016-02-27 19:21:24 +0100 | [diff] [blame] | 413 | It is not possible to use |ch_evalexpr()| or |ch_sendexpr()| on a raw channel. |
Bram Moolenaar | cbebd48 | 2016-02-07 23:02:56 +0100 | [diff] [blame] | 414 | |
Bram Moolenaar | 818078d | 2016-08-27 21:58:42 +0200 | [diff] [blame] | 415 | A String in Vim cannot contain NUL bytes. To send or receive NUL bytes read |
| 416 | or write from a buffer. See |in_io-buffer| and |out_io-buffer|. |
| 417 | |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 418 | ============================================================================== |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 419 | 7. More channel functions *channel-more* |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 420 | |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 421 | To obtain the status of a channel: ch_status(channel). The possible results |
| 422 | are: |
| 423 | "fail" Failed to open the channel. |
| 424 | "open" The channel can be used. |
Bram Moolenaar | 0648142 | 2016-04-30 15:13:38 +0200 | [diff] [blame] | 425 | "buffered" The channel was closed but there is data to read. |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 426 | "closed" The channel was closed. |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 427 | |
Bram Moolenaar | 187db50 | 2016-02-27 14:44:26 +0100 | [diff] [blame] | 428 | To obtain the job associated with a channel: ch_getjob(channel) |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 429 | |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 430 | To read one message from a channel: > |
| 431 | let output = ch_read(channel) |
| 432 | This uses the channel timeout. To read without a timeout, just get any |
| 433 | message that is available: > |
Bram Moolenaar | decb14d | 2016-02-20 23:32:02 +0100 | [diff] [blame] | 434 | let output = ch_read(channel, {'timeout': 0}) |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 435 | When no message was available then the result is v:none for a JSON or JS mode |
Bram Moolenaar | 4b785f6 | 2016-11-29 21:54:44 +0100 | [diff] [blame] | 436 | channels, an empty string for a RAW or NL channel. You can use |ch_canread()| |
| 437 | to check if there is something to read. |
| 438 | |
Bram Moolenaar | 05aafed | 2017-08-11 19:12:11 +0200 | [diff] [blame] | 439 | Note that when there is no callback, messages are dropped. To avoid that add |
| 440 | a close callback to the channel. |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 441 | |
Bram Moolenaar | decb14d | 2016-02-20 23:32:02 +0100 | [diff] [blame] | 442 | To read all output from a RAW channel that is available: > |
| 443 | let output = ch_readraw(channel) |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 444 | To read the error output: > |
Bram Moolenaar | decb14d | 2016-02-20 23:32:02 +0100 | [diff] [blame] | 445 | let output = ch_readraw(channel, {"part": "err"}) |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 446 | |
Bram Moolenaar | 4f3f668 | 2016-03-26 23:01:59 +0100 | [diff] [blame] | 447 | ch_read() and ch_readraw() use the channel timeout. When there is nothing to |
| 448 | read within that time an empty string is returned. To specify a different |
| 449 | timeout in msec use the "timeout" option: |
| 450 | {"timeout": 123} ~ |
| 451 | To read from the error output use the "part" option: |
| 452 | {"part": "err"} ~ |
| 453 | To read a message with a specific ID, on a JS or JSON channel: |
| 454 | {"id": 99} ~ |
| 455 | When no ID is specified or the ID is -1, the first message is returned. This |
| 456 | overrules any callback waiting for this message. |
| 457 | |
| 458 | For a RAW channel this returns whatever is available, since Vim does not know |
| 459 | where a message ends. |
| 460 | For a NL channel this returns one message. |
| 461 | For a JS or JSON channel this returns one decoded message. |
| 462 | This includes any sequence number. |
| 463 | |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 464 | ============================================================================== |
Bram Moolenaar | ed997ad | 2019-07-21 16:42:00 +0200 | [diff] [blame] | 465 | 8. channel functions details *channel-functions-details* |
| 466 | |
| 467 | ch_canread({handle}) *ch_canread()* |
| 468 | Return non-zero when there is something to read from {handle}. |
| 469 | {handle} can be a Channel or a Job that has a Channel. |
| 470 | |
| 471 | This is useful to read from a channel at a convenient time, |
| 472 | e.g. from a timer. |
| 473 | |
| 474 | Note that messages are dropped when the channel does not have |
| 475 | a callback. Add a close callback to avoid that. |
| 476 | |
| 477 | |
| 478 | ch_close({handle}) *ch_close()* |
| 479 | Close {handle}. See |channel-close|. |
| 480 | {handle} can be a Channel or a Job that has a Channel. |
| 481 | A close callback is not invoked. |
| 482 | |
| 483 | |
| 484 | ch_close_in({handle}) *ch_close_in()* |
| 485 | Close the "in" part of {handle}. See |channel-close-in|. |
| 486 | {handle} can be a Channel or a Job that has a Channel. |
| 487 | A close callback is not invoked. |
| 488 | |
| 489 | |
| 490 | ch_evalexpr({handle}, {expr} [, {options}]) *ch_evalexpr()* |
| 491 | Send {expr} over {handle}. The {expr} is encoded |
| 492 | according to the type of channel. The function cannot be used |
| 493 | with a raw channel. See |channel-use|. |
| 494 | {handle} can be a Channel or a Job that has a Channel. |
| 495 | *E917* |
| 496 | {options} must be a Dictionary. It must not have a "callback" |
| 497 | entry. It can have a "timeout" entry to specify the timeout |
| 498 | for this specific request. |
| 499 | |
| 500 | ch_evalexpr() waits for a response and returns the decoded |
| 501 | expression. When there is an error or timeout it returns an |
| 502 | empty string. |
| 503 | |
| 504 | |
| 505 | ch_evalraw({handle}, {string} [, {options}]) *ch_evalraw()* |
| 506 | Send {string} over {handle}. |
| 507 | {handle} can be a Channel or a Job that has a Channel. |
| 508 | |
| 509 | Works like |ch_evalexpr()|, but does not encode the request or |
| 510 | decode the response. The caller is responsible for the |
| 511 | correct contents. Also does not add a newline for a channel |
| 512 | in NL mode, the caller must do that. The NL in the response |
| 513 | is removed. |
| 514 | Note that Vim does not know when the text received on a raw |
| 515 | channel is complete, it may only return the first part and you |
| 516 | need to use |ch_readraw()| to fetch the rest. |
| 517 | See |channel-use|. |
| 518 | |
| 519 | |
| 520 | ch_getbufnr({handle}, {what}) *ch_getbufnr()* |
| 521 | Get the buffer number that {handle} is using for {what}. |
| 522 | {handle} can be a Channel or a Job that has a Channel. |
| 523 | {what} can be "err" for stderr, "out" for stdout or empty for |
| 524 | socket output. |
| 525 | Returns -1 when there is no buffer. |
| 526 | |
| 527 | |
| 528 | ch_getjob({channel}) *ch_getjob()* |
| 529 | Get the Job associated with {channel}. |
| 530 | If there is no job calling |job_status()| on the returned Job |
| 531 | will result in "fail". |
| 532 | |
| 533 | |
| 534 | ch_info({handle}) *ch_info()* |
| 535 | Returns a Dictionary with information about {handle}. The |
| 536 | items are: |
| 537 | "id" number of the channel |
| 538 | "status" "open", "buffered" or "closed", like |
| 539 | ch_status() |
| 540 | When opened with ch_open(): |
| 541 | "hostname" the hostname of the address |
| 542 | "port" the port of the address |
| 543 | "sock_status" "open" or "closed" |
| 544 | "sock_mode" "NL", "RAW", "JSON" or "JS" |
| 545 | "sock_io" "socket" |
| 546 | "sock_timeout" timeout in msec |
| 547 | When opened with job_start(): |
| 548 | "out_status" "open", "buffered" or "closed" |
| 549 | "out_mode" "NL", "RAW", "JSON" or "JS" |
| 550 | "out_io" "null", "pipe", "file" or "buffer" |
| 551 | "out_timeout" timeout in msec |
| 552 | "err_status" "open", "buffered" or "closed" |
| 553 | "err_mode" "NL", "RAW", "JSON" or "JS" |
| 554 | "err_io" "out", "null", "pipe", "file" or "buffer" |
| 555 | "err_timeout" timeout in msec |
| 556 | "in_status" "open" or "closed" |
| 557 | "in_mode" "NL", "RAW", "JSON" or "JS" |
| 558 | "in_io" "null", "pipe", "file" or "buffer" |
| 559 | "in_timeout" timeout in msec |
| 560 | |
| 561 | |
| 562 | ch_log({msg} [, {handle}]) *ch_log()* |
| 563 | Write {msg} in the channel log file, if it was opened with |
| 564 | |ch_logfile()|. |
| 565 | When {handle} is passed the channel number is used for the |
| 566 | message. |
| 567 | {handle} can be a Channel or a Job that has a Channel. The |
| 568 | Channel must be open for the channel number to be used. |
| 569 | |
| 570 | |
| 571 | ch_logfile({fname} [, {mode}]) *ch_logfile()* |
| 572 | Start logging channel activity to {fname}. |
| 573 | When {fname} is an empty string: stop logging. |
| 574 | |
| 575 | When {mode} is omitted or "a" append to the file. |
| 576 | When {mode} is "w" start with an empty file. |
| 577 | |
| 578 | Use |ch_log()| to write log messages. The file is flushed |
| 579 | after every message, on Unix you can use "tail -f" to see what |
| 580 | is going on in real time. |
| 581 | |
| 582 | This function is not available in the |sandbox|. |
| 583 | NOTE: the channel communication is stored in the file, be |
| 584 | aware that this may contain confidential and privacy sensitive |
| 585 | information, e.g. a password you type in a terminal window. |
| 586 | |
| 587 | |
| 588 | ch_open({address} [, {options}]) *ch_open()* |
| 589 | Open a channel to {address}. See |channel|. |
| 590 | Returns a Channel. Use |ch_status()| to check for failure. |
| 591 | |
| 592 | {address} has the form "hostname:port", e.g., |
| 593 | "localhost:8765". |
| 594 | |
| 595 | If {options} is given it must be a |Dictionary|. |
| 596 | See |channel-open-options|. |
| 597 | |
| 598 | |
| 599 | ch_read({handle} [, {options}]) *ch_read()* |
| 600 | Read from {handle} and return the received message. |
| 601 | {handle} can be a Channel or a Job that has a Channel. |
| 602 | For a NL channel this waits for a NL to arrive, except when |
| 603 | there is nothing more to read (channel was closed). |
| 604 | See |channel-more|. |
| 605 | |
| 606 | |
| 607 | ch_readblob({handle} [, {options}]) *ch_readblob()* |
| 608 | Like ch_read() but reads binary data and returns a |Blob|. |
| 609 | See |channel-more|. |
| 610 | |
| 611 | |
| 612 | ch_readraw({handle} [, {options}]) *ch_readraw()* |
| 613 | Like ch_read() but for a JS and JSON channel does not decode |
| 614 | the message. For a NL channel it does not block waiting for |
| 615 | the NL to arrive, but otherwise works like ch_read(). |
| 616 | See |channel-more|. |
| 617 | |
| 618 | |
| 619 | ch_sendexpr({handle}, {expr} [, {options}]) *ch_sendexpr()* |
| 620 | Send {expr} over {handle}. The {expr} is encoded |
| 621 | according to the type of channel. The function cannot be used |
| 622 | with a raw channel. |
| 623 | See |channel-use|. *E912* |
| 624 | {handle} can be a Channel or a Job that has a Channel. |
| 625 | |
| 626 | |
| 627 | ch_sendraw({handle}, {expr} [, {options}]) *ch_sendraw()* |
| 628 | Send |String| or |Blob| {expr} over {handle}. |
| 629 | Works like |ch_sendexpr()|, but does not encode the request or |
| 630 | decode the response. The caller is responsible for the |
| 631 | correct contents. Also does not add a newline for a channel |
| 632 | in NL mode, the caller must do that. The NL in the response |
| 633 | is removed. |
| 634 | See |channel-use|. |
| 635 | |
| 636 | |
| 637 | ch_setoptions({handle}, {options}) *ch_setoptions()* |
| 638 | Set options on {handle}: |
| 639 | "callback" the channel callback |
| 640 | "timeout" default read timeout in msec |
| 641 | "mode" mode for the whole channel |
| 642 | See |ch_open()| for more explanation. |
| 643 | {handle} can be a Channel or a Job that has a Channel. |
| 644 | |
| 645 | Note that changing the mode may cause queued messages to be |
| 646 | lost. |
| 647 | |
| 648 | These options cannot be changed: |
| 649 | "waittime" only applies to |ch_open()| |
| 650 | |
| 651 | |
| 652 | ch_status({handle} [, {options}]) *ch_status()* |
| 653 | Return the status of {handle}: |
| 654 | "fail" failed to open the channel |
| 655 | "open" channel can be used |
| 656 | "buffered" channel can be read, not written to |
| 657 | "closed" channel can not be used |
| 658 | {handle} can be a Channel or a Job that has a Channel. |
| 659 | "buffered" is used when the channel was closed but there is |
| 660 | still data that can be obtained with |ch_read()|. |
| 661 | |
| 662 | If {options} is given it can contain a "part" entry to specify |
| 663 | the part of the channel to return the status for: "out" or |
| 664 | "err". For example, to get the error status: > |
| 665 | ch_status(job, {"part": "err"}) |
| 666 | < |
| 667 | |
| 668 | ============================================================================== |
| 669 | 9. Starting a job with a channel *job-start* *job* |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 670 | |
| 671 | To start a job and open a channel for stdin/stdout/stderr: > |
| 672 | let job = job_start(command, {options}) |
| 673 | |
| 674 | You can get the channel with: > |
| 675 | let channel = job_getchannel(job) |
| 676 | |
| 677 | The channel will use NL mode. If you want another mode it's best to specify |
| 678 | this in {options}. When changing the mode later some text may have already |
| 679 | been received and not parsed correctly. |
| 680 | |
| 681 | If the command produces a line of output that you want to deal with, specify |
| 682 | a handler for stdout: > |
Bram Moolenaar | d6c2f05 | 2016-03-14 23:22:59 +0100 | [diff] [blame] | 683 | let job = job_start(command, {"out_cb": "MyHandler"}) |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 684 | The function will be called with the channel and a message. You would define |
| 685 | it like this: > |
| 686 | func MyHandler(channel, msg) |
| 687 | |
Bram Moolenaar | 02e83b4 | 2016-02-21 20:10:26 +0100 | [diff] [blame] | 688 | Without the handler you need to read the output with |ch_read()| or |
Bram Moolenaar | 0648142 | 2016-04-30 15:13:38 +0200 | [diff] [blame] | 689 | |ch_readraw()|. You can do this in the close callback, see |read-in-close-cb|. |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 690 | |
Bram Moolenaar | 1ccd8ff | 2017-08-11 19:50:37 +0200 | [diff] [blame] | 691 | Note that if the job exits before you read the output, the output may be lost. |
| 692 | This depends on the system (on Unix this happens because closing the write end |
| 693 | of a pipe causes the read end to get EOF). To avoid this make the job sleep |
| 694 | for a short while before it exits. |
| 695 | |
Bram Moolenaar | d6c2f05 | 2016-03-14 23:22:59 +0100 | [diff] [blame] | 696 | The handler defined for "out_cb" will not receive stderr. If you want to |
| 697 | handle that separately, add an "err_cb" handler: > |
| 698 | let job = job_start(command, {"out_cb": "MyHandler", |
| 699 | \ "err_cb": "ErrHandler"}) |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 700 | |
Bram Moolenaar | 02e83b4 | 2016-02-21 20:10:26 +0100 | [diff] [blame] | 701 | If you want to handle both stderr and stdout with one handler use the |
| 702 | "callback" option: > |
| 703 | let job = job_start(command, {"callback": "MyHandler"}) |
| 704 | |
Bram Moolenaar | 3ec574f | 2017-06-13 18:12:01 +0200 | [diff] [blame] | 705 | Depending on the system, starting a job can put Vim in the background, the |
| 706 | started job gets the focus. To avoid that, use the `foreground()` function. |
| 707 | This might not always work when called early, put in the callback handler or |
| 708 | use a timer to call it after the job has started. |
| 709 | |
Bram Moolenaar | 8b1862a | 2016-02-27 19:21:24 +0100 | [diff] [blame] | 710 | You can send a message to the command with ch_evalraw(). If the channel is in |
| 711 | JSON or JS mode you can use ch_evalexpr(). |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 712 | |
| 713 | There are several options you can use, see |job-options|. |
Bram Moolenaar | 187db50 | 2016-02-27 14:44:26 +0100 | [diff] [blame] | 714 | For example, to start a job and write its output in buffer "dummy": > |
| 715 | let logjob = job_start("tail -f /tmp/log", |
Bram Moolenaar | d6c2f05 | 2016-03-14 23:22:59 +0100 | [diff] [blame] | 716 | \ {'out_io': 'buffer', 'out_name': 'dummy'}) |
Bram Moolenaar | 187db50 | 2016-02-27 14:44:26 +0100 | [diff] [blame] | 717 | sbuf dummy |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 718 | |
Bram Moolenaar | 5f148ec | 2016-03-07 22:59:26 +0100 | [diff] [blame] | 719 | |
| 720 | Job input from a buffer ~ |
Bram Moolenaar | 818078d | 2016-08-27 21:58:42 +0200 | [diff] [blame] | 721 | *in_io-buffer* |
Bram Moolenaar | 328da0d | 2016-03-04 22:22:32 +0100 | [diff] [blame] | 722 | To run a job that reads from a buffer: > |
| 723 | let job = job_start({command}, |
Bram Moolenaar | d6c2f05 | 2016-03-14 23:22:59 +0100 | [diff] [blame] | 724 | \ {'in_io': 'buffer', 'in_name': 'mybuffer'}) |
Bram Moolenaar | 328da0d | 2016-03-04 22:22:32 +0100 | [diff] [blame] | 725 | < |
| 726 | *E915* *E918* |
| 727 | The buffer is found by name, similar to |bufnr()|. The buffer must exist and |
| 728 | be loaded when job_start() is called. |
| 729 | |
Bram Moolenaar | d6c2f05 | 2016-03-14 23:22:59 +0100 | [diff] [blame] | 730 | By default this reads the whole buffer. This can be changed with the "in_top" |
| 731 | and "in_bot" options. |
Bram Moolenaar | 328da0d | 2016-03-04 22:22:32 +0100 | [diff] [blame] | 732 | |
Bram Moolenaar | d6c2f05 | 2016-03-14 23:22:59 +0100 | [diff] [blame] | 733 | A special mode is when "in_top" is set to zero and "in_bot" is not set: Every |
Bram Moolenaar | 74675a6 | 2017-07-15 13:53:23 +0200 | [diff] [blame] | 734 | time a line is added to the buffer, the last-but-one line will be sent to the |
Bram Moolenaar | 5f148ec | 2016-03-07 22:59:26 +0100 | [diff] [blame] | 735 | job stdin. This allows for editing the last line and sending it when pressing |
| 736 | Enter. |
Bram Moolenaar | 0874a83 | 2016-09-01 15:11:51 +0200 | [diff] [blame] | 737 | *channel-close-in* |
| 738 | When not using the special mode the pipe or socket will be closed after the |
| 739 | last line has been written. This signals the reading end that the input |
| 740 | finished. You can also use |ch_close_in()| to close it sooner. |
Bram Moolenaar | 328da0d | 2016-03-04 22:22:32 +0100 | [diff] [blame] | 741 | |
Bram Moolenaar | 063b9d1 | 2016-07-09 20:21:48 +0200 | [diff] [blame] | 742 | NUL bytes in the text will be passed to the job (internally Vim stores these |
| 743 | as NL bytes). |
| 744 | |
Bram Moolenaar | 0648142 | 2016-04-30 15:13:38 +0200 | [diff] [blame] | 745 | |
| 746 | Reading job output in the close callback ~ |
| 747 | *read-in-close-cb* |
| 748 | If the job can take some time and you don't need intermediate results, you can |
| 749 | add a close callback and read the output there: > |
| 750 | |
| 751 | func! CloseHandler(channel) |
Bram Moolenaar | 2ec618c | 2016-10-01 14:47:05 +0200 | [diff] [blame] | 752 | while ch_status(a:channel, {'part': 'out'}) == 'buffered' |
Bram Moolenaar | 0648142 | 2016-04-30 15:13:38 +0200 | [diff] [blame] | 753 | echomsg ch_read(a:channel) |
| 754 | endwhile |
| 755 | endfunc |
| 756 | let job = job_start(command, {'close_cb': 'CloseHandler'}) |
| 757 | |
| 758 | You will want to do something more useful than "echomsg". |
| 759 | |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 760 | ============================================================================== |
Bram Moolenaar | ed997ad | 2019-07-21 16:42:00 +0200 | [diff] [blame] | 761 | 10. Starting a job without a channel *job-start-nochannel* |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 762 | |
| 763 | To start another process without creating a channel: > |
Bram Moolenaar | 328da0d | 2016-03-04 22:22:32 +0100 | [diff] [blame] | 764 | let job = job_start(command, |
Bram Moolenaar | 5162822 | 2016-12-01 23:03:28 +0100 | [diff] [blame] | 765 | \ {"in_io": "null", "out_io": "null", "err_io": "null"}) |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 766 | |
| 767 | This starts {command} in the background, Vim does not wait for it to finish. |
| 768 | |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 769 | When Vim sees that neither stdin, stdout or stderr are connected, no channel |
| 770 | will be created. Often you will want to include redirection in the command to |
| 771 | avoid it getting stuck. |
| 772 | |
| 773 | There are several options you can use, see |job-options|. |
| 774 | |
Bram Moolenaar | 77cdfd1 | 2016-03-12 12:57:59 +0100 | [diff] [blame] | 775 | *job-start-if-needed* |
| 776 | To start a job only when connecting to an address does not work, do something |
| 777 | like this: > |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 778 | let channel = ch_open(address, {"waittime": 0}) |
| 779 | if ch_status(channel) == "fail" |
| 780 | let job = job_start(command) |
| 781 | let channel = ch_open(address, {"waittime": 1000}) |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 782 | endif |
Bram Moolenaar | 77cdfd1 | 2016-03-12 12:57:59 +0100 | [diff] [blame] | 783 | |
| 784 | Note that the waittime for ch_open() gives the job one second to make the port |
| 785 | available. |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 786 | |
| 787 | ============================================================================== |
Bram Moolenaar | ed997ad | 2019-07-21 16:42:00 +0200 | [diff] [blame] | 788 | 11. Job functions *job-functions-details* |
| 789 | |
| 790 | job_getchannel({job}) *job_getchannel()* |
| 791 | Get the channel handle that {job} is using. |
| 792 | To check if the job has no channel: > |
| 793 | if string(job_getchannel()) == 'channel fail' |
| 794 | < |
| 795 | |
| 796 | job_info([{job}]) *job_info()* |
| 797 | Returns a Dictionary with information about {job}: |
| 798 | "status" what |job_status()| returns |
| 799 | "channel" what |job_getchannel()| returns |
| 800 | "cmd" List of command arguments used to start the job |
| 801 | "process" process ID |
| 802 | "tty_in" terminal input name, empty when none |
| 803 | "tty_out" terminal output name, empty when none |
| 804 | "exitval" only valid when "status" is "dead" |
| 805 | "exit_cb" function to be called on exit |
| 806 | "stoponexit" |job-stoponexit| |
| 807 | |
| 808 | Only in Unix: |
| 809 | "termsig" the signal which terminated the process |
| 810 | (See |job_stop()| for the values) |
| 811 | only valid when "status" is "dead" |
| 812 | |
| 813 | Only in MS-Windows: |
| 814 | "tty_type" Type of virtual console in use. |
| 815 | Values are "winpty" or "conpty". |
| 816 | See 'termwintype'. |
| 817 | |
| 818 | Without any arguments, returns a List with all Job objects. |
| 819 | |
| 820 | |
| 821 | job_setoptions({job}, {options}) *job_setoptions()* |
| 822 | Change options for {job}. Supported are: |
| 823 | "stoponexit" |job-stoponexit| |
| 824 | "exit_cb" |job-exit_cb| |
| 825 | |
| 826 | |
| 827 | job_start({command} [, {options}]) *job_start()* |
| 828 | Start a job and return a Job object. Unlike |system()| and |
| 829 | |:!cmd| this does not wait for the job to finish. |
| 830 | To start a job in a terminal window see |term_start()|. |
| 831 | |
| 832 | If the job fails to start then |job_status()| on the returned |
| 833 | Job object results in "fail" and none of the callbacks will be |
| 834 | invoked. |
| 835 | |
| 836 | {command} can be a String. This works best on MS-Windows. On |
| 837 | Unix it is split up in white-separated parts to be passed to |
| 838 | execvp(). Arguments in double quotes can contain white space. |
| 839 | |
| 840 | {command} can be a List, where the first item is the executable |
| 841 | and further items are the arguments. All items are converted |
| 842 | to String. This works best on Unix. |
| 843 | |
| 844 | On MS-Windows, job_start() makes a GUI application hidden. If |
| 845 | want to show it, Use |:!start| instead. |
| 846 | |
| 847 | The command is executed directly, not through a shell, the |
| 848 | 'shell' option is not used. To use the shell: > |
| 849 | let job = job_start(["/bin/sh", "-c", "echo hello"]) |
| 850 | < Or: > |
| 851 | let job = job_start('/bin/sh -c "echo hello"') |
| 852 | < Note that this will start two processes, the shell and the |
| 853 | command it executes. If you don't want this use the "exec" |
| 854 | shell command. |
| 855 | |
| 856 | On Unix $PATH is used to search for the executable only when |
| 857 | the command does not contain a slash. |
| 858 | |
| 859 | The job will use the same terminal as Vim. If it reads from |
| 860 | stdin the job and Vim will be fighting over input, that |
| 861 | doesn't work. Redirect stdin and stdout to avoid problems: > |
| 862 | let job = job_start(['sh', '-c', "myserver </dev/null >/dev/null"]) |
| 863 | < |
| 864 | The returned Job object can be used to get the status with |
| 865 | |job_status()| and stop the job with |job_stop()|. |
| 866 | |
| 867 | Note that the job object will be deleted if there are no |
| 868 | references to it. This closes the stdin and stderr, which may |
| 869 | cause the job to fail with an error. To avoid this keep a |
| 870 | reference to the job. Thus instead of: > |
| 871 | call job_start('my-command') |
| 872 | < use: > |
| 873 | let myjob = job_start('my-command') |
| 874 | < and unlet "myjob" once the job is not needed or is past the |
| 875 | point where it would fail (e.g. when it prints a message on |
| 876 | startup). Keep in mind that variables local to a function |
| 877 | will cease to exist if the function returns. Use a |
| 878 | script-local variable if needed: > |
| 879 | let s:myjob = job_start('my-command') |
| 880 | < |
| 881 | {options} must be a Dictionary. It can contain many optional |
| 882 | items, see |job-options|. |
| 883 | |
| 884 | |
| 885 | job_status({job}) *job_status()* *E916* |
| 886 | Returns a String with the status of {job}: |
| 887 | "run" job is running |
| 888 | "fail" job failed to start |
| 889 | "dead" job died or was stopped after running |
| 890 | |
| 891 | On Unix a non-existing command results in "dead" instead of |
| 892 | "fail", because a fork happens before the failure can be |
| 893 | detected. |
| 894 | |
| 895 | If an exit callback was set with the "exit_cb" option and the |
| 896 | job is now detected to be "dead" the callback will be invoked. |
| 897 | |
| 898 | For more information see |job_info()|. |
| 899 | |
| 900 | |
| 901 | job_stop({job} [, {how}]) *job_stop()* |
| 902 | Stop the {job}. This can also be used to signal the job. |
| 903 | |
| 904 | When {how} is omitted or is "term" the job will be terminated. |
| 905 | For Unix SIGTERM is sent. On MS-Windows the job will be |
| 906 | terminated forcedly (there is no "gentle" way). |
| 907 | This goes to the process group, thus children may also be |
| 908 | affected. |
| 909 | |
| 910 | Effect for Unix: |
| 911 | "term" SIGTERM (default) |
| 912 | "hup" SIGHUP |
| 913 | "quit" SIGQUIT |
| 914 | "int" SIGINT |
| 915 | "kill" SIGKILL (strongest way to stop) |
| 916 | number signal with that number |
| 917 | |
| 918 | Effect for MS-Windows: |
| 919 | "term" terminate process forcedly (default) |
| 920 | "hup" CTRL_BREAK |
| 921 | "quit" CTRL_BREAK |
| 922 | "int" CTRL_C |
| 923 | "kill" terminate process forcedly |
| 924 | Others CTRL_BREAK |
| 925 | |
| 926 | On Unix the signal is sent to the process group. This means |
| 927 | that when the job is "sh -c command" it affects both the shell |
| 928 | and the command. |
| 929 | |
| 930 | The result is a Number: 1 if the operation could be executed, |
| 931 | 0 if "how" is not supported on the system. |
| 932 | Note that even when the operation was executed, whether the |
| 933 | job was actually stopped needs to be checked with |
| 934 | |job_status()|. |
| 935 | |
| 936 | If the status of the job is "dead", the signal will not be |
| 937 | sent. This is to avoid to stop the wrong job (esp. on Unix, |
| 938 | where process numbers are recycled). |
| 939 | |
| 940 | When using "kill" Vim will assume the job will die and close |
| 941 | the channel. |
| 942 | |
| 943 | |
| 944 | ============================================================================== |
| 945 | 12. Job options *job-options* |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 946 | |
| 947 | The {options} argument in job_start() is a dictionary. All entries are |
Bram Moolenaar | 02e83b4 | 2016-02-21 20:10:26 +0100 | [diff] [blame] | 948 | optional. Some options can be used after the job has started, using |
| 949 | job_setoptions(job, {options}). Many options can be used with the channel |
| 950 | related to the job, using ch_setoptions(channel, {options}). |
| 951 | See |job_setoptions()| and |ch_setoptions()|. |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 952 | |
Bram Moolenaar | 4f3f668 | 2016-03-26 23:01:59 +0100 | [diff] [blame] | 953 | *in_mode* *out_mode* *err_mode* |
| 954 | "in_mode" mode specifically for stdin, only when using pipes |
| 955 | "out_mode" mode specifically for stdout, only when using pipes |
| 956 | "err_mode" mode specifically for stderr, only when using pipes |
| 957 | See |channel-mode| for the values. |
| 958 | |
| 959 | Note: when setting "mode" the part specific mode is |
| 960 | overwritten. Therefore set "mode" first and the part |
| 961 | specific mode later. |
| 962 | |
| 963 | Note: when writing to a file or buffer and when |
| 964 | reading from a buffer NL mode is used by default. |
| 965 | |
Bram Moolenaar | 0b14688 | 2018-09-06 16:27:24 +0200 | [diff] [blame] | 966 | *job-noblock* |
| 967 | "noblock": 1 When writing use a non-blocking write call. This |
| 968 | avoids getting stuck if Vim should handle other |
| 969 | messages in between, e.g. when a job sends back data |
| 970 | to Vim. It implies that when `ch_sendraw()` returns |
| 971 | not all data may have been written yet. |
| 972 | This option was added in patch 8.1.0350, test with: > |
| 973 | if has("patch-8.1.350") |
| 974 | let options['noblock'] = 1 |
| 975 | endif |
| 976 | < |
Bram Moolenaar | decb14d | 2016-02-20 23:32:02 +0100 | [diff] [blame] | 977 | *job-callback* |
| 978 | "callback": handler Callback for something to read on any part of the |
| 979 | channel. |
Bram Moolenaar | 4f3f668 | 2016-03-26 23:01:59 +0100 | [diff] [blame] | 980 | *job-out_cb* *out_cb* |
Bram Moolenaar | d6c2f05 | 2016-03-14 23:22:59 +0100 | [diff] [blame] | 981 | "out_cb": handler Callback for when there is something to read on |
Bram Moolenaar | 4f3f668 | 2016-03-26 23:01:59 +0100 | [diff] [blame] | 982 | stdout. Only for when the channel uses pipes. When |
| 983 | "out_cb" wasn't set the channel callback is used. |
Bram Moolenaar | 269f595 | 2016-07-15 22:54:41 +0200 | [diff] [blame] | 984 | The two arguments are the channel and the message. |
Bram Moolenaar | 4f3f668 | 2016-03-26 23:01:59 +0100 | [diff] [blame] | 985 | |
| 986 | *job-err_cb* *err_cb* |
Bram Moolenaar | d6c2f05 | 2016-03-14 23:22:59 +0100 | [diff] [blame] | 987 | "err_cb": handler Callback for when there is something to read on |
Bram Moolenaar | 4f3f668 | 2016-03-26 23:01:59 +0100 | [diff] [blame] | 988 | stderr. Only for when the channel uses pipes. When |
| 989 | "err_cb" wasn't set the channel callback is used. |
Bram Moolenaar | 269f595 | 2016-07-15 22:54:41 +0200 | [diff] [blame] | 990 | The two arguments are the channel and the message. |
Bram Moolenaar | d6c2f05 | 2016-03-14 23:22:59 +0100 | [diff] [blame] | 991 | *job-close_cb* |
| 992 | "close_cb": handler Callback for when the channel is closed. Same as |
Bram Moolenaar | 82af871 | 2016-06-04 20:20:29 +0200 | [diff] [blame] | 993 | "close_cb" on |ch_open()|, see |close_cb|. |
Bram Moolenaar | bc2eada | 2017-01-02 21:27:47 +0100 | [diff] [blame] | 994 | *job-drop* |
Bram Moolenaar | b6e0ec6 | 2017-07-23 22:12:20 +0200 | [diff] [blame] | 995 | "drop": when Specifies when to drop messages. Same as "drop" on |
Bram Moolenaar | 5162822 | 2016-12-01 23:03:28 +0100 | [diff] [blame] | 996 | |ch_open()|, see |channel-drop|. For "auto" the |
| 997 | exit_cb is not considered. |
Bram Moolenaar | bc2eada | 2017-01-02 21:27:47 +0100 | [diff] [blame] | 998 | *job-exit_cb* |
Bram Moolenaar | d6c2f05 | 2016-03-14 23:22:59 +0100 | [diff] [blame] | 999 | "exit_cb": handler Callback for when the job ends. The arguments are the |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 1000 | job and the exit status. |
Bram Moolenaar | b4ada79 | 2016-10-30 21:55:26 +0100 | [diff] [blame] | 1001 | Vim checks up to 10 times per second for jobs that |
| 1002 | ended. The check can also be triggered by calling |
| 1003 | |job_status()|, which may then invoke the exit_cb |
| 1004 | handler. |
Bram Moolenaar | 06d2d38 | 2016-05-20 17:24:11 +0200 | [diff] [blame] | 1005 | Note that data can be buffered, callbacks may still be |
| 1006 | called after the process ends. |
Bram Moolenaar | 4f3f668 | 2016-03-26 23:01:59 +0100 | [diff] [blame] | 1007 | *job-timeout* |
Bram Moolenaar | b6e0ec6 | 2017-07-23 22:12:20 +0200 | [diff] [blame] | 1008 | "timeout": time The time to wait for a request when blocking, E.g. |
Bram Moolenaar | 4f3f668 | 2016-03-26 23:01:59 +0100 | [diff] [blame] | 1009 | when using ch_evalexpr(). In milliseconds. The |
| 1010 | default is 2000 (2 seconds). |
| 1011 | *out_timeout* *err_timeout* |
Bram Moolenaar | b6e0ec6 | 2017-07-23 22:12:20 +0200 | [diff] [blame] | 1012 | "out_timeout": time Timeout for stdout. Only when using pipes. |
| 1013 | "err_timeout": time Timeout for stderr. Only when using pipes. |
Bram Moolenaar | 4f3f668 | 2016-03-26 23:01:59 +0100 | [diff] [blame] | 1014 | Note: when setting "timeout" the part specific mode is |
| 1015 | overwritten. Therefore set "timeout" first and the |
| 1016 | part specific mode later. |
| 1017 | |
Bram Moolenaar | 02e83b4 | 2016-02-21 20:10:26 +0100 | [diff] [blame] | 1018 | *job-stoponexit* |
| 1019 | "stoponexit": {signal} Send {signal} to the job when Vim exits. See |
| 1020 | |job_stop()| for possible values. |
| 1021 | "stoponexit": "" Do not stop the job when Vim exits. |
| 1022 | The default is "term". |
| 1023 | |
Bram Moolenaar | 77cdfd1 | 2016-03-12 12:57:59 +0100 | [diff] [blame] | 1024 | *job-term* |
Bram Moolenaar | b6e0ec6 | 2017-07-23 22:12:20 +0200 | [diff] [blame] | 1025 | "term": "open" Start a terminal in a new window and connect the job |
| 1026 | stdin/stdout/stderr to it. Similar to using |
| 1027 | `:terminal`. |
Bram Moolenaar | 77cdfd1 | 2016-03-12 12:57:59 +0100 | [diff] [blame] | 1028 | NOTE: Not implemented yet! |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 1029 | |
Bram Moolenaar | 77cdfd1 | 2016-03-12 12:57:59 +0100 | [diff] [blame] | 1030 | "channel": {channel} Use an existing channel instead of creating a new one. |
| 1031 | The parts of the channel that get used for the new job |
| 1032 | will be disconnected from what they were used before. |
Bram Moolenaar | 5162822 | 2016-12-01 23:03:28 +0100 | [diff] [blame] | 1033 | If the channel was still used by another job this may |
Bram Moolenaar | 77cdfd1 | 2016-03-12 12:57:59 +0100 | [diff] [blame] | 1034 | cause I/O errors. |
| 1035 | Existing callbacks and other settings remain. |
| 1036 | |
Bram Moolenaar | b6e0ec6 | 2017-07-23 22:12:20 +0200 | [diff] [blame] | 1037 | "pty": 1 Use a pty (pseudo-tty) instead of a pipe when |
| 1038 | possible. This is most useful in combination with a |
| 1039 | terminal window, see |terminal|. |
| 1040 | {only on Unix and Unix-like systems} |
| 1041 | |
Bram Moolenaar | d6c2f05 | 2016-03-14 23:22:59 +0100 | [diff] [blame] | 1042 | *job-in_io* *in_top* *in_bot* *in_name* *in_buf* |
| 1043 | "in_io": "null" disconnect stdin (read from /dev/null) |
| 1044 | "in_io": "pipe" stdin is connected to the channel (default) |
| 1045 | "in_io": "file" stdin reads from a file |
| 1046 | "in_io": "buffer" stdin reads from a buffer |
| 1047 | "in_top": number when using "buffer": first line to send (default: 1) |
| 1048 | "in_bot": number when using "buffer": last line to send (default: last) |
| 1049 | "in_name": "/path/file" the name of the file or buffer to read from |
| 1050 | "in_buf": number the number of the buffer to read from |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 1051 | |
Bram Moolenaar | d6c2f05 | 2016-03-14 23:22:59 +0100 | [diff] [blame] | 1052 | *job-out_io* *out_name* *out_buf* |
| 1053 | "out_io": "null" disconnect stdout (goes to /dev/null) |
| 1054 | "out_io": "pipe" stdout is connected to the channel (default) |
| 1055 | "out_io": "file" stdout writes to a file |
Bram Moolenaar | 5162822 | 2016-12-01 23:03:28 +0100 | [diff] [blame] | 1056 | "out_io": "buffer" stdout appends to a buffer (see below) |
Bram Moolenaar | d6c2f05 | 2016-03-14 23:22:59 +0100 | [diff] [blame] | 1057 | "out_name": "/path/file" the name of the file or buffer to write to |
| 1058 | "out_buf": number the number of the buffer to write to |
Bram Moolenaar | 9f5842e | 2016-05-29 16:17:08 +0200 | [diff] [blame] | 1059 | "out_modifiable": 0 when writing to a buffer, 'modifiable' will be off |
| 1060 | (see below) |
Bram Moolenaar | 169ebb0 | 2016-09-07 23:32:23 +0200 | [diff] [blame] | 1061 | "out_msg": 0 when writing to a new buffer, the first line will be |
| 1062 | set to "Reading from channel output..." |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 1063 | |
Bram Moolenaar | d6c2f05 | 2016-03-14 23:22:59 +0100 | [diff] [blame] | 1064 | *job-err_io* *err_name* *err_buf* |
| 1065 | "err_io": "out" stderr messages to go to stdout |
| 1066 | "err_io": "null" disconnect stderr (goes to /dev/null) |
| 1067 | "err_io": "pipe" stderr is connected to the channel (default) |
| 1068 | "err_io": "file" stderr writes to a file |
Bram Moolenaar | 5162822 | 2016-12-01 23:03:28 +0100 | [diff] [blame] | 1069 | "err_io": "buffer" stderr appends to a buffer (see below) |
Bram Moolenaar | d6c2f05 | 2016-03-14 23:22:59 +0100 | [diff] [blame] | 1070 | "err_name": "/path/file" the name of the file or buffer to write to |
| 1071 | "err_buf": number the number of the buffer to write to |
Bram Moolenaar | 9f5842e | 2016-05-29 16:17:08 +0200 | [diff] [blame] | 1072 | "err_modifiable": 0 when writing to a buffer, 'modifiable' will be off |
| 1073 | (see below) |
Bram Moolenaar | 169ebb0 | 2016-09-07 23:32:23 +0200 | [diff] [blame] | 1074 | "err_msg": 0 when writing to a new buffer, the first line will be |
| 1075 | set to "Reading from channel error..." |
Bram Moolenaar | 77cdfd1 | 2016-03-12 12:57:59 +0100 | [diff] [blame] | 1076 | |
Bram Moolenaar | 7db8f6f | 2016-03-29 23:12:46 +0200 | [diff] [blame] | 1077 | "block_write": number only for testing: pretend every other write to stdin |
| 1078 | will block |
| 1079 | |
Bram Moolenaar | 05aafed | 2017-08-11 19:12:11 +0200 | [diff] [blame] | 1080 | "env": dict environment variables for the new process |
| 1081 | "cwd": "/path/to/dir" current working directory for the new process; |
| 1082 | if the directory does not exist an error is given |
| 1083 | |
Bram Moolenaar | 77cdfd1 | 2016-03-12 12:57:59 +0100 | [diff] [blame] | 1084 | |
| 1085 | Writing to a buffer ~ |
Bram Moolenaar | 818078d | 2016-08-27 21:58:42 +0200 | [diff] [blame] | 1086 | *out_io-buffer* |
Bram Moolenaar | d6c2f05 | 2016-03-14 23:22:59 +0100 | [diff] [blame] | 1087 | When the out_io or err_io mode is "buffer" and there is a callback, the text |
Bram Moolenaar | 5f148ec | 2016-03-07 22:59:26 +0100 | [diff] [blame] | 1088 | is appended to the buffer before invoking the callback. |
| 1089 | |
| 1090 | When a buffer is used both for input and output, the output lines are put |
| 1091 | above the last line, since the last line is what is written to the channel |
Bram Moolenaar | 77cdfd1 | 2016-03-12 12:57:59 +0100 | [diff] [blame] | 1092 | input. Otherwise lines are appended below the last line. |
Bram Moolenaar | c7f0ebc | 2016-02-27 21:10:09 +0100 | [diff] [blame] | 1093 | |
Bram Moolenaar | 328da0d | 2016-03-04 22:22:32 +0100 | [diff] [blame] | 1094 | When using JS or JSON mode with "buffer", only messages with zero or negative |
| 1095 | ID will be added to the buffer, after decoding + encoding. Messages with a |
| 1096 | positive number will be handled by a callback, commands are handled as usual. |
| 1097 | |
Bram Moolenaar | 82af871 | 2016-06-04 20:20:29 +0200 | [diff] [blame] | 1098 | The name of the buffer from "out_name" or "err_name" is compared the full name |
| 1099 | of existing buffers, also after expanding the name for the current directory. |
| 1100 | E.g., when a buffer was created with ":edit somename" and the buffer name is |
| 1101 | "somename" it will use that buffer. |
| 1102 | |
| 1103 | If there is no matching buffer a new buffer is created. Use an empty name to |
| 1104 | always create a new buffer. |ch_getbufnr()| can then be used to get the |
| 1105 | buffer number. |
Bram Moolenaar | c7f0ebc | 2016-02-27 21:10:09 +0100 | [diff] [blame] | 1106 | |
| 1107 | For a new buffer 'buftype' is set to "nofile" and 'bufhidden' to "hide". If |
| 1108 | you prefer other settings, create the buffer first and pass the buffer number. |
Bram Moolenaar | 169ebb0 | 2016-09-07 23:32:23 +0200 | [diff] [blame] | 1109 | *out_modifiable* *err_modifiable* |
Bram Moolenaar | 9f5842e | 2016-05-29 16:17:08 +0200 | [diff] [blame] | 1110 | The "out_modifiable" and "err_modifiable" options can be used to set the |
| 1111 | 'modifiable' option off, or write to a buffer that has 'modifiable' off. That |
| 1112 | means that lines will be appended to the buffer, but the user can't easily |
| 1113 | change the buffer. |
Bram Moolenaar | 169ebb0 | 2016-09-07 23:32:23 +0200 | [diff] [blame] | 1114 | *out_msg* *err_msg* |
| 1115 | The "out_msg" option can be used to specify whether a new buffer will have the |
| 1116 | first line set to "Reading from channel output...". The default is to add the |
| 1117 | message. "err_msg" does the same for channel error. |
| 1118 | |
Bram Moolenaar | 9f5842e | 2016-05-29 16:17:08 +0200 | [diff] [blame] | 1119 | When an existing buffer is to be written where 'modifiable' is off and the |
| 1120 | "out_modifiable" or "err_modifiable" options is not zero, an error is given |
| 1121 | and the buffer will not be written to. |
| 1122 | |
Bram Moolenaar | 187db50 | 2016-02-27 14:44:26 +0100 | [diff] [blame] | 1123 | When the buffer written to is displayed in a window and the cursor is in the |
| 1124 | first column of the last line, the cursor will be moved to the newly added |
| 1125 | line and the window is scrolled up to show the cursor if needed. |
| 1126 | |
Bram Moolenaar | 063b9d1 | 2016-07-09 20:21:48 +0200 | [diff] [blame] | 1127 | Undo is synced for every added line. NUL bytes are accepted (internally Vim |
| 1128 | stores these as NL bytes). |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 1129 | |
Bram Moolenaar | 77cdfd1 | 2016-03-12 12:57:59 +0100 | [diff] [blame] | 1130 | |
| 1131 | Writing to a file ~ |
Bram Moolenaar | d6c2f05 | 2016-03-14 23:22:59 +0100 | [diff] [blame] | 1132 | *E920* |
Bram Moolenaar | 77cdfd1 | 2016-03-12 12:57:59 +0100 | [diff] [blame] | 1133 | The file is created with permissions 600 (read-write for the user, not |
| 1134 | accessible for others). Use |setfperm()| to change this. |
| 1135 | |
| 1136 | If the file already exists it is truncated. |
| 1137 | |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 1138 | ============================================================================== |
Bram Moolenaar | ed997ad | 2019-07-21 16:42:00 +0200 | [diff] [blame] | 1139 | 13. Controlling a job *job-control* |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 1140 | |
| 1141 | To get the status of a job: > |
| 1142 | echo job_status(job) |
| 1143 | |
| 1144 | To make a job stop running: > |
| 1145 | job_stop(job) |
| 1146 | |
| 1147 | This is the normal way to end a job. On Unix it sends a SIGTERM to the job. |
| 1148 | It is possible to use other ways to stop the job, or even send arbitrary |
| 1149 | signals. E.g. to force a job to stop, "kill it": > |
| 1150 | job_stop(job, "kill") |
| 1151 | |
| 1152 | For more options see |job_stop()|. |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 1153 | |
Bram Moolenaar | f273245 | 2018-06-03 14:47:35 +0200 | [diff] [blame] | 1154 | ============================================================================== |
Bram Moolenaar | ed997ad | 2019-07-21 16:42:00 +0200 | [diff] [blame] | 1155 | 14. Using a prompt buffer *prompt-buffer* |
Bram Moolenaar | f273245 | 2018-06-03 14:47:35 +0200 | [diff] [blame] | 1156 | |
| 1157 | If you want to type input for the job in a Vim window you have a few options: |
| 1158 | - Use a normal buffer and handle all possible commands yourself. |
| 1159 | This will be complicated, since there are so many possible commands. |
| 1160 | - Use a terminal window. This works well if what you type goes directly to |
| 1161 | the job and the job output is directly displayed in the window. |
| 1162 | See |terminal-window|. |
| 1163 | - Use a prompt window. This works well when entering a line for the job in Vim |
| 1164 | while displaying (possibly filtered) output from the job. |
| 1165 | |
| 1166 | A prompt buffer is created by setting 'buftype' to "prompt". You would |
| 1167 | normally only do that in a newly created buffer. |
| 1168 | |
| 1169 | The user can edit and enter one line of text at the very last line of the |
| 1170 | buffer. When pressing Enter in the prompt line the callback set with |
| 1171 | |prompt_setcallback()| is invoked. It would normally send the line to a job. |
| 1172 | Another callback would receive the output from the job and display it in the |
| 1173 | buffer, below the prompt (and above the next prompt). |
| 1174 | |
| 1175 | Only the text in the last line, after the prompt, is editable. The rest of the |
| 1176 | buffer is not modifiable with Normal mode commands. It can be modified by |
| 1177 | calling functions, such as |append()|. Using other commands may mess up the |
| 1178 | buffer. |
| 1179 | |
| 1180 | After setting 'buftype' to "prompt" Vim does not automatically start Insert |
| 1181 | mode, use `:startinsert` if you want to enter Insert mode, so that the user |
| 1182 | can start typing a line. |
| 1183 | |
| 1184 | The text of the prompt can be set with the |prompt_setprompt()| function. |
| 1185 | |
| 1186 | The user can go to Normal mode and navigate through the buffer. This can be |
| 1187 | useful see older output or copy text. |
| 1188 | |
Bram Moolenaar | d2f3a8b | 2018-06-19 14:35:59 +0200 | [diff] [blame] | 1189 | The CTRL-W key can be used to start a window command, such as CTRL-W w to |
| 1190 | switch to the next window. This also works in Insert mode (use Shift-CTRL-W |
| 1191 | to delete a word). When leaving the window Insert mode will be stopped. When |
| 1192 | coming back to the prompt window Insert mode will be restored. |
| 1193 | |
Bram Moolenaar | f273245 | 2018-06-03 14:47:35 +0200 | [diff] [blame] | 1194 | Any command that starts Insert mode, such as "a", "i", "A" and "I", will move |
Bram Moolenaar | d2f3a8b | 2018-06-19 14:35:59 +0200 | [diff] [blame] | 1195 | the cursor to the last line. "A" will move to the end of the line, "I" to the |
| 1196 | start of the line. |
Bram Moolenaar | f273245 | 2018-06-03 14:47:35 +0200 | [diff] [blame] | 1197 | |
Bram Moolenaar | 3b5f929 | 2016-01-28 22:37:01 +0100 | [diff] [blame] | 1198 | |
Bram Moolenaar | 91f84f6 | 2018-07-29 15:07:52 +0200 | [diff] [blame] | 1199 | vim:tw=78:ts=8:noet:ft=help:norl: |