Mercurial > vim

annotate runtime/doc/channel.txt @ 29274:d314efe6447a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Update runtime files Commit: https://github.com/vim/vim/commit/a57b553b432855667c9f26edfad95ccfdd24a6b7 Author: Bram Moolenaar <Bram@vim.org> Date: Fri Jun 24 11:48:03 2022 +0100 Update runtime files
author Bram Moolenaar <Bram@vim.org>
date Fri, 24 Jun 2022 13:00:09 +0200
parents 1e9e9d89f0ee
children dc4de65a7fb7
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
29274
d314efe6447a Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 29193
diff changeset
1 *channel.txt* For Vim version 8.2. Last change: 2022 Jun 23
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
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
30 {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
31 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
32 {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
33 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
34
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
35 ==============================================================================
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
36 1. Overview *job-channel-overview*
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
37
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
38 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
39 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
40 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
41 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
42 Uses a socket or pipes.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
43 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
44 Uses a socket or pipes.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
45 4. Running a filter, synchronously.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
46 Uses pipes.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
47
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
48 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
49 |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
50 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
51
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
52 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
53 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
54 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
55 JSON JSON encoding |json_encode()|
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
56 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
57 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
58
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
59 Common combination are:
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
60 - 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
61 checker and receive errors and warnings.
13735
a62eeee5f116 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12045
diff changeset
62 - 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
63 cross-references in a database.
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
64
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
65 ==============================================================================
9116
bc38030aec7d commit https://github.com/vim/vim/commit/26852128a2b713ef49341a0c18daba928444e7eb
Christian Brabandt <cb@256bit.org>
parents: 9097
diff changeset
66 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
67
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
68 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
69 $VIMRUNTIME/tools/demoserver.py
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
70 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
71
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
72 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
73 let channel = ch_open('localhost:8765')
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
74
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
75 In T1 you should see:
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
76 === socket opened === ~
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
77
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
78 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
79 echo ch_evalexpr(channel, 'hello!')
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
80
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
81 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
82 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
83 [1,"hello!"] ~
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
84 And the response is:
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
85 [1,"got it"] ~
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
86 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
87
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
88 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
89 the quotes):
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
90 ["ex","echo 'hi there'"] ~
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
91 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
92 ["normal","w"] ~
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
93
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
94 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
95 func MyHandler(channel, msg)
27903
d19b7aee1925 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 26438
diff changeset
96 echo "from the handler: " .. a:msg
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
97 endfunc
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
98 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
99 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
100 and MyHandler will be invoked.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
101
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
102 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
103 when opening the channel: >
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
104 call ch_close(channel)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
105 let channel = ch_open('localhost:8765', {'callback': "MyHandler"})
26438
c725b8e17f1f Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 25619
diff changeset
106 call ch_sendexpr(channel, 'hello channel!')
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
107
8392
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
108 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
109 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
110 call ch_logfile('channellog', 'w')
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
111 See |ch_logfile()|.
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
112
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
113 ==============================================================================
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
114 3. Opening a channel *channel-open*
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
115
7924
00d64eb49ce1 commit https://github.com/vim/vim/commit/681baaf4a4c81418693dcafb81421a8614832e91
Christian Brabandt <cb@256bit.org>
parents: 7864
diff changeset
116 To open a channel: >
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
117 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
118 if ch_status(channel) == "open"
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
119 " use the channel
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
120
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
121 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
122
28317
d32dc906dd2c patch 8.2.4684: cannot open a channel on a Unix domain socket
Bram Moolenaar <Bram@vim.org>
parents: 28246
diff changeset
123 *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
124 {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
125 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
126 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
127 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
128 [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
129 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
130
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
131 {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
132
3f2e0b62003d commit https://github.com/vim/vim/commit/4d919d748e4e435edb135aa5ccf6ee7de9212023
Christian Brabandt <cb@256bit.org>
parents: 7924
diff changeset
133 "mode" can be: *channel-mode*
3f2e0b62003d commit https://github.com/vim/vim/commit/4d919d748e4e435edb135aa5ccf6ee7de9212023
Christian Brabandt <cb@256bit.org>
parents: 7924
diff changeset
134 "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
135 "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
136 "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
137 "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
138 "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
139 *channel-callback* *E921*
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
140 "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
141 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
142 gets two arguments: the channel and the received message.
c725b8e17f1f Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 25619
diff changeset
143 Example: >
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
144 func Handle(channel, msg)
27903
d19b7aee1925 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 26438
diff changeset
145 echo 'Received: ' .. a:msg
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
146 endfunc
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
147 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
148 <
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
149 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
150 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
151 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
152 excluding the NL.
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
153 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
154 as a string.
8673
ed7251c3e2d3 commit https://github.com/vim/vim/commit/e18c0b39815c5a746887a509c2cd9f11fadaba07
Christian Brabandt <cb@256bit.org>
parents: 8540
diff changeset
155
ed7251c3e2d3 commit https://github.com/vim/vim/commit/e18c0b39815c5a746887a509c2cd9f11fadaba07
Christian Brabandt <cb@256bit.org>
parents: 8540
diff changeset
156 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
157 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
158 the Dictionary.
9097
071f9da012fb commit https://github.com/vim/vim/commit/06d2d38ab7564e1f784b1058a4ef4580cd6d1810
Christian Brabandt <cb@256bit.org>
parents: 9076
diff changeset
159
071f9da012fb commit https://github.com/vim/vim/commit/06d2d38ab7564e1f784b1058a4ef4580cd6d1810
Christian Brabandt <cb@256bit.org>
parents: 9076
diff changeset
160 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
161 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
162 multi-threading.
071f9da012fb commit https://github.com/vim/vim/commit/06d2d38ab7564e1f784b1058a4ef4580cd6d1810
Christian Brabandt <cb@256bit.org>
parents: 9076
diff changeset
163
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
164 *close_cb*
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
165 "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
166 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
167 func MyCloseHandler(channel)
9097
071f9da012fb commit https://github.com/vim/vim/commit/06d2d38ab7564e1f784b1058a4ef4580cd6d1810
Christian Brabandt <cb@256bit.org>
parents: 9076
diff changeset
168 < 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
169 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
170 be passed to the callbacks. However, if a callback causes Vim
c002c4899529 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 16553
diff changeset
171 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
172 in the callback. The plugin must handle this somehow, it can
c002c4899529 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 16553
diff changeset
173 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
174 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
175 try/catch block: >
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
176 try
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
177 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
178 catch
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
179 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
180 endtry
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
181 try
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
182 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
183 catch
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
184 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
185 endtry
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
186 < *channel-drop*
10426
acfc83aca8ee commit https://github.com/vim/vim/commit/958dc6923d341390531888058495569d73c356c3
Christian Brabandt <cb@256bit.org>
parents: 10422
diff changeset
187 "drop" Specifies when to drop messages:
acfc83aca8ee commit https://github.com/vim/vim/commit/958dc6923d341390531888058495569d73c356c3
Christian Brabandt <cb@256bit.org>
parents: 10422
diff changeset
188 "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
189 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
190 "never" All messages will be kept.
acfc83aca8ee commit https://github.com/vim/vim/commit/958dc6923d341390531888058495569d73c356c3
Christian Brabandt <cb@256bit.org>
parents: 10422
diff changeset
191
14675
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
192 *channel-noblock*
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
193 "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
194
9097
071f9da012fb commit https://github.com/vim/vim/commit/06d2d38ab7564e1f784b1058a4ef4580cd6d1810
Christian Brabandt <cb@256bit.org>
parents: 9076
diff changeset
195 *waittime*
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
196 "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
197 milliseconds. A negative number waits forever.
f16bfe02cef1 commit https://github.com/vim/vim/commit/f391327adbbffb11180cf6038a92af1ed144e907
Christian Brabandt <cb@256bit.org>
parents: 8178
diff changeset
198
f16bfe02cef1 commit https://github.com/vim/vim/commit/f391327adbbffb11180cf6038a92af1ed144e907
Christian Brabandt <cb@256bit.org>
parents: 8178
diff changeset
199 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
200 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
201 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
202 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
203 msec at least.
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
204 *channel-timeout*
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
205 "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
206 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
207 seconds).
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
208
7967
45ea5ebf3a98 commit https://github.com/vim/vim/commit/595e64e259faefb330866852e1b9f6168544572a
Christian Brabandt <cb@256bit.org>
parents: 7957
diff changeset
209 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
210 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
211
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
212 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
213 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
214 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
215
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
216 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
217 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
218 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
219
8392
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
220 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
221 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
222 `:redraw`.
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
223
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
224 The timeout can be changed: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
225 call ch_setoptions(channel, {'timeout': msec})
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
226 <
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
227 *channel-close* *E906*
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
228 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
229 call ch_close(channel)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
230 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
231 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
232 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
233 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
234
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
235 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
236 - 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
237 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
238 - 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
239 may still reference the channel.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
240 - 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
241
7992
78106b0f2c56 commit https://github.com/vim/vim/commit/cbebd4879cc78e670d79b2c57dc33d7b911c962a
Christian Brabandt <cb@256bit.org>
parents: 7967
diff changeset
242 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
243 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
244 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
245 *E898* *E901* *E902*
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
246
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
247 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
248 *E630* *E631*
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
249
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
250 ==============================================================================
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
251 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
252
8094
18a3f0f05244 commit https://github.com/vim/vim/commit/910b8aac5dc4693c4508b7acd2cef0bbfac04242
Christian Brabandt <cb@256bit.org>
parents: 8061
diff changeset
253 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
254 let response = ch_evalexpr(channel, {expr})
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
255 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
256
8094
18a3f0f05244 commit https://github.com/vim/vim/commit/910b8aac5dc4693c4508b7acd2cef0bbfac04242
Christian Brabandt <cb@256bit.org>
parents: 8061
diff changeset
257 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
258 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
259
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
260 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
261 handle the response: >
8285
e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f
Christian Brabandt <cb@256bit.org>
parents: 8267
diff changeset
262 call ch_sendexpr(channel, {expr})
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
263
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
264 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
265 asynchronously: >
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
266 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
267
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
268 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
269 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
270 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
271 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
272
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
273 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
274 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
275 [12,"hello"] ~
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
276
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
277 The format of the JSON sent is:
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
278 [{number},{expr}]
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
279
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
280 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
281 (if any):
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
282
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
283 [{number},{response}]
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
284
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
285 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
286 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
287
9969
176e34b0d678 commit https://github.com/vim/vim/commit/f1f0792e55e72cdc7c833b30f565a9b02f18bb1e
Christian Brabandt <cb@256bit.org>
parents: 9860
diff changeset
288 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
289 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
290 splitidx = read_text.find('\n')
176e34b0d678 commit https://github.com/vim/vim/commit/f1f0792e55e72cdc7c833b30f565a9b02f18bb1e
Christian Brabandt <cb@256bit.org>
parents: 9860
diff changeset
291 message = read_text[:splitidx]
176e34b0d678 commit https://github.com/vim/vim/commit/f1f0792e55e72cdc7c833b30f565a9b02f18bb1e
Christian Brabandt <cb@256bit.org>
parents: 9860
diff changeset
292 rest = read_text[splitidx + 1:]
176e34b0d678 commit https://github.com/vim/vim/commit/f1f0792e55e72cdc7c833b30f565a9b02f18bb1e
Christian Brabandt <cb@256bit.org>
parents: 9860
diff changeset
293
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
294 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
295 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
296 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
297
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
298 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
299 message, it must use the number zero:
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
300 [0,{response}]
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
301
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
302 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
303 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
304
8285
e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f
Christian Brabandt <cb@256bit.org>
parents: 8267
diff changeset
305 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
306 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
307 decoding.
7992
78106b0f2c56 commit https://github.com/vim/vim/commit/cbebd4879cc78e670d79b2c57dc33d7b911c962a
Christian Brabandt <cb@256bit.org>
parents: 7967
diff changeset
308
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
309 ==============================================================================
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
310 5. Channel commands *channel-commands*
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
311
8094
18a3f0f05244 commit https://github.com/vim/vim/commit/910b8aac5dc4693c4508b7acd2cef0bbfac04242
Christian Brabandt <cb@256bit.org>
parents: 8061
diff changeset
312 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
313 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
314
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
315 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
316 ["redraw", {forced}]
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
317 ["ex", {Ex command}]
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
318 ["normal", {Normal mode command}]
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
319 ["expr", {expression}, {number}]
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
320 ["expr", {expression}]
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
321 ["call", {func name}, {argument list}, {number}]
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
322 ["call", {func name}, {argument list}]
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
323
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
324 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
325 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
326 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
327 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
328 ["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
329
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
330 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
331 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
332 higher.
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
333
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
334
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
335 Command "redraw" ~
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
336
16086
bd7461db24b3 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 14675
diff changeset
337 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
338 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
339 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
340 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
341
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
342 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
343 ["redraw", ""] ~
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
344 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
345 ["redraw", "force"] ~
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
346
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 Command "ex" ~
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
349
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
350 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
351 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
352 ["ex","call myscript#MyFunc(arg)"]
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
353
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
354 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
355
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
356 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
357 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
358
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
359
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
360 Command "normal" ~
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
361
7924
00d64eb49ce1 commit https://github.com/vim/vim/commit/681baaf4a4c81418693dcafb81421a8614832e91
Christian Brabandt <cb@256bit.org>
parents: 7864
diff changeset
362 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
363 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
364 ["normal" "zO"]
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
365
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
366
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
367 Command "expr" with response ~
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
368
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
369 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
370 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
371 ["expr","line('$')", -2] ~
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
372
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
373 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
374 [-2, "last line"] ~
f5da459c5698 commit https://github.com/vim/vim/commit/e0fa3742ead676a3074a10edadbc955e1a89153d
Christian Brabandt <cb@256bit.org>
parents: 8094
diff changeset
375 The format is:
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
376 [{number}, {result}]
8267
108d30ed34ba commit https://github.com/vim/vim/commit/187db50d0499aecf4cfd42fb4db0a1bebf61c8cd
Christian Brabandt <cb@256bit.org>
parents: 8246
diff changeset
377
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
378 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
379 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
380 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
381
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
382 {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
383 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
384 "ERROR".
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
385
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
386
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
387 Command "expr" without a response ~
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
388
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
389 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
390 Example:
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
391 ["expr","setline('$', ['one', 'two', 'three'])"] ~
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
392 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
393
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 Command "call" ~
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
396
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
397 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
398 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
399 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
400 concatenating them. Example:
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
401 ["call", "line", ["$"], -2] ~
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
402
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
403 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
404 ["call", "setline", ["$", ["one", "two", "three"]]] ~
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
405
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
406 ==============================================================================
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
407 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
408
10385
368468ef35cf commit https://github.com/vim/vim/commit/c0514bf4777a1d55f5785b3887c5686fd0bbe870
Christian Brabandt <cb@256bit.org>
parents: 10319
diff changeset
409 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
410 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
411
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
412 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
413 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
414 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
415 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
416
8094
18a3f0f05244 commit https://github.com/vim/vim/commit/910b8aac5dc4693c4508b7acd2cef0bbfac04242
Christian Brabandt <cb@256bit.org>
parents: 8061
diff changeset
417 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
418 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
419 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
420 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
421 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
422
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
423 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
424 call ch_sendraw(channel, {string})
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
425 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
426 it.
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
427
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
428 *channel-onetime-callback*
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
429 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
430 asynchronously: >
8285
e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f
Christian Brabandt <cb@256bit.org>
parents: 8267
diff changeset
431 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
432
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
433 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
434 |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
435
8285
e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f
Christian Brabandt <cb@256bit.org>
parents: 8267
diff changeset
436 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
437
10004
8061455d9179 commit https://github.com/vim/vim/commit/818078ddfbb8cc2546f697c5675a251d095722ec
Christian Brabandt <cb@256bit.org>
parents: 9969
diff changeset
438 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
439 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
440
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
441 ==============================================================================
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
442 7. More channel functions *channel-more*
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
443
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
444 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
445 are:
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
446 "fail" Failed to open the channel.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
447 "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
448 "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
449 "closed" The channel was closed.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
450
8267
108d30ed34ba commit https://github.com/vim/vim/commit/187db50d0499aecf4cfd42fb4db0a1bebf61c8cd
Christian Brabandt <cb@256bit.org>
parents: 8246
diff changeset
451 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
452
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
453 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
454 let output = ch_read(channel)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
455 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
456 message that is available: >
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
457 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
458 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
459 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
460 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
461
12043
2796a2c9fc17 patch 8.0.0902: cannot specify directory or environment for a job
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
462 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
463 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
464
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
465 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
466 let output = ch_readraw(channel)
29274
d314efe6447a Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 29193
diff changeset
467 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
468 let output = ch_readraw(channel, {"part": "err"})
29274
d314efe6447a Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 29193
diff changeset
469 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
470 for each call.
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
471
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
472 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
473 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
474 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
475 {"timeout": 123} ~
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
476 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
477 {"part": "err"} ~
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
478 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
479 {"id": 99} ~
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
480 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
481 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
482
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
483 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
484 where a message ends.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
485 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
486 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
487 This includes any sequence number.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
488
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
489 ==============================================================================
17571
2704c4e3e20a Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 17456
diff changeset
490 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
491
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
492 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
493 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
494 {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
495
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
496 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
497 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
498
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
499 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
500 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
501
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
502 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
503 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
504
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
505 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
506 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
507 {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
508 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
509
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
510 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
511 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
512
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
513 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
514 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
515 {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
516 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
517
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
518 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
519 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
520
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
521
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
522 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
523 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
524 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
525 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
526 {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
527 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
528 *E917*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
529 {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
530 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
531 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
532
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
533 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
534 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
535 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
536 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
537
18053
8ac85adee561 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 17831
diff changeset
538 Note that while waiting for the response, Vim handles other
8ac85adee561 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 17831
diff changeset
539 messages. You need to make sure this doesn't cause trouble.
8ac85adee561 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 17831
diff changeset
540
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
541 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
542 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
543
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
544
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
545 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
546 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
547 {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
548
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
549 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
550 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
551 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
552 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
553 is removed.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
554 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
555 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
556 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
557 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
558
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
559 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
560 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
561
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
562 ch_getbufnr({handle}, {what}) *ch_getbufnr()*
25619
29ec2c198c8d Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 25252
diff changeset
563 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
564 {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
565 {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
566 socket output.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
567 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
568
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
569 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
570 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
571
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
572 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
573 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
574 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
575 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
576
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
577 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
578 GetChannel()->ch_getjob()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
579
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
580
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
581 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
582 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
583 items are:
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
584 "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
585 "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
586 ch_status()
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
587 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
588 "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
589 "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
590 "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
591 "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
592 "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
593 "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
594 "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
595
28379
6dd88e45d47d Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 28317
diff changeset
596 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
597 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
598
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
599 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
600 "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
601 "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
602 "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
603 "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
604 "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
605 "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
606 "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
607 "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
608 "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
609 "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
610 "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
611 "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
612
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
613 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
614 GetChannel()->ch_info()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
615
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
616
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
617 ch_log({msg} [, {handle}]) *ch_log()*
25619
29ec2c198c8d Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 25252
diff changeset
618 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
619 with |ch_logfile()|.
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
620 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
621 message.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
622 {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
623 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
624
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
625 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
626 '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
627
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
628
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
629 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
630 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
631 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
632
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
633 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
634 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
635 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
636 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
637 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
638
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
639 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
640 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
641 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
642
22077
335365fcbb60 patch 8.2.1588: cannot read back the prompt of a prompt buffer
Bram Moolenaar <Bram@vim.org>
parents: 21250
diff changeset
643 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
644 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
645 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
646 <
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
647 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
648 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
649 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
650 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
651
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
652 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
653 '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
654
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
655
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
656 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
657 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
658 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
659
28317
d32dc906dd2c patch 8.2.4684: cannot open a channel on a Unix domain socket
Bram Moolenaar <Bram@vim.org>
parents: 28246
diff changeset
660 {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
661 accepted forms.
20003
e373843e2980 patch 8.2.0557: no IPv6 support for channels
Bram Moolenaar <Bram@vim.org>
parents: 18879
diff changeset
662
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
663 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
664 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
665
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
666 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
667 GetAddress()->ch_open()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
668
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
669
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
670 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
671 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
672 {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
673 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
674 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
675 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
676
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
677 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
678 GetChannel()->ch_read()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
679
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
680
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
681 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
682 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
683 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
684
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
685 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
686 GetChannel()->ch_readblob()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
687
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
688
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
689 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
690 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
691 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
692 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
693 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
694
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
695 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
696 GetChannel()->ch_readraw()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
697
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
698
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
699 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
700 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
701 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
702 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
703 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
704 {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
705 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
706
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
707 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
708 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
709 {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
710 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
711 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
712 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
713
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 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
715 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
716
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
717 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
718 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
719
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
720
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
721 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
722 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
723 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
724 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
725 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
726 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
727 is removed.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
728 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
729
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
730 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
731 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
732
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
733
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
734 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
735 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
736 "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
737 "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
738 "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
739 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
740 {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
741
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
742 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
743 lost.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
744
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
745 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
746 "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
747
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
748 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
749 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
750
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
751
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
752 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
753 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
754 "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
755 "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
756 "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
757 "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
758 {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
759 "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
760 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
761
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
762 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
763 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
764 "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
765 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
766 <
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
767 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
768 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
769
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
770 ==============================================================================
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
771 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
772
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
773 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
774 let job = job_start(command, {options})
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
775
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
776 You can get the channel with: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
777 let channel = job_getchannel(job)
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
778
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
779 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
780 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
781 been received and not parsed correctly.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
782
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
783 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
784 a handler for stdout: >
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
785 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
786 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
787 it like this: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
788 func MyHandler(channel, msg)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
789
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
790 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
791 |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
792
12045
444ad56c0cac Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12043
diff changeset
793 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
794 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
795 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
796 for a short while before it exits.
444ad56c0cac Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12043
diff changeset
797
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
798 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
799 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
800 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
801 \ "err_cb": "ErrHandler"})
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
802
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
803 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
804 "callback" option: >
18831
6848b809a26e Runtime file updates.
Bram Moolenaar <Bram@vim.org>
parents: 18053
diff changeset
805 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
806
11518
63b0b7b79b25 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 10498
diff changeset
807 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
808 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
809 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
810 use a timer to call it after the job has started.
63b0b7b79b25 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 10498
diff changeset
811
8285
e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f
Christian Brabandt <cb@256bit.org>
parents: 8267
diff changeset
812 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
813 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
814
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
815 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
816 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
817 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
818 \ {'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
819 sbuf dummy
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
820
8440
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents: 8392
diff changeset
821
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents: 8392
diff changeset
822 Job input from a buffer ~
10004
8061455d9179 commit https://github.com/vim/vim/commit/818078ddfbb8cc2546f697c5675a251d095722ec
Christian Brabandt <cb@256bit.org>
parents: 9969
diff changeset
823 *in_io-buffer*
8392
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
824 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
825 let job = job_start({command},
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
826 \ {'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
827 <
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
828 *E915* *E918*
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
829 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
830 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
831
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
832 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
833 and "in_bot" options.
8392
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
834
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
835 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
836 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
837 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
838 Enter.
10054
d4b7232fc63a commit https://github.com/vim/vim/commit/0874a83e9be1b39fdb217f02b427bf1d6133a4d8
Christian Brabandt <cb@256bit.org>
parents: 10051
diff changeset
839 *channel-close-in*
d4b7232fc63a commit https://github.com/vim/vim/commit/0874a83e9be1b39fdb217f02b427bf1d6133a4d8
Christian Brabandt <cb@256bit.org>
parents: 10051
diff changeset
840 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
841 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
842 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
843
9464
be72f4201a1d commit https://github.com/vim/vim/commit/063b9d15abea041a5bfff3ffc4e219e26fd1d4fa
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
844 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
845 as NL bytes).
be72f4201a1d commit https://github.com/vim/vim/commit/063b9d15abea041a5bfff3ffc4e219e26fd1d4fa
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
846
9041
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
847
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
848 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
849 *read-in-close-cb*
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
850 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
851 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
852
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
853 func! CloseHandler(channel)
10244
876fbdd84e52 commit https://github.com/vim/vim/commit/2ec618c9feac4573b154510236ad8121c77d0eca
Christian Brabandt <cb@256bit.org>
parents: 10218
diff changeset
854 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
855 echomsg ch_read(a:channel)
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
856 endwhile
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
857 endfunc
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
858 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
859
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
860 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
861
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
862 ==============================================================================
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
863 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
864
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
865 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
866 let job = job_start(command,
10449
222b1432814e commit https://github.com/vim/vim/commit/5162822914372fc916a93f85848c0c82209e7cec
Christian Brabandt <cb@256bit.org>
parents: 10426
diff changeset
867 \ {"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
868
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
869 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
870
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
871 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
872 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
873 avoid it getting stuck.
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 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
876
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
877 *job-start-if-needed*
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
878 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
879 like this: >
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
880 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
881 if ch_status(channel) == "fail"
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
882 let job = job_start(command)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
883 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
884 endif
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
885
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
886 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
887 available.
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
888
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
889 ==============================================================================
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
890 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
891
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
892 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
893 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
894 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
895 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
896 <
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
897 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
898 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
899
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
900 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
901 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
902 "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
903 "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
904 "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
905 "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
906 "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
907 "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
908 "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
909 "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
910 "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
911
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
912 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
913 "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
914 (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
915 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
916
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
917 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
918 "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
919 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
920 See 'termwintype'.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
921
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
922 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
923
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
924 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
925 GetJob()->job_info()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
926
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
927
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
928 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
929 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
930 "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
931 "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
932
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
933 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
934 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
935
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
936
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
937 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
938 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
939 |:!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
940 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
941
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
942 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
943 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
944 invoked.
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 {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
947 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
948 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
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 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
951 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
952 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
953
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
954 On MS-Windows, job_start() makes a GUI application hidden. If
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
955 want to show it, Use |:!start| instead.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
956
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
957 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
958 '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
959 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
960 < Or: >
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
961 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
962 < 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
963 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
964 shell command.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
965
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
966 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
967 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
968
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
969 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
970 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
971 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
972 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
973 <
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
974 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
975 |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
976
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
977 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
978 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
979 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
980 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
981 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
982 < use: >
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
983 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
984 < 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
985 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
986 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
987 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
988 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
989 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
990 <
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
991 {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
992 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
993
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
994 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
995 BuildCommand()->job_start()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
996
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
997
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
998 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
999 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
1000 "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
1001 "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
1002 "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
1003
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1004 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
1005 "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
1006 detected.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1007
22723
5b7ea82bc18f Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 22077
diff changeset
1008 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
1009 never assigned to, passing that variable to job_status()
5b7ea82bc18f Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 22077
diff changeset
1010 returns "fail".
5b7ea82bc18f Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 22077
diff changeset
1011
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1012 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
1013 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
1014
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1015 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
1016
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
1017 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
1018 GetJob()->job_status()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
1019
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1020
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1021 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
1022 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
1023
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1024 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
1025 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
1026 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
1027 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
1028 affected.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1029
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1030 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
1031 "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
1032 "hup" SIGHUP
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1033 "quit" SIGQUIT
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1034 "int" SIGINT
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1035 "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
1036 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
1037
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1038 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
1039 "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
1040 "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
1041 "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
1042 "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
1043 "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
1044 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
1045
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1046 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
1047 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
1048 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
1049
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1050 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
1051 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
1052 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
1053 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
1054 |job_status()|.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1055
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1056 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
1057 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
1058 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
1059
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1060 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
1061 the channel.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1062
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
1063 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
1064 GetJob()->job_stop()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
1065
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1066
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1067 ==============================================================================
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1068 12. Job options *job-options*
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1069
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1070 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
1071 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
1072 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
1073 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
1074 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
1075
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1076 *in_mode* *out_mode* *err_mode*
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1077 "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
1078 "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
1079 "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
1080 See |channel-mode| for the values.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1081
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1082 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
1083 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
1084 specific mode later.
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 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
1087 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
1088
14675
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
1089 *job-noblock*
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
1090 "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
1091 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
1092 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
1093 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
1094 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
1095 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
1096 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
1097 let options['noblock'] = 1
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
1098 endif
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
1099 <
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
1100 *job-callback*
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
1101 "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
1102 channel.
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1103 *job-out_cb* *out_cb*
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1104 "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
1105 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
1106 "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
1107 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
1108
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1109 *job-err_cb* *err_cb*
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1110 "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
1111 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
1112 "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
1113 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
1114 *job-close_cb*
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1115 "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
1116 "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
1117 *job-drop*
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1118 "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
1119 |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
1120 exit_cb is not considered.
10498
883396809b45 commit https://github.com/vim/vim/commit/bc2eada5424bff06f7eb77c032ecc067da52b846
Christian Brabandt <cb@256bit.org>
parents: 10449
diff changeset
1121 *job-exit_cb*
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1122 "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
1123 job and the exit status.
10319
169a62d5bcb9 commit https://github.com/vim/vim/commit/b4ada79aa7d0d1e5da3a659b1a203d7cae9f7f59
Christian Brabandt <cb@256bit.org>
parents: 10244
diff changeset
1124 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
1125 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
1126 |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
1127 handler.
9097
071f9da012fb commit https://github.com/vim/vim/commit/06d2d38ab7564e1f784b1058a4ef4580cd6d1810
Christian Brabandt <cb@256bit.org>
parents: 9076
diff changeset
1128 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
1129 called after the process ends.
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1130 *job-timeout*
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1131 "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
1132 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
1133 default is 2000 (2 seconds).
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1134 *out_timeout* *err_timeout*
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1135 "out_timeout": time Timeout for stdout. Only when using pipes.
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1136 "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
1137 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
1138 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
1139 part specific mode later.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1140
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
1141 *job-stoponexit*
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
1142 "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
1143 |job_stop()| for possible values.
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
1144 "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
1145 The default is "term".
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
1146
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1147 *job-term*
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1148 "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
1149 stdin/stdout/stderr to it. Similar to using
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1150 `:terminal`.
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1151 NOTE: Not implemented yet!
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1152
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1153 "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
1154 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
1155 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
1156 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
1157 cause I/O errors.
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1158 Existing callbacks and other settings remain.
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1159
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1160 "pty": 1 Use a pty (pseudo-tty) instead of a pipe when
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1161 possible. This is most useful in combination with a
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1162 terminal window, see |terminal|.
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1163 {only on Unix and Unix-like systems}
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1164
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1165 *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
1166 "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
1167 "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
1168 "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
1169 "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
1170 "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
1171 "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
1172 "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
1173 "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
1174
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1175 *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
1176 "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
1177 "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
1178 "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
1179 "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
1180 "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
1181 "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
1182 "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
1183 (see below)
10147
65afd399ffa7 commit https://github.com/vim/vim/commit/169ebb080454357279ad5ad21ac532deaec605e8
Christian Brabandt <cb@256bit.org>
parents: 10054
diff changeset
1184 "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
1185 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
1186
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1187 *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
1188 "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
1189 "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
1190 "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
1191 "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
1192 "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
1193 "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
1194 "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
1195 "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
1196 (see below)
10147
65afd399ffa7 commit https://github.com/vim/vim/commit/169ebb080454357279ad5ad21ac532deaec605e8
Christian Brabandt <cb@256bit.org>
parents: 10054
diff changeset
1197 "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
1198 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
1199
8795
aba2d0a01290 commit https://github.com/vim/vim/commit/7db8f6f4f85e5d0526d23107b2a5e2334dc23354
Christian Brabandt <cb@256bit.org>
parents: 8748
diff changeset
1200 "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
1201 will block
aba2d0a01290 commit https://github.com/vim/vim/commit/7db8f6f4f85e5d0526d23107b2a5e2334dc23354
Christian Brabandt <cb@256bit.org>
parents: 8748
diff changeset
1202
12043
2796a2c9fc17 patch 8.0.0902: cannot specify directory or environment for a job
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
1203 "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
1204 "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
1205 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
1206
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1207
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1208 Writing to a buffer ~
10004
8061455d9179 commit https://github.com/vim/vim/commit/818078ddfbb8cc2546f697c5675a251d095722ec
Christian Brabandt <cb@256bit.org>
parents: 9969
diff changeset
1209 *out_io-buffer*
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1210 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
1211 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
1212
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents: 8392
diff changeset
1213 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
1214 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
1215 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
1216
8392
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
1217 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
1218 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
1219 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
1220
9227
ecb621205ed1 commit https://github.com/vim/vim/commit/82af8710bf8d1caeeceafb1370a052cb7d92f076
Christian Brabandt <cb@256bit.org>
parents: 9147
diff changeset
1221 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
1222 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
1223 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
1224 "somename" it will use that buffer.
ecb621205ed1 commit https://github.com/vim/vim/commit/82af8710bf8d1caeeceafb1370a052cb7d92f076
Christian Brabandt <cb@256bit.org>
parents: 9147
diff changeset
1225
ecb621205ed1 commit https://github.com/vim/vim/commit/82af8710bf8d1caeeceafb1370a052cb7d92f076
Christian Brabandt <cb@256bit.org>
parents: 9147
diff changeset
1226 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
1227 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
1228 buffer number.
8291
ac0c43e7af20 commit https://github.com/vim/vim/commit/c7f0ebc6d1e1cdaed816b88a0d6092c5ace615eb
Christian Brabandt <cb@256bit.org>
parents: 8285
diff changeset
1229
ac0c43e7af20 commit https://github.com/vim/vim/commit/c7f0ebc6d1e1cdaed816b88a0d6092c5ace615eb
Christian Brabandt <cb@256bit.org>
parents: 8285
diff changeset
1230 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
1231 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
1232 *out_modifiable* *err_modifiable*
65afd399ffa7 commit https://github.com/vim/vim/commit/169ebb080454357279ad5ad21ac532deaec605e8
Christian Brabandt <cb@256bit.org>
parents: 10054
diff changeset
1233 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
1234 '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
1235 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
1236 change the buffer.
65afd399ffa7 commit https://github.com/vim/vim/commit/169ebb080454357279ad5ad21ac532deaec605e8
Christian Brabandt <cb@256bit.org>
parents: 10054
diff changeset
1237 *out_msg* *err_msg*
65afd399ffa7 commit https://github.com/vim/vim/commit/169ebb080454357279ad5ad21ac532deaec605e8
Christian Brabandt <cb@256bit.org>
parents: 10054
diff changeset
1238 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
1239 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
1240 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
1241
9147
053bc64433ec commit https://github.com/vim/vim/commit/9f5842e63fc63d438cbffcec503e072a06f74dc2
Christian Brabandt <cb@256bit.org>
parents: 9116
diff changeset
1242 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
1243 "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
1244 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
1245
8267
108d30ed34ba commit https://github.com/vim/vim/commit/187db50d0499aecf4cfd42fb4db0a1bebf61c8cd
Christian Brabandt <cb@256bit.org>
parents: 8246
diff changeset
1246 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
1247 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
1248 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
1249
9464
be72f4201a1d commit https://github.com/vim/vim/commit/063b9d15abea041a5bfff3ffc4e219e26fd1d4fa
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
1250 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
1251 stores these as NL bytes).
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1252
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1253
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1254 Writing to a file ~
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1255 *E920*
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1256 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
1257 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
1258
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1259 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
1260
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1261 ==============================================================================
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1262 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
1263
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1264 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
1265 echo job_status(job)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1266
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1267 To make a job stop running: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1268 job_stop(job)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1269
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1270 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
1271 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
1272 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
1273 job_stop(job, "kill")
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1274
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1275 For more options see |job_stop()|.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
1276
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
1277 ==============================================================================
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1278 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
1279
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
1280 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
1281 - 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
1282 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
1283 - 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
1284 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
1285 See |terminal-window|.
20753
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1286 - 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
1287 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
1288
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 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
1290 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
1291
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 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
1293 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
1294 |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
1295 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
1296 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
1297
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 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
1299 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
1300 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
1301 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
1302
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 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
1304 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
1305 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
1306
22077
335365fcbb60 patch 8.2.1588: cannot read back the prompt of a prompt buffer
Bram Moolenaar <Bram@vim.org>
parents: 21250
diff changeset
1307 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
1308 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
1309 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
1310
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
1311 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
1312 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
1313
14123
583bf95b6c84 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14019
diff changeset
1314 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
1315 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
1316 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
1317 coming back to the prompt window Insert mode will be restored.
583bf95b6c84 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14019
diff changeset
1318
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
1319 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
1320 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
1321 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
1322
20753
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1323 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
1324 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
1325 prompt. >
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1326
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1327 " Create a channel log so we can see what happens.
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1328 call ch_logfile('logfile', 'w')
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1329
28010
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1330 " Function handling a line of text that has been typed.
20753
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1331 func TextEntered(text)
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1332 " Send the text to a shell with Enter appended.
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1333 call ch_sendraw(g:shell_job, a:text .. "\n")
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1334 endfunc
22723
5b7ea82bc18f Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 22077
diff changeset
1335
28010
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1336 " 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
1337 func GotOutput(channel, msg)
27903
d19b7aee1925 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 26438
diff changeset
1338 call append(line("$") - 1, "- " .. a:msg)
20753
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1339 endfunc
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1340
28010
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1341 " Function handling the shell exits: close the window.
20753
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1342 func JobExit(job, status)
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1343 quit!
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1344 endfunc
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1345
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1346 " Start a shell in the background.
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1347 let shell_job = job_start(["/bin/sh"], #{
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1348 \ out_cb: function('GotOutput'),
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1349 \ err_cb: function('GotOutput'),
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1350 \ exit_cb: function('JobExit'),
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1351 \ })
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1352
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1353 new
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1354 set buftype=prompt
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1355 let buf = bufnr('')
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1356 call prompt_setcallback(buf, function("TextEntered"))
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1357 eval prompt_setprompt(buf, "shell command: ")
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1358
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1359 " start accepting shell commands
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1360 startinsert
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1361 <
28010
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1362 The same in |Vim9| script: >
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1363
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1364 vim9script
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1365
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1366 # Create a channel log so we can see what happens.
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1367 ch_logfile('logfile', 'w')
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1368
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1369 var shell_job: job
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1370
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1371 # Function handling a line of text that has been typed.
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1372 def TextEntered(text: string)
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1373 # Send the text to a shell with Enter appended.
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1374 ch_sendraw(shell_job, text .. "\n")
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1375 enddef
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1376
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1377 # Function handling output from the shell: Add it above the prompt.
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1378 def GotOutput(channel: channel, msg: string)
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1379 append(line("$") - 1, "- " .. msg)
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1380 enddef
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1381
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1382 # Function handling the shell exits: close the window.
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1383 def JobExit(job: job, status: number)
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1384 quit!
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1385 enddef
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1386
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1387 # Start a shell in the background.
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1388 shell_job = job_start(["/bin/sh"], {
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1389 out_cb: GotOutput,
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1390 err_cb: GotOutput,
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1391 exit_cb: JobExit,
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1392 })
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1393
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1394 new
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1395 set buftype=prompt
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1396 var buf = bufnr('')
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1397 prompt_setcallback(buf, TextEntered)
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1398 prompt_setprompt(buf, "shell command: ")
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1399
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1400 # start accepting shell commands
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1401 startinsert
20753
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1402
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1403 ==============================================================================
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
1404 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
1405
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1406 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
1407
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1408 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
1409
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1410 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
1411 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
1412
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1413 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
1414
28473
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1415 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
1416 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
1417 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
1418 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
1419
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1420 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
1421 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
1422 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
1423 |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
1424 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
1425 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
1426 |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
1427 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
1428
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1429 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
1430 {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
1431
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1432 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
1433
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1434 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
1435 '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
1436
28473
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1437 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
1438 let opts = {}
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1439 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
1440 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
1441 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
1442 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
1443 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
1444 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
1445 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
1446
28511
d7ca583e5772 patch 8.2.4780: parsing an LSP message fails when it is split
Bram Moolenaar <Bram@vim.org>
parents: 28473
diff changeset
1447 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
1448 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
1449 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
1450 "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
1451
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
1452 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
1453 |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
1454 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
1455 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
1456 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
1457
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1458 let req = {}
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1459 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
1460 let req.params = {}
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1461 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
1462 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
1463 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
1464 if defs->empty()
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1465 ... <handle failure>
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1466 endif
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1467
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1468 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
1469 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
1470 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
1471 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
1472 request.
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1473
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1474 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
1475 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
1476 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
1477 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
1478 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
1479 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
1480
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1481 let req = {}
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1482 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
1483 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
1484 let req.params = {}
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1485 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
1486 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
1487 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
1488
28473
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1489 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
1490 |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
1491 |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
1492 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
1493
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
1494 " 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
1495 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
1496 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
1497 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
1498 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
1499 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
1500 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
1501 " 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
1502 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
1503 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
1504 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
1505 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
1506
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1507 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
1508 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
1509 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
1510
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1511 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
1512
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1513 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
1514 |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
1515 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
1516
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1517 let resp = {}
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1518 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
1519 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
1520 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
1521
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1522 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
1523 |channel-callback| function.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
1524
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
1525 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
1526 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
1527
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
1528 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
1529 "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
1530
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 "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
1533 "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
1534 "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
1535 "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
1536 }
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
29193
1e9e9d89f0ee Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 29087
diff changeset
1538 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
1539 "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
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 {
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
1542 "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
1543 "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
1544 "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
1545 "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
1546 }
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
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 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
1549 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
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 "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
1553 "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
1554 "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
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
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 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
1558 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
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 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
1561 "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
1562
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
1563 {
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
1564 "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
1565 "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
1566 "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
1567 "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
1568 }
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
1569
29193
1e9e9d89f0ee Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 29087
diff changeset
1570 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
1571 "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
1572
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
1573 {
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
1574 "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
1575 "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
1576 "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
1577 "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
1578 }
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
1579
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
1580 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
1581 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
1582
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
1583 {
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
1584 "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
1585 "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
1586 "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
1587 }
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
1588
14421
2f7e67dd088c Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14123
diff changeset
1589 vim:tw=78:ts=8:noet:ft=help:norl: