Mercurial > vim

annotate runtime/doc/channel.txt @ 28473:1c112473a54f v8.2.4761

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
patch 8.2.4761: documentation for using LSP messages is incomplete Commit: https://github.com/vim/vim/commit/e0805b849ce60f65149903b63584d49bf81f975e Author: Yegappan Lakshmanan <yegappan@yahoo.com> Date: Sat Apr 16 15:18:23 2022 +0100 patch 8.2.4761: documentation for using LSP messages is incomplete Problem: Documentation for using LSP messages is incomplete. Solution: Update the documentation. (Yegappan Lakshmanan, closes https://github.com/vim/vim/issues/10206)
author Bram Moolenaar <Bram@vim.org>
date Sat, 16 Apr 2022 16:30:03 +0200
parents 3beb14b12bbd
children d7ca583e5772
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
28379
6dd88e45d47d Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 28317
diff changeset
1 *channel.txt* For Vim version 8.2. Last change: 2022 Apr 05
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)
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
467 To read the error output: >
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"})
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
469
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
470 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
471 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
472 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
473 {"timeout": 123} ~
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
474 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
475 {"part": "err"} ~
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
476 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
477 {"id": 99} ~
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
478 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
479 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
480
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
481 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
482 where a message ends.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
483 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
484 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
485 This includes any sequence number.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
486
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
487 ==============================================================================
17571
2704c4e3e20a Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 17456
diff changeset
488 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
489
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
490 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
491 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
492 {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
493
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
494 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
495 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
496
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
497 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
498 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
499
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
500 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
501 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
502
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
503 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
504 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
505 {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
506 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
507
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
508 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
509 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
510
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
511 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
512 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
513 {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
514 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
515
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
516 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
517 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
518
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
519
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
520 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
521 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
522 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
523 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
524 {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
525 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
526 *E917*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
527 {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
528 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
529 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
530
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
531 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
532 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
533 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
534 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
535
18053
8ac85adee561 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 17831
diff changeset
536 Note that while waiting for the response, Vim handles other
8ac85adee561 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 17831
diff changeset
537 messages. You need to make sure this doesn't cause trouble.
8ac85adee561 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 17831
diff changeset
538
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
539 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
540 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
541
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
542
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
543 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
544 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
545 {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
546
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
547 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
548 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
549 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
550 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
551 is removed.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
552 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
553 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
554 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
555 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
556
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
557 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
558 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
559
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
560 ch_getbufnr({handle}, {what}) *ch_getbufnr()*
25619
29ec2c198c8d Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 25252
diff changeset
561 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
562 {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
563 {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
564 socket output.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
565 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
566
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
567 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
568 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
569
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
570 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
571 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
572 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
573 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
574
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
575 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
576 GetChannel()->ch_getjob()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
577
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
578
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
579 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
580 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
581 items are:
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
582 "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
583 "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
584 ch_status()
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
585 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
586 "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
587 "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
588 "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
589 "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
590 "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
591 "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
592 "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
593
28379
6dd88e45d47d Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 28317
diff changeset
594 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
595 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
596
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
597 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
598 "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
599 "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
600 "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
601 "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
602 "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
603 "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
604 "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
605 "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
606 "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
607 "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
608 "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
609 "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
610
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
611 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
612 GetChannel()->ch_info()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
613
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
614
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
615 ch_log({msg} [, {handle}]) *ch_log()*
25619
29ec2c198c8d Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 25252
diff changeset
616 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
617 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
618 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
619 message.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
620 {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
621 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
622
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
623 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
624 '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
625
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
626
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
627 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
628 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
629 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
630
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
631 When {mode} is omitted or "a" append to the file.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
632 When {mode} is "w" start with an empty file.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
633
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
634 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
635 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
636 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
637
22077
335365fcbb60 patch 8.2.1588: cannot read back the prompt of a prompt buffer
Bram Moolenaar <Bram@vim.org>
parents: 21250
diff changeset
638 To enable the log very early, to see what is received from a
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
639 terminal during startup, use |--log|: >
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
640 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
641 <
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
642 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
643 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
644 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
645 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
646
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
647 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
648 '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
649
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
650
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
651 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
652 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
653 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
654
28317
d32dc906dd2c patch 8.2.4684: cannot open a channel on a Unix domain socket
Bram Moolenaar <Bram@vim.org>
parents: 28246
diff changeset
655 {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
656 accepted forms.
20003
e373843e2980 patch 8.2.0557: no IPv6 support for channels
Bram Moolenaar <Bram@vim.org>
parents: 18879
diff changeset
657
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
658 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
659 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
660
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
661 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
662 GetAddress()->ch_open()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
663
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
664
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
665 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
666 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
667 {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
668 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
669 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
670 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
671
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
672 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
673 GetChannel()->ch_read()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
674
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
675
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
676 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
677 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
678 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
679
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
680 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
681 GetChannel()->ch_readblob()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
682
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
683
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
684 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
685 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
686 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
687 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
688 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
689
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
690 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
691 GetChannel()->ch_readraw()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
692
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
693
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
694 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
695 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
696 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
697 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
698 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
699 {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
700 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
701
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
702 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
703 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
704 {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
705 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
706 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
707 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
708
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 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
710 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
711
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
712 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
713 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
714
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
715
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
716 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
717 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
718 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
719 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
720 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
721 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
722 is removed.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
723 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
724
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
725 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
726 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
727
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
728
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
729 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
730 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
731 "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
732 "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
733 "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
734 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
735 {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
736
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
737 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
738 lost.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
739
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
740 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
741 "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
742
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
743 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
744 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
745
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
746
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
747 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
748 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
749 "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
750 "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
751 "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
752 "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
753 {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
754 "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
755 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
756
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
757 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
758 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
759 "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
760 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
761 <
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
762 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
763 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
764
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
765 ==============================================================================
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
766 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
767
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
768 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
769 let job = job_start(command, {options})
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
770
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
771 You can get the channel with: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
772 let channel = job_getchannel(job)
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
773
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
774 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
775 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
776 been received and not parsed correctly.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
777
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
778 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
779 a handler for stdout: >
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
780 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
781 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
782 it like this: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
783 func MyHandler(channel, msg)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
784
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
785 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
786 |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
787
12045
444ad56c0cac Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12043
diff changeset
788 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
789 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
790 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
791 for a short while before it exits.
444ad56c0cac Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12043
diff changeset
792
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
793 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
794 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
795 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
796 \ "err_cb": "ErrHandler"})
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
797
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
798 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
799 "callback" option: >
18831
6848b809a26e Runtime file updates.
Bram Moolenaar <Bram@vim.org>
parents: 18053
diff changeset
800 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
801
11518
63b0b7b79b25 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 10498
diff changeset
802 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
803 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
804 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
805 use a timer to call it after the job has started.
63b0b7b79b25 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 10498
diff changeset
806
8285
e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f
Christian Brabandt <cb@256bit.org>
parents: 8267
diff changeset
807 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
808 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
809
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
810 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
811 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
812 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
813 \ {'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
814 sbuf dummy
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
815
8440
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents: 8392
diff changeset
816
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents: 8392
diff changeset
817 Job input from a buffer ~
10004
8061455d9179 commit https://github.com/vim/vim/commit/818078ddfbb8cc2546f697c5675a251d095722ec
Christian Brabandt <cb@256bit.org>
parents: 9969
diff changeset
818 *in_io-buffer*
8392
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
819 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
820 let job = job_start({command},
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
821 \ {'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
822 <
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
823 *E915* *E918*
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
824 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
825 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
826
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
827 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
828 and "in_bot" options.
8392
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
829
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
830 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
831 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
832 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
833 Enter.
10054
d4b7232fc63a commit https://github.com/vim/vim/commit/0874a83e9be1b39fdb217f02b427bf1d6133a4d8
Christian Brabandt <cb@256bit.org>
parents: 10051
diff changeset
834 *channel-close-in*
d4b7232fc63a commit https://github.com/vim/vim/commit/0874a83e9be1b39fdb217f02b427bf1d6133a4d8
Christian Brabandt <cb@256bit.org>
parents: 10051
diff changeset
835 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
836 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
837 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
838
9464
be72f4201a1d commit https://github.com/vim/vim/commit/063b9d15abea041a5bfff3ffc4e219e26fd1d4fa
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
839 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
840 as NL bytes).
be72f4201a1d commit https://github.com/vim/vim/commit/063b9d15abea041a5bfff3ffc4e219e26fd1d4fa
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
841
9041
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
842
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
843 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
844 *read-in-close-cb*
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
845 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
846 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
847
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
848 func! CloseHandler(channel)
10244
876fbdd84e52 commit https://github.com/vim/vim/commit/2ec618c9feac4573b154510236ad8121c77d0eca
Christian Brabandt <cb@256bit.org>
parents: 10218
diff changeset
849 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
850 echomsg ch_read(a:channel)
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
851 endwhile
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
852 endfunc
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
853 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
854
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
855 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
856
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
857 ==============================================================================
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
858 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
859
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
860 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
861 let job = job_start(command,
10449
222b1432814e commit https://github.com/vim/vim/commit/5162822914372fc916a93f85848c0c82209e7cec
Christian Brabandt <cb@256bit.org>
parents: 10426
diff changeset
862 \ {"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
863
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
864 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
865
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
866 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
867 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
868 avoid it getting stuck.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
869
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
870 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
871
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
872 *job-start-if-needed*
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
873 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
874 like this: >
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
875 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
876 if ch_status(channel) == "fail"
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
877 let job = job_start(command)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
878 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
879 endif
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
880
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
881 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
882 available.
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
883
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
884 ==============================================================================
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
885 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
886
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
887 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
888 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
889 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
890 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
891 <
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
892 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
893 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
894
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
895 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
896 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
897 "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
898 "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
899 "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
900 "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
901 "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
902 "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
903 "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
904 "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
905 "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
906
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
907 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
908 "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
909 (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
910 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
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 MS-Windows:
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
913 "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
914 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
915 See 'termwintype'.
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 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
918
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
919 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
920 GetJob()->job_info()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
921
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
922
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
923 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
924 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
925 "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
926 "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
927
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
928 Can also be used as a |method|: >
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
929 GetJob()->job_setoptions(options)
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
930
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
931
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
932 job_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
933 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
934 |:!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
935 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
936
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
937 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
938 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
939 invoked.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
940
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
941 {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
942 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
943 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
944
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
945 {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
946 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
947 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
948
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
949 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
950 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
951
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
952 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
953 '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
954 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
955 < Or: >
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
956 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
957 < 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
958 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
959 shell command.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
960
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
961 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
962 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
963
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
964 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
965 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
966 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
967 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
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 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
970 |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
971
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
972 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
973 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
974 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
975 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
976 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
977 < use: >
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
978 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
979 < 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
980 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
981 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
982 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
983 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
984 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
985 <
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
986 {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
987 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
988
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
989 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
990 BuildCommand()->job_start()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
991
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
992
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
993 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
994 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
995 "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
996 "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
997 "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
998
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
999 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
1000 "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
1001 detected.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1002
22723
5b7ea82bc18f Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 22077
diff changeset
1003 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
1004 never assigned to, passing that variable to job_status()
5b7ea82bc18f Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 22077
diff changeset
1005 returns "fail".
5b7ea82bc18f Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 22077
diff changeset
1006
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1007 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
1008 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
1009
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1010 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
1011
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
1012 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
1013 GetJob()->job_status()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
1014
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1015
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1016 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
1017 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
1018
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1019 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
1020 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
1021 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
1022 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
1023 affected.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1024
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1025 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
1026 "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
1027 "hup" SIGHUP
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1028 "quit" SIGQUIT
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1029 "int" SIGINT
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1030 "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
1031 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
1032
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1033 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
1034 "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
1035 "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
1036 "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
1037 "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
1038 "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
1039 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
1040
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1041 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
1042 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
1043 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
1044
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1045 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
1046 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
1047 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
1048 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
1049 |job_status()|.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1050
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1051 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
1052 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
1053 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
1054
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1055 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
1056 the channel.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1057
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
1058 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
1059 GetJob()->job_stop()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
1060
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1061
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1062 ==============================================================================
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1063 12. Job options *job-options*
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1064
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1065 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
1066 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
1067 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
1068 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
1069 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
1070
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1071 *in_mode* *out_mode* *err_mode*
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1072 "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
1073 "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
1074 "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
1075 See |channel-mode| for the values.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1076
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1077 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
1078 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
1079 specific mode later.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1080
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1081 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
1082 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
1083
14675
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
1084 *job-noblock*
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
1085 "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
1086 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
1087 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
1088 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
1089 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
1090 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
1091 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
1092 let options['noblock'] = 1
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
1093 endif
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
1094 <
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
1095 *job-callback*
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
1096 "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
1097 channel.
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1098 *job-out_cb* *out_cb*
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1099 "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
1100 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
1101 "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
1102 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
1103
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1104 *job-err_cb* *err_cb*
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1105 "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
1106 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
1107 "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
1108 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
1109 *job-close_cb*
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1110 "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
1111 "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
1112 *job-drop*
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1113 "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
1114 |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
1115 exit_cb is not considered.
10498
883396809b45 commit https://github.com/vim/vim/commit/bc2eada5424bff06f7eb77c032ecc067da52b846
Christian Brabandt <cb@256bit.org>
parents: 10449
diff changeset
1116 *job-exit_cb*
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1117 "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
1118 job and the exit status.
10319
169a62d5bcb9 commit https://github.com/vim/vim/commit/b4ada79aa7d0d1e5da3a659b1a203d7cae9f7f59
Christian Brabandt <cb@256bit.org>
parents: 10244
diff changeset
1119 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
1120 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
1121 |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
1122 handler.
9097
071f9da012fb commit https://github.com/vim/vim/commit/06d2d38ab7564e1f784b1058a4ef4580cd6d1810
Christian Brabandt <cb@256bit.org>
parents: 9076
diff changeset
1123 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
1124 called after the process ends.
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1125 *job-timeout*
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1126 "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
1127 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
1128 default is 2000 (2 seconds).
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1129 *out_timeout* *err_timeout*
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1130 "out_timeout": time Timeout for stdout. Only when using pipes.
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1131 "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
1132 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
1133 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
1134 part specific mode later.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1135
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
1136 *job-stoponexit*
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
1137 "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
1138 |job_stop()| for possible values.
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
1139 "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
1140 The default is "term".
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
1141
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1142 *job-term*
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1143 "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
1144 stdin/stdout/stderr to it. Similar to using
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1145 `:terminal`.
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1146 NOTE: Not implemented yet!
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1147
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1148 "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
1149 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
1150 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
1151 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
1152 cause I/O errors.
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1153 Existing callbacks and other settings remain.
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1154
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1155 "pty": 1 Use a pty (pseudo-tty) instead of a pipe when
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1156 possible. This is most useful in combination with a
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1157 terminal window, see |terminal|.
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1158 {only on Unix and Unix-like systems}
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1159
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1160 *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
1161 "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
1162 "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
1163 "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
1164 "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
1165 "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
1166 "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
1167 "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
1168 "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
1169
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1170 *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
1171 "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
1172 "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
1173 "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
1174 "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
1175 "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
1176 "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
1177 "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
1178 (see below)
10147
65afd399ffa7 commit https://github.com/vim/vim/commit/169ebb080454357279ad5ad21ac532deaec605e8
Christian Brabandt <cb@256bit.org>
parents: 10054
diff changeset
1179 "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
1180 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
1181
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1182 *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
1183 "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
1184 "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
1185 "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
1186 "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
1187 "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
1188 "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
1189 "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
1190 "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
1191 (see below)
10147
65afd399ffa7 commit https://github.com/vim/vim/commit/169ebb080454357279ad5ad21ac532deaec605e8
Christian Brabandt <cb@256bit.org>
parents: 10054
diff changeset
1192 "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
1193 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
1194
8795
aba2d0a01290 commit https://github.com/vim/vim/commit/7db8f6f4f85e5d0526d23107b2a5e2334dc23354
Christian Brabandt <cb@256bit.org>
parents: 8748
diff changeset
1195 "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
1196 will block
aba2d0a01290 commit https://github.com/vim/vim/commit/7db8f6f4f85e5d0526d23107b2a5e2334dc23354
Christian Brabandt <cb@256bit.org>
parents: 8748
diff changeset
1197
12043
2796a2c9fc17 patch 8.0.0902: cannot specify directory or environment for a job
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
1198 "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
1199 "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
1200 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
1201
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1202
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1203 Writing to a buffer ~
10004
8061455d9179 commit https://github.com/vim/vim/commit/818078ddfbb8cc2546f697c5675a251d095722ec
Christian Brabandt <cb@256bit.org>
parents: 9969
diff changeset
1204 *out_io-buffer*
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1205 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
1206 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
1207
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents: 8392
diff changeset
1208 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
1209 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
1210 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
1211
8392
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
1212 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
1213 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
1214 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
1215
9227
ecb621205ed1 commit https://github.com/vim/vim/commit/82af8710bf8d1caeeceafb1370a052cb7d92f076
Christian Brabandt <cb@256bit.org>
parents: 9147
diff changeset
1216 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
1217 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
1218 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
1219 "somename" it will use that buffer.
ecb621205ed1 commit https://github.com/vim/vim/commit/82af8710bf8d1caeeceafb1370a052cb7d92f076
Christian Brabandt <cb@256bit.org>
parents: 9147
diff changeset
1220
ecb621205ed1 commit https://github.com/vim/vim/commit/82af8710bf8d1caeeceafb1370a052cb7d92f076
Christian Brabandt <cb@256bit.org>
parents: 9147
diff changeset
1221 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
1222 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
1223 buffer number.
8291
ac0c43e7af20 commit https://github.com/vim/vim/commit/c7f0ebc6d1e1cdaed816b88a0d6092c5ace615eb
Christian Brabandt <cb@256bit.org>
parents: 8285
diff changeset
1224
ac0c43e7af20 commit https://github.com/vim/vim/commit/c7f0ebc6d1e1cdaed816b88a0d6092c5ace615eb
Christian Brabandt <cb@256bit.org>
parents: 8285
diff changeset
1225 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
1226 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
1227 *out_modifiable* *err_modifiable*
65afd399ffa7 commit https://github.com/vim/vim/commit/169ebb080454357279ad5ad21ac532deaec605e8
Christian Brabandt <cb@256bit.org>
parents: 10054
diff changeset
1228 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
1229 '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
1230 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
1231 change the buffer.
65afd399ffa7 commit https://github.com/vim/vim/commit/169ebb080454357279ad5ad21ac532deaec605e8
Christian Brabandt <cb@256bit.org>
parents: 10054
diff changeset
1232 *out_msg* *err_msg*
65afd399ffa7 commit https://github.com/vim/vim/commit/169ebb080454357279ad5ad21ac532deaec605e8
Christian Brabandt <cb@256bit.org>
parents: 10054
diff changeset
1233 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
1234 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
1235 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
1236
9147
053bc64433ec commit https://github.com/vim/vim/commit/9f5842e63fc63d438cbffcec503e072a06f74dc2
Christian Brabandt <cb@256bit.org>
parents: 9116
diff changeset
1237 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
1238 "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
1239 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
1240
8267
108d30ed34ba commit https://github.com/vim/vim/commit/187db50d0499aecf4cfd42fb4db0a1bebf61c8cd
Christian Brabandt <cb@256bit.org>
parents: 8246
diff changeset
1241 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
1242 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
1243 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
1244
9464
be72f4201a1d commit https://github.com/vim/vim/commit/063b9d15abea041a5bfff3ffc4e219e26fd1d4fa
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
1245 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
1246 stores these as NL bytes).
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1247
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1248
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1249 Writing to a file ~
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1250 *E920*
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1251 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
1252 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
1253
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1254 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
1255
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1256 ==============================================================================
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1257 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
1258
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1259 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
1260 echo job_status(job)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1261
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1262 To make a job stop running: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1263 job_stop(job)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1264
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1265 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
1266 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
1267 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
1268 job_stop(job, "kill")
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 For more options see |job_stop()|.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
1271
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
1272 ==============================================================================
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1273 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
1274
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
1275 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
1276 - 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
1277 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
1278 - 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
1279 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
1280 See |terminal-window|.
20753
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1281 - 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
1282 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
1283
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1284 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
1285 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
1286
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1287 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
1288 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
1289 |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
1290 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
1291 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
1292
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1293 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
1294 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
1295 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
1296 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
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 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
1299 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
1300 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
1301
22077
335365fcbb60 patch 8.2.1588: cannot read back the prompt of a prompt buffer
Bram Moolenaar <Bram@vim.org>
parents: 21250
diff changeset
1302 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
1303 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
1304 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
1305
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 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
1307 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
1308
14123
583bf95b6c84 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14019
diff changeset
1309 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
1310 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
1311 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
1312 coming back to the prompt window Insert mode will be restored.
583bf95b6c84 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14019
diff changeset
1313
14019
dc67449d648c patch 8.1.0027: difficult to make a plugin that feeds a line to a job
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
1314 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
1315 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
1316 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
1317
20753
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1318 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
1319 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
1320 prompt. >
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1321
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1322 " Create a channel log so we can see what happens.
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1323 call ch_logfile('logfile', 'w')
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1324
28010
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1325 " Function handling a line of text that has been typed.
20753
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1326 func TextEntered(text)
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1327 " Send the text to a shell with Enter appended.
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1328 call ch_sendraw(g:shell_job, a:text .. "\n")
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1329 endfunc
22723
5b7ea82bc18f Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 22077
diff changeset
1330
28010
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1331 " 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
1332 func GotOutput(channel, msg)
27903
d19b7aee1925 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 26438
diff changeset
1333 call append(line("$") - 1, "- " .. a:msg)
20753
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1334 endfunc
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1335
28010
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1336 " Function handling the shell exits: close the window.
20753
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1337 func JobExit(job, status)
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1338 quit!
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
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1341 " Start a shell in the background.
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1342 let shell_job = job_start(["/bin/sh"], #{
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1343 \ out_cb: function('GotOutput'),
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1344 \ err_cb: function('GotOutput'),
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1345 \ exit_cb: function('JobExit'),
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1346 \ })
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1347
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1348 new
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1349 set buftype=prompt
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1350 let buf = bufnr('')
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1351 call prompt_setcallback(buf, function("TextEntered"))
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1352 eval prompt_setprompt(buf, "shell command: ")
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1353
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1354 " start accepting shell commands
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1355 startinsert
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1356 <
28010
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1357 The same in |Vim9| script: >
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1358
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1359 vim9script
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1360
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1361 # Create a channel log so we can see what happens.
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1362 ch_logfile('logfile', 'w')
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 var shell_job: job
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 # Function handling a line of text that has been typed.
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1367 def TextEntered(text: string)
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1368 # Send the text to a shell with Enter appended.
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1369 ch_sendraw(shell_job, text .. "\n")
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1370 enddef
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1371
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1372 # Function handling output from the shell: Add it above the prompt.
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1373 def GotOutput(channel: channel, msg: string)
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1374 append(line("$") - 1, "- " .. msg)
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 the shell exits: close the window.
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1378 def JobExit(job: job, status: number)
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1379 quit!
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 # Start a shell in the background.
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1383 shell_job = job_start(["/bin/sh"], {
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1384 out_cb: GotOutput,
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1385 err_cb: GotOutput,
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1386 exit_cb: JobExit,
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1387 })
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1388
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1389 new
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1390 set buftype=prompt
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1391 var buf = bufnr('')
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1392 prompt_setcallback(buf, TextEntered)
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1393 prompt_setprompt(buf, "shell command: ")
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1394
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1395 # start accepting shell commands
c968191a8557 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 27903
diff changeset
1396 startinsert
20753
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1397
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1398 ==============================================================================
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
1399 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
1400
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1401 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
1402
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1403 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
1404
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1405 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
1406 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
1407
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1408 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
1409
28473
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1410 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
1411 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
1412 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
1413 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
1414
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1415 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
1416 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
1417 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
1418 |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
1419 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
1420 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
1421 |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
1422 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
1423
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1424 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
1425 {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
1426
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1427 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
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 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
1430 '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
1431
28473
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1432 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
1433 let opts = {}
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1434 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
1435 let opts.out_mode = 'lsp'
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1436 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
1437 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
1438 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
1439 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
1440
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
1441 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
1442 |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
1443 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
1444 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
1445 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
1446
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1447 let req = {}
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1448 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
1449 let req.params = {}
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1450 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
1451 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
1452 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
1453 if defs->empty()
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1454 ... <handle failure>
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1455 endif
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1456
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1457 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
1458 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
1459 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
1460 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
1461 request.
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1462
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1463 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
1464 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
1465 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
1466 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
1467 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
1468 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
1469
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1470 let req = {}
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1471 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
1472 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
1473 let req.params = {}
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1474 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
1475 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
1476 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
1477
28473
1c112473a54f patch 8.2.4761: documentation for using LSP messages is incomplete
Bram Moolenaar <Bram@vim.org>
parents: 28467
diff changeset
1478 To cancel an outstanding asynchronous LSP request sent to the server using 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
1479 |ch_sendexpr()| function, send a cancelation 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
1480 |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
1481 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
1482
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 " 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
1484 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
1485 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
1486 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
1487 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
1488 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
1489 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
1490 " 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
1491 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
1492 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
1493 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
1494 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
1495
28244
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1496 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
1497 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
1498 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
1499
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1500 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
1501
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1502 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
1503 |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
1504 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
1505
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1506 let resp = {}
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1507 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
1508 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
1509 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
1510
85b07a942518 patch 8.2.4648: handling LSP messages is a bit slow
Bram Moolenaar <Bram@vim.org>
parents: 28010
diff changeset
1511 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
1512 |channel-callback| function.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
1513
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
1514 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
1515 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
1516
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
1517 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
1518 "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
1519
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
1520 {
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
1521 "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
1522 "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
1523 "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
1524 "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
1525 }
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
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 A LSP reponse 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
1528 "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
1529
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 "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
1532 "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
1533 "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
1534 "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
1535 }
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1536
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 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
1538 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
1539
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 "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
1542 "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
1543 "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
1544 }
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1545
3beb14b12bbd patch 8.2.4758: when using an LSP channel want to get the message ID
Bram Moolenaar <Bram@vim.org>
parents: 28435
diff changeset
1546 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
1547 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
1548
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 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
1550 "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
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 {
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 "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
1554 "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
1555 "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
1556 "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
1557 }
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
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 A LSP reponse 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
1560 "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
1561
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 "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
1564 "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
1565 "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
1566 "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
1567 }
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 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
1570 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
1571
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 "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
1574 "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
1575 "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
1576 }
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
14421
2f7e67dd088c Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14123
diff changeset
1578 vim:tw=78:ts=8:noet:ft=help:norl: