Mercurial > vim

annotate runtime/doc/channel.txt @ 20753:661eb972cb22

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Update runtime files Commit: https://github.com/vim/vim/commit/acc224064033e5cea21ef7f1eefb356ca06ff11d Author: Bram Moolenaar <Bram@vim.org> Date: Sun Jun 7 21:07:18 2020 +0200 Update runtime files
author Bram Moolenaar <Bram@vim.org>
date Sun, 07 Jun 2020 21:15:04 +0200
parents e373843e2980
children 21fb2a3ad3ca
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
20753
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1 *channel.txt* For Vim version 8.2. Last change: 2020 Jun 01
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|
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
28
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
29 {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
30 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
31 {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
32 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
33
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
34 ==============================================================================
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
35 1. Overview *job-channel-overview*
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
36
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
37 There are four main types of jobs:
10218
584c835a2de1 commit https://github.com/vim/vim/commit/50ba526fbf3e9e5e0e6b0b3086a4d5df581ebc7e
Christian Brabandt <cb@256bit.org>
parents: 10198
diff changeset
38 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
39 Vim connects to it with a socket.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
40 2. One job working with one Vim instance, asynchronously.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
41 Uses a socket or pipes.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
42 3. A job performing some work for a short time, asynchronously.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
43 Uses a socket or pipes.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
44 4. Running a filter, synchronously.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
45 Uses pipes.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
46
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
47 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
48 |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
49 For 4 use the ":{range}!cmd" command, see |filter|.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
50
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
51 Over the socket and pipes these protocols are available:
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
52 RAW nothing known, Vim cannot tell where a message ends
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
53 NL every message ends in a NL (newline) character
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
54 JSON JSON encoding |json_encode()|
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
55 JS JavaScript style JSON-like encoding |js_encode()|
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
56
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
57 Common combination are:
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
58 - Using a job connected through pipes in NL mode. E.g., to run a style
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
59 checker and receive errors and warnings.
13735
a62eeee5f116 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12045
diff changeset
60 - 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
61 cross-references in a database.
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
62
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
63 ==============================================================================
9116
bc38030aec7d commit https://github.com/vim/vim/commit/26852128a2b713ef49341a0c18daba928444e7eb
Christian Brabandt <cb@256bit.org>
parents: 9097
diff changeset
64 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
65
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
66 This requires Python. The demo program can be found in
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
67 $VIMRUNTIME/tools/demoserver.py
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
68 Run it in one terminal. We will call this T1.
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
69
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
70 Run Vim in another terminal. Connect to the demo server with: >
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
71 let channel = ch_open('localhost:8765')
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
72
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
73 In T1 you should see:
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
74 === socket opened === ~
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
75
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
76 You can now send a message to the server: >
8285
e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f
Christian Brabandt <cb@256bit.org>
parents: 8267
diff changeset
77 echo ch_evalexpr(channel, 'hello!')
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
78
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
79 The message is received in T1 and a response is sent back to Vim.
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
80 You can see the raw messages in T1. What Vim sends is:
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
81 [1,"hello!"] ~
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
82 And the response is:
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
83 [1,"got it"] ~
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
84 The number will increase every time you send a message.
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
85
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
86 The server can send a command to Vim. Type this on T1 (literally, including
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
87 the quotes):
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
88 ["ex","echo 'hi there'"] ~
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
89 And you should see the message in Vim. You can move the cursor a word forward:
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
90 ["normal","w"] ~
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
91
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
92 To handle asynchronous communication a callback needs to be used: >
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
93 func MyHandler(channel, msg)
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
94 echo "from the handler: " . a:msg
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
95 endfunc
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
96 call ch_sendexpr(channel, 'hello!', {'callback': "MyHandler"})
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
97 Vim will not wait for a response. Now the server can send the response later
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
98 and MyHandler will be invoked.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
99
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
100 Instead of giving a callback with every send call, it can also be specified
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
101 when opening the channel: >
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
102 call ch_close(channel)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
103 let channel = ch_open('localhost:8765', {'callback': "MyHandler"})
8285
e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f
Christian Brabandt <cb@256bit.org>
parents: 8267
diff changeset
104 call ch_sendexpr(channel, 'hello!')
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
105
8392
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
106 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
107 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
108 call ch_logfile('channellog', 'w')
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
109 See |ch_logfile()|.
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
110
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
111 ==============================================================================
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
112 3. Opening a channel *channel-open*
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
113
7924
00d64eb49ce1 commit https://github.com/vim/vim/commit/681baaf4a4c81418693dcafb81421a8614832e91
Christian Brabandt <cb@256bit.org>
parents: 7864
diff changeset
114 To open a channel: >
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
115 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
116 if ch_status(channel) == "open"
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
117 " use the channel
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
118
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
119 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
120
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
121 {address} has the form "hostname:port". E.g., "localhost:8765".
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
122
20003
e373843e2980 patch 8.2.0557: no IPv6 support for channels
Bram Moolenaar <Bram@vim.org>
parents: 18879
diff changeset
123 When using an IPv6 address, enclose it within square brackets. E.g.,
e373843e2980 patch 8.2.0557: no IPv6 support for channels
Bram Moolenaar <Bram@vim.org>
parents: 18879
diff changeset
124 "[2001:db8::1]:8765".
e373843e2980 patch 8.2.0557: no IPv6 support for channels
Bram Moolenaar <Bram@vim.org>
parents: 18879
diff changeset
125
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
126 {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
127
3f2e0b62003d commit https://github.com/vim/vim/commit/4d919d748e4e435edb135aa5ccf6ee7de9212023
Christian Brabandt <cb@256bit.org>
parents: 7924
diff changeset
128 "mode" can be: *channel-mode*
3f2e0b62003d commit https://github.com/vim/vim/commit/4d919d748e4e435edb135aa5ccf6ee7de9212023
Christian Brabandt <cb@256bit.org>
parents: 7924
diff changeset
129 "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
130 "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
131 "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
132 "raw" - Use raw messages
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
133 *channel-callback* *E921*
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
134 "callback" A function that is called when a message is received that is
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
135 not handled otherwise. It gets two arguments: the channel
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
136 and the received message. Example: >
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
137 func Handle(channel, msg)
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
138 echo 'Received: ' . a:msg
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
139 endfunc
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
140 let channel = ch_open("localhost:8765", {"callback": "Handle"})
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
141 <
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
142 When "mode" is "json" or "js" the "msg" argument is the body
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
143 of the received message, converted to Vim types.
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
144 When "mode" is "nl" the "msg" argument is one message,
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
145 excluding the NL.
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
146 When "mode" is "raw" the "msg" argument is the whole message
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
147 as a string.
8673
ed7251c3e2d3 commit https://github.com/vim/vim/commit/e18c0b39815c5a746887a509c2cd9f11fadaba07
Christian Brabandt <cb@256bit.org>
parents: 8540
diff changeset
148
ed7251c3e2d3 commit https://github.com/vim/vim/commit/e18c0b39815c5a746887a509c2cd9f11fadaba07
Christian Brabandt <cb@256bit.org>
parents: 8540
diff changeset
149 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
150 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
151 the Dictionary.
9097
071f9da012fb commit https://github.com/vim/vim/commit/06d2d38ab7564e1f784b1058a4ef4580cd6d1810
Christian Brabandt <cb@256bit.org>
parents: 9076
diff changeset
152
071f9da012fb commit https://github.com/vim/vim/commit/06d2d38ab7564e1f784b1058a4ef4580cd6d1810
Christian Brabandt <cb@256bit.org>
parents: 9076
diff changeset
153 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
154 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
155 multi-threading.
071f9da012fb commit https://github.com/vim/vim/commit/06d2d38ab7564e1f784b1058a4ef4580cd6d1810
Christian Brabandt <cb@256bit.org>
parents: 9076
diff changeset
156
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
157 *close_cb*
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
158 "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
159 than by calling ch_close(). It should be defined like this: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
160 func MyCloseHandler(channel)
9097
071f9da012fb commit https://github.com/vim/vim/commit/06d2d38ab7564e1f784b1058a4ef4580cd6d1810
Christian Brabandt <cb@256bit.org>
parents: 9076
diff changeset
161 < 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
162 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
163 be passed to the callbacks. However, if a callback causes Vim
c002c4899529 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 16553
diff changeset
164 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
165 in the callback. The plugin must handle this somehow, it can
c002c4899529 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 16553
diff changeset
166 be useful to know that no more data is coming.
10426
acfc83aca8ee commit https://github.com/vim/vim/commit/958dc6923d341390531888058495569d73c356c3
Christian Brabandt <cb@256bit.org>
parents: 10422
diff changeset
167 *channel-drop*
acfc83aca8ee commit https://github.com/vim/vim/commit/958dc6923d341390531888058495569d73c356c3
Christian Brabandt <cb@256bit.org>
parents: 10422
diff changeset
168 "drop" Specifies when to drop messages:
acfc83aca8ee commit https://github.com/vim/vim/commit/958dc6923d341390531888058495569d73c356c3
Christian Brabandt <cb@256bit.org>
parents: 10422
diff changeset
169 "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
170 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
171 "never" All messages will be kept.
acfc83aca8ee commit https://github.com/vim/vim/commit/958dc6923d341390531888058495569d73c356c3
Christian Brabandt <cb@256bit.org>
parents: 10422
diff changeset
172
14675
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
173 *channel-noblock*
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
174 "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
175
9097
071f9da012fb commit https://github.com/vim/vim/commit/06d2d38ab7564e1f784b1058a4ef4580cd6d1810
Christian Brabandt <cb@256bit.org>
parents: 9076
diff changeset
176 *waittime*
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
177 "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
178 milliseconds. A negative number waits forever.
f16bfe02cef1 commit https://github.com/vim/vim/commit/f391327adbbffb11180cf6038a92af1ed144e907
Christian Brabandt <cb@256bit.org>
parents: 8178
diff changeset
179
f16bfe02cef1 commit https://github.com/vim/vim/commit/f391327adbbffb11180cf6038a92af1ed144e907
Christian Brabandt <cb@256bit.org>
parents: 8178
diff changeset
180 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
181 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
182 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
183 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
184 msec at least.
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
185 *channel-timeout*
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
186 "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
187 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
188 seconds).
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
189
7967
45ea5ebf3a98 commit https://github.com/vim/vim/commit/595e64e259faefb330866852e1b9f6168544572a
Christian Brabandt <cb@256bit.org>
parents: 7957
diff changeset
190 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
191 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
192
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
193 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
194 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
195 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
196
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
197 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
198 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
199 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
200
8392
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
201 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
202 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
203 `:redraw`.
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
204
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
205 The timeout can be changed: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
206 call ch_setoptions(channel, {'timeout': msec})
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
207 <
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
208 *channel-close* *E906*
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
209 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
210 call ch_close(channel)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
211 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
212 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
213 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
214 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
215
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
216 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
217 - 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
218 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
219 - 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
220 may still reference the channel.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
221 - 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
222
7992
78106b0f2c56 commit https://github.com/vim/vim/commit/cbebd4879cc78e670d79b2c57dc33d7b911c962a
Christian Brabandt <cb@256bit.org>
parents: 7967
diff changeset
223 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
224 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
225 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
226 *E898* *E901* *E902*
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
227
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
228 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
229 *E630* *E631*
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
230
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
231 ==============================================================================
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
232 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
233
8094
18a3f0f05244 commit https://github.com/vim/vim/commit/910b8aac5dc4693c4508b7acd2cef0bbfac04242
Christian Brabandt <cb@256bit.org>
parents: 8061
diff changeset
234 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
235 let response = ch_evalexpr(channel, {expr})
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
236 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
237
8094
18a3f0f05244 commit https://github.com/vim/vim/commit/910b8aac5dc4693c4508b7acd2cef0bbfac04242
Christian Brabandt <cb@256bit.org>
parents: 8061
diff changeset
238 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
239 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
240
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
241 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
242 handle the response: >
8285
e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f
Christian Brabandt <cb@256bit.org>
parents: 8267
diff changeset
243 call ch_sendexpr(channel, {expr})
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
244
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
245 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
246 asynchronously: >
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
247 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
248
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
249 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
250 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
251 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
252 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
253
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
254 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
255 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
256 [12,"hello"] ~
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
257
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
258 The format of the JSON sent is:
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
259 [{number},{expr}]
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
260
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
261 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
262 (if any):
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 [{number},{response}]
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
265
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
266 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
267 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
268
9969
176e34b0d678 commit https://github.com/vim/vim/commit/f1f0792e55e72cdc7c833b30f565a9b02f18bb1e
Christian Brabandt <cb@256bit.org>
parents: 9860
diff changeset
269 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
270 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
271 splitidx = read_text.find('\n')
176e34b0d678 commit https://github.com/vim/vim/commit/f1f0792e55e72cdc7c833b30f565a9b02f18bb1e
Christian Brabandt <cb@256bit.org>
parents: 9860
diff changeset
272 message = read_text[:splitidx]
176e34b0d678 commit https://github.com/vim/vim/commit/f1f0792e55e72cdc7c833b30f565a9b02f18bb1e
Christian Brabandt <cb@256bit.org>
parents: 9860
diff changeset
273 rest = read_text[splitidx + 1:]
176e34b0d678 commit https://github.com/vim/vim/commit/f1f0792e55e72cdc7c833b30f565a9b02f18bb1e
Christian Brabandt <cb@256bit.org>
parents: 9860
diff changeset
274
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
275 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
276 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
277 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
278
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
279 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
280 message, it must use the number zero:
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
281 [0,{response}]
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 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
284 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
285
8285
e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f
Christian Brabandt <cb@256bit.org>
parents: 8267
diff changeset
286 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
287 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
288 decoding.
7992
78106b0f2c56 commit https://github.com/vim/vim/commit/cbebd4879cc78e670d79b2c57dc33d7b911c962a
Christian Brabandt <cb@256bit.org>
parents: 7967
diff changeset
289
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
290 ==============================================================================
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
291 5. Channel commands *channel-commands*
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
292
8094
18a3f0f05244 commit https://github.com/vim/vim/commit/910b8aac5dc4693c4508b7acd2cef0bbfac04242
Christian Brabandt <cb@256bit.org>
parents: 8061
diff changeset
293 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
294 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
295
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
296 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
297 ["redraw", {forced}]
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
298 ["ex", {Ex command}]
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
299 ["normal", {Normal mode command}]
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
300 ["expr", {expression}, {number}]
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
301 ["expr", {expression}]
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
302 ["call", {func name}, {argument list}, {number}]
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
303 ["call", {func name}, {argument list}]
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
304
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
305 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
306 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
307 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
308 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
309 ["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
310
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
311 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
312 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
313 higher.
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
314
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
315
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
316 Command "redraw" ~
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
317
16086
bd7461db24b3 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 14675
diff changeset
318 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
319 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
320 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
321 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
322
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
323 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
324 ["redraw", ""] ~
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
325 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
326 ["redraw", "force"] ~
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
327
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
328
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
329 Command "ex" ~
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
330
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
331 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
332 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
333 ["ex","call myscript#MyFunc(arg)"]
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 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
336
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
337 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
338 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
339
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
340
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
341 Command "normal" ~
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
342
7924
00d64eb49ce1 commit https://github.com/vim/vim/commit/681baaf4a4c81418693dcafb81421a8614832e91
Christian Brabandt <cb@256bit.org>
parents: 7864
diff changeset
343 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
344 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
345 ["normal" "zO"]
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
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
348 Command "expr" with response ~
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
349
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
350 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
351 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
352 ["expr","line('$')", -2] ~
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
353
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
354 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
355 [-2, "last line"] ~
f5da459c5698 commit https://github.com/vim/vim/commit/e0fa3742ead676a3074a10edadbc955e1a89153d
Christian Brabandt <cb@256bit.org>
parents: 8094
diff changeset
356 The format is:
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
357 [{number}, {result}]
8267
108d30ed34ba commit https://github.com/vim/vim/commit/187db50d0499aecf4cfd42fb4db0a1bebf61c8cd
Christian Brabandt <cb@256bit.org>
parents: 8246
diff changeset
358
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
359 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
360 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
361 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
362
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
363 {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
364 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
365 "ERROR".
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
366
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
367
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
368 Command "expr" without a response ~
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
369
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
370 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
371 Example:
7864
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2
Christian Brabandt <cb@256bit.org>
parents: 7788
diff changeset
372 ["expr","setline('$', ['one', 'two', 'three'])"] ~
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
373 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
374
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
375
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
376 Command "call" ~
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
377
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
378 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
379 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
380 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
381 concatenating them. Example:
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
382 ["call", "line", ["$"], -2] ~
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
383
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
384 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
385 ["call", "setline", ["$", ["one", "two", "three"]]] ~
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
386
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
387 ==============================================================================
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
388 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
389
10385
368468ef35cf commit https://github.com/vim/vim/commit/c0514bf4777a1d55f5785b3887c5686fd0bbe870
Christian Brabandt <cb@256bit.org>
parents: 10319
diff changeset
390 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
391 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
392
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
393 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
394 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
395 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
396 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
397
8094
18a3f0f05244 commit https://github.com/vim/vim/commit/910b8aac5dc4693c4508b7acd2cef0bbfac04242
Christian Brabandt <cb@256bit.org>
parents: 8061
diff changeset
398 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
399 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
400 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
401 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
402 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
403
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
404 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
405 call ch_sendraw(channel, {string})
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
406 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
407 it.
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
408
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
409 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
410 asynchronously: >
8285
e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f
Christian Brabandt <cb@256bit.org>
parents: 8267
diff changeset
411 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
412
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
413 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
414 |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
415
8285
e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f
Christian Brabandt <cb@256bit.org>
parents: 8267
diff changeset
416 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
417
10004
8061455d9179 commit https://github.com/vim/vim/commit/818078ddfbb8cc2546f697c5675a251d095722ec
Christian Brabandt <cb@256bit.org>
parents: 9969
diff changeset
418 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
419 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
420
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
421 ==============================================================================
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
422 7. More channel functions *channel-more*
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
423
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
424 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
425 are:
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
426 "fail" Failed to open the channel.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
427 "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
428 "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
429 "closed" The channel was closed.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
430
8267
108d30ed34ba commit https://github.com/vim/vim/commit/187db50d0499aecf4cfd42fb4db0a1bebf61c8cd
Christian Brabandt <cb@256bit.org>
parents: 8246
diff changeset
431 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
432
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
433 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
434 let output = ch_read(channel)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
435 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
436 message that is available: >
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
437 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
438 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
439 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
440 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
441
12043
2796a2c9fc17 patch 8.0.0902: cannot specify directory or environment for a job
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
442 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
443 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
444
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
445 To read all output from a RAW channel that is available: >
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
446 let output = ch_readraw(channel)
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
447 To read the error output: >
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
448 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
449
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
450 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
451 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
452 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
453 {"timeout": 123} ~
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
454 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
455 {"part": "err"} ~
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
456 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
457 {"id": 99} ~
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
458 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
459 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
460
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
461 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
462 where a message ends.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
463 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
464 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
465 This includes any sequence number.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
466
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
467 ==============================================================================
17571
2704c4e3e20a Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 17456
diff changeset
468 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
469
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
470 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
471 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
472 {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
473
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
474 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
475 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
476
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
477 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
478 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
479
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
480 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
481 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
482
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
483 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
484 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
485 {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
486 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
487
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
488 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
489 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
490
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
491 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
492 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
493 {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
494 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
495
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
496 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
497 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
498
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
499
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
500 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
501 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
502 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
503 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
504 {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
505 *E917*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
506 {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
507 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
508 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
509
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
510 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
511 expression. When there is an error or timeout it returns an
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
512 empty string.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
513
18053
8ac85adee561 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 17831
diff changeset
514 Note that while waiting for the response, Vim handles other
8ac85adee561 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 17831
diff changeset
515 messages. You need to make sure this doesn't cause trouble.
8ac85adee561 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 17831
diff changeset
516
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
517 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
518 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
519
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
520
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
521 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
522 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
523 {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
524
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
525 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
526 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
527 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
528 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
529 is removed.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
530 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
531 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
532 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
533 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
534
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
535 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
536 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
537
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
538 ch_getbufnr({handle}, {what}) *ch_getbufnr()*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
539 Get the buffer number that {handle} is using for {what}.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
540 {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
541 {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
542 socket output.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
543 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
544
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
545 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
546 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
547
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
548 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
549 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
550 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
551 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
552
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
553 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
554 GetChannel()->ch_getjob()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
555
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
556
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
557 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
558 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
559 items are:
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
560 "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
561 "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
562 ch_status()
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
563 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
564 "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
565 "port" the port 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
566 "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
567 "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
568 "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
569 "sock_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
570 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
571 "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
572 "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
573 "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
574 "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
575 "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
576 "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
577 "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
578 "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
579 "in_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
580 "in_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
581 "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
582 "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
583
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
584 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
585 GetChannel()->ch_info()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
586
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
587
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
588 ch_log({msg} [, {handle}]) *ch_log()*
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
589 Write {msg} in the channel log file, if it was opened with
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
590 |ch_logfile()|.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
591 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
592 message.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
593 {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
594 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
595
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
596 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
597 '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
598
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
599
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
600 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
601 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
602 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
603
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
604 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
605 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
606
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
607 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
608 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
609 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
610
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
611 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
612 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
613 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
614 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
615
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
616 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
617 '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
618
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
619
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
620 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
621 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
622 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
623
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
624 {address} has the form "hostname:port", e.g.,
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
625 "localhost:8765".
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
626
20003
e373843e2980 patch 8.2.0557: no IPv6 support for channels
Bram Moolenaar <Bram@vim.org>
parents: 18879
diff changeset
627 When using an IPv6 address, enclose it within square brackets.
e373843e2980 patch 8.2.0557: no IPv6 support for channels
Bram Moolenaar <Bram@vim.org>
parents: 18879
diff changeset
628 E.g., "[2001:db8::1]:8765".
e373843e2980 patch 8.2.0557: no IPv6 support for channels
Bram Moolenaar <Bram@vim.org>
parents: 18879
diff changeset
629
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
630 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
631 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
632
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
633 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
634 GetAddress()->ch_open()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
635
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
636
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
637 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
638 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
639 {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
640 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
641 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
642 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
643
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
644 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
645 GetChannel()->ch_read()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
646
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
647
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
648 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
649 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
650 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
651
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
652 Can also be used as a |method|: >
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
653 GetChannel()->ch_readblob()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
654
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
655
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
656 ch_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
657 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
658 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
659 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
660 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
661
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
662 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
663 GetChannel()->ch_readraw()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
664
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
665
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
666 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
667 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
668 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
669 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
670 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
671 {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
672
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
673 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
674 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
675
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
676
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
677 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
678 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
679 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
680 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
681 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
682 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
683 is removed.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
684 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
685
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
686 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
687 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
688
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
689
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
690 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
691 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
692 "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
693 "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
694 "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
695 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
696 {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
697
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
698 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
699 lost.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
700
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
701 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
702 "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
703
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
704 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
705 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
706
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
707
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
708 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
709 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
710 "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
711 "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
712 "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
713 "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
714 {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
715 "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
716 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
717
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
718 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
719 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
720 "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
721 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
722 <
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
723 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
724 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
725
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
726 ==============================================================================
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
727 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
728
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
729 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
730 let job = job_start(command, {options})
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
731
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
732 You can get the channel with: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
733 let channel = job_getchannel(job)
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
734
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
735 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
736 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
737 been received and not parsed correctly.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
738
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
739 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
740 a handler for stdout: >
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
741 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
742 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
743 it like this: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
744 func MyHandler(channel, msg)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
745
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
746 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
747 |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
748
12045
444ad56c0cac Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12043
diff changeset
749 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
750 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
751 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
752 for a short while before it exits.
444ad56c0cac Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12043
diff changeset
753
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
754 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
755 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
756 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
757 \ "err_cb": "ErrHandler"})
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
758
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
759 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
760 "callback" option: >
18831
6848b809a26e Runtime file updates.
Bram Moolenaar <Bram@vim.org>
parents: 18053
diff changeset
761 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
762
11518
63b0b7b79b25 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 10498
diff changeset
763 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
764 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
765 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
766 use a timer to call it after the job has started.
63b0b7b79b25 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 10498
diff changeset
767
8285
e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f
Christian Brabandt <cb@256bit.org>
parents: 8267
diff changeset
768 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
769 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
770
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
771 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
772 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
773 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
774 \ {'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
775 sbuf dummy
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
776
8440
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents: 8392
diff changeset
777
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents: 8392
diff changeset
778 Job input from a buffer ~
10004
8061455d9179 commit https://github.com/vim/vim/commit/818078ddfbb8cc2546f697c5675a251d095722ec
Christian Brabandt <cb@256bit.org>
parents: 9969
diff changeset
779 *in_io-buffer*
8392
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
780 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
781 let job = job_start({command},
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
782 \ {'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
783 <
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
784 *E915* *E918*
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
785 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
786 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
787
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
788 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
789 and "in_bot" options.
8392
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
790
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
791 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
792 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
793 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
794 Enter.
10054
d4b7232fc63a commit https://github.com/vim/vim/commit/0874a83e9be1b39fdb217f02b427bf1d6133a4d8
Christian Brabandt <cb@256bit.org>
parents: 10051
diff changeset
795 *channel-close-in*
d4b7232fc63a commit https://github.com/vim/vim/commit/0874a83e9be1b39fdb217f02b427bf1d6133a4d8
Christian Brabandt <cb@256bit.org>
parents: 10051
diff changeset
796 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
797 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
798 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
799
9464
be72f4201a1d commit https://github.com/vim/vim/commit/063b9d15abea041a5bfff3ffc4e219e26fd1d4fa
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
800 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
801 as NL bytes).
be72f4201a1d commit https://github.com/vim/vim/commit/063b9d15abea041a5bfff3ffc4e219e26fd1d4fa
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
802
9041
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
803
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
804 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
805 *read-in-close-cb*
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
806 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
807 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
808
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
809 func! CloseHandler(channel)
10244
876fbdd84e52 commit https://github.com/vim/vim/commit/2ec618c9feac4573b154510236ad8121c77d0eca
Christian Brabandt <cb@256bit.org>
parents: 10218
diff changeset
810 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
811 echomsg ch_read(a:channel)
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
812 endwhile
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
813 endfunc
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
814 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
815
34c45ee4210d commit https://github.com/vim/vim/commit/06481427005a9dae39721087df94855f7d4d1feb
Christian Brabandt <cb@256bit.org>
parents: 8951
diff changeset
816 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
817
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
818 ==============================================================================
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
819 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
820
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
821 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
822 let job = job_start(command,
10449
222b1432814e commit https://github.com/vim/vim/commit/5162822914372fc916a93f85848c0c82209e7cec
Christian Brabandt <cb@256bit.org>
parents: 10426
diff changeset
823 \ {"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
824
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
825 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
826
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
827 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
828 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
829 avoid it getting stuck.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
830
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
831 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
832
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
833 *job-start-if-needed*
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
834 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
835 like this: >
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
836 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
837 if ch_status(channel) == "fail"
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
838 let job = job_start(command)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
839 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
840 endif
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
841
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
842 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
843 available.
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
844
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
845 ==============================================================================
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
846 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
847
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
848 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
849 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
850 To check if the job has no channel: >
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
851 if string(job_getchannel()) == 'channel fail'
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
852 <
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
853 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
854 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
855
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
856 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
857 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
858 "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
859 "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
860 "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
861 "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
862 "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
863 "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
864 "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
865 "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
866 "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
867
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
868 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
869 "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
870 (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
871 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
872
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
873 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
874 "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
875 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
876 See 'termwintype'.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
877
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
878 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
879
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
880 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
881 GetJob()->job_info()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
882
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
883
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
884 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
885 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
886 "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
887 "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
888
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
889 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
890 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
891
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
892
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
893 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
894 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
895 |:!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
896 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
897
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
898 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
899 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
900 invoked.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
901
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
902 {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
903 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
904 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
905
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
906 {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
907 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
908 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
909
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
910 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
911 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
912
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
913 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
914 '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
915 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
916 < Or: >
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
917 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
918 < 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
919 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
920 shell command.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
921
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
922 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
923 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
924
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
925 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
926 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
927 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
928 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
929 <
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
930 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
931 |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
932
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
933 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
934 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
935 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
936 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
937 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
938 < use: >
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
939 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
940 < 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
941 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
942 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
943 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
944 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
945 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
946 <
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
947 {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
948 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
949
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
950 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
951 BuildCommand()->job_start()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
952
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
953
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
954 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
955 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
956 "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
957 "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
958 "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
959
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
960 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
961 "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
962 detected.
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 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
965 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
966
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
967 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
968
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
969 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
970 GetJob()->job_status()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
971
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
972
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
973 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
974 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
975
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
976 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
977 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
978 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
979 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
980 affected.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
981
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
982 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
983 "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
984 "hup" SIGHUP
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
985 "quit" SIGQUIT
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
986 "int" SIGINT
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
987 "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
988 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
989
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
990 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
991 "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
992 "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
993 "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
994 "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
995 "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
996 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
997
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
998 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
999 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
1000 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
1001
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1002 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
1003 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
1004 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
1005 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
1006 |job_status()|.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1007
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1008 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
1009 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
1010 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
1011
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1012 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
1013 the channel.
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1014
17831
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
1015 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
1016 GetJob()->job_stop()
4ab97fdf7ff7 patch 8.1.1912: more functions can be used as methods
Bram Moolenaar <Bram@vim.org>
parents: 17571
diff changeset
1017
17456
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 ==============================================================================
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1020 12. Job options *job-options*
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1021
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1022 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
1023 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
1024 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
1025 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
1026 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
1027
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1028 *in_mode* *out_mode* *err_mode*
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1029 "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
1030 "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
1031 "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
1032 See |channel-mode| for the values.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1033
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1034 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
1035 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
1036 specific mode later.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1037
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1038 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
1039 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
1040
14675
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
1041 *job-noblock*
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
1042 "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
1043 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
1044 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
1045 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
1046 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
1047 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
1048 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
1049 let options['noblock'] = 1
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
1050 endif
71c17b688bc6 patch 8.1.0350: Vim may block on ch_sendraw()
Christian Brabandt <cb@256bit.org>
parents: 14421
diff changeset
1051 <
8167
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
1052 *job-callback*
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a
Christian Brabandt <cb@256bit.org>
parents: 8148
diff changeset
1053 "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
1054 channel.
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1055 *job-out_cb* *out_cb*
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1056 "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
1057 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
1058 "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
1059 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
1060
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1061 *job-err_cb* *err_cb*
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1062 "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
1063 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
1064 "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
1065 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
1066 *job-close_cb*
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1067 "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
1068 "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
1069 *job-drop*
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1070 "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
1071 |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
1072 exit_cb is not considered.
10498
883396809b45 commit https://github.com/vim/vim/commit/bc2eada5424bff06f7eb77c032ecc067da52b846
Christian Brabandt <cb@256bit.org>
parents: 10449
diff changeset
1073 *job-exit_cb*
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1074 "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
1075 job and the exit status.
10319
169a62d5bcb9 commit https://github.com/vim/vim/commit/b4ada79aa7d0d1e5da3a659b1a203d7cae9f7f59
Christian Brabandt <cb@256bit.org>
parents: 10244
diff changeset
1076 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
1077 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
1078 |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
1079 handler.
9097
071f9da012fb commit https://github.com/vim/vim/commit/06d2d38ab7564e1f784b1058a4ef4580cd6d1810
Christian Brabandt <cb@256bit.org>
parents: 9076
diff changeset
1080 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
1081 called after the process ends.
8748
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1082 *job-timeout*
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1083 "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
1084 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
1085 default is 2000 (2 seconds).
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1086 *out_timeout* *err_timeout*
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1087 "out_timeout": time Timeout for stdout. Only when using pipes.
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1088 "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
1089 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
1090 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
1091 part specific mode later.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents: 8673
diff changeset
1092
8178
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
1093 *job-stoponexit*
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
1094 "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
1095 |job_stop()| for possible values.
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
1096 "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
1097 The default is "term".
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Christian Brabandt <cb@256bit.org>
parents: 8167
diff changeset
1098
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1099 *job-term*
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1100 "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
1101 stdin/stdout/stderr to it. Similar to using
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1102 `:terminal`.
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1103 NOTE: Not implemented yet!
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1104
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1105 "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
1106 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
1107 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
1108 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
1109 cause I/O errors.
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1110 Existing callbacks and other settings remain.
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1111
11763
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1112 "pty": 1 Use a pty (pseudo-tty) instead of a pipe when
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1113 possible. This is most useful in combination with a
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1114 terminal window, see |terminal|.
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1115 {only on Unix and Unix-like systems}
21f3930dfe6e Documentation updates.
Christian Brabandt <cb@256bit.org>
parents: 11659
diff changeset
1116
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1117 *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
1118 "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
1119 "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
1120 "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
1121 "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
1122 "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
1123 "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
1124 "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
1125 "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
1126
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1127 *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
1128 "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
1129 "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
1130 "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
1131 "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
1132 "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
1133 "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
1134 "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
1135 (see below)
10147
65afd399ffa7 commit https://github.com/vim/vim/commit/169ebb080454357279ad5ad21ac532deaec605e8
Christian Brabandt <cb@256bit.org>
parents: 10054
diff changeset
1136 "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
1137 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
1138
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1139 *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
1140 "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
1141 "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
1142 "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
1143 "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
1144 "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
1145 "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
1146 "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
1147 "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
1148 (see below)
10147
65afd399ffa7 commit https://github.com/vim/vim/commit/169ebb080454357279ad5ad21ac532deaec605e8
Christian Brabandt <cb@256bit.org>
parents: 10054
diff changeset
1149 "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
1150 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
1151
8795
aba2d0a01290 commit https://github.com/vim/vim/commit/7db8f6f4f85e5d0526d23107b2a5e2334dc23354
Christian Brabandt <cb@256bit.org>
parents: 8748
diff changeset
1152 "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
1153 will block
aba2d0a01290 commit https://github.com/vim/vim/commit/7db8f6f4f85e5d0526d23107b2a5e2334dc23354
Christian Brabandt <cb@256bit.org>
parents: 8748
diff changeset
1154
12043
2796a2c9fc17 patch 8.0.0902: cannot specify directory or environment for a job
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
1155 "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
1156 "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
1157 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
1158
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1159
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1160 Writing to a buffer ~
10004
8061455d9179 commit https://github.com/vim/vim/commit/818078ddfbb8cc2546f697c5675a251d095722ec
Christian Brabandt <cb@256bit.org>
parents: 9969
diff changeset
1161 *out_io-buffer*
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1162 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
1163 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
1164
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents: 8392
diff changeset
1165 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
1166 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
1167 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
1168
8392
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents: 8291
diff changeset
1169 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
1170 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
1171 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
1172
9227
ecb621205ed1 commit https://github.com/vim/vim/commit/82af8710bf8d1caeeceafb1370a052cb7d92f076
Christian Brabandt <cb@256bit.org>
parents: 9147
diff changeset
1173 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
1174 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
1175 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
1176 "somename" it will use that buffer.
ecb621205ed1 commit https://github.com/vim/vim/commit/82af8710bf8d1caeeceafb1370a052cb7d92f076
Christian Brabandt <cb@256bit.org>
parents: 9147
diff changeset
1177
ecb621205ed1 commit https://github.com/vim/vim/commit/82af8710bf8d1caeeceafb1370a052cb7d92f076
Christian Brabandt <cb@256bit.org>
parents: 9147
diff changeset
1178 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
1179 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
1180 buffer number.
8291
ac0c43e7af20 commit https://github.com/vim/vim/commit/c7f0ebc6d1e1cdaed816b88a0d6092c5ace615eb
Christian Brabandt <cb@256bit.org>
parents: 8285
diff changeset
1181
ac0c43e7af20 commit https://github.com/vim/vim/commit/c7f0ebc6d1e1cdaed816b88a0d6092c5ace615eb
Christian Brabandt <cb@256bit.org>
parents: 8285
diff changeset
1182 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
1183 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
1184 *out_modifiable* *err_modifiable*
65afd399ffa7 commit https://github.com/vim/vim/commit/169ebb080454357279ad5ad21ac532deaec605e8
Christian Brabandt <cb@256bit.org>
parents: 10054
diff changeset
1185 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
1186 '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
1187 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
1188 change the buffer.
65afd399ffa7 commit https://github.com/vim/vim/commit/169ebb080454357279ad5ad21ac532deaec605e8
Christian Brabandt <cb@256bit.org>
parents: 10054
diff changeset
1189 *out_msg* *err_msg*
65afd399ffa7 commit https://github.com/vim/vim/commit/169ebb080454357279ad5ad21ac532deaec605e8
Christian Brabandt <cb@256bit.org>
parents: 10054
diff changeset
1190 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
1191 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
1192 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
1193
9147
053bc64433ec commit https://github.com/vim/vim/commit/9f5842e63fc63d438cbffcec503e072a06f74dc2
Christian Brabandt <cb@256bit.org>
parents: 9116
diff changeset
1194 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
1195 "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
1196 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
1197
8267
108d30ed34ba commit https://github.com/vim/vim/commit/187db50d0499aecf4cfd42fb4db0a1bebf61c8cd
Christian Brabandt <cb@256bit.org>
parents: 8246
diff changeset
1198 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
1199 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
1200 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
1201
9464
be72f4201a1d commit https://github.com/vim/vim/commit/063b9d15abea041a5bfff3ffc4e219e26fd1d4fa
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
1202 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
1203 stores these as NL bytes).
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1204
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1205
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1206 Writing to a file ~
8540
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16
Christian Brabandt <cb@256bit.org>
parents: 8497
diff changeset
1207 *E920*
8497
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1208 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
1209 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
1210
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151
Christian Brabandt <cb@256bit.org>
parents: 8440
diff changeset
1211 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
1212
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1213 ==============================================================================
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1214 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
1215
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1216 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
1217 echo job_status(job)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1218
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1219 To make a job stop running: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1220 job_stop(job)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1221
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1222 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
1223 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
1224 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
1225 job_stop(job, "kill")
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1226
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7992
diff changeset
1227 For more options see |job_stop()|.
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
1228
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
1229 ==============================================================================
17456
e414281d8bb4 patch 8.1.1726: the eval.txt help file is too big
Bram Moolenaar <Bram@vim.org>
parents: 16808
diff changeset
1230 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
1231
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
1232 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
1233 - 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
1234 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
1235 - 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
1236 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
1237 See |terminal-window|.
20753
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1238 - 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
1239 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
1240
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
1241 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
1242 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
1243
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
1244 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
1245 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
1246 |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
1247 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
1248 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
1249
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
1250 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
1251 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
1252 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
1253 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
1254
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
1255 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
1256 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
1257 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
1258
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
1259 The text of the prompt can be set with the |prompt_setprompt()| function.
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
1260
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
1261 The user can go to Normal mode and navigate through the buffer. This can be
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
1262 useful see older output or copy text.
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
1263
14123
583bf95b6c84 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14019
diff changeset
1264 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
1265 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
1266 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
1267 coming back to the prompt window Insert mode will be restored.
583bf95b6c84 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14019
diff changeset
1268
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
1269 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
1270 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
1271 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
1272
20753
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1273 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
1274 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
1275 prompt. >
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1276
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1277 " Create a channel log so we can see what happens.
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1278 call ch_logfile('logfile', 'w')
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1279
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1280 " Function handling a line of text has been typed.
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1281 func TextEntered(text)
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1282 " Send the text to a shell with Enter appended.
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1283 call ch_sendraw(g:shell_job, a:text .. "\n")
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1284 endfunc
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1285
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1286 " Function handling output from the shell: Added above the prompt.
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1287 func GotOutput(channel, msg)
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1288 call append(line("$") - 1, "- " . a:msg)
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1289 endfunc
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1290
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1291 " Function handling the shell exist: close the window.
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1292 func JobExit(job, status)
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1293 quit!
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1294 endfunc
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1295
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1296 " Start a shell in the background.
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1297 let shell_job = job_start(["/bin/sh"], #{
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1298 \ out_cb: function('GotOutput'),
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1299 \ err_cb: function('GotOutput'),
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1300 \ exit_cb: function('JobExit'),
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1301 \ })
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1302 let shell_ch = job_getchannel(shell_job)
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1303
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1304 new
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1305 set buftype=prompt
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1306 let buf = bufnr('')
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1307 call prompt_setcallback(buf, function("TextEntered"))
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1308 eval prompt_setprompt(buf, "shell command: ")
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1309
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1310 " start accepting shell commands
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1311 startinsert
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1312 <
661eb972cb22 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 20003
diff changeset
1313
7788
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b
Christian Brabandt <cb@256bit.org>
parents:
diff changeset
1314
14421
2f7e67dd088c Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 14123
diff changeset
1315 vim:tw=78:ts=8:noet:ft=help:norl: