Mercurial > vim

annotate runtime/doc/channel.txt @ 8178:e77efd7a7dad v7.4.1382

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686 Author: Bram Moolenaar <Bram@vim.org> Date: Sun Feb 21 20:10:26 2016 +0100 patch 7.4.1382 Problem: Can't get the job of a channel. Solution: Add ch_getjob().
author Christian Brabandt <cb@256bit.org>
date Sun, 21 Feb 2016 20:15:04 +0100
parents 9ca3885edfed
children f16bfe02cef1
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
1 *channel.txt* For Vim version 7.4. Last change: 2016 Feb 21
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
2
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
3
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
4 VIM REFERENCE MANUAL by Bram Moolenaar
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
5
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
6
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
7 Inter-process communication *channel*
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
8
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
9 DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
10
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
11 Vim uses channels to communicate with other processes.
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
12 A channel uses a socket or pipes *socket-interface*
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
13 Jobs can be used to start processes and communicate with them.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
14
7924
00d64eb49ce1 commit https://github.com/vim/vim/commit/681baaf4a4c81418693dcafb81421a8614832e91
Christian Brabandt <cb@256bit.org>
parents: 7864
diff changeset
15 Vim current supports up to 10 simultaneous channels.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
16 The Netbeans interface also uses a channel. |netbeans|
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
17
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
18 1. Overview |job-channel-overview|
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
19 2. Channel demo |channel-demo|
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
20 3. Opening a channel |channel-open|
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
21 4. Using a JSON or JS channel |channel-use|
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
22 5. Channel commands |channel-commands|
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
23 6. Using a RAW or NL channel |channel-raw|
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
24 7. More channel functions |channel-more|
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
25 8. Starting a job with a channel |job-start|
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
26 9. Starting a job without a channel |job-start-nochannel|
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
27 10. Job options |job-options|
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
28 11. Controlling a job |job-control|
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
29
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
30 {Vi does not have any of these features}
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
31 {only when compiled with the |+channel| feature for channel stuff}
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
32 {only when compiled with the |+job| feature for job stuff}
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
33
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
34 ==============================================================================
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
35 1. Overview *job-channel-overview*
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
36
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
37 There are four main types of jobs:
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
38 1. A deamon, serving several Vim instances.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
39 Vim connects to it with a socket.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
40 2. One job working with one Vim instance, asynchronously.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
41 Uses a socket or pipes.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
42 3. A job performing some work for a short time, asynchronously.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
43 Uses a socket or pipes.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
44 4. Running a filter, synchronously.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
45 Uses pipes.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
46
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
47 For when using sockets See |job-start|, |job-may-start| and |channel-open|.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
48 For 2 and 3, one or more jobs using pipes, see |job-start|.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
49 For 4 use the ":{range}!cmd" command, see |filter|.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
50
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
51 Over the socket and pipes these protocols are available:
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
52 RAW nothing known, Vim cannot tell where a message ends
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
53 NL every message ends in a NL (newline) character
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
54 JSON JSON encoding |json_encode()|
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
55 JS JavaScript style JSON-like encoding |js_encode()|
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
56
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
57 Common combination are:
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
58 - Using a job connected through pipes in NL mode. E.g., to run a style
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
59 checker and receive errors and warnings.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
60 - Using a deamon, connecting over a socket in JSON mode. E.g. to lookup
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
61 crosss-refrences in a database.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
62
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
63 ==============================================================================
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
64 2. Channel demo *channel-demo*
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
65
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
66 This requires Python. The demo program can be found in
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
67 $VIMRUNTIME/tools/demoserver.py
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
68 Run it in one terminal. We will call this T1.
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
69
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
70 Run Vim in another terminal. Connect to the demo server with: >
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
71 let channel = ch_open('localhost:8765')
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
72
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
73 In T1 you should see:
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
74 === socket opened === ~
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
75
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
76 You can now send a message to the server: >
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
77 echo ch_sendexpr(channel, 'hello!')
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
78
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
79 The message is received in T1 and a response is sent back to Vim.
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
80 You can see the raw messages in T1. What Vim sends is:
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
81 [1,"hello!"] ~
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
82 And the response is:
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
83 [1,"got it"] ~
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
84 The number will increase every time you send a message.
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
85
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
86 The server can send a command to Vim. Type this on T1 (literally, including
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
87 the quotes):
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
88 ["ex","echo 'hi there'"] ~
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
89 And you should see the message in Vim. You can move the cursor a word forward:
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
90 ["normal","w"] ~
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
91
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
92 To handle asynchronous communication a callback needs to be used: >
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
93 func MyHandler(channel, msg)
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
94 echo "from the handler: " . a:msg
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
95 endfunc
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
96 call ch_sendexpr(channel, 'hello!', {'callback': "MyHandler"})
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
97 Vim will not wait for a response. Now the server can send the response later
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
98 and MyHandler will be invoked.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
99
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
100 Instead of giving a callback with every send call, it can also be specified
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
101 when opening the channel: >
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
102 call ch_close(channel)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
103 let channel = ch_open('localhost:8765', {'callback': "MyHandler"})
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
104 call ch_sendexpr(channel, 'hello!', {'callback': 0})
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
105
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
106 ==============================================================================
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
107 3. Opening a channel *channel-open*
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
108
7924
00d64eb49ce1 commit https://github.com/vim/vim/commit/681baaf4a4c81418693dcafb81421a8614832e91
Christian Brabandt <cb@256bit.org>
parents: 7864
diff changeset
109 To open a channel: >
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
110 let channel = ch_open({address} [, {options}])
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
111 if ch_status(channel) == "open"
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
112 " use the channel
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
113
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
114 Use |ch_status()| to see if the channel could be opened.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
115
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
116 {address} has the form "hostname:port". E.g., "localhost:8765".
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
117
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
118 {options} is a dictionary with optional entries:
7935
3f2e0b62003d commit https://github.com/vim/vim/commit/4d919d748e4e435edb135aa5ccf6ee7de9212023
Christian Brabandt <cb@256bit.org>
parents: 7924
diff changeset
119
3f2e0b62003d commit https://github.com/vim/vim/commit/4d919d748e4e435edb135aa5ccf6ee7de9212023
Christian Brabandt <cb@256bit.org>
parents: 7924
diff changeset
120 "mode" can be: *channel-mode*
3f2e0b62003d commit https://github.com/vim/vim/commit/4d919d748e4e435edb135aa5ccf6ee7de9212023
Christian Brabandt <cb@256bit.org>
parents: 7924
diff changeset
121 "json" - Use JSON, see below; most convenient way. Default.
8094
18a3f0f05244 commit https://github.com/vim/vim/commit/910b8aac5dc4693c4508b7acd2cef0bbfac04242
Christian Brabandt <cb@256bit.org>
parents: 8061
diff changeset
122 "js" - Use JS (JavaScript) encoding, more efficient than JSON.
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
123 "nl" - Use messages that end in a NL character
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
124 "raw" - Use raw messages
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
125
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
126 "in-mode" mode specifically for stdin, only when using pipes
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
127 "out-mode" mode specifically for stdout, only when using pipes
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
128 "err-mode" mode specifically for stderr, only when using pipes
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
129 Note: when setting "mode" the part specific mode is
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
130 overwritten. Therefore set "mode" first and the part specific
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
131 mode later.
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
132
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
133 *channel-callback*
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
134 "callback" A function that is called when a message is received that is
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
135 not handled otherwise. It gets two arguments: the channel
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
136 and the received message. Example: >
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
137 func Handle(channel, msg)
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
138 echo 'Received: ' . a:msg
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
139 endfunc
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
140 let channel = ch_open("localhost:8765", {"callback": "Handle"})
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
141 <
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
142 When "mode" is "json" or "js" the "msg" argument is the body
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
143 of the received message, converted to Vim types.
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
144 When "mode" is "nl" the "msg" argument is one message,
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
145 excluding the NL.
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
146 When "mode" is "raw" the "msg" argument is the whole message
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
147 as a string.
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
148 *out-cb*
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
149 "out-cb" A function like "callback" but used for stdout. Only for when
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
150 the channel uses pipes. When "out-cb" wasn't set the channel
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
151 callback is used.
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
152 *err-cb*
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
153 "err-cb" A function like "callback" but used for stderr. Only for when
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
154 the channel uses pipes. When "err-cb" wasn't set the channel
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
155 callback is used.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
156
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
157 TODO: *close-cb*
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
158 "close-cb" A function that is called when the channel gets closed, other
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
159 than by calling ch_close(). It should be defined like this: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
160 func MyCloseHandler(channel)
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
161 < *waittime*
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
162 "waittime" The time to wait for the connection to be made in
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
163 milliseconds. The default is zero, don't wait, which is
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
164 useful if the server is supposed to be running already. A
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
165 negative number waits forever.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
166
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
167 "timeout" The time to wait for a request when blocking, E.g. when using
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
168 ch_sendexpr(). In milliseconds. The default is 2000 (2
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
169 seconds).
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
170 *out-timeout* *err-timeout*
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
171 "out-timeout" Timeout for stdout. Only when using pipes.
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
172 "err-timeout" Timeout for stderr. Only when using pipes.
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
173 Note: when setting "timeout" the part specific mode is
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
174 overwritten. Therefore set "timeout" first and the part
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
175 specific mode later.
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
176
7967
45ea5ebf3a98 commit https://github.com/vim/vim/commit/595e64e259faefb330866852e1b9f6168544572a
Christian Brabandt <cb@256bit.org>
parents: 7957
diff changeset
177 When "mode" is "json" or "js" the "callback" is optional. When omitted it is
45ea5ebf3a98 commit https://github.com/vim/vim/commit/595e64e259faefb330866852e1b9f6168544572a
Christian Brabandt <cb@256bit.org>
parents: 7957
diff changeset
178 only possible to receive a message after sending one.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
179
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
180 To change the channel options after opening it use |ch_setoptions()|. The
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
181 arguments are similar to what is passed to |ch_open()|, but "waittime" cannot
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
182 be given, since that only applies to opening the channel.
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
183
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
184 For example, the handler can be added or changed: >
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
185 call ch_setoptions(channel, {'callback': callback})
7957
b74549818500 commit https://github.com/vim/vim/commit/835dc636a5350f610b62f110227d2363b5b2880a
Christian Brabandt <cb@256bit.org>
parents: 7935
diff changeset
186 When "callback" is empty (zero or an empty string) the handler is removed.
7935
3f2e0b62003d commit https://github.com/vim/vim/commit/4d919d748e4e435edb135aa5ccf6ee7de9212023
Christian Brabandt <cb@256bit.org>
parents: 7924
diff changeset
187
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
188 The timeout can be changed: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
189 call ch_setoptions(channel, {'timeout': msec})
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
190 <
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
191 *channel-close* *E906*
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
192 Once done with the channel, disconnect it like this: >
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
193 call ch_close(channel)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
194 When a socket is used this will close the socket for both directions. When
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
195 pipes are used (stdin/stdout/stderr) they are all closed. This might not be
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
196 what you want! Stopping the job with job_stop() might be better.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
197
7992
78106b0f2c56 commit https://github.com/vim/vim/commit/cbebd4879cc78e670d79b2c57dc33d7b911c962a
Christian Brabandt <cb@256bit.org>
parents: 7967
diff changeset
198 When the channel can't be opened you will get an error message. There is a
78106b0f2c56 commit https://github.com/vim/vim/commit/cbebd4879cc78e670d79b2c57dc33d7b911c962a
Christian Brabandt <cb@256bit.org>
parents: 7967
diff changeset
199 difference between MS-Windows and Unix: On Unix when the port doesn't exist
78106b0f2c56 commit https://github.com/vim/vim/commit/cbebd4879cc78e670d79b2c57dc33d7b911c962a
Christian Brabandt <cb@256bit.org>
parents: 7967
diff changeset
200 ch_open() fails quickly. On MS-Windows "waittime" applies.
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
201 *E898* *E899* *E900* *E901* *E902*
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
202
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
203 If there is an error reading or writing a channel it will be closed.
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
204 *E896* *E630* *E631*
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
205
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
206 ==============================================================================
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
207 4. Using a JSON or JS channel *channel-use*
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
208
8094
18a3f0f05244 commit https://github.com/vim/vim/commit/910b8aac5dc4693c4508b7acd2cef0bbfac04242
Christian Brabandt <cb@256bit.org>
parents: 8061
diff changeset
209 If mode is JSON then a message can be sent synchronously like this: >
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
210 let response = ch_sendexpr(channel, {expr})
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
211 This awaits a response from the other side.
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
212
8094
18a3f0f05244 commit https://github.com/vim/vim/commit/910b8aac5dc4693c4508b7acd2cef0bbfac04242
Christian Brabandt <cb@256bit.org>
parents: 8061
diff changeset
213 When mode is JS this works the same, except that the messages use
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
214 JavaScript encoding. See |js_encode()| for the difference.
7967
45ea5ebf3a98 commit https://github.com/vim/vim/commit/595e64e259faefb330866852e1b9f6168544572a
Christian Brabandt <cb@256bit.org>
parents: 7957
diff changeset
215
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
216 To send a message, without handling a response or letting the channel callback
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
217 handle the response: >
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
218 call ch_sendexpr(channel, {expr}, {'callback': 0})
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
219
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
220 To send a message and letting the response handled by a specific function,
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
221 asynchronously: >
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
222 call ch_sendexpr(channel, {expr}, {'callback': Handler})
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
223
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
224 Vim will match the response with the request using the message ID. Once the
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
225 response is received the callback will be invoked. Further responses with the
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
226 same ID will be ignored. If your server sends back multiple responses you
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
227 need to send them with ID zero, they will be passed to the channel callback.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
228
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
229 The {expr} is converted to JSON and wrapped in an array. An example of the
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
230 message that the receiver will get when {expr} is the string "hello":
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
231 [12,"hello"] ~
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
232
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
233 The format of the JSON sent is:
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
234 [{number},{expr}]
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
235
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
236 In which {number} is different every time. It must be used in the response
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
237 (if any):
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
238
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
239 [{number},{response}]
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
240
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
241 This way Vim knows which sent message matches with which received message and
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
242 can call the right handler. Also when the messages arrive out of order.
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
243
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
244 The sender must always send valid JSON to Vim. Vim can check for the end of
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
245 the message by parsing the JSON. It will only accept the message if the end
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
246 was received.
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
247
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
248 When the process wants to send a message to Vim without first receiving a
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
249 message, it must use the number zero:
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
250 [0,{response}]
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
251
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
252 Then channel handler will then get {response} converted to Vim types. If the
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
253 channel does not have a handler the message is dropped.
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
254
8148
f5da459c5698 commit https://github.com/vim/vim/commit/e0fa3742ead676a3074a10edadbc955e1a89153d
Christian Brabandt <cb@256bit.org>
parents: 8094
diff changeset
255 On read error or ch_close(), when using a socket, the string "DETACH" is sent,
f5da459c5698 commit https://github.com/vim/vim/commit/e0fa3742ead676a3074a10edadbc955e1a89153d
Christian Brabandt <cb@256bit.org>
parents: 8094
diff changeset
256 if still possible. The channel will then be inactive.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
257
7992
78106b0f2c56 commit https://github.com/vim/vim/commit/cbebd4879cc78e670d79b2c57dc33d7b911c962a
Christian Brabandt <cb@256bit.org>
parents: 7967
diff changeset
258 It is also possible to use ch_sendraw() on a JSON or JS channel. The caller
78106b0f2c56 commit https://github.com/vim/vim/commit/cbebd4879cc78e670d79b2c57dc33d7b911c962a
Christian Brabandt <cb@256bit.org>
parents: 7967
diff changeset
259 is then completely responsible for correct encoding and decoding.
78106b0f2c56 commit https://github.com/vim/vim/commit/cbebd4879cc78e670d79b2c57dc33d7b911c962a
Christian Brabandt <cb@256bit.org>
parents: 7967
diff changeset
260
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
261 ==============================================================================
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
262 5. Channel commands *channel-commands*
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
263
8094
18a3f0f05244 commit https://github.com/vim/vim/commit/910b8aac5dc4693c4508b7acd2cef0bbfac04242
Christian Brabandt <cb@256bit.org>
parents: 8061
diff changeset
264 With a JSON channel the process can send commands to Vim that will be
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
265 handled by Vim internally, it does not require a handler for the channel.
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
266
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
267 Possible commands are: *E903* *E904* *E905*
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
268 ["redraw" {forced}]
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
269 ["ex", {Ex command}]
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
270 ["normal", {Normal mode command}]
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
271 ["expr", {expression}, {number}]
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
272 ["expr", {expression}]
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
273 ["call", {func name}, {argument list}, {number}]
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
274 ["call", {func name}, {argument list}]
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
275
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
276 With all of these: Be careful what these commands do! You can easily
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
277 interfere with what the user is doing. To avoid trouble use |mode()| to check
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
278 that the editor is in the expected state. E.g., to send keys that must be
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
279 inserted as text, not executed as a command:
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
280 ["ex","if mode() == 'i' | call feedkeys('ClassName') | endif"] ~
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
281
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
282 Errors in these commands are normally not reported to avoid them messing up
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
283 the display. If you do want to see them, set the 'verbose' option to 3 or
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
284 higher.
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
285
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
286
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
287 Command "redraw" ~
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
288
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
289 The other commands do not update the screen, so that you can send a sequence
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
290 of commands without the cursor moving around. You must end with the "redraw"
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
291 command to show any changed text and show the cursor where it belongs.
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
292
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
293 The argument is normally an empty string:
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
294 ["redraw", ""] ~
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
295 To first clear the screen pass "force":
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
296 ["redraw", "force"] ~
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
297
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
298
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
299 Command "ex" ~
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
300
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
301 The "ex" command is executed as any Ex command. There is no response for
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
302 completion or error. You could use functions in an |autoload| script:
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
303 ["ex","call myscript#MyFunc(arg)"]
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
304
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
305 You can also use "call |feedkeys()|" to insert any key sequence.
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
306
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
307
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
308 Command "normal" ~
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
309
7924
00d64eb49ce1 commit https://github.com/vim/vim/commit/681baaf4a4c81418693dcafb81421a8614832e91
Christian Brabandt <cb@256bit.org>
parents: 7864
diff changeset
310 The "normal" command is executed like with ":normal!", commands are not
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
311 mapped. Example to open the folds under the cursor:
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
312 ["normal" "zO"]
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
313
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
314
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
315 Command "expr" with response ~
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
316
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
317 The "expr" command can be used to get the result of an expression. For
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
318 example, to get the number of lines in the current buffer:
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
319 ["expr","line('$')", -2] ~
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
320
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
321 It will send back the result of the expression:
8148
f5da459c5698 commit https://github.com/vim/vim/commit/e0fa3742ead676a3074a10edadbc955e1a89153d
Christian Brabandt <cb@256bit.org>
parents: 8094
diff changeset
322 [-2, "last line"] ~
f5da459c5698 commit https://github.com/vim/vim/commit/e0fa3742ead676a3074a10edadbc955e1a89153d
Christian Brabandt <cb@256bit.org>
parents: 8094
diff changeset
323 The format is:
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
324 [{number}, {result}]
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
325 *E915*
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
326 Here {number} is the same as what was in the request. Use a negative number
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
327 to avoid confusion with message that Vim sends. Use a different number on
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
328 every request to be able to match the request with the response.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
329
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
330 {result} is the result of the evaluation and is JSON encoded. If the
7967
45ea5ebf3a98 commit https://github.com/vim/vim/commit/595e64e259faefb330866852e1b9f6168544572a
Christian Brabandt <cb@256bit.org>
parents: 7957
diff changeset
331 evaluation fails or the result can't be encoded in JSON it is the string
45ea5ebf3a98 commit https://github.com/vim/vim/commit/595e64e259faefb330866852e1b9f6168544572a
Christian Brabandt <cb@256bit.org>
parents: 7957
diff changeset
332 "ERROR".
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
333
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
334
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
335 Command "expr" without a response ~
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
336
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
337 This command is similar to "expr" above, but does not send back any response.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
338 Example:
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
339 ["expr","setline('$', ['one', 'two', 'three'])"] ~
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
340 There is no third argument in the request.
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
341
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
342
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
343 Command "call" ~
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
344
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
345 This is similar to "expr", but instead of passing the whole expression as a
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
346 string this passes the name of a function and a list of arguments. This
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
347 avoids the conversion of the arguments to a string and escaping and
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
348 concatenating them. Example:
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
349 ["call", "line", ["$"], -2] ~
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
350
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
351 Leave out the fourth argument if no response is to be sent:
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
352 ["call", "setline", ["$", ["one", "two", "three"]]] ~
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
353
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
354 ==============================================================================
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
355 6. Using a RAW or NL channel *channel-raw*
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
356
8094
18a3f0f05244 commit https://github.com/vim/vim/commit/910b8aac5dc4693c4508b7acd2cef0bbfac04242
Christian Brabandt <cb@256bit.org>
parents: 8061
diff changeset
357 If mode is RAW or NL then a message can be send like this: >
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
358 let response = ch_sendraw(channel, {string})
8094
18a3f0f05244 commit https://github.com/vim/vim/commit/910b8aac5dc4693c4508b7acd2cef0bbfac04242
Christian Brabandt <cb@256bit.org>
parents: 8061
diff changeset
359
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
360 The {string} is sent as-is. The response will be what can be read from the
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
361 channel right away. Since Vim doesn't know how to recognize the end of the
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
362 message you need to take care of it yourself. The timeout applies for reading
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
363 the first byte, after that it will not wait for anything more.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
364
8094
18a3f0f05244 commit https://github.com/vim/vim/commit/910b8aac5dc4693c4508b7acd2cef0bbfac04242
Christian Brabandt <cb@256bit.org>
parents: 8061
diff changeset
365 If mode is "nl" you can send a message in a similar way. You are expected
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
366 to put in the NL after each message. Thus you can also send several messages
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
367 ending in a NL at once. The response will be the text up to and including the
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
368 first NL. This can also be just the NL for an empty response.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
369 If no NL was read before the channel timeout an empty string is returned.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
370
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
371 To send a message, without expecting a response: >
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
372 call ch_sendraw(channel, {string}, 0)
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
373 The process can send back a response, the channel handler will be called with
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
374 it.
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
375
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
376 To send a message and letting the response handled by a specific function,
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
377 asynchronously: >
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
378 call ch_sendraw(channel, {string}, {callback})
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
379
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
380 This {string} can also be JSON, use |json_encode()| to create it and
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
381 |json_decode()| to handle a received JSON message.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
382
7992
78106b0f2c56 commit https://github.com/vim/vim/commit/cbebd4879cc78e670d79b2c57dc33d7b911c962a
Christian Brabandt <cb@256bit.org>
parents: 7967
diff changeset
383 It is not possible to use |ch_sendexpr()| on a raw channel.
78106b0f2c56 commit https://github.com/vim/vim/commit/cbebd4879cc78e670d79b2c57dc33d7b911c962a
Christian Brabandt <cb@256bit.org>
parents: 7967
diff changeset
384
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
385 ==============================================================================
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
386 7. More channel functions *channel-more*
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
387
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
388 To obtain the status of a channel: ch_status(channel). The possible results
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
389 are:
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
390 "fail" Failed to open the channel.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
391 "open" The channel can be used.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
392 "closed" The channel was closed.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
393
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
394 TODO:
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
395 To objain the job associated with a channel: ch_getjob(channel)
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
396
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
397 To read one message from a channel: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
398 let output = ch_read(channel)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
399 This uses the channel timeout. To read without a timeout, just get any
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
400 message that is available: >
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
401 let output = ch_read(channel, {'timeout': 0})
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
402 When no message was available then the result is v:none for a JSON or JS mode
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
403 channels, an empty string for a RAW or NL channel.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
404
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
405 To read all output from a RAW channel that is available: >
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
406 let output = ch_readraw(channel)
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
407 To read the error output: >
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
408 let output = ch_readraw(channel, {"part": "err"})
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
409
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
410 ==============================================================================
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
411 8. Starting a job with a channel *job-start* *job*
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
412
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
413 To start a job and open a channel for stdin/stdout/stderr: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
414 let job = job_start(command, {options})
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
415
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
416 You can get the channel with: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
417 let channel = job_getchannel(job)
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
418
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
419 The channel will use NL mode. If you want another mode it's best to specify
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
420 this in {options}. When changing the mode later some text may have already
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
421 been received and not parsed correctly.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
422
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
423 If the command produces a line of output that you want to deal with, specify
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
424 a handler for stdout: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
425 let job = job_start(command, {"out-cb": "MyHandler"})
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
426 The function will be called with the channel and a message. You would define
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
427 it like this: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
428 func MyHandler(channel, msg)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
429
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
430 Without the handler you need to read the output with |ch_read()| or
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
431 |ch_readraw()|.
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
432
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
433 The handler defined for "out-cb" will not receive stderr. If you want to
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
434 handle that separately, add an "err-cb" handler: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
435 let job = job_start(command, {"out-cb": "MyHandler",
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
436 \ "err-cb": "ErrHandler"})
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
437
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
438 If you want to handle both stderr and stdout with one handler use the
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
439 "callback" option: >
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
440 let job = job_start(command, {"callback": "MyHandler"})
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
441
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
442 You can send a message to the command with ch_sendraw(). If the channel is in
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
443 JSON or JS mode you can use ch_sendexpr().
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
444
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
445 There are several options you can use, see |job-options|.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
446
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
447 TODO:
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
448 To run a job and read its output once it is done: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
449
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
450 let job = job_start({command}, {'exit-cb': 'MyHandler'})
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
451 func MyHandler(job, status)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
452 let channel = job_getchannel()
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
453 let output = ch_readall(channel)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
454 " parse output
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
455 endfunc
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
456
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
457 ==============================================================================
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
458 9. Starting a job without a channel *job-start-nochannel*
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
459
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
460 To start another process without creating a channel: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
461 let job = job_start(command, {"in-io": "null", "out-io": "null"})
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
462
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
463 This starts {command} in the background, Vim does not wait for it to finish.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
464
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
465 TODO:
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
466 When Vim sees that neither stdin, stdout or stderr are connected, no channel
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
467 will be created. Often you will want to include redirection in the command to
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
468 avoid it getting stuck.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
469
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
470 There are several options you can use, see |job-options|.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
471
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
472 TODO: *job-may-start*
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
473 To start a job only when connecting to an address does not work use
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
474 job_maystart('command', {address}, {options}), For Example: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
475 let job = job_maystart(command, address, {"waittime": 1000})
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
476 let channel = job_gethandle(job)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
477
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
478 This comes down to: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
479 let channel = ch_open(address, {"waittime": 0})
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
480 if ch_status(channel) == "fail"
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
481 let job = job_start(command)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
482 let channel = ch_open(address, {"waittime": 1000})
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
483 call job_sethandle(channel)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
484 endif
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
485 Note that the specified waittime applies to when the job has been started.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
486 This gives the job some time to make the port available.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
487
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
488 ==============================================================================
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
489 10. Job options *job-options*
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
490
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
491 The {options} argument in job_start() is a dictionary. All entries are
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
492 optional. Some options can be used after the job has started, using
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
493 job_setoptions(job, {options}). Many options can be used with the channel
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
494 related to the job, using ch_setoptions(channel, {options}).
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
495 See |job_setoptions()| and |ch_setoptions()|.
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
496
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
497 *job-callback*
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
498 "callback": handler Callback for something to read on any part of the
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
499 channel.
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
500 *job-out-cb*
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
501 "out-cb": handler Callback for when there is something to read on
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
502 stdout.
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
503 *job-err-cb*
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
504 "err-cb": handler Callback for when there is something to read on
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
505 stderr.
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
506 TODO: *job-close-cb*
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
507 "close-cb": handler Callback for when the channel is closed. Same as
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
508 "close-cb" on ch_open().
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
509 *job-exit-cb*
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
510 "exit-cb": handler Callback for when the job ends. The arguments are the
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
511 job and the exit status.
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
512 Vim checks about every 10 seconds for jobs that ended.
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
513 The callback can also be triggered by calling
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
514 |job_status()|.
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
515 *job-stoponexit*
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
516 "stoponexit": {signal} Send {signal} to the job when Vim exits. See
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
517 |job_stop()| for possible values.
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
518 "stoponexit": "" Do not stop the job when Vim exits.
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
519 The default is "term".
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
520
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
521 TODO: *job-term*
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
522 "term": "open" Start a terminal and connect the job
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
523 stdin/stdout/stderr to it.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
524
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
525 TODO: *job-in-io*
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
526 "in-io": "null" disconnect stdin
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
527 "in-io": "pipe" stdin is connected to the channel (default)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
528 "in-io": "file" stdin reads from a file
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
529 "in-file": "/path/file" the file to read from
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
530
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
531 TODO: *job-out-io*
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
532 "out-io": "null" disconnect stdout
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
533 "out-io": "pipe" stdout is connected to the channel (default)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
534 "out-io": "file" stdout writes to a file
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
535 "out-file": "/path/file" the file to write to
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
536 "out-io": "buffer" stdout appends to a buffer
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
537 "out-buffer": "name" buffer to append to
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
538
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
539 TODO: *job-err-io*
8094
18a3f0f05244 commit https://github.com/vim/vim/commit/910b8aac5dc4693c4508b7acd2cef0bbfac04242
Christian Brabandt <cb@256bit.org>
parents: 8061
diff changeset
540 "err-io": "out" same type as stdout (default)
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
541 "err-io": "null" disconnect stderr
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
542 "err-io": "pipe" stderr is connected to the channel
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
543 "err-io": "file" stderr writes to a file
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
544 "err-file": "/path/file" the file to write to
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
545 "err-io": "buffer" stderr appends to a buffer
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
546 "err-buffer": "name" buffer to append to
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
547
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
548 ==============================================================================
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
549 11. Controlling a job *job-control*
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
550
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
551 To get the status of a job: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
552 echo job_status(job)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
553
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
554 To make a job stop running: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
555 job_stop(job)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
556
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
557 This is the normal way to end a job. On Unix it sends a SIGTERM to the job.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
558 It is possible to use other ways to stop the job, or even send arbitrary
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
559 signals. E.g. to force a job to stop, "kill it": >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
560 job_stop(job, "kill")
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
561
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
562 For more options see |job_stop()|.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
563
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
564
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
565 vim:tw=78:ts=8:ft=help:norl: