Mercurial > vim

annotate runtime/doc/channel.txt @ 18652:94b88fa5825d v8.1.2318

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