vim: runtime/doc/channel.txt annotate

annotate runtime/doc/channel.txt @ 8540:fec8655cf1bf v7.4.1560

commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Author: Bram Moolenaar <Bram@vim.org> Date: Mon Mar 14 23:22:59 2016 +0100 patch 7.4.1560 Problem: Dict options with a dash are more difficult to use. Solution: Use an underscore, so that dict.err_io can be used.

author	Christian Brabandt <cb@256bit.org>
date	Mon, 14 Mar 2016 23:30:05 +0100
parents	da01d5da2cfa
children	ed7251c3e2d3

rev	line source
8540 fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	1 channel.txt For Vim version 7.4. Last change: 2016 Mar 14
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 DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	10
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	11 Vim uses channels to communicate with other processes.
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	12 A channel uses a socket or pipes socket-interface
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	13 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	14
7924 00d64eb49ce1 commit https://github.com/vim/vim/commit/681baaf4a4c81418693dcafb81421a8614832e91 Christian Brabandt <cb@256bit.org> parents: 7864 diff changeset	15 Vim current supports up to 10 simultaneous channels.
7788 192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	16 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	17
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	18 1. Overview \|job-channel-overview\|
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	19 2. Channel demo \|channel-demo\|
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	20 3. Opening a channel \|channel-open\|
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	21 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	22 5. Channel commands \|channel-commands\|
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	23 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	24 7. More channel functions \|channel-more\|
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	25 8. Starting a job with a channel \|job-start\|
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	26 9. Starting a job without a channel \|job-start-nochannel\|
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	27 10. Job options \|job-options\|
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	28 11. Controlling a job \|job-control\|
7788 192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	29
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	30 {Vi does not have any of these features}
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	31 {only when compiled with the \|+channel\| feature for channel stuff}
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	32 {only when compiled with the \|+job\| feature for job stuff}
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:
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	38 1. A deamon, serving several Vim instances.
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.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	60 - Using a deamon, connecting over a socket in JSON mode. E.g. to lookup
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	61 crosss-refrences in a database.
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 ==============================================================================
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	64 2. Channel demo channel-demo
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
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	123 {options} is a dictionary with optional entries:
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 in_mode out_mode err_mode
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	131 "in_mode" mode specifically for stdin, only when using pipes
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	132 "out_mode" mode specifically for stdout, only when using pipes
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	133 "err_mode" mode specifically for stderr, only when using pipes
8167 9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	134 Note: when setting "mode" the part specific mode is
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	135 overwritten. Therefore set "mode" first and the part specific
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	136 mode later.
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	137
8392 1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8291 diff changeset	138 Note: when writing to a file or buffer and when reading from a
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8291 diff changeset	139 buffer NL mode is used by default.
8267 108d30ed34ba commit https://github.com/vim/vim/commit/187db50d0499aecf4cfd42fb4db0a1bebf61c8cd Christian Brabandt <cb@256bit.org> parents: 8246 diff changeset	140
8540 fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	141 channel-callback E921
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	142 "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	143 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	144 and the received message. Example: >
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	145 func Handle(channel, msg)
7788 192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	146 echo 'Received: ' . a:msg
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	147 endfunc
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	148 let channel = ch_open("localhost:8765", {"callback": "Handle"})
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	149 <
8178 e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686 Christian Brabandt <cb@256bit.org> parents: 8167 diff changeset	150 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	151 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	152 When "mode" is "nl" the "msg" argument is one message,
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686 Christian Brabandt <cb@256bit.org> parents: 8167 diff changeset	153 excluding the NL.
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686 Christian Brabandt <cb@256bit.org> parents: 8167 diff changeset	154 When "mode" is "raw" the "msg" argument is the whole message
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686 Christian Brabandt <cb@256bit.org> parents: 8167 diff changeset	155 as a string.
8540 fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	156 out_cb
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	157 "out_cb" A function like "callback" but used for stdout. Only for when
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	158 the channel uses pipes. When "out_cb" wasn't set the channel
8167 9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	159 callback is used.
8540 fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	160 err_cb
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	161 "err_cb" A function like "callback" but used for stderr. Only for when
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	162 the channel uses pipes. When "err_cb" wasn't set the channel
8167 9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	163 callback is used.
7788 192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	164
8540 fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	165 close_cb
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	166 "close_cb" A function that is called when the channel gets closed, other
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	167 than by calling ch_close(). It should be defined like this: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	168 func MyCloseHandler(channel)
8178 e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686 Christian Brabandt <cb@256bit.org> parents: 8167 diff changeset	169 < waittime
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	170 "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	171 milliseconds. A negative number waits forever.
f16bfe02cef1 commit https://github.com/vim/vim/commit/f391327adbbffb11180cf6038a92af1ed144e907 Christian Brabandt <cb@256bit.org> parents: 8178 diff changeset	172
f16bfe02cef1 commit https://github.com/vim/vim/commit/f391327adbbffb11180cf6038a92af1ed144e907 Christian Brabandt <cb@256bit.org> parents: 8178 diff changeset	173 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	174 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	175 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	176 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	177 msec at least.
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	178
8167 9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	179 "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	180 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	181 seconds).
8540 fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	182 out_timeout err_timeout
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	183 "out_timeout" Timeout for stdout. Only when using pipes.
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	184 "err_timeout" Timeout for stderr. Only when using pipes.
8167 9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	185 Note: when setting "timeout" the part specific mode is
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	186 overwritten. Therefore set "timeout" first and the part
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	187 specific mode later.
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	188
7967 45ea5ebf3a98 commit https://github.com/vim/vim/commit/595e64e259faefb330866852e1b9f6168544572a Christian Brabandt <cb@256bit.org> parents: 7957 diff changeset	189 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	190 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	191
8178 e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686 Christian Brabandt <cb@256bit.org> parents: 8167 diff changeset	192 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	193 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	194 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	195
8178 e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686 Christian Brabandt <cb@256bit.org> parents: 8167 diff changeset	196 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	197 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	198 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	199
8392 1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8291 diff changeset	200 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	201 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	202 `:redraw`.
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8291 diff changeset	203
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	204 The timeout can be changed: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	205 call ch_setoptions(channel, {'timeout': msec})
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	206 <
8178 e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686 Christian Brabandt <cb@256bit.org> parents: 8167 diff changeset	207 channel-close E906
7788 192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	208 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	209 call ch_close(channel)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	210 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	211 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	212 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	213 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	214
7992 78106b0f2c56 commit https://github.com/vim/vim/commit/cbebd4879cc78e670d79b2c57dc33d7b911c962a Christian Brabandt <cb@256bit.org> parents: 7967 diff changeset	215 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	216 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	217 ch_open() fails quickly. On MS-Windows "waittime" applies.
7864 6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	218 E898 E899 E900 E901 E902
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	219
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	220 If there is an error reading or writing a channel it will be closed.
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	221 E896 E630 E631
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	222
7788 192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	223 ==============================================================================
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	224 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	225
8094 18a3f0f05244 commit https://github.com/vim/vim/commit/910b8aac5dc4693c4508b7acd2cef0bbfac04242 Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	226 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	227 let response = ch_evalexpr(channel, {expr})
7788 192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	228 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	229
8094 18a3f0f05244 commit https://github.com/vim/vim/commit/910b8aac5dc4693c4508b7acd2cef0bbfac04242 Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	230 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	231 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	232
8178 e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686 Christian Brabandt <cb@256bit.org> parents: 8167 diff changeset	233 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	234 handle the response: >
8285 e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f Christian Brabandt <cb@256bit.org> parents: 8267 diff changeset	235 call ch_sendexpr(channel, {expr})
7788 192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	236
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	237 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	238 asynchronously: >
8178 e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686 Christian Brabandt <cb@256bit.org> parents: 8167 diff changeset	239 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	240
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	241 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	242 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	243 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	244 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	245
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	246 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	247 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	248 [12,"hello"] ~
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	249
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	250 The format of the JSON sent is:
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	251 [{number},{expr}]
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	252
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	253 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	254 (if any):
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	255
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	256 [{number},{response}]
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 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	259 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	260
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	261 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	262 the message by parsing the JSON. It will only accept the message if the end
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	263 was received.
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	264
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	265 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	266 message, it must use the number zero:
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	267 [0,{response}]
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	268
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	269 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	270 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	271
8392 1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8291 diff changeset	272 On read error or ch_close(), when using a socket with RAW or NL mode, the
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8291 diff changeset	273 string "DETACH\n" is sent, if still possible. The channel will then be
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8291 diff changeset	274 inactive.
7788 192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	275
8285 e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f Christian Brabandt <cb@256bit.org> parents: 8267 diff changeset	276 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	277 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	278 decoding.
7992 78106b0f2c56 commit https://github.com/vim/vim/commit/cbebd4879cc78e670d79b2c57dc33d7b911c962a Christian Brabandt <cb@256bit.org> parents: 7967 diff changeset	279
7788 192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	280 ==============================================================================
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	281 5. Channel commands channel-commands
7788 192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	282
8094 18a3f0f05244 commit https://github.com/vim/vim/commit/910b8aac5dc4693c4508b7acd2cef0bbfac04242 Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	283 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	284 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	285
7864 6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	286 Possible commands are: E903 E904 E905
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	287 ["redraw" {forced}]
7788 192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	288 ["ex", {Ex command}]
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	289 ["normal", {Normal mode command}]
8167 9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	290 ["expr", {expression}, {number}]
7788 192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	291 ["expr", {expression}]
8167 9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	292 ["call", {func name}, {argument list}, {number}]
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	293 ["call", {func name}, {argument list}]
7788 192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	294
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	295 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	296 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	297 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	298 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	299 ["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	300
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	301 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	302 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	303 higher.
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	304
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	305
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	306 Command "redraw" ~
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 The other commands do not update the screen, so that you can send a sequence
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	309 of commands without the cursor moving around. You must end with the "redraw"
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	310 command to show any changed text and show the cursor where it belongs.
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 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	313 ["redraw", ""] ~
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	314 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	315 ["redraw", "force"] ~
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	316
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	317
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	318 Command "ex" ~
7788 192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	319
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	320 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	321 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	322 ["ex","call myscript#MyFunc(arg)"]
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	323
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	324 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	325
7788 192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	326
7864 6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	327 Command "normal" ~
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	328
7924 00d64eb49ce1 commit https://github.com/vim/vim/commit/681baaf4a4c81418693dcafb81421a8614832e91 Christian Brabandt <cb@256bit.org> parents: 7864 diff changeset	329 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	330 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	331 ["normal" "zO"]
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	332
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	333
8167 9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	334 Command "expr" with response ~
7788 192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	335
8167 9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	336 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	337 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	338 ["expr","line('$')", -2] ~
7864 6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	339
8167 9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	340 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	341 [-2, "last line"] ~
f5da459c5698 commit https://github.com/vim/vim/commit/e0fa3742ead676a3074a10edadbc955e1a89153d Christian Brabandt <cb@256bit.org> parents: 8094 diff changeset	342 The format is:
7788 192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	343 [{number}, {result}]
8267 108d30ed34ba commit https://github.com/vim/vim/commit/187db50d0499aecf4cfd42fb4db0a1bebf61c8cd Christian Brabandt <cb@256bit.org> parents: 8246 diff changeset	344
7864 6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	345 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	346 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	347 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	348
7864 6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	349 {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	350 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	351 "ERROR".
7864 6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	352
6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	353
8167 9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	354 Command "expr" without a response ~
7864 6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	355
8167 9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	356 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	357 Example:
7864 6b0891de44a9 commit https://github.com/vim/vim/commit/fb1f62691eae7c79a28b3b17a60e72ce198c71a2 Christian Brabandt <cb@256bit.org> parents: 7788 diff changeset	358 ["expr","setline('$', ['one', 'two', 'three'])"] ~
8167 9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	359 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	360
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	361
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	362 Command "call" ~
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	363
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	364 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	365 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	366 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	367 concatenating them. Example:
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	368 ["call", "line", ["$"], -2] ~
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	369
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	370 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	371 ["call", "setline", ["$", ["one", "two", "three"]]] ~
7788 192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	372
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	373 ==============================================================================
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	374 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	375
8094 18a3f0f05244 commit https://github.com/vim/vim/commit/910b8aac5dc4693c4508b7acd2cef0bbfac04242 Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	376 If mode is RAW or NL then a message can be send like this: >
8285 e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f Christian Brabandt <cb@256bit.org> parents: 8267 diff changeset	377 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	378
7788 192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	379 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	380 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	381 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	382 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	383
8094 18a3f0f05244 commit https://github.com/vim/vim/commit/910b8aac5dc4693c4508b7acd2cef0bbfac04242 Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	384 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	385 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	386 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	387 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	388 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	389
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	390 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	391 call ch_sendraw(channel, {string})
7788 192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	392 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	393 it.
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	394
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	395 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	396 asynchronously: >
8285 e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f Christian Brabandt <cb@256bit.org> parents: 8267 diff changeset	397 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	398
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	399 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	400 \|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	401
8285 e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f Christian Brabandt <cb@256bit.org> parents: 8267 diff changeset	402 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	403
7788 192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	404 ==============================================================================
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	405 7. More channel functions channel-more
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	406
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	407 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	408 are:
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	409 "fail" Failed to open the channel.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	410 "open" The channel can be used.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	411 "closed" The channel was closed.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	412
8267 108d30ed34ba commit https://github.com/vim/vim/commit/187db50d0499aecf4cfd42fb4db0a1bebf61c8cd Christian Brabandt <cb@256bit.org> parents: 8246 diff changeset	413 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	414
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	415 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	416 let output = ch_read(channel)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	417 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	418 message that is available: >
8167 9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	419 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	420 When no message was available then the result is v:none for a JSON or JS mode
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	421 channels, an empty string for a RAW or NL channel.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	422
8167 9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	423 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	424 let output = ch_readraw(channel)
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	425 To read the error output: >
8167 9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	426 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	427
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	428 ==============================================================================
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	429 8. Starting a job with a channel job-start job
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	430
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	431 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	432 let job = job_start(command, {options})
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	433
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	434 You can get the channel with: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	435 let channel = job_getchannel(job)
7788 192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	436
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	437 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	438 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	439 been received and not parsed correctly.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	440
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	441 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	442 a handler for stdout: >
8540 fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	443 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	444 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	445 it like this: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	446 func MyHandler(channel, msg)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	447
8178 e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686 Christian Brabandt <cb@256bit.org> parents: 8167 diff changeset	448 Without the handler you need to read the output with \|ch_read()\| or
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686 Christian Brabandt <cb@256bit.org> parents: 8167 diff changeset	449 \|ch_readraw()\|.
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	450
8540 fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	451 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	452 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	453 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	454 \ "err_cb": "ErrHandler"})
7788 192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	455
8178 e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686 Christian Brabandt <cb@256bit.org> parents: 8167 diff changeset	456 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	457 "callback" option: >
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686 Christian Brabandt <cb@256bit.org> parents: 8167 diff changeset	458 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	459
8285 e05e28dcb590 commit https://github.com/vim/vim/commit/8b1862a31639becadcbbca5dc2eaa92db73e8e5f Christian Brabandt <cb@256bit.org> parents: 8267 diff changeset	460 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	461 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	462
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	463 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	464 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	465 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	466 \ {'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	467 sbuf dummy
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	468
8440 4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8392 diff changeset	469
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8392 diff changeset	470 Job input from a buffer ~
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8392 diff changeset	471
8392 1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8291 diff changeset	472 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	473 let job = job_start({command},
8540 fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	474 \ {'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	475 <
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8291 diff changeset	476 E915 E918
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8291 diff changeset	477 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	478 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	479
8540 fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	480 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	481 and "in_bot" options.
8392 1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8291 diff changeset	482
8540 fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	483 A special mode is when "in_top" is set to zero and "in_bot" is not set: Every
8440 4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8392 diff changeset	484 time a line is added to the buffer, the last-but-one line will be send to the
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8392 diff changeset	485 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	486 Enter.
8392 1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8291 diff changeset	487
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	488 ==============================================================================
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	489 9. Starting a job without a channel job-start-nochannel
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	490
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	491 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	492 let job = job_start(command,
8540 fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	493 \ {"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	494
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	495 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	496
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	497 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	498 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	499 avoid it getting stuck.
7788 192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	500
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	501 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	502
8497 da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151 Christian Brabandt <cb@256bit.org> parents: 8440 diff changeset	503 job-start-if-needed
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151 Christian Brabandt <cb@256bit.org> parents: 8440 diff changeset	504 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	505 like this: >
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	506 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	507 if ch_status(channel) == "fail"
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	508 let job = job_start(command)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	509 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	510 endif
8497 da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151 Christian Brabandt <cb@256bit.org> parents: 8440 diff changeset	511
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151 Christian Brabandt <cb@256bit.org> parents: 8440 diff changeset	512 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	513 available.
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	514
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	515 ==============================================================================
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	516 10. Job options job-options
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	517
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	518 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	519 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	520 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	521 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	522 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	523
8167 9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	524 job-callback
9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	525 "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	526 channel.
8540 fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	527 job-out_cb
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	528 "out_cb": handler Callback for when there is something to read on
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	529 stdout.
8540 fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	530 job-err_cb
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	531 "err_cb": handler Callback for when there is something to read on
8167 9ca3885edfed commit https://github.com/vim/vim/commit/decb14d68c3e3736566466aed2190f1d1cab587a Christian Brabandt <cb@256bit.org> parents: 8148 diff changeset	532 stderr.
8540 fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	533 job-close_cb
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	534 "close_cb": handler Callback for when the channel is closed. Same as
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	535 "close_cb" on ch_open().
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	536 job-exit_cb
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	537 "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	538 job and the exit status.
8178 e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686 Christian Brabandt <cb@256bit.org> parents: 8167 diff changeset	539 Vim checks about every 10 seconds for jobs that ended.
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686 Christian Brabandt <cb@256bit.org> parents: 8167 diff changeset	540 The callback can also be triggered by calling
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686 Christian Brabandt <cb@256bit.org> parents: 8167 diff changeset	541 \|job_status()\|.
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686 Christian Brabandt <cb@256bit.org> parents: 8167 diff changeset	542 job-stoponexit
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686 Christian Brabandt <cb@256bit.org> parents: 8167 diff changeset	543 "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	544 \|job_stop()\| for possible values.
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686 Christian Brabandt <cb@256bit.org> parents: 8167 diff changeset	545 "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	546 The default is "term".
e77efd7a7dad commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686 Christian Brabandt <cb@256bit.org> parents: 8167 diff changeset	547
8497 da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151 Christian Brabandt <cb@256bit.org> parents: 8440 diff changeset	548 job-term
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	549 "term": "open" Start a terminal and connect the job
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	550 stdin/stdout/stderr to it.
8497 da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151 Christian Brabandt <cb@256bit.org> parents: 8440 diff changeset	551 NOTE: Not implemented yet!
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	552
8497 da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151 Christian Brabandt <cb@256bit.org> parents: 8440 diff changeset	553 "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	554 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	555 will be disconnected from what they were used before.
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151 Christian Brabandt <cb@256bit.org> parents: 8440 diff changeset	556 If the channel was still use by another job this may
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151 Christian Brabandt <cb@256bit.org> parents: 8440 diff changeset	557 cause I/O errors.
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151 Christian Brabandt <cb@256bit.org> parents: 8440 diff changeset	558 Existing callbacks and other settings remain.
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151 Christian Brabandt <cb@256bit.org> parents: 8440 diff changeset	559
8540 fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	560 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	561 "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	562 "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	563 "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	564 "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	565 "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	566 "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	567 "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	568 "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	569
8540 fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	570 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	571 "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	572 "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	573 "out_io": "file" stdout writes to a file
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	574 "out_io": "buffer" stdout appends to a buffer
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	575 "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	576 "out_buf": number the number of the buffer to write to
8267 108d30ed34ba commit https://github.com/vim/vim/commit/187db50d0499aecf4cfd42fb4db0a1bebf61c8cd Christian Brabandt <cb@256bit.org> parents: 8246 diff changeset	577
8540 fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	578 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	579 "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	580 "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	581 "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	582 "err_io": "file" stderr writes to a file
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	583 "err_io": "buffer" stderr appends to a buffer
fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	584 "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	585 "err_buf": number the number of the buffer to write to
8497 da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151 Christian Brabandt <cb@256bit.org> parents: 8440 diff changeset	586
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151 Christian Brabandt <cb@256bit.org> parents: 8440 diff changeset	587
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151 Christian Brabandt <cb@256bit.org> parents: 8440 diff changeset	588 Writing to a buffer ~
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	589
8540 fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	590 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	591 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	592
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8392 diff changeset	593 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	594 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	595 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	596
8392 1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8291 diff changeset	597 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	598 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	599 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	600
8267 108d30ed34ba commit https://github.com/vim/vim/commit/187db50d0499aecf4cfd42fb4db0a1bebf61c8cd Christian Brabandt <cb@256bit.org> parents: 8246 diff changeset	601 The name of the buffer is compared the full name of existing buffers. If
8291 ac0c43e7af20 commit https://github.com/vim/vim/commit/c7f0ebc6d1e1cdaed816b88a0d6092c5ace615eb Christian Brabandt <cb@256bit.org> parents: 8285 diff changeset	602 there is a match that buffer is used. Otherwise a new buffer is created.
ac0c43e7af20 commit https://github.com/vim/vim/commit/c7f0ebc6d1e1cdaed816b88a0d6092c5ace615eb Christian Brabandt <cb@256bit.org> parents: 8285 diff changeset	603 Use an empty name to always create a new buffer. \|ch_getbufnr()\| can then be
ac0c43e7af20 commit https://github.com/vim/vim/commit/c7f0ebc6d1e1cdaed816b88a0d6092c5ace615eb Christian Brabandt <cb@256bit.org> parents: 8285 diff changeset	604 used to get the buffer number.
ac0c43e7af20 commit https://github.com/vim/vim/commit/c7f0ebc6d1e1cdaed816b88a0d6092c5ace615eb Christian Brabandt <cb@256bit.org> parents: 8285 diff changeset	605
ac0c43e7af20 commit https://github.com/vim/vim/commit/c7f0ebc6d1e1cdaed816b88a0d6092c5ace615eb Christian Brabandt <cb@256bit.org> parents: 8285 diff changeset	606 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	607 you prefer other settings, create the buffer first and pass the buffer number.
8267 108d30ed34ba commit https://github.com/vim/vim/commit/187db50d0499aecf4cfd42fb4db0a1bebf61c8cd Christian Brabandt <cb@256bit.org> parents: 8246 diff changeset	608
108d30ed34ba commit https://github.com/vim/vim/commit/187db50d0499aecf4cfd42fb4db0a1bebf61c8cd Christian Brabandt <cb@256bit.org> parents: 8246 diff changeset	609 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	610 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	611 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	612
108d30ed34ba commit https://github.com/vim/vim/commit/187db50d0499aecf4cfd42fb4db0a1bebf61c8cd Christian Brabandt <cb@256bit.org> parents: 8246 diff changeset	613 Undo is synced for every added line.
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	614
8497 da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151 Christian Brabandt <cb@256bit.org> parents: 8440 diff changeset	615
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151 Christian Brabandt <cb@256bit.org> parents: 8440 diff changeset	616 Writing to a file ~
8540 fec8655cf1bf commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Christian Brabandt <cb@256bit.org> parents: 8497 diff changeset	617 E920
8497 da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151 Christian Brabandt <cb@256bit.org> parents: 8440 diff changeset	618 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	619 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	620
da01d5da2cfa commit https://github.com/vim/vim/commit/77cdfd10382e01cc51f4ba1a9177032351843151 Christian Brabandt <cb@256bit.org> parents: 8440 diff changeset	621 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	622
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	623 ==============================================================================
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	624 11. Controlling a job job-control
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	625
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	626 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	627 echo job_status(job)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	628
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	629 To make a job stop running: >
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	630 job_stop(job)
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	631
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	632 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	633 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	634 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	635 job_stop(job, "kill")
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	636
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7992 diff changeset	637 For more options see \|job_stop()\|.
7788 192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	638
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	639
192ae655ac91 commit https://github.com/vim/vim/commit/3b5f929b18492fec291d1ec95a91f54e5912c03b Christian Brabandt <cb@256bit.org> parents: diff changeset	640 vim:tw=78:ts=8:ft=help:norl:

Mercurial > vim

annotate runtime/doc/channel.txt @ 8540:fec8655cf1bf v7.4.1560