1- *channel.txt* For Vim version 8.0 . Last change: 2016 Dec 02
1+ *channel.txt* For Vim version 8.1 . Last change: 2018 Apr 18
22
33
44 VIM REFERENCE MANUAL by Bram Moolenaar
@@ -22,6 +22,7 @@ The Netbeans interface also uses a channel. |netbeans|
22229. Starting a job without a channel | job-start-nochannel |
232310. Job options | job-options |
242411. Controlling a job | job-control |
25+ 12. Using a prompt buffer | prompt-buffer |
2526
2627{Vi does not have any of these features}
2728{only when compiled with the | +channel | feature for channel stuff}
@@ -55,7 +56,7 @@ JS JavaScript style JSON-like encoding |js_encode()|
5556Common combination are:
5657- Using a job connected through pipes in NL mode. E.g., to run a style
5758 checker and receive errors and warnings.
58- - Using a deamon , connecting over a socket in JSON mode. E.g. to lookup
59+ - Using a daemon , connecting over a socket in JSON mode. E.g. to lookup
5960 cross-references in a database.
6061
6162==============================================================================
@@ -427,8 +428,8 @@ When no message was available then the result is v:none for a JSON or JS mode
427428channels, an empty string for a RAW or NL channel. You can use | ch_canread() |
428429to check if there is something to read.
429430
430- Note that when there is no callback message are dropped. To avoid that add a
431- close callback to the channel.
431+ Note that when there is no callback, messages are dropped. To avoid that add
432+ a close callback to the channel.
432433
433434To read all output from a RAW channel that is available: >
434435 let output = ch_readraw(channel)
@@ -489,6 +490,11 @@ If you want to handle both stderr and stdout with one handler use the
489490"callback" option: >
490491 let job = job_start(command, {"callback": "MyHandler"})
491492
493+
494+ started job gets the focus. To avoid that, use the `foreground ()` function.
495+ This might not always work when called early, put in the callback handler or
496+ use a timer to call it after the job has started.
497+
492498You can send a message to the command with ch_evalraw(). If the channel is in
493499JSON or JS mode you can use ch_evalexpr().
494500
@@ -513,7 +519,7 @@ By default this reads the whole buffer. This can be changed with the "in_top"
513519and "in_bot" options.
514520
515521A special mode is when "in_top" is set to zero and "in_bot" is not set: Every
516- time a line is added to the buffer, the last-but-one line will be send to the
522+ time a line is added to the buffer, the last-but-one line will be sent to the
517523job stdin. This allows for editing the last line and sending it when pressing
518524Enter.
519525 *channel-close-in*
@@ -606,7 +612,7 @@ See |job_setoptions()| and |ch_setoptions()|.
606612"close_cb": handler Callback for when the channel is closed. Same as
607613 "close_cb" on | ch_open() | , see | close_cb | .
608614 *job-drop*
609- "drop" Specifies when to drop messages. Same as "drop" on
615+ "drop": when Specifies when to drop messages. Same as "drop" on
610616 | ch_open() | , see | channel-drop | . For "auto" the
611617 exit_cb is not considered.
612618 *job-exit_cb*
@@ -619,12 +625,12 @@ See |job_setoptions()| and |ch_setoptions()|.
619625 Note that data can be buffered, callbacks may still be
620626 called after the process ends.
621627 *job-timeout*
622- "timeout" The time to wait for a request when blocking, E.g.
628+ "timeout": time The time to wait for a request when blocking, E.g.
623629 when using ch_evalexpr(). In milliseconds. The
624630 default is 2000 (2 seconds).
625631 *out_timeout* *err_timeout*
626- "out_timeout" Timeout for stdout. Only when using pipes.
627- "err_timeout" Timeout for stderr. Only when using pipes.
632+ "out_timeout": time Timeout for stdout. Only when using pipes.
633+ "err_timeout": time Timeout for stderr. Only when using pipes.
628634 Note: when setting "timeout" the part specific mode is
629635 overwritten. Therefore set "timeout" first and the
630636 part specific mode later.
@@ -636,8 +642,9 @@ See |job_setoptions()| and |ch_setoptions()|.
636642 The default is "term".
637643
638644 *job-term*
639- "term": "open" Start a terminal and connect the job
640- stdin/stdout/stderr to it.
645+ "term": "open" Start a terminal in a new window and connect the job
646+ stdin/stdout/stderr to it. Similar to using
647+ `:terminal ` .
641648 NOTE: Not implemented yet!
642649
643650"channel": {channel} Use an existing channel instead of creating a new one.
@@ -647,6 +654,11 @@ See |job_setoptions()| and |ch_setoptions()|.
647654 cause I/O errors.
648655 Existing callbacks and other settings remain.
649656
657+ "pty": 1 Use a pty (pseudo-tty) instead of a pipe when
658+ possible. This is most useful in combination with a
659+ terminal window, see | terminal | .
660+ {only on Unix and Unix-like systems}
661+
650662 *job-in_io* *in_top* *in_bot* *in_name* *in_buf*
651663"in_io": "null" disconnect stdin (read from /dev/null)
652664"in_io": "pipe" stdin is connected to the channel (default)
@@ -685,6 +697,10 @@ See |job_setoptions()| and |ch_setoptions()|.
685697"block_write": number only for testing: pretend every other write to stdin
686698 will block
687699
700+ "env": dict environment variables for the new process
701+ "cwd": "/path/to/dir" current working directory for the new process;
702+ if the directory does not exist an error is given
703+
688704
689705Writing to a buffer ~
690706 *out_io-buffer*
@@ -720,10 +736,6 @@ The "out_msg" option can be used to specify whether a new buffer will have the
720736first line set to "Reading from channel output...". The default is to add the
721737message. "err_msg" does the same for channel error.
722738
723- 'modifiable' option off, or write to a buffer that has 'modifiable' off. That
724- means that lines will be appended to the buffer, but the user can't easily
725- change the buffer.
726-
727739When an existing buffer is to be written where 'modifiable' is off and the
728740"out_modifiable" or "err_modifiable" options is not zero, an error is given
729741and the buffer will not be written to.
@@ -759,5 +771,49 @@ signals. E.g. to force a job to stop, "kill it": >
759771
760772| job_stop() | .
761773
774+ ==============================================================================
775+ 12. Using a prompt buffer *prompt-buffer*
776+
777+ If you want to type input for the job in a Vim window you have a few options:
778+ - Use a normal buffer and handle all possible commands yourself.
779+ This will be complicated, since there are so many possible commands.
780+ - Use a terminal window. This works well if what you type goes directly to
781+ the job and the job output is directly displayed in the window.
782+ See | terminal-window | .
783+ - Use a prompt window. This works well when entering a line for the job in Vim
784+ while displaying (possibly filtered) output from the job.
785+
786+ A prompt buffer is created by setting 'buftype' to "prompt". You would
787+ normally only do that in a newly created buffer.
788+
789+ The user can edit and enter one line of text at the very last line of the
790+ buffer. When pressing Enter in the prompt line the callback set with
791+ | prompt_setcallback() | is invoked. It would normally send the line to a job.
792+ Another callback would receive the output from the job and display it in the
793+ buffer, below the prompt (and above the next prompt).
794+
795+ Only the text in the last line, after the prompt, is editable. The rest of the
796+ buffer is not modifiable with Normal mode commands. It can be modified by
797+ calling functions, such as | append() | . Using other commands may mess up the
798+ buffer.
799+
800+ After setting 'buftype' to "prompt" Vim does not automatically start Insert
801+ mode, use `:startinsert ` if you want to enter Insert mode, so that the user
802+ can start typing a line.
803+
804+ The text of the prompt can be set with the | prompt_setprompt() | function.
805+
806+ The user can go to Normal mode and navigate through the buffer. This can be
807+ useful see older output or copy text.
808+
809+ The CTRL-W key can be used to start a window command, such as CTRL-W w to
810+ switch to the next window. This also works in Insert mode (use Shift-CTRL-W
811+ to delete a word). When leaving the window Insert mode will be stopped. When
812+ coming back to the prompt window Insert mode will be restored.
813+
814+ Any command that starts Insert mode, such as "a", "i", "A" and "I", will move
815+ the cursor to the last line. "A" will move to the end of the line, "I" to the
816+ start of the line.
817+
762818
763- vim:tw=78:ts=8:ft=help:norl:
819+ vim:tw=78:ts=8:noet: ft=help:norl:
0 commit comments