Mercurial > vim

annotate runtime/doc/channel.txt @ 33299:4c975fa0a442 v9.0.1915

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
patch 9.0.1915: r_CTRL-C works differently in visual mode Commit: https://github.com/vim/vim/commit/476733f3d06876c7ac105e064108c973a57984d3 Author: Christian Brabandt <cb@256bit.org> Date: Tue Sep 19 20:41:51 2023 +0200 patch 9.0.1915: r_CTRL-C works differently in visual mode Problem: r_CTRL-C works differently in visual mode Solution: Make r_CTRL-C behave consistent in visual mode in terminal and Windows GUI in visual mode, r CTRL-C behaves strange in Unix like environments. It seems to end visual mode, but still is waiting for few more chars, however it never seems to replace it by any characters and eventually just returns back into normal mode. In contrast in Windows GUI mode, r_CTRL-C replaces in the selected area all characters by a literal CTRL-C. Not sure why it behaves like this. It seems in the Windows GUI, got_int is not set and therefore behaves as if any other normal character has been pressed. So remove the special casing of what happens when got_int is set and make it always behave like in Windows GUI mode. Add a test to verify it always behaves like replacing in the selected area each selected character by a literal CTRL-C. closes: #13091 closes: #13112 Signed-off-by: Christian Brabandt <cb@256bit.org>
author Christian Brabandt <cb@256bit.org>
date Tue, 19 Sep 2023 21:00:03 +0200
parents 3bc84e3fd05c
children 4635e43f2c6f
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
33253
3bc84e3fd05c runtime(doc): documentation updates
Christian Brabandt <cb@256bit.org>
parents: 31383
diff changeset
1 *channel.txt* For Vim version 9.0. Last change: 2023 Aug 15
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 Vim uses channels to communicate with other processes.
9533
9f921133ee90 commit https://github.com/vim/vim/commit/269f595f9eef584937e7eae70fde68cdd7da5bcf
Christian Brabandt <cb@256bit.org>
parents: 9464
diff changeset
10 A channel uses a socket or pipes. *socket-interface*
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
11 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
12 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
13
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
14 1. Overview |job-channel-overview|
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
15 2. Channel demo |channel-demo|
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
16 3. Opening a channel |channel-open|
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
17 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
18 5. Channel commands |channel-commands|
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
19 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
20 7. More channel functions |channel-more|
17571
2704c4e3e20a Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 17456
diff changeset
21 8. Channel functions details |channel-functions-details|
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
22 9. Starting a job with a channel |job-start|
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
23 10. Starting a job without a channel |job-start-nochannel|
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
24 11. Job functions |job-functions-details|
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
25 12. Job options |job-options|
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
26 13. Controlling a job |job-control|
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
27 14. Using a prompt buffer |prompt-buffer|
28467
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
28 15. Language Server Protocol |language-server-protocol|
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
29
29533
34c1f4cd0c18 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 29314
diff changeset
30 *E1277*
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}
10051
46763b01cd9a commit https://github.com/vim/vim/commit/f37506f60f87d52a9e8850e30067645e2b13783c
Christian Brabandt <cb@256bit.org>
parents: 10004
diff changeset
32 You can check this with: `has('channel')`
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
33 {only when compiled with the |+job| feature for job stuff}
10051
46763b01cd9a commit https://github.com/vim/vim/commit/f37506f60f87d52a9e8850e30067645e2b13783c
Christian Brabandt <cb@256bit.org>
parents: 10004
diff changeset
34 You can check this with: `has('job')`
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
35
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
36 ==============================================================================
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
37 1. Overview *job-channel-overview*
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
38
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
39 There are four main types of jobs:
10218
584c835a2de1 commit https://github.com/vim/vim/commit/50ba526fbf3e9e5e0e6b0b3086a4d5df581ebc7e
Christian Brabandt <cb@256bit.org>
parents: 10198
diff changeset
40 1. A daemon, serving several Vim instances.
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
41 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
42 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
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 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
45 Uses a socket or pipes.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
46 4. Running a filter, synchronously.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
47 Uses pipes.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
48
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
49 For when using sockets See |job-start|, |job-start-nochannel| and
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
50 |channel-open|. For 2 and 3, one or more jobs using pipes, see |job-start|.
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
51 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
52
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
53 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
54 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
55 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
56 JSON JSON encoding |json_encode()|
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
57 JS JavaScript style JSON-like encoding |js_encode()|
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
58 LSP Language Server Protocol encoding |language-server-protocol|
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
59
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
60 Common combination are:
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
61 - 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
62 checker and receive errors and warnings.
13735
a62eeee5f116 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12045
diff changeset
63 - Using a daemon, connecting over a socket in JSON mode. E.g. to lookup
9860
9eaf8ef656e9 commit https://github.com/vim/vim/commit/0952131376a517fc12dc5ae908a97018b4ee23f0
Christian Brabandt <cb@256bit.org>
parents: 9533
diff changeset
64 cross-references in a database.
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
65
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
66 ==============================================================================
9116
bc38030aec7d commit https://github.com/vim/vim/commit/26852128a2b713ef49341a0c18daba928444e7eb
Christian Brabandt <cb@256bit.org>
parents: 9097
diff changeset
67 2. Channel demo *channel-demo* *demoserver.py*
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
68
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
69 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
70 $VIMRUNTIME/tools/demoserver.py
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
71 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
72
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
73 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
74 let channel = ch_open('localhost:8765')
7788
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 In T1 you should see:
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
77 === socket opened === ~
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 You can now send a message to the server: >
8285
e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f
Christian Brabandt <cb@256bit.org>
parents: 8267
diff changeset
80 echo ch_evalexpr(channel, 'hello!')
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
81
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
82 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
83 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
84 [1,"hello!"] ~
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
85 And the response is:
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
86 [1,"got it"] ~
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
87 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
88
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
89 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
90 the quotes):
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
91 ["ex","echo 'hi there'"] ~
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
92 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
93 ["normal","w"] ~
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
94
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
95 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
96 func MyHandler(channel, msg)
27903
d19b7aee1925 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 26438
diff changeset
97 echo "from the handler: " .. a:msg
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
98 endfunc
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
99 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
100 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
101 and MyHandler will be invoked.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
102
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
103 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
104 when opening the channel: >
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
105 call ch_close(channel)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
106 let channel = ch_open('localhost:8765', {'callback': "MyHandler"})
26438
c725b8e17f1f Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 25619
diff changeset
107 call ch_sendexpr(channel, 'hello channel!')
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
108
8392
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
109 When trying out channels it's useful to see what is going on. You can tell
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
110 Vim to write lines in log file: >
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
111 call ch_logfile('channellog', 'w')
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
112 See |ch_logfile()|.
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
113
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
114 ==============================================================================
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
115 3. Opening a channel *channel-open*
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
116
7924
00d64eb49ce1 commit https://github.com/vim/vim/commit/681baaf4a4c81418693dcafb81421a8614832e91
Christian Brabandt <cb@256bit.org>
parents: 7864
diff changeset
117 To open a channel: >
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
118 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
119 if ch_status(channel) == "open"
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
120 " use the channel
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
121
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
122 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
123
28317
d32dc906dd2c patch 8.2.4684: cannot open a channel on a Unix domain socket
Bram Moolenaar <Bram@vim.org>
parents: 28246
diff changeset
124 *channel-address*
d32dc906dd2c patch 8.2.4684: cannot open a channel on a Unix domain socket
Bram Moolenaar <Bram@vim.org>
parents: 28246
diff changeset
125 {address} can be a domain name or an IP address, followed by a port number, or
d32dc906dd2c patch 8.2.4684: cannot open a channel on a Unix domain socket
Bram Moolenaar <Bram@vim.org>
parents: 28246
diff changeset
126 a Unix-domain socket path prefixed by "unix:". E.g. >
d32dc906dd2c patch 8.2.4684: cannot open a channel on a Unix domain socket
Bram Moolenaar <Bram@vim.org>
parents: 28246
diff changeset
127 www.example.com:80 " domain + port
d32dc906dd2c patch 8.2.4684: cannot open a channel on a Unix domain socket
Bram Moolenaar <Bram@vim.org>
parents: 28246
diff changeset
128 127.0.0.1:1234 " IPv4 + port
d32dc906dd2c patch 8.2.4684: cannot open a channel on a Unix domain socket
Bram Moolenaar <Bram@vim.org>
parents: 28246
diff changeset
129 [2001:db8::1]:8765 " IPv6 + port
d32dc906dd2c patch 8.2.4684: cannot open a channel on a Unix domain socket
Bram Moolenaar <Bram@vim.org>
parents: 28246
diff changeset
130 unix:/tmp/my-socket " Unix-domain socket path
20003
e373843e2980 patch 8.2.0557: no IPv6 support for channels
Bram Moolenaar <Bram@vim.org>
parents: 18879
diff changeset
131
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
132 {options} is a dictionary with optional entries: *channel-open-options*
7935
3f2e0b62003d commit https://github.com/vim/vim/commit/4d919d748e4e435edb135aa5ccf6ee7de9212023
Christian Brabandt <cb@256bit.org>
parents: 7924
diff changeset
133
3f2e0b62003d commit https://github.com/vim/vim/commit/4d919d748e4e435edb135aa5ccf6ee7de9212023
Christian Brabandt <cb@256bit.org>
parents: 7924
diff changeset
134 "mode" can be: *channel-mode*
3f2e0b62003d commit https://github.com/vim/vim/commit/4d919d748e4e435edb135aa5ccf6ee7de9212023
Christian Brabandt <cb@256bit.org>
parents: 7924
diff changeset
135 "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
136 "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
137 "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
138 "raw" - Use raw messages
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
139 "lsp" - Use language server protocol encoding
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
140 *channel-callback* *E921*
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
141 "callback" A function that is called when a message is received that is
26438
c725b8e17f1f Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 25619
diff changeset
142 not handled otherwise (e.g. a JSON message with ID zero). It
c725b8e17f1f Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 25619
diff changeset
143 gets two arguments: the channel and the received message.
c725b8e17f1f Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 25619
diff changeset
144 Example: >
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
145 func Handle(channel, msg)
27903
d19b7aee1925 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 26438
diff changeset
146 echo 'Received: ' .. a:msg
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
147 endfunc
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
148 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
149 <
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
150 When "mode" is "json" or "js" or "lsp" the "msg" argument is
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
151 the body of the received message, converted to Vim types.
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
152 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
153 excluding the NL.
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
154 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
155 as a string.
8673
ed7251c3e2d3 commit https://github.com/vim/vim/commit/e18c0b39815c5a746887a509c2cd9f11fadaba07
Christian Brabandt <cb@256bit.org>
parents: 8540
diff changeset
156
ed7251c3e2d3 commit https://github.com/vim/vim/commit/e18c0b39815c5a746887a509c2cd9f11fadaba07
Christian Brabandt <cb@256bit.org>
parents: 8540
diff changeset
157 For all callbacks: Use |function()| to bind it to arguments
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
158 and/or a Dictionary. Or use the form "dict.function" to bind
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
159 the Dictionary.
9097
071f9da012fb commit https://github.com/vim/vim/commit/06d2d38ab7564e1f784b1058a4ef4580cd6d1810
Christian Brabandt <cb@256bit.org>
parents: 9076
diff changeset
160
071f9da012fb commit https://github.com/vim/vim/commit/06d2d38ab7564e1f784b1058a4ef4580cd6d1810
Christian Brabandt <cb@256bit.org>
parents: 9076
diff changeset
161 Callbacks are only called at a "safe" moment, usually when Vim
071f9da012fb commit https://github.com/vim/vim/commit/06d2d38ab7564e1f784b1058a4ef4580cd6d1810
Christian Brabandt <cb@256bit.org>
parents: 9076
diff changeset
162 is waiting for the user to type a character. Vim does not use
071f9da012fb commit https://github.com/vim/vim/commit/06d2d38ab7564e1f784b1058a4ef4580cd6d1810
Christian Brabandt <cb@256bit.org>
parents: 9076
diff changeset
163 multi-threading.
071f9da012fb commit https://github.com/vim/vim/commit/06d2d38ab7564e1f784b1058a4ef4580cd6d1810
Christian Brabandt <cb@256bit.org>
parents: 9076
diff changeset
164
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
165 *close_cb*
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
166 "close_cb" A function that is called when the channel gets closed, other
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
167 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
168 func MyCloseHandler(channel)
9097
071f9da012fb commit https://github.com/vim/vim/commit/06d2d38ab7564e1f784b1058a4ef4580cd6d1810
Christian Brabandt <cb@256bit.org>
parents: 9076
diff changeset
169 < Vim will invoke callbacks that handle data before invoking
071f9da012fb commit https://github.com/vim/vim/commit/06d2d38ab7564e1f784b1058a4ef4580cd6d1810
Christian Brabandt <cb@256bit.org>
parents: 9076
diff changeset
170 close_cb, thus when this function is called no more data will
16808
c002c4899529 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 16553
diff changeset
171 be passed to the callbacks. However, if a callback causes Vim
c002c4899529 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 16553
diff changeset
172 to check for messages, the close_cb may be invoked while still
c002c4899529 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 16553
diff changeset
173 in the callback. The plugin must handle this somehow, it can
c002c4899529 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 16553
diff changeset
174 be useful to know that no more data is coming.
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
175 If it is not known if there is a message to be read, use a
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
176 try/catch block: >
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
177 try
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
178 let msg = ch_readraw(a:channel)
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
179 catch
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
180 let msg = 'no message'
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
181 endtry
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
182 try
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
183 let err = ch_readraw(a:channel, #{part: 'err'})
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
184 catch
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
185 let err = 'no error'
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
186 endtry
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
187 < *channel-drop*
10426
acfc83aca8ee commit https://github.com/vim/vim/commit/958dc6923d341390531888058495569d73c356c3
Christian Brabandt <cb@256bit.org>
parents: 10422
diff changeset
188 "drop" Specifies when to drop messages:
acfc83aca8ee commit https://github.com/vim/vim/commit/958dc6923d341390531888058495569d73c356c3
Christian Brabandt <cb@256bit.org>
parents: 10422
diff changeset
189 "auto" When there is no callback to handle a message.
acfc83aca8ee commit https://github.com/vim/vim/commit/958dc6923d341390531888058495569d73c356c3
Christian Brabandt <cb@256bit.org>
parents: 10422
diff changeset
190 The "close_cb" is also considered for this.
acfc83aca8ee commit https://github.com/vim/vim/commit/958dc6923d341390531888058495569d73c356c3
Christian Brabandt <cb@256bit.org>
parents: 10422
diff changeset
191 "never" All messages will be kept.
acfc83aca8ee commit https://github.com/vim/vim/commit/958dc6923d341390531888058495569d73c356c3
Christian Brabandt <cb@256bit.org>
parents: 10422
diff changeset
192
14675
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
193 *channel-noblock*
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
194 "noblock" Same effect as |job-noblock|. Only matters for writing.
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
195
9097
071f9da012fb commit https://github.com/vim/vim/commit/06d2d38ab7564e1f784b1058a4ef4580cd6d1810
Christian Brabandt <cb@256bit.org>
parents: 9076
diff changeset
196 *waittime*
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
197 "waittime" The time to wait for the connection to be made in
8246
f16bfe02cef1 commit https://github.com/vim/vim/commit/f391327adbbffb11180cf6038a92af1ed144e907
Christian Brabandt <cb@256bit.org>
parents: 8178
diff changeset
198 milliseconds. A negative number waits forever.
f16bfe02cef1 commit https://github.com/vim/vim/commit/f391327adbbffb11180cf6038a92af1ed144e907
Christian Brabandt <cb@256bit.org>
parents: 8178
diff changeset
199
f16bfe02cef1 commit https://github.com/vim/vim/commit/f391327adbbffb11180cf6038a92af1ed144e907
Christian Brabandt <cb@256bit.org>
parents: 8178
diff changeset
200 The default is zero, don't wait, which is useful if a local
f16bfe02cef1 commit https://github.com/vim/vim/commit/f391327adbbffb11180cf6038a92af1ed144e907
Christian Brabandt <cb@256bit.org>
parents: 8178
diff changeset
201 server is supposed to be running already. On Unix Vim
f16bfe02cef1 commit https://github.com/vim/vim/commit/f391327adbbffb11180cf6038a92af1ed144e907
Christian Brabandt <cb@256bit.org>
parents: 8178
diff changeset
202 actually uses a 1 msec timeout, that is required on many
f16bfe02cef1 commit https://github.com/vim/vim/commit/f391327adbbffb11180cf6038a92af1ed144e907
Christian Brabandt <cb@256bit.org>
parents: 8178
diff changeset
203 systems. Use a larger value for a remote server, e.g. 10
f16bfe02cef1 commit https://github.com/vim/vim/commit/f391327adbbffb11180cf6038a92af1ed144e907
Christian Brabandt <cb@256bit.org>
parents: 8178
diff changeset
204 msec at least.
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
205 *channel-timeout*
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
206 "timeout" The time to wait for a request when blocking, E.g. when using
8285
e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f
Christian Brabandt <cb@256bit.org>
parents: 8267
diff changeset
207 ch_evalexpr(). 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
208 seconds).
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
209
7967
45ea5ebf3a98 commit https://github.com/vim/vim/commit/595e64e259faefb330866852e1b9f6168544572a
Christian Brabandt <cb@256bit.org>
parents: 7957
diff changeset
210 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
211 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
212
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
213 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
214 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
215 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
216
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
217 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
218 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
219 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
220
8392
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
221 After a callback has been invoked Vim will update the screen and put the
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
222 cursor back where it belongs. Thus the callback should not need to do
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
223 `:redraw`.
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
224
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
225 The timeout can be changed: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
226 call ch_setoptions(channel, {'timeout': msec})
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
227 <
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
228 *channel-close* *E906*
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
229 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
230 call ch_close(channel)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
231 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
232 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
233 what you want! Stopping the job with job_stop() might be better.
8267
108d30ed34ba commit https://github.com/vim/vim/commit/187db50d0499aecf4cfd42fb4db0a1bebf61c8cd
Christian Brabandt <cb@256bit.org>
parents: 8246
diff changeset
234 All readahead is discarded, callbacks will no longer be invoked.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
235
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
236 Note that a channel is closed in three stages:
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
237 - The I/O ends, log message: "Closing channel". There can still be queued
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
238 messages to read or callbacks to invoke.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
239 - The readahead is cleared, log message: "Clearing channel". Some variables
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
240 may still reference the channel.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
241 - The channel is freed, log message: "Freeing channel".
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
242
7992
78106b0f2c56 commit https://github.com/vim/vim/commit/cbebd4879cc78e670d79b2c57dc33d7b911c962a
Christian Brabandt <cb@256bit.org>
parents: 7967
diff changeset
243 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
244 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
245 ch_open() fails quickly. On MS-Windows "waittime" applies.
8951
0bdeaf7092bc commit https://github.com/vim/vim/commit/aa3b15dbebf333282503d6031e2f9ba6ee4398ed
Christian Brabandt <cb@256bit.org>
parents: 8795
diff changeset
246 *E898* *E901* *E902*
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
247
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
248 If there is an error reading or writing a channel it will be closed.
18831
6848b809a26e Runtime file updates.
Bram Moolenaar <Bram@vim.org>
parents: 18053
diff changeset
249 *E630* *E631*
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
250
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
251 ==============================================================================
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
252 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
253
8094
18a3f0f05244 commit https://github.com/vim/vim/commit/910b8aac5dc4693c4508b7acd2cef0bbfac04242
Christian Brabandt <cb@256bit.org>
parents: 8061
diff changeset
254 If mode is JSON then a message can be sent synchronously like this: >
8285
e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f
Christian Brabandt <cb@256bit.org>
parents: 8267
diff changeset
255 let response = ch_evalexpr(channel, {expr})
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
256 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
257
8094
18a3f0f05244 commit https://github.com/vim/vim/commit/910b8aac5dc4693c4508b7acd2cef0bbfac04242
Christian Brabandt <cb@256bit.org>
parents: 8061
diff changeset
258 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
259 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
260
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
261 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
262 handle the response: >
8285
e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f
Christian Brabandt <cb@256bit.org>
parents: 8267
diff changeset
263 call ch_sendexpr(channel, {expr})
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
264
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
265 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
266 asynchronously: >
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
267 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
268
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
269 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
270 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
271 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
272 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
273
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
274 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
275 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
276 [12,"hello"] ~
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
277
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
278 The format of the JSON sent is:
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
279 [{number},{expr}]
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
280
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
281 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
282 (if any):
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
283
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
284 [{number},{response}]
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
285
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
286 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
287 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
288
9969
176e34b0d678 commit https://github.com/vim/vim/commit/f1f0792e55e72cdc7c833b30f565a9b02f18bb1e
Christian Brabandt <cb@256bit.org>
parents: 9860
diff changeset
289 A newline character is terminating the JSON text. This can be used to
176e34b0d678 commit https://github.com/vim/vim/commit/f1f0792e55e72cdc7c833b30f565a9b02f18bb1e
Christian Brabandt <cb@256bit.org>
parents: 9860
diff changeset
290 separate the read text. For example, in Python:
176e34b0d678 commit https://github.com/vim/vim/commit/f1f0792e55e72cdc7c833b30f565a9b02f18bb1e
Christian Brabandt <cb@256bit.org>
parents: 9860
diff changeset
291 splitidx = read_text.find('\n')
176e34b0d678 commit https://github.com/vim/vim/commit/f1f0792e55e72cdc7c833b30f565a9b02f18bb1e
Christian Brabandt <cb@256bit.org>
parents: 9860
diff changeset
292 message = read_text[:splitidx]
176e34b0d678 commit https://github.com/vim/vim/commit/f1f0792e55e72cdc7c833b30f565a9b02f18bb1e
Christian Brabandt <cb@256bit.org>
parents: 9860
diff changeset
293 rest = read_text[splitidx + 1:]
176e34b0d678 commit https://github.com/vim/vim/commit/f1f0792e55e72cdc7c833b30f565a9b02f18bb1e
Christian Brabandt <cb@256bit.org>
parents: 9860
diff changeset
294
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
295 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
296 the message by parsing the JSON. It will only accept the message if the end
9969
176e34b0d678 commit https://github.com/vim/vim/commit/f1f0792e55e72cdc7c833b30f565a9b02f18bb1e
Christian Brabandt <cb@256bit.org>
parents: 9860
diff changeset
297 was received. A newline after the message is optional.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
298
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
299 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
300 message, it must use the number zero:
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
301 [0,{response}]
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
302
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
303 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
304 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
305
8285
e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f
Christian Brabandt <cb@256bit.org>
parents: 8267
diff changeset
306 It is also possible to use ch_sendraw() and ch_evalraw() on a JSON or JS
e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f
Christian Brabandt <cb@256bit.org>
parents: 8267
diff changeset
307 channel. The caller is then completely responsible for correct encoding and
e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f
Christian Brabandt <cb@256bit.org>
parents: 8267
diff changeset
308 decoding.
7992
78106b0f2c56 commit https://github.com/vim/vim/commit/cbebd4879cc78e670d79b2c57dc33d7b911c962a
Christian Brabandt <cb@256bit.org>
parents: 7967
diff changeset
309
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
310 ==============================================================================
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
311 5. Channel commands *channel-commands*
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
312
8094
18a3f0f05244 commit https://github.com/vim/vim/commit/910b8aac5dc4693c4508b7acd2cef0bbfac04242
Christian Brabandt <cb@256bit.org>
parents: 8061
diff changeset
313 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
314 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
315
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
316 Possible commands are: *E903* *E904* *E905*
10191
01521953bdf1 commit https://github.com/vim/vim/commit/220adb1e9f9e0b27d28185167d2730bf2f93057d
Christian Brabandt <cb@256bit.org>
parents: 10147
diff changeset
317 ["redraw", {forced}]
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
318 ["ex", {Ex command}]
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
319 ["normal", {Normal mode command}]
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
320 ["expr", {expression}, {number}]
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
321 ["expr", {expression}]
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
322 ["call", {func name}, {argument list}, {number}]
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
323 ["call", {func name}, {argument list}]
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
324
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
325 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
326 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
327 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
328 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
329 ["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
330
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
331 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
332 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
333 higher.
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
334
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
335
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
336 Command "redraw" ~
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
337
16086
bd7461db24b3 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 14675
diff changeset
338 The other commands do not explicitly update the screen, so that you can send a
bd7461db24b3 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 14675
diff changeset
339 sequence of commands without the cursor moving around. A redraw can happen as
bd7461db24b3 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 14675
diff changeset
340 a side effect of some commands. You must end with the "redraw" command to
bd7461db24b3 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 14675
diff changeset
341 show any changed text and show the cursor where it belongs.
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
342
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
343 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
344 ["redraw", ""] ~
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
345 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
346 ["redraw", "force"] ~
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
347
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
348
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
349 Command "ex" ~
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
350
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
351 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
352 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
353 ["ex","call myscript#MyFunc(arg)"]
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
354
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
355 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
356
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
357 When there is an error a message is written to the channel log, if it exists,
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
358 and v:errmsg is set to the error.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
359
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
360
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
361 Command "normal" ~
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
362
7924
00d64eb49ce1 commit https://github.com/vim/vim/commit/681baaf4a4c81418693dcafb81421a8614832e91
Christian Brabandt <cb@256bit.org>
parents: 7864
diff changeset
363 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
364 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
365 ["normal" "zO"]
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
366
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
367
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
368 Command "expr" with response ~
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
369
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
370 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
371 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
372 ["expr","line('$')", -2] ~
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
373
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
374 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
375 [-2, "last line"] ~
f5da459c5698 commit https://github.com/vim/vim/commit/e0fa3742ead676a3074a10edadbc955e1a89153d
Christian Brabandt <cb@256bit.org>
parents: 8094
diff changeset
376 The format is:
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
377 [{number}, {result}]
8267
108d30ed34ba commit https://github.com/vim/vim/commit/187db50d0499aecf4cfd42fb4db0a1bebf61c8cd
Christian Brabandt <cb@256bit.org>
parents: 8246
diff changeset
378
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
379 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
380 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
381 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
382
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
383 {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
384 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
385 "ERROR".
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
386
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
387
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
388 Command "expr" without a response ~
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
389
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
390 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
391 Example:
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
392 ["expr","setline('$', ['one', 'two', 'three'])"] ~
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
393 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
394
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
395
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
396 Command "call" ~
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
397
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
398 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
399 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
400 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
401 concatenating them. Example:
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
402 ["call", "line", ["$"], -2] ~
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
403
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
404 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
405 ["call", "setline", ["$", ["one", "two", "three"]]] ~
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
406
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
407 ==============================================================================
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
408 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
409
10385
368468ef35cf commit https://github.com/vim/vim/commit/c0514bf4777a1d55f5785b3887c5686fd0bbe870
Christian Brabandt <cb@256bit.org>
parents: 10319
diff changeset
410 If mode is RAW or NL then a message can be sent like this: >
8285
e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f
Christian Brabandt <cb@256bit.org>
parents: 8267
diff changeset
411 let response = ch_evalraw(channel, {string})
8094
18a3f0f05244 commit https://github.com/vim/vim/commit/910b8aac5dc4693c4508b7acd2cef0bbfac04242
Christian Brabandt <cb@256bit.org>
parents: 8061
diff changeset
412
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
413 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
414 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
415 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
416 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
417
8094
18a3f0f05244 commit https://github.com/vim/vim/commit/910b8aac5dc4693c4508b7acd2cef0bbfac04242
Christian Brabandt <cb@256bit.org>
parents: 8061
diff changeset
418 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
419 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
420 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
421 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
422 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
423
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
424 To send a message, without expecting a response: >
8285
e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f
Christian Brabandt <cb@256bit.org>
parents: 8267
diff changeset
425 call ch_sendraw(channel, {string})
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
426 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
427 it.
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
428
28467
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
429 *channel-onetime-callback*
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
430 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
431 asynchronously: >
8285
e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f
Christian Brabandt <cb@256bit.org>
parents: 8267
diff changeset
432 call ch_sendraw(channel, {string}, {'callback': 'MyHandler'})
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
433
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
434 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
435 |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
436
8285
e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f
Christian Brabandt <cb@256bit.org>
parents: 8267
diff changeset
437 It is not possible to use |ch_evalexpr()| or |ch_sendexpr()| on a raw channel.
7992
78106b0f2c56 commit https://github.com/vim/vim/commit/cbebd4879cc78e670d79b2c57dc33d7b911c962a
Christian Brabandt <cb@256bit.org>
parents: 7967
diff changeset
438
10004
8061455d9179 commit https://github.com/vim/vim/commit/818078ddfbb8cc2546f697c5675a251d095722ec
Christian Brabandt <cb@256bit.org>
parents: 9969
diff changeset
439 A String in Vim cannot contain NUL bytes. To send or receive NUL bytes read
8061455d9179 commit https://github.com/vim/vim/commit/818078ddfbb8cc2546f697c5675a251d095722ec
Christian Brabandt <cb@256bit.org>
parents: 9969
diff changeset
440 or write from a buffer. See |in_io-buffer| and |out_io-buffer|.
8061455d9179 commit https://github.com/vim/vim/commit/818078ddfbb8cc2546f697c5675a251d095722ec
Christian Brabandt <cb@256bit.org>
parents: 9969
diff changeset
441
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
442 ==============================================================================
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
443 7. More channel functions *channel-more*
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 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
446 are:
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
447 "fail" Failed to open the channel.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
448 "open" The channel can be used.
9041
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
449 "buffered" The channel was closed but there is data to read.
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
450 "closed" The channel was closed.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
451
8267
108d30ed34ba commit https://github.com/vim/vim/commit/187db50d0499aecf4cfd42fb4db0a1bebf61c8cd
Christian Brabandt <cb@256bit.org>
parents: 8246
diff changeset
452 To obtain 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
453
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
454 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
455 let output = ch_read(channel)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
456 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
457 message that is available: >
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
458 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
459 When no message was available then the result is v:none for a JSON or JS mode
10422
e664ee056a84 commit https://github.com/vim/vim/commit/4b785f69c0616dba5d3f38e8ce4b5398cec89407
Christian Brabandt <cb@256bit.org>
parents: 10385
diff changeset
460 channels, an empty string for a RAW or NL channel. You can use |ch_canread()|
e664ee056a84 commit https://github.com/vim/vim/commit/4b785f69c0616dba5d3f38e8ce4b5398cec89407
Christian Brabandt <cb@256bit.org>
parents: 10385
diff changeset
461 to check if there is something to read.
e664ee056a84 commit https://github.com/vim/vim/commit/4b785f69c0616dba5d3f38e8ce4b5398cec89407
Christian Brabandt <cb@256bit.org>
parents: 10385
diff changeset
462
12043
2796a2c9fc17 patch 8.0.0902: cannot specify directory or environment for a job
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
463 Note that when there is no callback, messages are dropped. To avoid that add
2796a2c9fc17 patch 8.0.0902: cannot specify directory or environment for a job
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
464 a close callback to the channel.
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
465
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
466 To read all normal output from a RAW channel that is available: >
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
467 let output = ch_readraw(channel)
31028
5acd6f02ea35 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 29533
diff changeset
468 To read all error output from a RAW channel that is available: >
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
469 let output = ch_readraw(channel, {"part": "err"})
29274
d314efe6447a Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 29193
diff changeset
470 Note that if the channel is in NL mode, ch_readraw() will only return one line
d314efe6447a Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 29193
diff changeset
471 for each call.
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
472
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
473 ch_read() and ch_readraw() use the channel timeout. When there is nothing to
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
474 read within that time an empty string is returned. To specify a different
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
475 timeout in msec use the "timeout" option:
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
476 {"timeout": 123} ~
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
477 To read from the error output use the "part" option:
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
478 {"part": "err"} ~
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
479 To read a message with a specific ID, on a JS or JSON channel:
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
480 {"id": 99} ~
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
481 When no ID is specified or the ID is -1, the first message is returned. This
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
482 overrules any callback waiting for this message.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
483
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
484 For a RAW channel this returns whatever is available, since Vim does not know
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
485 where a message ends.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
486 For a NL channel this returns one message.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
487 For a JS or JSON channel this returns one decoded message.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
488 This includes any sequence number.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
489
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
490 ==============================================================================
17571
2704c4e3e20a Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 17456
diff changeset
491 8. Channel functions details *channel-functions-details*
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
492
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
493 ch_canread({handle}) *ch_canread()*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
494 Return non-zero when there is something to read from {handle}.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
495 {handle} can be a Channel or a Job that has a Channel.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
496
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
497 This is useful to read from a channel at a convenient time,
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
498 e.g. from a timer.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
499
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
500 Note that messages are dropped when the channel does not have
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
501 a callback. Add a close callback to avoid that.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
502
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
503 Can also be used as a |method|: >
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
504 GetChannel()->ch_canread()
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
505
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
506 ch_close({handle}) *ch_close()*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
507 Close {handle}. See |channel-close|.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
508 {handle} can be a Channel or a Job that has a Channel.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
509 A close callback is not invoked.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
510
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
511 Can also be used as a |method|: >
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
512 GetChannel()->ch_close()
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
513
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
514 ch_close_in({handle}) *ch_close_in()*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
515 Close the "in" part of {handle}. See |channel-close-in|.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
516 {handle} can be a Channel or a Job that has a Channel.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
517 A close callback is not invoked.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
518
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
519 Can also be used as a |method|: >
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
520 GetChannel()->ch_close_in()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
521
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
522
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
523 ch_evalexpr({handle}, {expr} [, {options}]) *ch_evalexpr()*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
524 Send {expr} over {handle}. The {expr} is encoded
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
525 according to the type of channel. The function cannot be used
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
526 with a raw channel. See |channel-use|.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
527 {handle} can be a Channel or a Job that has a Channel.
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
528 When using the "lsp" channel mode, {expr} must be a |Dict|.
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
529 *E917*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
530 {options} must be a Dictionary. It must not have a "callback"
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
531 entry. It can have a "timeout" entry to specify the timeout
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
532 for this specific request.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
533
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
534 ch_evalexpr() waits for a response and returns the decoded
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
535 expression. When there is an error or timeout it returns an
28473
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
536 empty |String| or, when using the "lsp" channel mode, returns an
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
537 empty |Dict|.
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
538
18053
8ac85adee561 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 17831
diff changeset
539 Note that while waiting for the response, Vim handles other
8ac85adee561 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 17831
diff changeset
540 messages. You need to make sure this doesn't cause trouble.
8ac85adee561 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 17831
diff changeset
541
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
542 Can also be used as a |method|: >
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
543 GetChannel()->ch_evalexpr(expr)
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
544
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
545
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
546 ch_evalraw({handle}, {string} [, {options}]) *ch_evalraw()*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
547 Send {string} over {handle}.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
548 {handle} can be a Channel or a Job that has a Channel.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
549
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
550 Works like |ch_evalexpr()|, but does not encode the request or
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
551 decode the response. The caller is responsible for the
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
552 correct contents. Also does not add a newline for a channel
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
553 in NL mode, the caller must do that. The NL in the response
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
554 is removed.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
555 Note that Vim does not know when the text received on a raw
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
556 channel is complete, it may only return the first part and you
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
557 need to use |ch_readraw()| to fetch the rest.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
558 See |channel-use|.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
559
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
560 Can also be used as a |method|: >
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
561 GetChannel()->ch_evalraw(rawstring)
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
562
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
563 ch_getbufnr({handle}, {what}) *ch_getbufnr()*
25619
29ec2c198c8d Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 25252
diff changeset
564 Get the buffer number that {handle} is using for String {what}.
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
565 {handle} can be a Channel or a Job that has a Channel.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
566 {what} can be "err" for stderr, "out" for stdout or empty for
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
567 socket output.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
568 Returns -1 when there is no buffer.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
569
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
570 Can also be used as a |method|: >
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
571 GetChannel()->ch_getbufnr(what)
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
572
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
573 ch_getjob({channel}) *ch_getjob()*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
574 Get the Job associated with {channel}.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
575 If there is no job calling |job_status()| on the returned Job
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
576 will result in "fail".
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
577
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
578 Can also be used as a |method|: >
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
579 GetChannel()->ch_getjob()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
580
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
581
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
582 ch_info({handle}) *ch_info()*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
583 Returns a Dictionary with information about {handle}. The
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
584 items are:
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
585 "id" number of the channel
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
586 "status" "open", "buffered" or "closed", like
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
587 ch_status()
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
588 When opened with ch_open():
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
589 "hostname" the hostname of the address
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
590 "port" the port of the address
28317
d32dc906dd2c patch 8.2.4684: cannot open a channel on a Unix domain socket
Bram Moolenaar <Bram@vim.org>
parents: 28246
diff changeset
591 "path" the path of the Unix-domain socket
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
592 "sock_status" "open" or "closed"
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
593 "sock_mode" "NL", "RAW", "JSON" or "JS"
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
594 "sock_io" "socket"
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
595 "sock_timeout" timeout in msec
28317
d32dc906dd2c patch 8.2.4684: cannot open a channel on a Unix domain socket
Bram Moolenaar <Bram@vim.org>
parents: 28246
diff changeset
596
28379
6dd88e45d47d Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 28317
diff changeset
597 Note that "path" is only present for Unix-domain sockets, for
28317
d32dc906dd2c patch 8.2.4684: cannot open a channel on a Unix domain socket
Bram Moolenaar <Bram@vim.org>
parents: 28246
diff changeset
598 regular ones "hostname" and "port" are present instead.
d32dc906dd2c patch 8.2.4684: cannot open a channel on a Unix domain socket
Bram Moolenaar <Bram@vim.org>
parents: 28246
diff changeset
599
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
600 When opened with job_start():
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
601 "out_status" "open", "buffered" or "closed"
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
602 "out_mode" "NL", "RAW", "JSON" or "JS"
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
603 "out_io" "null", "pipe", "file" or "buffer"
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
604 "out_timeout" timeout in msec
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
605 "err_status" "open", "buffered" or "closed"
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
606 "err_mode" "NL", "RAW", "JSON" or "JS"
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
607 "err_io" "out", "null", "pipe", "file" or "buffer"
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
608 "err_timeout" timeout in msec
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
609 "in_status" "open" or "closed"
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
610 "in_mode" "NL", "RAW", "JSON", "JS" or "LSP"
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
611 "in_io" "null", "pipe", "file" or "buffer"
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
612 "in_timeout" timeout in msec
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
613
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
614 Can also be used as a |method|: >
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
615 GetChannel()->ch_info()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
616
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
617
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
618 ch_log({msg} [, {handle}]) *ch_log()*
25619
29ec2c198c8d Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 25252
diff changeset
619 Write String {msg} in the channel log file, if it was opened
29ec2c198c8d Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 25252
diff changeset
620 with |ch_logfile()|.
31291
16fc80710970 patch 9.0.0979: ch_log() text can be hard to find in the log file
Bram Moolenaar <Bram@vim.org>
parents: 31028
diff changeset
621 The text "ch_log():" is prepended to the message to make clear
16fc80710970 patch 9.0.0979: ch_log() text can be hard to find in the log file
Bram Moolenaar <Bram@vim.org>
parents: 31028
diff changeset
622 it came from this function call and make it easier to find in
16fc80710970 patch 9.0.0979: ch_log() text can be hard to find in the log file
Bram Moolenaar <Bram@vim.org>
parents: 31028
diff changeset
623 the log file.
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
624 When {handle} is passed the channel number is used for the
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
625 message.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
626 {handle} can be a Channel or a Job that has a Channel. The
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
627 Channel must be open for the channel number to be used.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
628
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
629 Can also be used as a |method|: >
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
630 'did something'->ch_log()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
631
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
632
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
633 ch_logfile({fname} [, {mode}]) *ch_logfile()*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
634 Start logging channel activity to {fname}.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
635 When {fname} is an empty string: stop logging.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
636
29069
be6c32395444 patch 8.2.5056: the channel log only contains some of the raw terminal output
Bram Moolenaar <Bram@vim.org>
parents: 28517
diff changeset
637 When {mode} is omitted or contains "a" or is "o" then append
be6c32395444 patch 8.2.5056: the channel log only contains some of the raw terminal output
Bram Moolenaar <Bram@vim.org>
parents: 28517
diff changeset
638 to the file.
be6c32395444 patch 8.2.5056: the channel log only contains some of the raw terminal output
Bram Moolenaar <Bram@vim.org>
parents: 28517
diff changeset
639 When {mode} contains "w" and not "a" start with an empty file.
be6c32395444 patch 8.2.5056: the channel log only contains some of the raw terminal output
Bram Moolenaar <Bram@vim.org>
parents: 28517
diff changeset
640 When {mode} contains "o" then log all terminal output.
be6c32395444 patch 8.2.5056: the channel log only contains some of the raw terminal output
Bram Moolenaar <Bram@vim.org>
parents: 28517
diff changeset
641 Otherwise only some interesting terminal output is logged.
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
642
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
643 Use |ch_log()| to write log messages. The file is flushed
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
644 after every message, on Unix you can use "tail -f" to see what
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
645 is going on in real time.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
646
22077
335365fcbb60 patch 8.2.1588: cannot read back the prompt of a prompt buffer
Bram Moolenaar <Bram@vim.org>
parents: 21250
diff changeset
647 To enable the log very early, to see what is received from a
29069
be6c32395444 patch 8.2.5056: the channel log only contains some of the raw terminal output
Bram Moolenaar <Bram@vim.org>
parents: 28517
diff changeset
648 terminal during startup, use |--log| (this uses mode "ao"): >
28435
0533e7466ef0 patch 8.2.4742: there is no way to start logging very early in startup
Bram Moolenaar <Bram@vim.org>
parents: 28379
diff changeset
649 vim --log logfile
22077
335365fcbb60 patch 8.2.1588: cannot read back the prompt of a prompt buffer
Bram Moolenaar <Bram@vim.org>
parents: 21250
diff changeset
650 <
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
651 This function is not available in the |sandbox|.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
652 NOTE: the channel communication is stored in the file, be
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
653 aware that this may contain confidential and privacy sensitive
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
654 information, e.g. a password you type in a terminal window.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
655
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
656 Can also be used as a |method|: >
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
657 'logfile'->ch_logfile('w')
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
658
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
659
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
660 ch_open({address} [, {options}]) *ch_open()*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
661 Open a channel to {address}. See |channel|.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
662 Returns a Channel. Use |ch_status()| to check for failure.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
663
28317
d32dc906dd2c patch 8.2.4684: cannot open a channel on a Unix domain socket
Bram Moolenaar <Bram@vim.org>
parents: 28246
diff changeset
664 {address} is a String, see |channel-address| for the possible
d32dc906dd2c patch 8.2.4684: cannot open a channel on a Unix domain socket
Bram Moolenaar <Bram@vim.org>
parents: 28246
diff changeset
665 accepted forms.
20003
e373843e2980 patch 8.2.0557: no IPv6 support for channels
Bram Moolenaar <Bram@vim.org>
parents: 18879
diff changeset
666
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
667 If {options} is given it must be a |Dictionary|.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
668 See |channel-open-options|.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
669
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
670 Can also be used as a |method|: >
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
671 GetAddress()->ch_open()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
672
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
673
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
674 ch_read({handle} [, {options}]) *ch_read()*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
675 Read from {handle} and return the received message.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
676 {handle} can be a Channel or a Job that has a Channel.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
677 For a NL channel this waits for a NL to arrive, except when
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
678 there is nothing more to read (channel was closed).
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
679 See |channel-more|.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
680
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
681 Can also be used as a |method|: >
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
682 GetChannel()->ch_read()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
683
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
684
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
685 ch_readblob({handle} [, {options}]) *ch_readblob()*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
686 Like ch_read() but reads binary data and returns a |Blob|.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
687 See |channel-more|.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
688
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
689 Can also be used as a |method|: >
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
690 GetChannel()->ch_readblob()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
691
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
692
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
693 ch_readraw({handle} [, {options}]) *ch_readraw()*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
694 Like ch_read() but for a JS and JSON channel does not decode
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
695 the message. For a NL channel it does not block waiting for
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
696 the NL to arrive, but otherwise works like ch_read().
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
697 See |channel-more|.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
698
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
699 Can also be used as a |method|: >
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
700 GetChannel()->ch_readraw()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
701
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
702
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
703 ch_sendexpr({handle}, {expr} [, {options}]) *ch_sendexpr()*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
704 Send {expr} over {handle}. The {expr} is encoded
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
705 according to the type of channel. The function cannot be used
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
706 with a raw channel.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
707 See |channel-use|. *E912*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
708 {handle} can be a Channel or a Job that has a Channel.
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
709 When using the "lsp" channel mode, {expr} must be a |Dict|.
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
710
28467
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
711 If the channel mode is "lsp", then returns a Dict. Otherwise
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
712 returns an empty String. If the "callback" item is present in
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
713 {options}, then the returned Dict contains the ID of the
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
714 request message. The ID can be used to send a cancellation
28473
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
715 request to the LSP server (if needed). Returns an empty Dict
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
716 on error.
28467
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
717
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
718 If a response message is not expected for {expr}, then don't
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
719 specify the "callback" item in {options}.
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
720
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
721 Can also be used as a |method|: >
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
722 GetChannel()->ch_sendexpr(expr)
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
723
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
724
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
725 ch_sendraw({handle}, {expr} [, {options}]) *ch_sendraw()*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
726 Send |String| or |Blob| {expr} over {handle}.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
727 Works like |ch_sendexpr()|, but does not encode the request or
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
728 decode the response. The caller is responsible for the
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
729 correct contents. Also does not add a newline for a channel
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
730 in NL mode, the caller must do that. The NL in the response
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
731 is removed.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
732 See |channel-use|.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
733
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
734 Can also be used as a |method|: >
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
735 GetChannel()->ch_sendraw(rawexpr)
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
736
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
737
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
738 ch_setoptions({handle}, {options}) *ch_setoptions()*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
739 Set options on {handle}:
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
740 "callback" the channel callback
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
741 "timeout" default read timeout in msec
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
742 "mode" mode for the whole channel
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
743 See |ch_open()| for more explanation.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
744 {handle} can be a Channel or a Job that has a Channel.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
745
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
746 Note that changing the mode may cause queued messages to be
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
747 lost.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
748
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
749 These options cannot be changed:
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
750 "waittime" only applies to |ch_open()|
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
751
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
752 Can also be used as a |method|: >
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
753 GetChannel()->ch_setoptions(options)
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
754
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
755
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
756 ch_status({handle} [, {options}]) *ch_status()*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
757 Return the status of {handle}:
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
758 "fail" failed to open the channel
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
759 "open" channel can be used
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
760 "buffered" channel can be read, not written to
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
761 "closed" channel can not be used
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
762 {handle} can be a Channel or a Job that has a Channel.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
763 "buffered" is used when the channel was closed but there is
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
764 still data that can be obtained with |ch_read()|.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
765
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
766 If {options} is given it can contain a "part" entry to specify
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
767 the part of the channel to return the status for: "out" or
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
768 "err". For example, to get the error status: >
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
769 ch_status(job, {"part": "err"})
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
770 <
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
771 Can also be used as a |method|: >
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
772 GetChannel()->ch_status()
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
773
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
774 ==============================================================================
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
775 9. Starting a job with a channel *job-start* *job*
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
776
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
777 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
778 let job = job_start(command, {options})
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
779
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
780 You can get the channel with: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
781 let channel = job_getchannel(job)
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
782
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
783 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
784 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
785 been received and not parsed correctly.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
786
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
787 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
788 a handler for stdout: >
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
789 let job = job_start(command, {"out_cb": "MyHandler"})
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
790 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
791 it like this: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
792 func MyHandler(channel, msg)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
793
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
794 Without the handler you need to read the output with |ch_read()| or
9041
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
795 |ch_readraw()|. You can do this in the close callback, see |read-in-close-cb|.
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
796
12045
444ad56c0cac Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12043
diff changeset
797 Note that if the job exits before you read the output, the output may be lost.
444ad56c0cac Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12043
diff changeset
798 This depends on the system (on Unix this happens because closing the write end
444ad56c0cac Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12043
diff changeset
799 of a pipe causes the read end to get EOF). To avoid this make the job sleep
444ad56c0cac Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12043
diff changeset
800 for a short while before it exits.
444ad56c0cac Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12043
diff changeset
801
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
802 The handler defined for "out_cb" will not receive stderr. If you want to
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
803 handle that separately, add an "err_cb" handler: >
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
804 let job = job_start(command, {"out_cb": "MyHandler",
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
805 \ "err_cb": "ErrHandler"})
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
806
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
807 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
808 "callback" option: >
18831
6848b809a26e Runtime file updates.
Bram Moolenaar <Bram@vim.org>
parents: 18053
diff changeset
809 let job = job_start(command, {"callback": "MyHandler"})
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
810
11518
63b0b7b79b25 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 10498
diff changeset
811 Depending on the system, starting a job can put Vim in the background, the
63b0b7b79b25 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 10498
diff changeset
812 started job gets the focus. To avoid that, use the `foreground()` function.
63b0b7b79b25 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 10498
diff changeset
813 This might not always work when called early, put in the callback handler or
63b0b7b79b25 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 10498
diff changeset
814 use a timer to call it after the job has started.
63b0b7b79b25 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 10498
diff changeset
815
8285
e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f
Christian Brabandt <cb@256bit.org>
parents: 8267
diff changeset
816 You can send a message to the command with ch_evalraw(). If the channel is in
e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f
Christian Brabandt <cb@256bit.org>
parents: 8267
diff changeset
817 JSON or JS mode you can use ch_evalexpr().
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
818
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
819 There are several options you can use, see |job-options|.
8267
108d30ed34ba commit https://github.com/vim/vim/commit/187db50d0499aecf4cfd42fb4db0a1bebf61c8cd
Christian Brabandt <cb@256bit.org>
parents: 8246
diff changeset
820 For example, to start a job and write its output in buffer "dummy": >
108d30ed34ba commit https://github.com/vim/vim/commit/187db50d0499aecf4cfd42fb4db0a1bebf61c8cd
Christian Brabandt <cb@256bit.org>
parents: 8246
diff changeset
821 let logjob = job_start("tail -f /tmp/log",
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
822 \ {'out_io': 'buffer', 'out_name': 'dummy'})
8267
108d30ed34ba commit https://github.com/vim/vim/commit/187db50d0499aecf4cfd42fb4db0a1bebf61c8cd
Christian Brabandt <cb@256bit.org>
parents: 8246
diff changeset
823 sbuf dummy
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
824
8440
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents: 8392
diff changeset
825
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents: 8392
diff changeset
826 Job input from a buffer ~
10004
8061455d9179 commit https://github.com/vim/vim/commit/818078ddfbb8cc2546f697c5675a251d095722ec
Christian Brabandt <cb@256bit.org>
parents: 9969
diff changeset
827 *in_io-buffer*
8392
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
828 To run a job that reads from a buffer: >
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
829 let job = job_start({command},
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
830 \ {'in_io': 'buffer', 'in_name': 'mybuffer'})
8392
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
831 <
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
832 *E915* *E918*
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
833 The buffer is found by name, similar to |bufnr()|. The buffer must exist and
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
834 be loaded when job_start() is called.
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
835
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
836 By default this reads the whole buffer. This can be changed with the "in_top"
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
837 and "in_bot" options.
8392
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
838
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
839 A special mode is when "in_top" is set to zero and "in_bot" is not set: Every
11659
49c12c93abf3 Updated runtime files and translations.
Christian Brabandt <cb@256bit.org>
parents: 11518
diff changeset
840 time a line is added to the buffer, the last-but-one line will be sent to the
8440
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents: 8392
diff changeset
841 job stdin. This allows for editing the last line and sending it when pressing
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents: 8392
diff changeset
842 Enter.
10054
d4b7232fc63a commit https://github.com/vim/vim/commit/0874a83e9be1b39fdb217f02b427bf1d6133a4d8
Christian Brabandt <cb@256bit.org>
parents: 10051
diff changeset
843 *channel-close-in*
d4b7232fc63a commit https://github.com/vim/vim/commit/0874a83e9be1b39fdb217f02b427bf1d6133a4d8
Christian Brabandt <cb@256bit.org>
parents: 10051
diff changeset
844 When not using the special mode the pipe or socket will be closed after the
d4b7232fc63a commit https://github.com/vim/vim/commit/0874a83e9be1b39fdb217f02b427bf1d6133a4d8
Christian Brabandt <cb@256bit.org>
parents: 10051
diff changeset
845 last line has been written. This signals the reading end that the input
d4b7232fc63a commit https://github.com/vim/vim/commit/0874a83e9be1b39fdb217f02b427bf1d6133a4d8
Christian Brabandt <cb@256bit.org>
parents: 10051
diff changeset
846 finished. You can also use |ch_close_in()| to close it sooner.
8392
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
847
9464
be72f4201a1d commit https://github.com/vim/vim/commit/063b9d15abea041a5bfff3ffc4e219e26fd1d4fa
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
848 NUL bytes in the text will be passed to the job (internally Vim stores these
be72f4201a1d commit https://github.com/vim/vim/commit/063b9d15abea041a5bfff3ffc4e219e26fd1d4fa
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
849 as NL bytes).
be72f4201a1d commit https://github.com/vim/vim/commit/063b9d15abea041a5bfff3ffc4e219e26fd1d4fa
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
850
9041
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
851
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
852 Reading job output in the close callback ~
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
853 *read-in-close-cb*
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
854 If the job can take some time and you don't need intermediate results, you can
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
855 add a close callback and read the output there: >
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
856
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
857 func! CloseHandler(channel)
10244
876fbdd84e52 commit https://github.com/vim/vim/commit/2ec618c9feac4573b154510236ad8121c77d0eca
Christian Brabandt <cb@256bit.org>
parents: 10218
diff changeset
858 while ch_status(a:channel, {'part': 'out'}) == 'buffered'
9041
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
859 echomsg ch_read(a:channel)
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
860 endwhile
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
861 endfunc
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
862 let job = job_start(command, {'close_cb': 'CloseHandler'})
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
863
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
864 You will want to do something more useful than "echomsg".
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
865
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
866 ==============================================================================
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
867 10. Starting a job without a channel *job-start-nochannel*
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
868
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
869 To start another process without creating a channel: >
8392
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
870 let job = job_start(command,
10449
222b1432814e commit https://github.com/vim/vim/commit/5162822914372fc916a93f85848c0c82209e7cec
Christian Brabandt <cb@256bit.org>
parents: 10426
diff changeset
871 \ {"in_io": "null", "out_io": "null", "err_io": "null"})
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
872
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
873 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
874
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
875 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
876 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
877 avoid it getting stuck.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
878
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
879 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
880
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
881 *job-start-if-needed*
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
882 To start a job only when connecting to an address does not work, do something
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
883 like this: >
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
884 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
885 if ch_status(channel) == "fail"
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
886 let job = job_start(command)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
887 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
888 endif
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
889
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
890 Note that the waittime for ch_open() gives the job one second to make the port
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
891 available.
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
892
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
893 ==============================================================================
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
894 11. Job functions *job-functions-details*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
895
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
896 job_getchannel({job}) *job_getchannel()*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
897 Get the channel handle that {job} is using.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
898 To check if the job has no channel: >
25252
acda780ffc3e patch 8.2.3162: Vim9: argument types are not checked at compile time
Bram Moolenaar <Bram@vim.org>
parents: 22723
diff changeset
899 if string(job_getchannel(job)) == 'channel fail'
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
900 <
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
901 Can also be used as a |method|: >
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
902 GetJob()->job_getchannel()
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
903
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
904 job_info([{job}]) *job_info()*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
905 Returns a Dictionary with information about {job}:
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
906 "status" what |job_status()| returns
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
907 "channel" what |job_getchannel()| returns
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
908 "cmd" List of command arguments used to start the job
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
909 "process" process ID
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
910 "tty_in" terminal input name, empty when none
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
911 "tty_out" terminal output name, empty when none
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
912 "exitval" only valid when "status" is "dead"
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
913 "exit_cb" function to be called on exit
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
914 "stoponexit" |job-stoponexit|
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
915
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
916 Only in Unix:
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
917 "termsig" the signal which terminated the process
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
918 (See |job_stop()| for the values)
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
919 only valid when "status" is "dead"
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
920
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
921 Only in MS-Windows:
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
922 "tty_type" Type of virtual console in use.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
923 Values are "winpty" or "conpty".
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
924 See 'termwintype'.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
925
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
926 Without any arguments, returns a List with all Job objects.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
927
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
928 Can also be used as a |method|: >
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
929 GetJob()->job_info()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
930
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
931
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
932 job_setoptions({job}, {options}) *job_setoptions()*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
933 Change options for {job}. Supported are:
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
934 "stoponexit" |job-stoponexit|
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
935 "exit_cb" |job-exit_cb|
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
936
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
937 Can also be used as a |method|: >
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
938 GetJob()->job_setoptions(options)
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
939
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
940
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
941 job_start({command} [, {options}]) *job_start()*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
942 Start a job and return a Job object. Unlike |system()| and
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
943 |:!cmd| this does not wait for the job to finish.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
944 To start a job in a terminal window see |term_start()|.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
945
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
946 If the job fails to start then |job_status()| on the returned
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
947 Job object results in "fail" and none of the callbacks will be
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
948 invoked.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
949
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
950 {command} can be a String. This works best on MS-Windows. On
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
951 Unix it is split up in white-separated parts to be passed to
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
952 execvp(). Arguments in double quotes can contain white space.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
953
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
954 {command} can be a List, where the first item is the executable
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
955 and further items are the arguments. All items are converted
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
956 to String. This works best on Unix.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
957
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
958 On MS-Windows, job_start() makes a GUI application hidden. If
33253
3bc84e3fd05c runtime(doc): documentation updates
Christian Brabandt <cb@256bit.org>
parents: 31383
diff changeset
959 you want to show it, use |:!start| instead.
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
960
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
961 The command is executed directly, not through a shell, the
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
962 'shell' option is not used. To use the shell: >
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
963 let job = job_start(["/bin/sh", "-c", "echo hello"])
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
964 < Or: >
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
965 let job = job_start('/bin/sh -c "echo hello"')
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
966 < Note that this will start two processes, the shell and the
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
967 command it executes. If you don't want this use the "exec"
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
968 shell command.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
969
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
970 On Unix $PATH is used to search for the executable only when
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
971 the command does not contain a slash.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
972
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
973 The job will use the same terminal as Vim. If it reads from
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
974 stdin the job and Vim will be fighting over input, that
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
975 doesn't work. Redirect stdin and stdout to avoid problems: >
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
976 let job = job_start(['sh', '-c', "myserver </dev/null >/dev/null"])
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
977 <
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
978 The returned Job object can be used to get the status with
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
979 |job_status()| and stop the job with |job_stop()|.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
980
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
981 Note that the job object will be deleted if there are no
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
982 references to it. This closes the stdin and stderr, which may
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
983 cause the job to fail with an error. To avoid this keep a
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
984 reference to the job. Thus instead of: >
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
985 call job_start('my-command')
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
986 < use: >
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
987 let myjob = job_start('my-command')
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
988 < and unlet "myjob" once the job is not needed or is past the
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
989 point where it would fail (e.g. when it prints a message on
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
990 startup). Keep in mind that variables local to a function
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
991 will cease to exist if the function returns. Use a
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
992 script-local variable if needed: >
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
993 let s:myjob = job_start('my-command')
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
994 <
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
995 {options} must be a Dictionary. It can contain many optional
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
996 items, see |job-options|.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
997
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
998 Can also be used as a |method|: >
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
999 BuildCommand()->job_start()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
1000
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1001
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1002 job_status({job}) *job_status()* *E916*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1003 Returns a String with the status of {job}:
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1004 "run" job is running
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1005 "fail" job failed to start
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1006 "dead" job died or was stopped after running
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1007
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1008 On Unix a non-existing command results in "dead" instead of
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1009 "fail", because a fork happens before the failure can be
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1010 detected.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1011
22723
5b7ea82bc18f Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 22077
diff changeset
1012 If in Vim9 script a variable is declared with type "job" but
5b7ea82bc18f Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 22077
diff changeset
1013 never assigned to, passing that variable to job_status()
5b7ea82bc18f Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 22077
diff changeset
1014 returns "fail".
5b7ea82bc18f Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 22077
diff changeset
1015
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1016 If an exit callback was set with the "exit_cb" option and the
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1017 job is now detected to be "dead" the callback will be invoked.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1018
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1019 For more information see |job_info()|.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1020
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
1021 Can also be used as a |method|: >
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
1022 GetJob()->job_status()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
1023
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1024
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1025 job_stop({job} [, {how}]) *job_stop()*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1026 Stop the {job}. This can also be used to signal the job.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1027
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1028 When {how} is omitted or is "term" the job will be terminated.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1029 For Unix SIGTERM is sent. On MS-Windows the job will be
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1030 terminated forcedly (there is no "gentle" way).
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1031 This goes to the process group, thus children may also be
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1032 affected.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1033
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1034 Effect for Unix:
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1035 "term" SIGTERM (default)
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1036 "hup" SIGHUP
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1037 "quit" SIGQUIT
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1038 "int" SIGINT
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1039 "kill" SIGKILL (strongest way to stop)
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1040 number signal with that number
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1041
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1042 Effect for MS-Windows:
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1043 "term" terminate process forcedly (default)
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1044 "hup" CTRL_BREAK
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1045 "quit" CTRL_BREAK
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1046 "int" CTRL_C
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1047 "kill" terminate process forcedly
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1048 Others CTRL_BREAK
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1049
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1050 On Unix the signal is sent to the process group. This means
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1051 that when the job is "sh -c command" it affects both the shell
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1052 and the command.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1053
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1054 The result is a Number: 1 if the operation could be executed,
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1055 0 if "how" is not supported on the system.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1056 Note that even when the operation was executed, whether the
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1057 job was actually stopped needs to be checked with
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1058 |job_status()|.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1059
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1060 If the status of the job is "dead", the signal will not be
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1061 sent. This is to avoid to stop the wrong job (esp. on Unix,
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1062 where process numbers are recycled).
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1063
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1064 When using "kill" Vim will assume the job will die and close
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1065 the channel.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1066
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
1067 Can also be used as a |method|: >
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
1068 GetJob()->job_stop()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
1069
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1070
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1071 ==============================================================================
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1072 12. Job options *job-options*
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1073
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1074 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
1075 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
1076 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
1077 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
1078 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
1079
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1080 *in_mode* *out_mode* *err_mode*
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1081 "in_mode" mode specifically for stdin, only when using pipes
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1082 "out_mode" mode specifically for stdout, only when using pipes
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1083 "err_mode" mode specifically for stderr, only when using pipes
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1084 See |channel-mode| for the values.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1085
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1086 Note: when setting "mode" the part specific mode is
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1087 overwritten. Therefore set "mode" first and the part
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1088 specific mode later.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1089
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1090 Note: when writing to a file or buffer and when
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1091 reading from a buffer NL mode is used by default.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1092
14675
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
1093 *job-noblock*
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
1094 "noblock": 1 When writing use a non-blocking write call. This
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
1095 avoids getting stuck if Vim should handle other
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
1096 messages in between, e.g. when a job sends back data
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
1097 to Vim. It implies that when `ch_sendraw()` returns
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
1098 not all data may have been written yet.
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
1099 This option was added in patch 8.1.0350, test with: >
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
1100 if has("patch-8.1.350")
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
1101 let options['noblock'] = 1
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
1102 endif
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
1103 <
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
1104 *job-callback*
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
1105 "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
1106 channel.
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1107 *job-out_cb* *out_cb*
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1108 "out_cb": handler Callback for when there is something to read on
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1109 stdout. Only for when the channel uses pipes. When
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1110 "out_cb" wasn't set the channel callback is used.
9533
9f921133ee90 commit https://github.com/vim/vim/commit/269f595f9eef584937e7eae70fde68cdd7da5bcf
Christian Brabandt <cb@256bit.org>
parents: 9464
diff changeset
1111 The two arguments are the channel and the message.
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1112
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1113 *job-err_cb* *err_cb*
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1114 "err_cb": handler Callback for when there is something to read on
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1115 stderr. Only for when the channel uses pipes. When
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1116 "err_cb" wasn't set the channel callback is used.
9533
9f921133ee90 commit https://github.com/vim/vim/commit/269f595f9eef584937e7eae70fde68cdd7da5bcf
Christian Brabandt <cb@256bit.org>
parents: 9464
diff changeset
1117 The two arguments are the channel and the message.
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1118 *job-close_cb*
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1119 "close_cb": handler Callback for when the channel is closed. Same as
9227
ecb621205ed1 commit https://github.com/vim/vim/commit/82af8710bf8d1caeeceafb1370a052cb7d92f076
Christian Brabandt <cb@256bit.org>
parents: 9147
diff changeset
1120 "close_cb" on |ch_open()|, see |close_cb|.
10498
883396809b45 commit https://github.com/vim/vim/commit/bc2eada5424bff06f7eb77c032ecc067da52b846
Christian Brabandt <cb@256bit.org>
parents: 10449
diff changeset
1121 *job-drop*
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1122 "drop": when Specifies when to drop messages. Same as "drop" on
10449
222b1432814e commit https://github.com/vim/vim/commit/5162822914372fc916a93f85848c0c82209e7cec
Christian Brabandt <cb@256bit.org>
parents: 10426
diff changeset
1123 |ch_open()|, see |channel-drop|. For "auto" the
222b1432814e commit https://github.com/vim/vim/commit/5162822914372fc916a93f85848c0c82209e7cec
Christian Brabandt <cb@256bit.org>
parents: 10426
diff changeset
1124 exit_cb is not considered.
10498
883396809b45 commit https://github.com/vim/vim/commit/bc2eada5424bff06f7eb77c032ecc067da52b846
Christian Brabandt <cb@256bit.org>
parents: 10449
diff changeset
1125 *job-exit_cb*
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1126 "exit_cb": handler Callback for when the job ends. The arguments are the
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1127 job and the exit status.
10319
169a62d5bcb9 commit https://github.com/vim/vim/commit/b4ada79aa7d0d1e5da3a659b1a203d7cae9f7f59
Christian Brabandt <cb@256bit.org>
parents: 10244
diff changeset
1128 Vim checks up to 10 times per second for jobs that
169a62d5bcb9 commit https://github.com/vim/vim/commit/b4ada79aa7d0d1e5da3a659b1a203d7cae9f7f59
Christian Brabandt <cb@256bit.org>
parents: 10244
diff changeset
1129 ended. The check can also be triggered by calling
169a62d5bcb9 commit https://github.com/vim/vim/commit/b4ada79aa7d0d1e5da3a659b1a203d7cae9f7f59
Christian Brabandt <cb@256bit.org>
parents: 10244
diff changeset
1130 |job_status()|, which may then invoke the exit_cb
169a62d5bcb9 commit https://github.com/vim/vim/commit/b4ada79aa7d0d1e5da3a659b1a203d7cae9f7f59
Christian Brabandt <cb@256bit.org>
parents: 10244
diff changeset
1131 handler.
9097
071f9da012fb commit https://github.com/vim/vim/commit/06d2d38ab7564e1f784b1058a4ef4580cd6d1810
Christian Brabandt <cb@256bit.org>
parents: 9076
diff changeset
1132 Note that data can be buffered, callbacks may still be
071f9da012fb commit https://github.com/vim/vim/commit/06d2d38ab7564e1f784b1058a4ef4580cd6d1810
Christian Brabandt <cb@256bit.org>
parents: 9076
diff changeset
1133 called after the process ends.
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1134 *job-timeout*
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1135 "timeout": time The time to wait for a request when blocking, E.g.
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1136 when using ch_evalexpr(). In milliseconds. The
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1137 default is 2000 (2 seconds).
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1138 *out_timeout* *err_timeout*
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1139 "out_timeout": time Timeout for stdout. Only when using pipes.
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1140 "err_timeout": time Timeout for stderr. Only when using pipes.
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1141 Note: when setting "timeout" the part specific mode is
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1142 overwritten. Therefore set "timeout" first and the
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1143 part specific mode later.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1144
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
1145 *job-stoponexit*
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
1146 "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
1147 |job_stop()| for possible values.
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
1148 "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
1149 The default is "term".
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
1150
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1151 *job-term*
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1152 "term": "open" Start a terminal in a new window and connect the job
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1153 stdin/stdout/stderr to it. Similar to using
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1154 `:terminal`.
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1155 NOTE: Not implemented yet!
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1156
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1157 "channel": {channel} Use an existing channel instead of creating a new one.
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1158 The parts of the channel that get used for the new job
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1159 will be disconnected from what they were used before.
10449
222b1432814e commit https://github.com/vim/vim/commit/5162822914372fc916a93f85848c0c82209e7cec
Christian Brabandt <cb@256bit.org>
parents: 10426
diff changeset
1160 If the channel was still used by another job this may
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1161 cause I/O errors.
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1162 Existing callbacks and other settings remain.
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1163
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1164 "pty": 1 Use a pty (pseudo-tty) instead of a pipe when
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1165 possible. This is most useful in combination with a
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1166 terminal window, see |terminal|.
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1167 {only on Unix and Unix-like systems}
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1168
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1169 *job-in_io* *in_top* *in_bot* *in_name* *in_buf*
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1170 "in_io": "null" disconnect stdin (read from /dev/null)
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1171 "in_io": "pipe" stdin is connected to the channel (default)
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1172 "in_io": "file" stdin reads from a file
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1173 "in_io": "buffer" stdin reads from a buffer
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1174 "in_top": number when using "buffer": first line to send (default: 1)
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1175 "in_bot": number when using "buffer": last line to send (default: last)
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1176 "in_name": "/path/file" the name of the file or buffer to read from
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1177 "in_buf": number the number of the buffer to read from
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1178
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1179 *job-out_io* *out_name* *out_buf*
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1180 "out_io": "null" disconnect stdout (goes to /dev/null)
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1181 "out_io": "pipe" stdout is connected to the channel (default)
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1182 "out_io": "file" stdout writes to a file
10449
222b1432814e commit https://github.com/vim/vim/commit/5162822914372fc916a93f85848c0c82209e7cec
Christian Brabandt <cb@256bit.org>
parents: 10426
diff changeset
1183 "out_io": "buffer" stdout appends to a buffer (see below)
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1184 "out_name": "/path/file" the name of the file or buffer to write to
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1185 "out_buf": number the number of the buffer to write to
9147
053bc64433ec commit https://github.com/vim/vim/commit/9f5842e63fc63d438cbffcec503e072a06f74dc2
Christian Brabandt <cb@256bit.org>
parents: 9116
diff changeset
1186 "out_modifiable": 0 when writing to a buffer, 'modifiable' will be off
053bc64433ec commit https://github.com/vim/vim/commit/9f5842e63fc63d438cbffcec503e072a06f74dc2
Christian Brabandt <cb@256bit.org>
parents: 9116
diff changeset
1187 (see below)
10147
65afd399ffa7 commit https://github.com/vim/vim/commit/169ebb080454357279ad5ad21ac532deaec605e8
Christian Brabandt <cb@256bit.org>
parents: 10054
diff changeset
1188 "out_msg": 0 when writing to a new buffer, the first line will be
65afd399ffa7 commit https://github.com/vim/vim/commit/169ebb080454357279ad5ad21ac532deaec605e8
Christian Brabandt <cb@256bit.org>
parents: 10054
diff changeset
1189 set to "Reading from channel output..."
8267
108d30ed34ba commit https://github.com/vim/vim/commit/187db50d0499aecf4cfd42fb4db0a1bebf61c8cd
Christian Brabandt <cb@256bit.org>
parents: 8246
diff changeset
1190
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1191 *job-err_io* *err_name* *err_buf*
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1192 "err_io": "out" stderr messages to go to stdout
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1193 "err_io": "null" disconnect stderr (goes to /dev/null)
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1194 "err_io": "pipe" stderr is connected to the channel (default)
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1195 "err_io": "file" stderr writes to a file
10449
222b1432814e commit https://github.com/vim/vim/commit/5162822914372fc916a93f85848c0c82209e7cec
Christian Brabandt <cb@256bit.org>
parents: 10426
diff changeset
1196 "err_io": "buffer" stderr appends to a buffer (see below)
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1197 "err_name": "/path/file" the name of the file or buffer to write to
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1198 "err_buf": number the number of the buffer to write to
9147
053bc64433ec commit https://github.com/vim/vim/commit/9f5842e63fc63d438cbffcec503e072a06f74dc2
Christian Brabandt <cb@256bit.org>
parents: 9116
diff changeset
1199 "err_modifiable": 0 when writing to a buffer, 'modifiable' will be off
053bc64433ec commit https://github.com/vim/vim/commit/9f5842e63fc63d438cbffcec503e072a06f74dc2
Christian Brabandt <cb@256bit.org>
parents: 9116
diff changeset
1200 (see below)
10147
65afd399ffa7 commit https://github.com/vim/vim/commit/169ebb080454357279ad5ad21ac532deaec605e8
Christian Brabandt <cb@256bit.org>
parents: 10054
diff changeset
1201 "err_msg": 0 when writing to a new buffer, the first line will be
65afd399ffa7 commit https://github.com/vim/vim/commit/169ebb080454357279ad5ad21ac532deaec605e8
Christian Brabandt <cb@256bit.org>
parents: 10054
diff changeset
1202 set to "Reading from channel error..."
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1203
8795
aba2d0a01290 commit https://github.com/vim/vim/commit/7db8f6f4f85e5d0526d23107b2a5e2334dc23354
Christian Brabandt <cb@256bit.org>
parents: 8748
diff changeset
1204 "block_write": number only for testing: pretend every other write to stdin
aba2d0a01290 commit https://github.com/vim/vim/commit/7db8f6f4f85e5d0526d23107b2a5e2334dc23354
Christian Brabandt <cb@256bit.org>
parents: 8748
diff changeset
1205 will block
aba2d0a01290 commit https://github.com/vim/vim/commit/7db8f6f4f85e5d0526d23107b2a5e2334dc23354
Christian Brabandt <cb@256bit.org>
parents: 8748
diff changeset
1206
12043
2796a2c9fc17 patch 8.0.0902: cannot specify directory or environment for a job
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
1207 "env": dict environment variables for the new process
2796a2c9fc17 patch 8.0.0902: cannot specify directory or environment for a job
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
1208 "cwd": "/path/to/dir" current working directory for the new process;
2796a2c9fc17 patch 8.0.0902: cannot specify directory or environment for a job
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
1209 if the directory does not exist an error is given
2796a2c9fc17 patch 8.0.0902: cannot specify directory or environment for a job
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
1210
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1211
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1212 Writing to a buffer ~
10004
8061455d9179 commit https://github.com/vim/vim/commit/818078ddfbb8cc2546f697c5675a251d095722ec
Christian Brabandt <cb@256bit.org>
parents: 9969
diff changeset
1213 *out_io-buffer*
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1214 When the out_io or err_io mode is "buffer" and there is a callback, the text
8440
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents: 8392
diff changeset
1215 is appended to the buffer before invoking the callback.
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents: 8392
diff changeset
1216
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents: 8392
diff changeset
1217 When a buffer is used both for input and output, the output lines are put
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents: 8392
diff changeset
1218 above the last line, since the last line is what is written to the channel
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1219 input. Otherwise lines are appended below the last line.
8291
ac0c43e7af20 commit https://github.com/vim/vim/commit/c7f0ebc6d1e1cdaed816b88a0d6092c5ace615eb
Christian Brabandt <cb@256bit.org>
parents: 8285
diff changeset
1220
8392
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
1221 When using JS or JSON mode with "buffer", only messages with zero or negative
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
1222 ID will be added to the buffer, after decoding + encoding. Messages with a
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
1223 positive number will be handled by a callback, commands are handled as usual.
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
1224
9227
ecb621205ed1 commit https://github.com/vim/vim/commit/82af8710bf8d1caeeceafb1370a052cb7d92f076
Christian Brabandt <cb@256bit.org>
parents: 9147
diff changeset
1225 The name of the buffer from "out_name" or "err_name" is compared the full name
ecb621205ed1 commit https://github.com/vim/vim/commit/82af8710bf8d1caeeceafb1370a052cb7d92f076
Christian Brabandt <cb@256bit.org>
parents: 9147
diff changeset
1226 of existing buffers, also after expanding the name for the current directory.
ecb621205ed1 commit https://github.com/vim/vim/commit/82af8710bf8d1caeeceafb1370a052cb7d92f076
Christian Brabandt <cb@256bit.org>
parents: 9147
diff changeset
1227 E.g., when a buffer was created with ":edit somename" and the buffer name is
ecb621205ed1 commit https://github.com/vim/vim/commit/82af8710bf8d1caeeceafb1370a052cb7d92f076
Christian Brabandt <cb@256bit.org>
parents: 9147
diff changeset
1228 "somename" it will use that buffer.
ecb621205ed1 commit https://github.com/vim/vim/commit/82af8710bf8d1caeeceafb1370a052cb7d92f076
Christian Brabandt <cb@256bit.org>
parents: 9147
diff changeset
1229
ecb621205ed1 commit https://github.com/vim/vim/commit/82af8710bf8d1caeeceafb1370a052cb7d92f076
Christian Brabandt <cb@256bit.org>
parents: 9147
diff changeset
1230 If there is no matching buffer a new buffer is created. Use an empty name to
ecb621205ed1 commit https://github.com/vim/vim/commit/82af8710bf8d1caeeceafb1370a052cb7d92f076
Christian Brabandt <cb@256bit.org>
parents: 9147
diff changeset
1231 always create a new buffer. |ch_getbufnr()| can then be used to get the
ecb621205ed1 commit https://github.com/vim/vim/commit/82af8710bf8d1caeeceafb1370a052cb7d92f076
Christian Brabandt <cb@256bit.org>
parents: 9147
diff changeset
1232 buffer number.
8291
ac0c43e7af20 commit https://github.com/vim/vim/commit/c7f0ebc6d1e1cdaed816b88a0d6092c5ace615eb
Christian Brabandt <cb@256bit.org>
parents: 8285
diff changeset
1233
ac0c43e7af20 commit https://github.com/vim/vim/commit/c7f0ebc6d1e1cdaed816b88a0d6092c5ace615eb
Christian Brabandt <cb@256bit.org>
parents: 8285
diff changeset
1234 For a new buffer 'buftype' is set to "nofile" and 'bufhidden' to "hide". If
ac0c43e7af20 commit https://github.com/vim/vim/commit/c7f0ebc6d1e1cdaed816b88a0d6092c5ace615eb
Christian Brabandt <cb@256bit.org>
parents: 8285
diff changeset
1235 you prefer other settings, create the buffer first and pass the buffer number.
10147
65afd399ffa7 commit https://github.com/vim/vim/commit/169ebb080454357279ad5ad21ac532deaec605e8
Christian Brabandt <cb@256bit.org>
parents: 10054
diff changeset
1236 *out_modifiable* *err_modifiable*
65afd399ffa7 commit https://github.com/vim/vim/commit/169ebb080454357279ad5ad21ac532deaec605e8
Christian Brabandt <cb@256bit.org>
parents: 10054
diff changeset
1237 The "out_modifiable" and "err_modifiable" options can be used to set the
65afd399ffa7 commit https://github.com/vim/vim/commit/169ebb080454357279ad5ad21ac532deaec605e8
Christian Brabandt <cb@256bit.org>
parents: 10054
diff changeset
1238 'modifiable' option off, or write to a buffer that has 'modifiable' off. That
65afd399ffa7 commit https://github.com/vim/vim/commit/169ebb080454357279ad5ad21ac532deaec605e8
Christian Brabandt <cb@256bit.org>
parents: 10054
diff changeset
1239 means that lines will be appended to the buffer, but the user can't easily
65afd399ffa7 commit https://github.com/vim/vim/commit/169ebb080454357279ad5ad21ac532deaec605e8
Christian Brabandt <cb@256bit.org>
parents: 10054
diff changeset
1240 change the buffer.
65afd399ffa7 commit https://github.com/vim/vim/commit/169ebb080454357279ad5ad21ac532deaec605e8
Christian Brabandt <cb@256bit.org>
parents: 10054
diff changeset
1241 *out_msg* *err_msg*
65afd399ffa7 commit https://github.com/vim/vim/commit/169ebb080454357279ad5ad21ac532deaec605e8
Christian Brabandt <cb@256bit.org>
parents: 10054
diff changeset
1242 The "out_msg" option can be used to specify whether a new buffer will have the
65afd399ffa7 commit https://github.com/vim/vim/commit/169ebb080454357279ad5ad21ac532deaec605e8
Christian Brabandt <cb@256bit.org>
parents: 10054
diff changeset
1243 first line set to "Reading from channel output...". The default is to add the
65afd399ffa7 commit https://github.com/vim/vim/commit/169ebb080454357279ad5ad21ac532deaec605e8
Christian Brabandt <cb@256bit.org>
parents: 10054
diff changeset
1244 message. "err_msg" does the same for channel error.
8267
108d30ed34ba commit https://github.com/vim/vim/commit/187db50d0499aecf4cfd42fb4db0a1bebf61c8cd
Christian Brabandt <cb@256bit.org>
parents: 8246
diff changeset
1245
9147
053bc64433ec commit https://github.com/vim/vim/commit/9f5842e63fc63d438cbffcec503e072a06f74dc2
Christian Brabandt <cb@256bit.org>
parents: 9116
diff changeset
1246 When an existing buffer is to be written where 'modifiable' is off and the
053bc64433ec commit https://github.com/vim/vim/commit/9f5842e63fc63d438cbffcec503e072a06f74dc2
Christian Brabandt <cb@256bit.org>
parents: 9116
diff changeset
1247 "out_modifiable" or "err_modifiable" options is not zero, an error is given
053bc64433ec commit https://github.com/vim/vim/commit/9f5842e63fc63d438cbffcec503e072a06f74dc2
Christian Brabandt <cb@256bit.org>
parents: 9116
diff changeset
1248 and the buffer will not be written to.
053bc64433ec commit https://github.com/vim/vim/commit/9f5842e63fc63d438cbffcec503e072a06f74dc2
Christian Brabandt <cb@256bit.org>
parents: 9116
diff changeset
1249
8267
108d30ed34ba commit https://github.com/vim/vim/commit/187db50d0499aecf4cfd42fb4db0a1bebf61c8cd
Christian Brabandt <cb@256bit.org>
parents: 8246
diff changeset
1250 When the buffer written to is displayed in a window and the cursor is in the
108d30ed34ba commit https://github.com/vim/vim/commit/187db50d0499aecf4cfd42fb4db0a1bebf61c8cd
Christian Brabandt <cb@256bit.org>
parents: 8246
diff changeset
1251 first column of the last line, the cursor will be moved to the newly added
108d30ed34ba commit https://github.com/vim/vim/commit/187db50d0499aecf4cfd42fb4db0a1bebf61c8cd
Christian Brabandt <cb@256bit.org>
parents: 8246
diff changeset
1252 line and the window is scrolled up to show the cursor if needed.
108d30ed34ba commit https://github.com/vim/vim/commit/187db50d0499aecf4cfd42fb4db0a1bebf61c8cd
Christian Brabandt <cb@256bit.org>
parents: 8246
diff changeset
1253
9464
be72f4201a1d commit https://github.com/vim/vim/commit/063b9d15abea041a5bfff3ffc4e219e26fd1d4fa
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
1254 Undo is synced for every added line. NUL bytes are accepted (internally Vim
be72f4201a1d commit https://github.com/vim/vim/commit/063b9d15abea041a5bfff3ffc4e219e26fd1d4fa
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
1255 stores these as NL bytes).
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1256
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1257
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1258 Writing to a file ~
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1259 *E920*
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1260 The file is created with permissions 600 (read-write for the user, not
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1261 accessible for others). Use |setfperm()| to change this.
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1262
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1263 If the file already exists it is truncated.
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1264
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1265 ==============================================================================
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1266 13. Controlling a job *job-control*
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1267
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1268 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
1269 echo job_status(job)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1270
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1271 To make a job stop running: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1272 job_stop(job)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1273
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1274 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
1275 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
1276 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
1277 job_stop(job, "kill")
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1278
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1279 For more options see |job_stop()|.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
1280
14019
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1281 ==============================================================================
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1282 14. Using a prompt buffer *prompt-buffer*
14019
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1283
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1284 If you want to type input for the job in a Vim window you have a few options:
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1285 - Use a normal buffer and handle all possible commands yourself.
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1286 This will be complicated, since there are so many possible commands.
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1287 - Use a terminal window. This works well if what you type goes directly to
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1288 the job and the job output is directly displayed in the window.
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1289 See |terminal-window|.
20753
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1290 - Use a window with a prompt buffer. This works well when entering a line for
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1291 the job in Vim while displaying (possibly filtered) output from the job.
14019
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1292
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1293 A prompt buffer is created by setting 'buftype' to "prompt". You would
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1294 normally only do that in a newly created buffer.
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1295
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1296 The user can edit and enter one line of text at the very last line of the
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1297 buffer. When pressing Enter in the prompt line the callback set with
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1298 |prompt_setcallback()| is invoked. It would normally send the line to a job.
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1299 Another callback would receive the output from the job and display it in the
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1300 buffer, below the prompt (and above the next prompt).
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1301
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1302 Only the text in the last line, after the prompt, is editable. The rest of the
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1303 buffer is not modifiable with Normal mode commands. It can be modified by
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1304 calling functions, such as |append()|. Using other commands may mess up the
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1305 buffer.
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1306
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1307 After setting 'buftype' to "prompt" Vim does not automatically start Insert
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1308 mode, use `:startinsert` if you want to enter Insert mode, so that the user
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1309 can start typing a line.
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1310
22077
335365fcbb60 patch 8.2.1588: cannot read back the prompt of a prompt buffer
Bram Moolenaar <Bram@vim.org>
parents: 21250
diff changeset
1311 The text of the prompt can be set with the |prompt_setprompt()| function. If
335365fcbb60 patch 8.2.1588: cannot read back the prompt of a prompt buffer
Bram Moolenaar <Bram@vim.org>
parents: 21250
diff changeset
1312 no prompt is set with |prompt_setprompt()|, "% " is used. You can get the
335365fcbb60 patch 8.2.1588: cannot read back the prompt of a prompt buffer
Bram Moolenaar <Bram@vim.org>
parents: 21250
diff changeset
1313 effective prompt text for a buffer, with |prompt_getprompt()|.
14019
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1314
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1315 The user can go to Normal mode and navigate through the buffer. This can be
21250
21fb2a3ad3ca Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20753
diff changeset
1316 useful to see older output or copy text.
14019
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1317
14123
583bf95b6c84 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14019
diff changeset
1318 The CTRL-W key can be used to start a window command, such as CTRL-W w to
583bf95b6c84 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14019
diff changeset
1319 switch to the next window. This also works in Insert mode (use Shift-CTRL-W
583bf95b6c84 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14019
diff changeset
1320 to delete a word). When leaving the window Insert mode will be stopped. When
583bf95b6c84 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14019
diff changeset
1321 coming back to the prompt window Insert mode will be restored.
583bf95b6c84 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14019
diff changeset
1322
14019
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1323 Any command that starts Insert mode, such as "a", "i", "A" and "I", will move
14123
583bf95b6c84 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14019
diff changeset
1324 the cursor to the last line. "A" will move to the end of the line, "I" to the
583bf95b6c84 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14019
diff changeset
1325 start of the line.
14019
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1326
20753
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1327 Here is an example for Unix. It starts a shell in the background and prompts
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1328 for the next shell command. Output from the shell is displayed above the
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1329 prompt. >
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1330
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1331 " Create a channel log so we can see what happens.
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1332 call ch_logfile('logfile', 'w')
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1333
28010
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1334 " Function handling a line of text that has been typed.
20753
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1335 func TextEntered(text)
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1336 " Send the text to a shell with Enter appended.
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1337 call ch_sendraw(g:shell_job, a:text .. "\n")
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1338 endfunc
22723
5b7ea82bc18f Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 22077
diff changeset
1339
28010
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1340 " Function handling output from the shell: Add it above the prompt.
20753
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1341 func GotOutput(channel, msg)
27903
d19b7aee1925 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 26438
diff changeset
1342 call append(line("$") - 1, "- " .. a:msg)
20753
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1343 endfunc
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1344
28010
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1345 " Function handling the shell exits: close the window.
20753
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1346 func JobExit(job, status)
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1347 quit!
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1348 endfunc
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1349
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1350 " Start a shell in the background.
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1351 let shell_job = job_start(["/bin/sh"], #{
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1352 \ out_cb: function('GotOutput'),
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1353 \ err_cb: function('GotOutput'),
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1354 \ exit_cb: function('JobExit'),
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1355 \ })
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1356
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1357 new
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1358 set buftype=prompt
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1359 let buf = bufnr('')
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1360 call prompt_setcallback(buf, function("TextEntered"))
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1361 eval prompt_setprompt(buf, "shell command: ")
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1362
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1363 " start accepting shell commands
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1364 startinsert
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1365 <
28010
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1366 The same in |Vim9| script: >
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1367
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1368 vim9script
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1369
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1370 # Create a channel log so we can see what happens.
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1371 ch_logfile('logfile', 'w')
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1372
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1373 var shell_job: job
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1374
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1375 # Function handling a line of text that has been typed.
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1376 def TextEntered(text: string)
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1377 # Send the text to a shell with Enter appended.
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1378 ch_sendraw(shell_job, text .. "\n")
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1379 enddef
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1380
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1381 # Function handling output from the shell: Add it above the prompt.
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1382 def GotOutput(channel: channel, msg: string)
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1383 append(line("$") - 1, "- " .. msg)
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1384 enddef
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1385
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1386 # Function handling the shell exits: close the window.
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1387 def JobExit(job: job, status: number)
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1388 quit!
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1389 enddef
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1390
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1391 # Start a shell in the background.
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1392 shell_job = job_start(["/bin/sh"], {
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1393 out_cb: GotOutput,
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1394 err_cb: GotOutput,
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1395 exit_cb: JobExit,
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1396 })
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1397
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1398 new
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1399 set buftype=prompt
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1400 var buf = bufnr('')
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1401 prompt_setcallback(buf, TextEntered)
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1402 prompt_setprompt(buf, "shell command: ")
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1403
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1404 # start accepting shell commands
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1405 startinsert
20753
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1406
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1407 ==============================================================================
28467
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1408 15. Language Server Protocol *language-server-protocol*
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1409
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1410 The language server protocol specification is available at:
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1411
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1412 https://microsoft.github.io/language-server-protocol/specification
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1413
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1414 Each LSP protocol message starts with a simple HTTP header followed by the
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1415 payload encoded in JSON-RPC format. This is described in:
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1416
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1417 https://www.jsonrpc.org/specification
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1418
28473
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1419 To encode and send a LSP request/notification message in a Vim |Dict| into a
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1420 LSP JSON-RPC message and to receive and decode a LSP JSON-RPC
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1421 response/notification message into a Vim |Dict|, connect to the LSP server
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1422 with the |channel-mode| set to "lsp".
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1423
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1424 For messages received on a channel with |channel-mode| set to "lsp", Vim will
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1425 process the HTTP header and decode the JSON-RPC payload into a Vim |Dict| type
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1426 and call the |channel-callback| function or the specified
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1427 |channel-onetime-callback| function. When sending messages on a channel using
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1428 the |ch_evalexpr()| or |ch_sendexpr()| functions, Vim will add the HTTP header
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1429 and encode the Vim expression into JSON. Refer to |json_encode()| and
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1430 |json_decode()| for more information about how Vim encodes and decodes the
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1431 builtin types into JSON.
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1432
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1433 To open a channel using the 'lsp' mode, set the 'mode' item in the |ch_open()|
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1434 {options} argument to 'lsp'. Example: >
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1435
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1436 let ch = ch_open(..., #{mode: 'lsp'})
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1437
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1438 To open a channel using the 'lsp' mode with a job, set the 'in_mode' and
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1439 'out_mode' items in the |job_start()| {options} argument to 'lsp'. Example: >
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1440
28473
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1441 let cmd = ['clangd', '--background-index', '--clang-tidy']
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1442 let opts = {}
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1443 let opts.in_mode = 'lsp'
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1444 let opts.out_mode = 'lsp'
28511
d7ca583e5772 patch 8.2.4780: parsing an LSP message fails when it is split
Bram Moolenaar <Bram@vim.org>
parents: 28473
diff changeset
1445 let opts.err_mode = 'nl'
28473
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1446 let opts.out_cb = function('LspOutCallback')
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1447 let opts.err_cb = function('LspErrCallback')
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1448 let opts.exit_cb = function('LspExitCallback')
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1449 let job = job_start(cmd, opts)
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1450
28511
d7ca583e5772 patch 8.2.4780: parsing an LSP message fails when it is split
Bram Moolenaar <Bram@vim.org>
parents: 28473
diff changeset
1451 Note that if a job outputs LSP messages on stdout and non-LSP messages on
d7ca583e5772 patch 8.2.4780: parsing an LSP message fails when it is split
Bram Moolenaar <Bram@vim.org>
parents: 28473
diff changeset
1452 stderr, then the channel-callback function should handle both the message
d7ca583e5772 patch 8.2.4780: parsing an LSP message fails when it is split
Bram Moolenaar <Bram@vim.org>
parents: 28473
diff changeset
1453 formats appropriately or you should use a separate callback function for
d7ca583e5772 patch 8.2.4780: parsing an LSP message fails when it is split
Bram Moolenaar <Bram@vim.org>
parents: 28473
diff changeset
1454 "out_cb" and "err_cb" to handle them as shown above.
d7ca583e5772 patch 8.2.4780: parsing an LSP message fails when it is split
Bram Moolenaar <Bram@vim.org>
parents: 28473
diff changeset
1455
28467
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1456 To synchronously send a JSON-RPC request to the server, use the
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1457 |ch_evalexpr()| function. This function will wait and return the decoded
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1458 response message from the server. You can use either the |channel-timeout| or
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1459 the 'timeout' field in the {options} argument to control the response wait
28473
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1460 time. If the request times out, then an empty |Dict| is returned. Example: >
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1461
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1462 let req = {}
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1463 let req.method = 'textDocument/definition'
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1464 let req.params = {}
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1465 let req.params.textDocument = #{uri: 'a.c'}
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1466 let req.params.position = #{line: 10, character: 3}
28473
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1467 let defs = ch_evalexpr(ch, req, #{timeout: 100})
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1468 if defs->empty()
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1469 ... <handle failure>
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1470 endif
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1471
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1472 Note that in the request message the 'id' field should not be specified. If it
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1473 is specified, then Vim will overwrite the value with an internally generated
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1474 identifier. Vim currently supports only a number type for the 'id' field.
28467
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1475 The callback function will be invoked for both a successful and a failed RPC
28473
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1476 request.
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1477
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1478 To send a JSON-RPC request to the server and asynchronously process the
28473
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1479 response, use the |ch_sendexpr()| function and supply a callback function. If
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1480 the "id" field is present in the request message, then Vim will overwrite it
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1481 with an internally generated number. This function returns a Dict with the
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1482 identifier used for the message. This can be used to send cancellation
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1483 request to the LSP server (if needed). Example: >
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1484
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1485 let req = {}
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1486 let req.method = 'textDocument/hover'
28467
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1487 let req.id = 200
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1488 let req.params = {}
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1489 let req.params.textDocument = #{uri: 'a.c'}
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1490 let req.params.position = #{line: 10, character: 3}
28473
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1491 let resp = ch_sendexpr(ch, req, #{callback: 'HoverFunc'})
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1492
28473
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1493 To cancel an outstanding asynchronous LSP request sent to the server using the
29193
1e9e9d89f0ee Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 29087
diff changeset
1494 |ch_sendexpr()| function, send a cancellation message to the server using the
28473
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1495 |ch_sendexpr()| function with the ID returned by the |ch_sendexpr()| function
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1496 for the request. Example: >
28467
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1497
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1498 " send a completion request
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1499 let req = {}
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1500 let req.method = 'textDocument/completion'
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1501 let req.params = {}
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1502 let req.params.textDocument = #{uri: 'a.c'}
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1503 let req.params.position = #{line: 10, character: 3}
28473
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1504 let reqstatus = ch_sendexpr(ch, req, #{callback: 'LspComplete'})
28467
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1505 " send a cancellation notification
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1506 let notif = {}
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1507 let notif.method = '$/cancelRequest'
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1508 let notif.id = reqstatus.id
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1509 call ch_sendexpr(ch, notif)
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1510
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1511 To send a JSON-RPC notification message to the server, use the |ch_sendexpr()|
28467
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1512 function. As the server will not send a response message to the notification,
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1513 don't specify the "callback" item. Example: >
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1514
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1515 call ch_sendexpr(ch, #{method: 'initialized'})
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1516
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1517 To respond to a JSON-RPC request message from the server, use the
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1518 |ch_sendexpr()| function. In the response message, copy the 'id' field value
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1519 from the server request message. Example: >
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1520
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1521 let resp = {}
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1522 let resp.id = req.id
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1523 let resp.result = 1
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1524 call ch_sendexpr(ch, resp)
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1525
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1526 The JSON-RPC notification messages from the server are delivered through the
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1527 |channel-callback| function.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
1528
28467
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1529 Depending on the use case, you can use the ch_evalexpr(), ch_sendexpr() and
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1530 ch_sendraw() functions on the same channel.
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1531
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1532 A LSP request message has the following format (expressed as a Vim Dict). The
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1533 "params" field is optional: >
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1534
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1535 {
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1536 "jsonrpc": "2.0",
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1537 "id": <number>,
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1538 "method": <string>,
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1539 "params": <list|dict>
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1540 }
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1541
29193
1e9e9d89f0ee Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 29087
diff changeset
1542 A LSP response message has the following format (expressed as a Vim Dict). The
28467
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1543 "result" and "error" fields are optional: >
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1544
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1545 {
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1546 "jsonrpc": "2.0",
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1547 "id": <number>,
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1548 "result": <vim type>
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1549 "error": <dict>
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1550 }
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1551
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1552 A LSP notification message has the following format (expressed as a Vim Dict).
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1553 The "params" field is optional: >
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1554
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1555 {
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1556 "jsonrpc": "2.0",
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1557 "method": <string>,
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1558 "params": <list|dict>
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1559 }
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1560
29290
dc4de65a7fb7 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 29274
diff changeset
1561 <
14421
2f7e67dd088c Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14123
diff changeset
1562 vim:tw=78:ts=8:noet:ft=help:norl: