adam/vim
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

patch 8.1.1726: the eval.txt help file is too big

Browse Source 
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.
This commit is contained in:
Bram Moolenaar
2019-07-21 16:42:00 +02:00
parent 663bbc09ba
commit ed997adaa1
9 changed files with 1356 additions and 1266 deletions
Download Patch File Download Diff File Expand all files Collapse all files

385
runtime/doc/channel.txt
View File

@ -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 @@ The Netbeans interface also uses a channel. |netbeans|
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 one decoded message.
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 there: >
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() gives the job one second to make the port
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()| to change this.
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, "kill it": >
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.