/usr/share/doc/vim-doc/html/channel.html is in vim-doc 2:7.4.1689-3ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 | <HTML>
<HEAD>
<META HTTP-EQUIV="Content-type" content="text/html; charset=ISO-8859-1">
<TITLE>Vim documentation: channel</TITLE>
</HEAD>
<BODY BGCOLOR="#ffffff">
<H1>Vim documentation: channel</H1>
<A NAME="top"></A>
<A HREF="index.html">main help file</A>
<HR>
<PRE>
*<A NAME="channel.txt"></A><B>channel.txt</B>* For Vim version 7.4. Last change: 2016 Mar 28
VIM REFERENCE MANUAL by <A HREF="intro.html#Bram">Bram</A> <A HREF="intro.html#Moolenaar">Moolenaar</A>
Inter-process communication *<A NAME="channel"></A><B>channel</B>*
DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT
Vim uses channels to communicate with other processes.
A <A HREF="#channel">channel</A> uses a socket or pipes *<A NAME="socket-interface"></A><B>socket-interface</B>*
Jobs can be used to start processes and communicate with them.
Vim current supports up to 10 simultaneous channels.
The Netbeans interface also uses a <A HREF="#channel">channel</A>. |<A HREF="netbeans.html#netbeans">netbeans</A>|
1. Overview |<A HREF="#job-channel-overview">job-channel-overview</A>|
2. <A HREF="eval.html#Channel">Channel</A> demo |<A HREF="#channel-demo">channel-demo</A>|
3. Opening a channel |<A HREF="#channel-open">channel-open</A>|
4. Using a JSON or JS channel |<A HREF="#channel-use">channel-use</A>|
5. <A HREF="eval.html#Channel">Channel</A> commands |<A HREF="#channel-commands">channel-commands</A>|
6. Using a RAW or NL channel |<A HREF="#channel-raw">channel-raw</A>|
7. More channel <A HREF="eval.html#functions">functions</A> |<A HREF="#channel-more">channel-more</A>|
8. Starting a job with a <A HREF="#channel">channel</A> |<A HREF="#job-start">job-start</A>|
9. Starting a job without a channel |<A HREF="#job-start-nochannel">job-start-nochannel</A>|
10. <A HREF="eval.html#Job">Job</A> options |<A HREF="#job-options">job-options</A>|
11. Controlling a job |<A HREF="#job-control">job-control</A>|
{Vi does not have any of these features}
{only when compiled with the |<A HREF="various.html#+channel">+channel</A>| feature for channel stuff}
{only when compiled with the |<A HREF="various.html#+job">+job</A>| feature for job stuff}
==============================================================================
1. Overview *<A NAME="job-channel-overview"></A><B>job-channel-overview</B>*
There are four main types of jobs:
1. A deamon, serving several Vim instances.
Vim connects to <A HREF="motion.html#it">it</A> with a socket.
2. One <A HREF="#job">job</A> working with one Vim instance, asynchronously.
Uses a socket or pipes.
3. A <A HREF="#job">job</A> performing some work for a short time, asynchronously.
Uses a socket or pipes.
4. Running a <A HREF="change.html#filter">filter</A>, synchronously.
Uses pipes.
For when using sockets See |<A HREF="#job-start">job-start</A>|, |<A HREF="#job-start-nochannel">job-start-nochannel</A>| and
|<A HREF="#channel-open">channel-open</A>|. For 2 and 3, one or more jobs using pipes, see |<A HREF="#job-start">job-start</A>|.
For 4 use the ":{range}!cmd" command, see |<A HREF="change.html#filter">filter</A>|.
Over the socket and pipes these protocols are available:
RAW nothing known, Vim cannot tell where a message ends
NL every message ends in a NL (newline) character
JSON JSON encoding |<A HREF="eval.html#json_encode()">json_encode()</A>|
JS JavaScript style JSON-like encoding |<A HREF="eval.html#js_encode()">js_encode()</A>|
Common combination are:
- Using a <A HREF="#job">job</A> connected through pipes in NL mode. E.g., to run a style
checker and receive <A HREF="message.html#errors">errors</A> and warnings.
- Using a deamon, connecting over a socket in JSON mode. E.g. to lookup
crosss-refrences in a database.
==============================================================================
2. <A HREF="eval.html#Channel">Channel</A> demo *<A NAME="channel-demo"></A><B>channel-demo</B>*
This requires <A HREF="if_pyth.html#Python">Python</A>. The demo program can be found in
$VIMRUNTIME/tools/demoserver.py
Run <A HREF="motion.html#it">it</A> in one terminal. We will call this T1.
Run Vim in another terminal. Connect to the demo server with:
<B> let channel = ch_open('localhost:8765')</B>
In T1 you should see:
<B><FONT COLOR="PURPLE"> === socket opened === </FONT></B>
You can now send a message to the server:
<B> echo ch_evalexpr(channel, 'hello!')</B>
The message is received in T1 and a response is sent back to Vim.
You can see the raw <A HREF="message.html#messages">messages</A> in T1. What Vim sends is:
<B><FONT COLOR="PURPLE"> [1,"hello!"] </FONT></B>
And the response is:
<B><FONT COLOR="PURPLE"> [1,"got it"] </FONT></B>
The number will increase every time you send a message.
The server can send a command to Vim. Type this on T1 (literally, including
the quotes):
<B><FONT COLOR="PURPLE"> ["ex","echo 'hi there'"] </FONT></B>
And you should see the message in Vim. You can move the cursor a <A HREF="motion.html#word">word</A> forward:
<B><FONT COLOR="PURPLE"> ["normal","w"] </FONT></B>
To handle asynchronous communication a callback needs to be used:
<B> func MyHandler(channel, msg)</B>
<B> echo "from the handler: " . a:msg</B>
<B> endfunc</B>
<B> call ch_sendexpr(channel, 'hello!', {'callback': "MyHandler"})</B>
Vim will not wait for a response. Now the server can send the response later
and MyHandler will be invoked.
Instead of giving a callback with every send call, <A HREF="motion.html#it">it</A> can also be specified
when opening the <A HREF="#channel">channel</A>:
<B> call ch_close(channel)</B>
<B> let channel = ch_open('localhost:8765', {'callback': "MyHandler"})</B>
<B> call ch_sendexpr(channel, 'hello!')</B>
When trying out channels it's useful to see what is going on. You can tell
Vim to write lines in log file:
<B> call ch_logfile('channellog', 'w')</B>
See |<A HREF="eval.html#ch_logfile()">ch_logfile()</A>|.
==============================================================================
3. Opening a <A HREF="#channel">channel</A> *<A NAME="channel-open"></A><B>channel-open</B>*
To open a <A HREF="#channel">channel</A>:
<B> let channel = ch_open({address} [, {options}])</B>
<B> if ch_status(channel) == "open"</B>
<B> " use the channel</B>
Use |<A HREF="eval.html#ch_status()">ch_status()</A>| to see if the <A HREF="#channel">channel</A> could be opened.
<A HREF="cmdline.html#{address}">{address}</A> has the form "hostname:port". E.g., "localhost:8765".
{options} is a dictionary with optional entries: *<A NAME="channel-open-options"></A><B>channel-open-options</B>*
"mode" can be: *<A NAME="channel-mode"></A><B>channel-mode</B>*
"json" - Use JSON, see below; most convenient way. Default.
"js" - Use JS (JavaScript) encoding, more efficient than JSON.
"nl" - Use <A HREF="message.html#messages">messages</A> that end in a NL character
"raw" - Use raw <A HREF="message.html#messages">messages</A>
*<A NAME="channel-callback"></A><B>channel-callback</B>* *<A NAME="E921"></A><B>E921</B>*
"callback" A function that is called when a message is received that is
not handled otherwise. It gets two arguments: the <A HREF="#channel">channel</A>
and the received message. Example:
<B> func Handle(channel, msg)</B>
<B> echo 'Received: ' . a:msg</B>
<B> endfunc</B>
<B> let channel = ch_open("localhost:8765", {"callback": "Handle"})</B>
When "mode" is "json" or "js" the "msg" argument is the body
of the received message, converted to Vim types.
When "mode" is "nl" the "msg" argument is one message,
excluding the NL.
When "mode" is "raw" the "msg" argument is the whole message
<A HREF="motion.html#as">as</A> a <A HREF="eval.html#string">string</A>.
For all callbacks: Use |<A HREF="eval.html#function()">function()</A>| to bind <A HREF="motion.html#it">it</A> to arguments
and/or a <A HREF="eval.html#Dictionary">Dictionary</A>. Or use the form "dict.function" to bind
the <A HREF="eval.html#Dictionary">Dictionary</A>.
*<A NAME="close_cb"></A><B>close_cb</B>*
"<A HREF="#close_cb">close_cb</A>" A function that is called when the <A HREF="#channel">channel</A> gets closed, other
than by calling <A HREF="eval.html#ch_close()">ch_close()</A>. It should be defined like this:
<B> func MyCloseHandler(channel)</B>
*<A NAME="waittime"></A><B>waittime</B>*
"<A HREF="#waittime">waittime</A>" The time to wait for the connection to be made in
milliseconds. A negative number waits forever.
The default is zero, don't wait, which is useful if a local
server is supposed to be running already. On <A HREF="os_unix.html#Unix">Unix</A> Vim
actually uses a 1 msec timeout, that is required on many
systems. Use a larger value for a remote server, e.g. 10
msec at least.
*<A NAME="channel-timeout"></A><B>channel-timeout</B>*
"timeout" The time to wait for a request when blocking, E.g. when using
<A HREF="eval.html#ch_evalexpr()">ch_evalexpr()</A>. In milliseconds. The default is 2000 (2
seconds).
When "mode" is "json" or "js" the "callback" is optional. When omitted <A HREF="motion.html#it">it</A> is
only possible to receive a message after sending one.
To change the <A HREF="#channel">channel</A> options after opening <A HREF="motion.html#it">it</A> use |<A HREF="eval.html#ch_setoptions()">ch_setoptions()</A>|. The
arguments are similar to what is passed to |<A HREF="eval.html#ch_open()">ch_open()</A>|, but "<A HREF="#waittime">waittime</A>" cannot
be given, since that only applies to opening the <A HREF="#channel">channel</A>.
For example, the handler can be added or changed:
<B> call ch_setoptions(channel, {'callback': callback})</B>
When "callback" is empty (zero or an empty <A HREF="eval.html#string">string</A>) the handler is removed.
After a callback has been invoked Vim will update the screen and put the
cursor back where <A HREF="motion.html#it">it</A> belongs. Thus the callback should not need to <A HREF="diff.html#do">do</A>
`:redraw`.
The timeout can be changed:
<B> call ch_setoptions(channel, {'timeout': msec})</B>
*<A NAME="channel-close"></A><B>channel-close</B>* *<A NAME="E906"></A><B>E906</B>*
Once done with the <A HREF="#channel">channel</A>, disconnect <A HREF="motion.html#it">it</A> like this:
<B> call ch_close(channel)</B>
When a socket is used this will close the socket for both directions. When
pipes are used (stdin/stdout/stderr) they are all closed. This might not be
what you want! Stopping the <A HREF="#job">job</A> with <A HREF="eval.html#job_stop()">job_stop()</A> might be better.
All readahead is discarded, callbacks will no longer be invoked.
Note that a <A HREF="#channel">channel</A> is closed in three stages:
- The I/O ends, log message: "Closing channel". There can still be queued
<A HREF="message.html#messages">messages</A> to read or callbacks to invoke.
- The readahead is cleared, log message: "Clearing channel". Some <A HREF="eval.html#variables">variables</A>
may still reference the <A HREF="#channel">channel</A>.
- The <A HREF="#channel">channel</A> is freed, log message: "Freeing channel".
When the <A HREF="#channel">channel</A> can't be opened you will get an error message. There is a
difference between <A HREF="os_win32.html#MS-Windows">MS-Windows</A> and <A HREF="os_unix.html#Unix">Unix</A>: On <A HREF="os_unix.html#Unix">Unix</A> when the port doesn't exist
<A HREF="eval.html#ch_open()">ch_open()</A> fails quickly. On <A HREF="os_win32.html#MS-Windows">MS-Windows</A> "<A HREF="#waittime">waittime</A>" applies.
*<A NAME="E898"></A><B>E898</B>* *<A NAME="E899"></A><B>E899</B>* *<A NAME="E900"></A><B>E900</B>* *<A NAME="E901"></A><B>E901</B>* *<A NAME="E902"></A><B>E902</B>*
If there is an error reading or <A HREF="editing.html#writing">writing</A> a <A HREF="#channel">channel</A> <A HREF="motion.html#it">it</A> will be closed.
*<A NAME="E896"></A><B>E896</B>* *<A NAME="E630"></A><B>E630</B>* *<A NAME="E631"></A><B>E631</B>*
==============================================================================
4. Using a JSON or JS <A HREF="#channel">channel</A> *<A NAME="channel-use"></A><B>channel-use</B>*
If mode is JSON then a message can be sent synchronously like this:
<B> let response = ch_evalexpr(channel, {expr})</B>
This awaits a response from the other side.
When mode is JS this works the same, except that the <A HREF="message.html#messages">messages</A> use
JavaScript encoding. See |<A HREF="eval.html#js_encode()">js_encode()</A>| for the difference.
To send a message, without handling a response or letting the <A HREF="#channel">channel</A> callback
handle the response:
<B> call ch_sendexpr(channel, {expr})</B>
To send a message and letting the response handled by a specific function,
asynchronously:
<B> call ch_sendexpr(channel, {expr}, {'callback': Handler})</B>
Vim will match the response with the request using the message ID. Once the
response is received the callback will be invoked. Further responses with the
same ID will be ignored. If your server sends back multiple responses you
need to send them with ID zero, they will be passed to the <A HREF="#channel">channel</A> callback.
The {expr} is converted to JSON and wrapped in an array. An example of the
message that the receiver will get when {expr} is the <A HREF="eval.html#string">string</A> "hello":
<B><FONT COLOR="PURPLE"> [12,"hello"] </FONT></B>
The format of the JSON sent is:
[{number},{expr}]
In which {number} is different every time. It must be used in the response
(if any):
[{number},{response}]
This way Vim knows which sent message matches with which received message and
can call the right handler. Also when the <A HREF="message.html#messages">messages</A> arrive out of order.
The sender must always send valid JSON to Vim. Vim can check for the end of
the message by parsing the JSON. It will only accept the message if the end
was received.
When the process wants to send a message to Vim without first receiving a
message, <A HREF="motion.html#it">it</A> must use the number zero:
[0,{response}]
Then <A HREF="#channel">channel</A> handler will then get {response} converted to Vim types. If the
<A HREF="#channel">channel</A> does not have a handler the message is dropped.
On read error or <A HREF="eval.html#ch_close()">ch_close()</A>, when using a socket with RAW or NL mode, the
<A HREF="eval.html#string">string</A> "DETACH\n" is sent, if still possible. The <A HREF="#channel">channel</A> will then be
inactive.
It is also possible to use <A HREF="eval.html#ch_sendraw()">ch_sendraw()</A> and <A HREF="eval.html#ch_evalraw()">ch_evalraw()</A> on a JSON or JS
<A HREF="#channel">channel</A>. The caller is then completely responsible for correct encoding and
decoding.
==============================================================================
5. <A HREF="eval.html#Channel">Channel</A> commands *<A NAME="channel-commands"></A><B>channel-commands</B>*
With a JSON <A HREF="#channel">channel</A> the process can send commands to Vim that will be
handled by Vim internally, <A HREF="motion.html#it">it</A> does not require a handler for the <A HREF="#channel">channel</A>.
Possible commands are: *<A NAME="E903"></A><B>E903</B>* *<A NAME="E904"></A><B>E904</B>* *<A NAME="E905"></A><B>E905</B>*
["redraw" {forced}]
["ex", {Ex command}]
["normal", {Normal mode command}]
["expr", {expression}, {number}]
["expr", {expression}]
["call", {func name}, {argument list}, {number}]
["call", {func name}, {argument list}]
With all of these: Be careful what these commands <A HREF="diff.html#do">do</A>! You can easily
interfere with what the user is doing. To avoid trouble use |<A HREF="eval.html#mode()">mode()</A>| to check
that the editor is in the expected state. E.g., to send keys that must be
inserted <A HREF="motion.html#as">as</A> text, not executed <A HREF="motion.html#as">as</A> a command:
<B><FONT COLOR="PURPLE"> ["ex","if mode() == 'i' | call feedkeys('ClassName') | endif"] </FONT></B>
Errors in these commands are normally not reported to avoid them messing up
the display. If you <A HREF="diff.html#do">do</A> want to see them, set the <A HREF="options.html#'verbose'">'verbose'</A> option to 3 or
higher.
<B><FONT COLOR="PURPLE">Command "redraw" </FONT></B>
The other commands <A HREF="diff.html#do">do</A> not update the screen, so that you can send a sequence
of commands without the cursor moving around. You must end with the "redraw"
command to show any changed text and show the cursor where <A HREF="motion.html#it">it</A> belongs.
The argument is normally an empty <A HREF="eval.html#string">string</A>:
<B><FONT COLOR="PURPLE"> ["redraw", ""] </FONT></B>
To first clear the screen pass "force":
<B><FONT COLOR="PURPLE"> ["redraw", "force"] </FONT></B>
<B><FONT COLOR="PURPLE">Command "ex" </FONT></B>
The "<A HREF="starting.html#ex">ex</A>" command is executed <A HREF="motion.html#as">as</A> any <A HREF="intro.html#Ex">Ex</A> command. There is no response for
completion or error. You could use <A HREF="eval.html#functions">functions</A> in an |<A HREF="eval.html#autoload">autoload</A>| <A HREF="usr_41.html#script">script</A>:
["ex","call myscript#MyFunc(arg)"]
You can also use "call |feedkeys()|" to insert any key sequence.
When there is an error a message is written to the <A HREF="#channel">channel</A> log, if <A HREF="motion.html#it">it</A> exists,
and <A HREF="eval.html#v:errmsg">v:errmsg</A> is set to the error.
<B><FONT COLOR="PURPLE">Command "normal" </FONT></B>
The "normal" command is executed like with ":normal!", commands are not
mapped. Example to open the <A HREF="fold.html#folds">folds</A> under the cursor:
["normal" "<A HREF="fold.html#zO">zO</A>"]
<B><FONT COLOR="PURPLE">Command "expr" with response </FONT></B>
The "<A HREF="eval.html#expr">expr</A>" command can be used to get the result of an <A HREF="eval.html#expression">expression</A>. For
example, to get the number of lines in the current buffer:
<B><FONT COLOR="PURPLE"> ["expr","line('$')", -2] </FONT></B>
It will send back the result of the <A HREF="eval.html#expression">expression</A>:
<B><FONT COLOR="PURPLE"> [-2, "last line"] </FONT></B>
The format is:
[{number}, {result}]
Here {number} is the same <A HREF="motion.html#as">as</A> what was in the request. Use a negative number
to avoid confusion with message that Vim sends. Use a different number on
every request to be able to match the request with the response.
{result} is the result of the evaluation and is JSON encoded. If the
evaluation fails or the result can't be encoded in JSON <A HREF="motion.html#it">it</A> is the <A HREF="eval.html#string">string</A>
"ERROR".
<B><FONT COLOR="PURPLE">Command "expr" without a response </FONT></B>
This command is similar to "<A HREF="eval.html#expr">expr</A>" above, but does not send back any response.
Example:
<B><FONT COLOR="PURPLE"> ["expr","setline('$', ['one', 'two', 'three'])"] </FONT></B>
There is no third argument in the request.
<B><FONT COLOR="PURPLE">Command "call" </FONT></B>
This is similar to "<A HREF="eval.html#expr">expr</A>", but instead of passing the whole <A HREF="eval.html#expression">expression</A> <A HREF="motion.html#as">as</A> a
<A HREF="eval.html#string">string</A> this passes the name of a function and a <A HREF="eval.html#list">list</A> of arguments. This
avoids the conversion of the arguments to a <A HREF="eval.html#string">string</A> and escaping and
concatenating them. Example:
<B><FONT COLOR="PURPLE"> ["call", "line", ["$"], -2] </FONT></B>
Leave out the fourth argument if no response is to be sent:
<B><FONT COLOR="PURPLE"> ["call", "setline", ["$", ["one", "two", "three"]]] </FONT></B>
==============================================================================
6. Using a RAW or NL <A HREF="#channel">channel</A> *<A NAME="channel-raw"></A><B>channel-raw</B>*
If mode is RAW or NL then a message can be send like this:
<B> let response = ch_evalraw(channel, {string})</B>
The {string} is sent as-is. The response will be what can be read from the
<A HREF="#channel">channel</A> right away. Since Vim doesn't know how to recognize the end of the
message you need to take care of <A HREF="motion.html#it">it</A> yourself. The timeout applies for reading
the first byte, after that <A HREF="motion.html#it">it</A> will not wait for anything more.
If mode is "nl" you can send a message in a similar way. You are expected
to put in the NL after each message. Thus you can also send several <A HREF="message.html#messages">messages</A>
ending in a NL at once. The response will be the text up to and including the
first NL. This can also be just the NL for an empty response.
If no NL was read before the <A HREF="#channel">channel</A> timeout an empty <A HREF="eval.html#string">string</A> is returned.
To send a message, without expecting a response:
<B> call ch_sendraw(channel, {string})</B>
The process can send back a response, the <A HREF="#channel">channel</A> handler will be called with
<A HREF="motion.html#it">it</A>.
To send a message and letting the response handled by a specific function,
asynchronously:
<B> call ch_sendraw(channel, {string}, {'callback': 'MyHandler'})</B>
This {string} can also be JSON, use |<A HREF="eval.html#json_encode()">json_encode()</A>| to create <A HREF="motion.html#it">it</A> and
|<A HREF="eval.html#json_decode()">json_decode()</A>| to handle a received JSON message.
It is not possible to use |<A HREF="eval.html#ch_evalexpr()">ch_evalexpr()</A>| or |<A HREF="eval.html#ch_sendexpr()">ch_sendexpr()</A>| on a raw <A HREF="#channel">channel</A>.
==============================================================================
7. More <A HREF="#channel">channel</A> <A HREF="eval.html#functions">functions</A> *<A NAME="channel-more"></A><B>channel-more</B>*
To obtain the status of a <A HREF="#channel">channel</A>: ch_status(channel). The possible results
are:
"fail" Failed to open the <A HREF="#channel">channel</A>.
"open" The <A HREF="#channel">channel</A> can be used.
"closed" The <A HREF="#channel">channel</A> was closed.
To obtain the <A HREF="#job">job</A> associated with a <A HREF="#channel">channel</A>: ch_getjob(channel)
To read one message from a <A HREF="#channel">channel</A>:
<B> let output = ch_read(channel)</B>
This uses the <A HREF="#channel">channel</A> timeout. To read without a timeout, just get any
message that is available:
<B> let output = ch_read(channel, {'timeout': 0})</B>
When no message was available then the result is <A HREF="eval.html#v:none">v:none</A> for a JSON or JS mode
channels, an empty <A HREF="eval.html#string">string</A> for a RAW or NL <A HREF="#channel">channel</A>.
To read all output from a RAW <A HREF="#channel">channel</A> that is available:
<B> let output = ch_readraw(channel)</B>
To read the error output:
<B> let output = ch_readraw(channel, {"part": "err"})</B>
<A HREF="eval.html#ch_read()">ch_read()</A> and <A HREF="eval.html#ch_readraw()">ch_readraw()</A> use the <A HREF="#channel">channel</A> timeout. When there is nothing to
read within that time an empty <A HREF="eval.html#string">string</A> is returned. To specify a different
timeout in msec use the "timeout" option:
<B><FONT COLOR="PURPLE"> {"timeout": 123} </FONT></B>
To read from the error output use the "part" option:
<B><FONT COLOR="PURPLE"> {"part": "err"} </FONT></B>
To read a message with a specific ID, on a JS or JSON <A HREF="#channel">channel</A>:
<B><FONT COLOR="PURPLE"> {"id": 99} </FONT></B>
When no ID is specified or the ID is -1, the first message is returned. This
overrules any callback waiting for this message.
For a RAW <A HREF="#channel">channel</A> this returns whatever is available, since Vim does not know
where a message ends.
For a NL <A HREF="#channel">channel</A> this returns one message.
For a JS or JSON <A HREF="#channel">channel</A> this returns one decoded message.
This includes any sequence number.
==============================================================================
8. Starting a <A HREF="#job">job</A> with a <A HREF="#channel">channel</A> *<A NAME="job-start"></A><B>job-start</B>* *<A NAME="job"></A><B>job</B>*
To start a <A HREF="#job">job</A> and open a <A HREF="#channel">channel</A> for stdin/stdout/stderr:
<B> let job = job_start(command, {options})</B>
You can get the <A HREF="#channel">channel</A> with:
<B> let channel = job_getchannel(job)</B>
The <A HREF="#channel">channel</A> will use NL mode. If you want another mode it's best to specify
this in {options}. When <A HREF="change.html#changing">changing</A> the mode later some text may have already
been received and not parsed correctly.
If the command produces a line of output that you want to deal with, specify
a handler for stdout:
<B> let job = job_start(command, {"out_cb": "MyHandler"})</B>
The function will be called with the <A HREF="#channel">channel</A> and a message. You would define
<A HREF="motion.html#it">it</A> like this:
<B> func MyHandler(channel, msg)</B>
Without the handler you need to read the output with |<A HREF="eval.html#ch_read()">ch_read()</A>| or
|<A HREF="eval.html#ch_readraw()">ch_readraw()</A>|.
The handler defined for "<A HREF="#out_cb">out_cb</A>" will not receive stderr. If you want to
handle that separately, add an "<A HREF="#err_cb">err_cb</A>" handler:
<B> let job = job_start(command, {"out_cb": "MyHandler",</B>
<B> \ "err_cb": "ErrHandler"})</B>
If you want to handle both stderr and stdout with one handler use the
"callback" option:
<B> let job = job_start(command, {"callback": "MyHandler"}) </B>
You can send a message to the command with <A HREF="eval.html#ch_evalraw()">ch_evalraw()</A>. If the <A HREF="#channel">channel</A> is in
JSON or JS mode you can use <A HREF="eval.html#ch_evalexpr()">ch_evalexpr()</A>.
There are several options you can use, see |<A HREF="#job-options">job-options</A>|.
For example, to start a <A HREF="#job">job</A> and write its output in buffer "dummy":
<B> let logjob = job_start("tail -f /tmp/log",</B>
<B> \ {'out_io': 'buffer', 'out_name': 'dummy'})</B>
<B> sbuf dummy</B>
<B><FONT COLOR="PURPLE">Job input from a buffer </FONT></B>
To run a <A HREF="#job">job</A> that reads from a buffer:
<B> let job = job_start({command},</B>
<B> \ {'in_io': 'buffer', 'in_name': 'mybuffer'})</B>
*<A NAME="E915"></A><B>E915</B>* *<A NAME="E918"></A><B>E918</B>*
The buffer is found by name, similar to |<A HREF="eval.html#bufnr()">bufnr()</A>|. The buffer must exist and
be loaded when <A HREF="eval.html#job_start()">job_start()</A> is called.
By default this reads the whole buffer. This can be changed with the "<A HREF="#in_top">in_top</A>"
and "<A HREF="#in_bot">in_bot</A>" <A HREF="options.html#options">options</A>.
A special mode is when "<A HREF="#in_top">in_top</A>" is set to zero and "<A HREF="#in_bot">in_bot</A>" is not set: Every
time a line is added to the buffer, the last-but-one line will be send to the
<A HREF="#job">job</A> stdin. This allows for editing the last line and sending <A HREF="motion.html#it">it</A> when pressing
Enter.
==============================================================================
9. Starting a <A HREF="#job">job</A> without a <A HREF="#channel">channel</A> *<A NAME="job-start-nochannel"></A><B>job-start-nochannel</B>*
To start another process without creating a <A HREF="#channel">channel</A>:
<B> let job = job_start(command,</B>
<B> \ {"in_io": "null", "out_io": "null", "err_io": "null"})</B>
This starts {command} in the background, Vim does not wait for <A HREF="motion.html#it">it</A> to finish.
When Vim sees that neither stdin, stdout or stderr are connected, no <A HREF="#channel">channel</A>
will be created. Often you will want to include redirection in the command to
avoid <A HREF="motion.html#it">it</A> getting stuck.
There are several options you can use, see |<A HREF="#job-options">job-options</A>|.
*<A NAME="job-start-if-needed"></A><B>job-start-if-needed</B>*
To start a <A HREF="#job">job</A> only when connecting to an address does not work, <A HREF="diff.html#do">do</A> something
like this:
<B> let channel = ch_open(address, {"waittime": 0})</B>
<B> if ch_status(channel) == "fail"</B>
<B> let job = job_start(command)</B>
<B> let channel = ch_open(address, {"waittime": 1000})</B>
<B> endif</B>
Note that the <A HREF="#waittime">waittime</A> for <A HREF="eval.html#ch_open()">ch_open()</A> gives the <A HREF="#job">job</A> one second to make the port
available.
==============================================================================
10. <A HREF="eval.html#Job">Job</A> <A HREF="options.html#options">options</A> *<A NAME="job-options"></A><B>job-options</B>*
The {options} argument in <A HREF="eval.html#job_start()">job_start()</A> is a dictionary. All entries are
optional. Some <A HREF="options.html#options">options</A> can be used after the <A HREF="#job">job</A> has started, using
job_setoptions(job, {options}). Many <A HREF="options.html#options">options</A> can be used with the <A HREF="#channel">channel</A>
related to the <A HREF="#job">job</A>, using ch_setoptions(channel, {options}).
See |<A HREF="eval.html#job_setoptions()">job_setoptions()</A>| and |<A HREF="eval.html#ch_setoptions()">ch_setoptions()</A>|.
*<A NAME="in_mode"></A><B>in_mode</B>* *<A NAME="out_mode"></A><B>out_mode</B>* *<A NAME="err_mode"></A><B>err_mode</B>*
"<A HREF="#in_mode">in_mode</A>" mode specifically for stdin, only when using pipes
"<A HREF="#out_mode">out_mode</A>" mode specifically for stdout, only when using pipes
"<A HREF="#err_mode">err_mode</A>" mode specifically for stderr, only when using pipes
See |<A HREF="#channel-mode">channel-mode</A>| for the values.
Note: when setting "mode" the part specific mode is
overwritten. Therefore set "mode" first and the part
specific mode later.
Note: when <A HREF="editing.html#writing">writing</A> to a file or buffer and when
reading from a buffer NL mode is used by default.
*<A NAME="job-callback"></A><B>job-callback</B>*
"callback": handler Callback for something to read on any part of the
<A HREF="#channel">channel</A>.
*<A NAME="job-out_cb"></A><B>job-out_cb</B>* *<A NAME="out_cb"></A><B>out_cb</B>*
"<A HREF="#out_cb">out_cb</A>": handler Callback for when there is something to read on
stdout. Only for when the <A HREF="#channel">channel</A> uses pipes. When
"<A HREF="#out_cb">out_cb</A>" wasn't set the <A HREF="#channel">channel</A> callback is used.
*<A NAME="job-err_cb"></A><B>job-err_cb</B>* *<A NAME="err_cb"></A><B>err_cb</B>*
"<A HREF="#err_cb">err_cb</A>": handler Callback for when there is something to read on
stderr. Only for when the <A HREF="#channel">channel</A> uses pipes. When
"<A HREF="#err_cb">err_cb</A>" wasn't set the <A HREF="#channel">channel</A> callback is used.
*<A NAME="job-close_cb"></A><B>job-close_cb</B>*
"<A HREF="#close_cb">close_cb</A>": handler Callback for when the <A HREF="#channel">channel</A> is closed. Same <A HREF="motion.html#as">as</A>
"<A HREF="#close_cb">close_cb</A>" on <A HREF="eval.html#ch_open()">ch_open()</A>.
*<A NAME="job-exit_cb"></A><B>job-exit_cb</B>*
"exit_cb": handler Callback for when the <A HREF="#job">job</A> ends. The arguments are the
<A HREF="#job">job</A> and the exit status.
Vim checks about every 10 seconds for jobs that ended.
The callback can also be triggered by calling
|<A HREF="eval.html#job_status()">job_status()</A>|.
*<A NAME="job-timeout"></A><B>job-timeout</B>*
"timeout" The time to wait for a request when blocking, E.g.
when using <A HREF="eval.html#ch_evalexpr()">ch_evalexpr()</A>. In milliseconds. The
default is 2000 (2 seconds).
*<A NAME="out_timeout"></A><B>out_timeout</B>* *<A NAME="err_timeout"></A><B>err_timeout</B>*
"<A HREF="#out_timeout">out_timeout</A>" Timeout for stdout. Only when using pipes.
"<A HREF="#err_timeout">err_timeout</A>" Timeout for stderr. Only when using pipes.
Note: when setting "timeout" the part specific mode is
overwritten. Therefore set "timeout" first and the
part specific mode later.
*<A NAME="job-stoponexit"></A><B>job-stoponexit</B>*
"stoponexit": {signal} Send {signal} to the <A HREF="#job">job</A> when Vim exits. See
|<A HREF="eval.html#job_stop()">job_stop()</A>| for possible values.
"stoponexit": "" Do not stop the <A HREF="#job">job</A> when Vim exits.
The default is "term".
*<A NAME="job-term"></A><B>job-term</B>*
"term": "open" Start a terminal and connect the <A HREF="#job">job</A>
stdin/stdout/stderr to <A HREF="motion.html#it">it</A>.
NOTE: Not implemented yet!
"<A HREF="#channel">channel</A>": {channel} Use an existing <A HREF="#channel">channel</A> instead of creating a new one.
The parts of the <A HREF="#channel">channel</A> that get used for the new <A HREF="#job">job</A>
will be disconnected from what they were used before.
If the <A HREF="#channel">channel</A> was still use by another <A HREF="#job">job</A> this may
cause I/O <A HREF="message.html#errors">errors</A>.
Existing callbacks and other settings remain.
*<A NAME="job-in_io"></A><B>job-in_io</B>* *<A NAME="in_top"></A><B>in_top</B>* *<A NAME="in_bot"></A><B>in_bot</B>* *<A NAME="in_name"></A><B>in_name</B>* *<A NAME="in_buf"></A><B>in_buf</B>*
"in_io": "null" disconnect stdin (read from /dev/null)
"in_io": "pipe" stdin is connected to the <A HREF="#channel">channel</A> (default)
"in_io": "file" stdin reads from a file
"in_io": "buffer" stdin reads from a buffer
"<A HREF="#in_top">in_top</A>": number when using "buffer": first line to send (default: 1)
"<A HREF="#in_bot">in_bot</A>": number when using "buffer": last line to send (default: last)
"<A HREF="#in_name">in_name</A>": "/path/file" the name of the file or buffer to read from
"<A HREF="#in_buf">in_buf</A>": number the number of the buffer to read from
*<A NAME="job-out_io"></A><B>job-out_io</B>* *<A NAME="out_name"></A><B>out_name</B>* *<A NAME="out_buf"></A><B>out_buf</B>*
"out_io": "null" disconnect stdout (goes to /dev/null)
"out_io": "pipe" stdout is connected to the <A HREF="#channel">channel</A> (default)
"out_io": "file" stdout writes to a file
"out_io": "buffer" stdout appends to a buffer
"<A HREF="#out_name">out_name</A>": "/path/file" the name of the file or buffer to write to
"<A HREF="#out_buf">out_buf</A>": number the number of the buffer to write to
*<A NAME="job-err_io"></A><B>job-err_io</B>* *<A NAME="err_name"></A><B>err_name</B>* *<A NAME="err_buf"></A><B>err_buf</B>*
"err_io": "out" stderr <A HREF="message.html#messages">messages</A> to go to stdout
"err_io": "null" disconnect stderr (goes to /dev/null)
"err_io": "pipe" stderr is connected to the <A HREF="#channel">channel</A> (default)
"err_io": "file" stderr writes to a file
"err_io": "buffer" stderr appends to a buffer
"<A HREF="#err_name">err_name</A>": "/path/file" the name of the file or buffer to write to
"<A HREF="#err_buf">err_buf</A>": number the number of the buffer to write to
"block_write": number only for testing: pretend every other write to stdin
will block
<B><FONT COLOR="PURPLE">Writing to a buffer </FONT></B>
When the out_io or err_io mode is "buffer" and there is a callback, the text
is appended to the buffer before invoking the callback.
When a buffer is used both for input and output, the output lines are put
above the last line, since the last line is what is written to the <A HREF="#channel">channel</A>
input. Otherwise lines are appended below the last line.
When using JS or JSON mode with "buffer", only <A HREF="message.html#messages">messages</A> with zero or negative
ID will be added to the buffer, after decoding + encoding. Messages with a
positive number will be handled by a callback, commands are handled <A HREF="motion.html#as">as</A> usual.
The name of the buffer is compared the full name of existing <A HREF="windows.html#buffers">buffers</A>. If
there is a match that buffer is used. Otherwise a new buffer is created.
Use an empty name to always create a new buffer. |<A HREF="eval.html#ch_getbufnr()">ch_getbufnr()</A>| can then be
used to get the buffer number.
For a new buffer <A HREF="options.html#'buftype'">'buftype'</A> is set to "nofile" and <A HREF="options.html#'bufhidden'">'bufhidden'</A> to "hide". If
you prefer other settings, create the buffer first and pass the buffer number.
When the buffer written to is displayed in a <A HREF="windows.html#window">window</A> and the cursor is in the
first column of the last line, the cursor will be moved to the newly added
line and the <A HREF="windows.html#window">window</A> is scrolled up to show the cursor if needed.
Undo is synced for every added line.
<B><FONT COLOR="PURPLE">Writing to a file </FONT></B>
*<A NAME="E920"></A><B>E920</B>*
The file is created with permissions 600 (read-write for the user, not
accessible for others). Use |<A HREF="eval.html#setfperm()">setfperm()</A>| to change this.
If the file already exists <A HREF="motion.html#it">it</A> is truncated.
==============================================================================
11. Controlling a <A HREF="#job">job</A> *<A NAME="job-control"></A><B>job-control</B>*
To get the status of a <A HREF="#job">job</A>:
<B> echo job_status(job)</B>
To make a <A HREF="#job">job</A> stop running:
<B> job_stop(job)</B>
This is the normal way to end a <A HREF="#job">job</A>. On <A HREF="os_unix.html#Unix">Unix</A> <A HREF="motion.html#it">it</A> sends a SIGTERM to the <A HREF="#job">job</A>.
It is possible to use other ways to stop the <A HREF="#job">job</A>, or even send arbitrary
signals. E.g. to force a <A HREF="#job">job</A> to stop, "kill it":
<B> job_stop(job, "kill")</B>
For more <A HREF="options.html#options">options</A> see |<A HREF="eval.html#job_stop()">job_stop()</A>|.
<A HREF="#top">top</A> - <A HREF="index.html">main help file</A>
</PRE>
</BODY>
</HTML>
|