Mercurial > vim
diff runtime/doc/channel.txt @ 17456:e414281d8bb4 v8.1.1726
patch 8.1.1726: the eval.txt help file is too big
commit https://github.com/vim/vim/commit/ed997adaa1e9bd057ce732a73d933b739e9d0c30
Author: Bram Moolenaar <Bram@vim.org>
Date: Sun Jul 21 16:42:00 2019 +0200
patch 8.1.1726: the eval.txt help file is too big
Problem: The eval.txt help file is too big.
Solution: Split off testing support to testing.txt. Move function details
to where the functionality is explained.
author | Bram Moolenaar <Bram@vim.org> |
---|---|
date | Sun, 21 Jul 2019 16:45:05 +0200 |
parents | c002c4899529 |
children | 2704c4e3e20a |
line wrap: on
line diff
--- a/runtime/doc/channel.txt +++ b/runtime/doc/channel.txt @@ -1,4 +1,4 @@ -*channel.txt* For Vim version 8.1. Last change: 2019 May 12 +*channel.txt* For Vim version 8.1. Last change: 2019 Jul 21 VIM REFERENCE MANUAL by Bram Moolenaar @@ -18,11 +18,13 @@ 4. Using a JSON or JS channel |channel- 5. Channel commands |channel-commands| 6. Using a RAW or NL channel |channel-raw| 7. More channel functions |channel-more| -8. Starting a job with a channel |job-start| -9. Starting a job without a channel |job-start-nochannel| -10. Job options |job-options| -11. Controlling a job |job-control| -12. Using a prompt buffer |prompt-buffer| +8. channel functions details |channel-functions-details| +9. Starting a job with a channel |job-start| +10. Starting a job without a channel |job-start-nochannel| +11. Job functions |job-functions-details| +12. Job options |job-options| +13. Controlling a job |job-control| +14. Using a prompt buffer |prompt-buffer| {only when compiled with the |+channel| feature for channel stuff} You can check this with: `has('channel')` @@ -460,7 +462,211 @@ For a JS or JSON channel this returns on This includes any sequence number. ============================================================================== -8. Starting a job with a channel *job-start* *job* +8. channel functions details *channel-functions-details* + +ch_canread({handle}) *ch_canread()* + Return non-zero when there is something to read from {handle}. + {handle} can be a Channel or a Job that has a Channel. + + This is useful to read from a channel at a convenient time, + e.g. from a timer. + + Note that messages are dropped when the channel does not have + a callback. Add a close callback to avoid that. + + +ch_close({handle}) *ch_close()* + Close {handle}. See |channel-close|. + {handle} can be a Channel or a Job that has a Channel. + A close callback is not invoked. + + +ch_close_in({handle}) *ch_close_in()* + Close the "in" part of {handle}. See |channel-close-in|. + {handle} can be a Channel or a Job that has a Channel. + A close callback is not invoked. + + +ch_evalexpr({handle}, {expr} [, {options}]) *ch_evalexpr()* + Send {expr} over {handle}. The {expr} is encoded + according to the type of channel. The function cannot be used + with a raw channel. See |channel-use|. + {handle} can be a Channel or a Job that has a Channel. + *E917* + {options} must be a Dictionary. It must not have a "callback" + entry. It can have a "timeout" entry to specify the timeout + for this specific request. + + ch_evalexpr() waits for a response and returns the decoded + expression. When there is an error or timeout it returns an + empty string. + + +ch_evalraw({handle}, {string} [, {options}]) *ch_evalraw()* + Send {string} over {handle}. + {handle} can be a Channel or a Job that has a Channel. + + Works like |ch_evalexpr()|, but does not encode the request or + decode the response. The caller is responsible for the + correct contents. Also does not add a newline for a channel + in NL mode, the caller must do that. The NL in the response + is removed. + Note that Vim does not know when the text received on a raw + channel is complete, it may only return the first part and you + need to use |ch_readraw()| to fetch the rest. + See |channel-use|. + + +ch_getbufnr({handle}, {what}) *ch_getbufnr()* + Get the buffer number that {handle} is using for {what}. + {handle} can be a Channel or a Job that has a Channel. + {what} can be "err" for stderr, "out" for stdout or empty for + socket output. + Returns -1 when there is no buffer. + + +ch_getjob({channel}) *ch_getjob()* + Get the Job associated with {channel}. + If there is no job calling |job_status()| on the returned Job + will result in "fail". + + +ch_info({handle}) *ch_info()* + Returns a Dictionary with information about {handle}. The + items are: + "id" number of the channel + "status" "open", "buffered" or "closed", like + ch_status() + When opened with ch_open(): + "hostname" the hostname of the address + "port" the port of the address + "sock_status" "open" or "closed" + "sock_mode" "NL", "RAW", "JSON" or "JS" + "sock_io" "socket" + "sock_timeout" timeout in msec + When opened with job_start(): + "out_status" "open", "buffered" or "closed" + "out_mode" "NL", "RAW", "JSON" or "JS" + "out_io" "null", "pipe", "file" or "buffer" + "out_timeout" timeout in msec + "err_status" "open", "buffered" or "closed" + "err_mode" "NL", "RAW", "JSON" or "JS" + "err_io" "out", "null", "pipe", "file" or "buffer" + "err_timeout" timeout in msec + "in_status" "open" or "closed" + "in_mode" "NL", "RAW", "JSON" or "JS" + "in_io" "null", "pipe", "file" or "buffer" + "in_timeout" timeout in msec + + +ch_log({msg} [, {handle}]) *ch_log()* + Write {msg} in the channel log file, if it was opened with + |ch_logfile()|. + When {handle} is passed the channel number is used for the + message. + {handle} can be a Channel or a Job that has a Channel. The + Channel must be open for the channel number to be used. + + +ch_logfile({fname} [, {mode}]) *ch_logfile()* + Start logging channel activity to {fname}. + When {fname} is an empty string: stop logging. + + When {mode} is omitted or "a" append to the file. + When {mode} is "w" start with an empty file. + + Use |ch_log()| to write log messages. The file is flushed + after every message, on Unix you can use "tail -f" to see what + is going on in real time. + + This function is not available in the |sandbox|. + NOTE: the channel communication is stored in the file, be + aware that this may contain confidential and privacy sensitive + information, e.g. a password you type in a terminal window. + + +ch_open({address} [, {options}]) *ch_open()* + Open a channel to {address}. See |channel|. + Returns a Channel. Use |ch_status()| to check for failure. + + {address} has the form "hostname:port", e.g., + "localhost:8765". + + If {options} is given it must be a |Dictionary|. + See |channel-open-options|. + + +ch_read({handle} [, {options}]) *ch_read()* + Read from {handle} and return the received message. + {handle} can be a Channel or a Job that has a Channel. + For a NL channel this waits for a NL to arrive, except when + there is nothing more to read (channel was closed). + See |channel-more|. + + +ch_readblob({handle} [, {options}]) *ch_readblob()* + Like ch_read() but reads binary data and returns a |Blob|. + See |channel-more|. + + +ch_readraw({handle} [, {options}]) *ch_readraw()* + Like ch_read() but for a JS and JSON channel does not decode + the message. For a NL channel it does not block waiting for + the NL to arrive, but otherwise works like ch_read(). + See |channel-more|. + + +ch_sendexpr({handle}, {expr} [, {options}]) *ch_sendexpr()* + Send {expr} over {handle}. The {expr} is encoded + according to the type of channel. The function cannot be used + with a raw channel. + See |channel-use|. *E912* + {handle} can be a Channel or a Job that has a Channel. + + +ch_sendraw({handle}, {expr} [, {options}]) *ch_sendraw()* + Send |String| or |Blob| {expr} over {handle}. + Works like |ch_sendexpr()|, but does not encode the request or + decode the response. The caller is responsible for the + correct contents. Also does not add a newline for a channel + in NL mode, the caller must do that. The NL in the response + is removed. + See |channel-use|. + + +ch_setoptions({handle}, {options}) *ch_setoptions()* + Set options on {handle}: + "callback" the channel callback + "timeout" default read timeout in msec + "mode" mode for the whole channel + See |ch_open()| for more explanation. + {handle} can be a Channel or a Job that has a Channel. + + Note that changing the mode may cause queued messages to be + lost. + + These options cannot be changed: + "waittime" only applies to |ch_open()| + + +ch_status({handle} [, {options}]) *ch_status()* + Return the status of {handle}: + "fail" failed to open the channel + "open" channel can be used + "buffered" channel can be read, not written to + "closed" channel can not be used + {handle} can be a Channel or a Job that has a Channel. + "buffered" is used when the channel was closed but there is + still data that can be obtained with |ch_read()|. + + If {options} is given it can contain a "part" entry to specify + the part of the channel to return the status for: "out" or + "err". For example, to get the error status: > + ch_status(job, {"part": "err"}) +< + +============================================================================== +9. Starting a job with a channel *job-start* *job* To start a job and open a channel for stdin/stdout/stderr: > let job = job_start(command, {options}) @@ -552,7 +758,7 @@ add a close callback and read the output You will want to do something more useful than "echomsg". ============================================================================== -9. Starting a job without a channel *job-start-nochannel* +10. Starting a job without a channel *job-start-nochannel* To start another process without creating a channel: > let job = job_start(command, @@ -579,7 +785,164 @@ Note that the waittime for ch_open() giv available. ============================================================================== -10. Job options *job-options* +11. Job functions *job-functions-details* + +job_getchannel({job}) *job_getchannel()* + Get the channel handle that {job} is using. + To check if the job has no channel: > + if string(job_getchannel()) == 'channel fail' +< + +job_info([{job}]) *job_info()* + Returns a Dictionary with information about {job}: + "status" what |job_status()| returns + "channel" what |job_getchannel()| returns + "cmd" List of command arguments used to start the job + "process" process ID + "tty_in" terminal input name, empty when none + "tty_out" terminal output name, empty when none + "exitval" only valid when "status" is "dead" + "exit_cb" function to be called on exit + "stoponexit" |job-stoponexit| + + Only in Unix: + "termsig" the signal which terminated the process + (See |job_stop()| for the values) + only valid when "status" is "dead" + + Only in MS-Windows: + "tty_type" Type of virtual console in use. + Values are "winpty" or "conpty". + See 'termwintype'. + + Without any arguments, returns a List with all Job objects. + + +job_setoptions({job}, {options}) *job_setoptions()* + Change options for {job}. Supported are: + "stoponexit" |job-stoponexit| + "exit_cb" |job-exit_cb| + + +job_start({command} [, {options}]) *job_start()* + Start a job and return a Job object. Unlike |system()| and + |:!cmd| this does not wait for the job to finish. + To start a job in a terminal window see |term_start()|. + + If the job fails to start then |job_status()| on the returned + Job object results in "fail" and none of the callbacks will be + invoked. + + {command} can be a String. This works best on MS-Windows. On + Unix it is split up in white-separated parts to be passed to + execvp(). Arguments in double quotes can contain white space. + + {command} can be a List, where the first item is the executable + and further items are the arguments. All items are converted + to String. This works best on Unix. + + On MS-Windows, job_start() makes a GUI application hidden. If + want to show it, Use |:!start| instead. + + The command is executed directly, not through a shell, the + 'shell' option is not used. To use the shell: > + let job = job_start(["/bin/sh", "-c", "echo hello"]) +< Or: > + let job = job_start('/bin/sh -c "echo hello"') +< Note that this will start two processes, the shell and the + command it executes. If you don't want this use the "exec" + shell command. + + On Unix $PATH is used to search for the executable only when + the command does not contain a slash. + + The job will use the same terminal as Vim. If it reads from + stdin the job and Vim will be fighting over input, that + doesn't work. Redirect stdin and stdout to avoid problems: > + let job = job_start(['sh', '-c', "myserver </dev/null >/dev/null"]) +< + The returned Job object can be used to get the status with + |job_status()| and stop the job with |job_stop()|. + + Note that the job object will be deleted if there are no + references to it. This closes the stdin and stderr, which may + cause the job to fail with an error. To avoid this keep a + reference to the job. Thus instead of: > + call job_start('my-command') +< use: > + let myjob = job_start('my-command') +< and unlet "myjob" once the job is not needed or is past the + point where it would fail (e.g. when it prints a message on + startup). Keep in mind that variables local to a function + will cease to exist if the function returns. Use a + script-local variable if needed: > + let s:myjob = job_start('my-command') +< + {options} must be a Dictionary. It can contain many optional + items, see |job-options|. + + +job_status({job}) *job_status()* *E916* + Returns a String with the status of {job}: + "run" job is running + "fail" job failed to start + "dead" job died or was stopped after running + + On Unix a non-existing command results in "dead" instead of + "fail", because a fork happens before the failure can be + detected. + + If an exit callback was set with the "exit_cb" option and the + job is now detected to be "dead" the callback will be invoked. + + For more information see |job_info()|. + + +job_stop({job} [, {how}]) *job_stop()* + Stop the {job}. This can also be used to signal the job. + + When {how} is omitted or is "term" the job will be terminated. + For Unix SIGTERM is sent. On MS-Windows the job will be + terminated forcedly (there is no "gentle" way). + This goes to the process group, thus children may also be + affected. + + Effect for Unix: + "term" SIGTERM (default) + "hup" SIGHUP + "quit" SIGQUIT + "int" SIGINT + "kill" SIGKILL (strongest way to stop) + number signal with that number + + Effect for MS-Windows: + "term" terminate process forcedly (default) + "hup" CTRL_BREAK + "quit" CTRL_BREAK + "int" CTRL_C + "kill" terminate process forcedly + Others CTRL_BREAK + + On Unix the signal is sent to the process group. This means + that when the job is "sh -c command" it affects both the shell + and the command. + + The result is a Number: 1 if the operation could be executed, + 0 if "how" is not supported on the system. + Note that even when the operation was executed, whether the + job was actually stopped needs to be checked with + |job_status()|. + + If the status of the job is "dead", the signal will not be + sent. This is to avoid to stop the wrong job (esp. on Unix, + where process numbers are recycled). + + When using "kill" Vim will assume the job will die and close + the channel. + + +============================================================================== +12. Job options *job-options* The {options} argument in job_start() is a dictionary. All entries are optional. Some options can be used after the job has started, using @@ -773,7 +1136,7 @@ accessible for others). Use |setfperm() If the file already exists it is truncated. ============================================================================== -11. Controlling a job *job-control* +13. Controlling a job *job-control* To get the status of a job: > echo job_status(job) @@ -789,7 +1152,7 @@ signals. E.g. to force a job to stop, " For more options see |job_stop()|. ============================================================================== -12. Using a prompt buffer *prompt-buffer* +14. Using a prompt buffer *prompt-buffer* If you want to type input for the job in a Vim window you have a few options: - Use a normal buffer and handle all possible commands yourself.