diff options
| -rw-r--r-- | runtime/doc/Makefile | 2 | ||||
| -rw-r--r-- | runtime/doc/channel.txt | 385 | ||||
| -rw-r--r-- | runtime/doc/eval.txt | 1178 | ||||
| -rw-r--r-- | runtime/doc/help.txt | 3 | ||||
| -rw-r--r-- | runtime/doc/sign.txt | 356 | ||||
| -rw-r--r-- | runtime/doc/tags | 183 | ||||
| -rw-r--r-- | runtime/doc/testing.txt | 317 | ||||
| -rw-r--r-- | runtime/doc/textprop.txt | 198 | ||||
| -rw-r--r-- | src/version.c | 2 |
9 files changed, 1357 insertions, 1267 deletions
diff --git a/runtime/doc/Makefile b/runtime/doc/Makefile index 3db1190a0a..4a1ea03fd7 100644 --- a/runtime/doc/Makefile +++ b/runtime/doc/Makefile @@ -103,6 +103,7 @@ DOCS = \ tagsrch.txt \ term.txt \ terminal.txt \ + testing.txt \ textprop.txt \ tips.txt \ todo.txt \ @@ -241,6 +242,7 @@ HTMLS = \ tagsrch.html \ term.html \ terminal.html \ + testing.html \ textprop.html \ tips.html \ todo.html \ diff --git a/runtime/doc/channel.txt b/runtime/doc/channel.txt index 632628a878..a8e5857728 100644 --- 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 @@ 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. diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 6a44c9f3ab..79c5409c51 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -1,4 +1,4 @@ -*eval.txt* For Vim version 8.1. Last change: 2019 Jul 19 +*eval.txt* For Vim version 8.1. Last change: 2019 Jul 21 VIM REFERENCE MANUAL by Bram Moolenaar @@ -31,7 +31,9 @@ done, the features in this document are not available. See |+eval| and 11. No +eval feature |no-eval-feature| 12. The sandbox |eval-sandbox| 13. Textlock |textlock| -14. Testing |testing| + +Testing support is documented in |testing.txt|. +Profiling is documented at |profiling|. ============================================================================== 1. Variables *variables* @@ -2952,117 +2954,9 @@ argv([{nr} [, {winid}]) The {winid} argument specifies the window ID, see |argc()|. -assert_beeps({cmd}) *assert_beeps()* - Run {cmd} and add an error message to |v:errors| if it does - NOT produce a beep or visual bell. - Also see |assert_fails()| and |assert-return|. - - *assert_equal()* -assert_equal({expected}, {actual} [, {msg}]) - When {expected} and {actual} are not equal an error message is - added to |v:errors| and 1 is returned. Otherwise zero is - returned |assert-return|. - There is no automatic conversion, the String "4" is different - from the Number 4. And the number 4 is different from the - Float 4.0. The value of 'ignorecase' is not used here, case - always matters. - When {msg} is omitted an error in the form "Expected - {expected} but got {actual}" is produced. - Example: > - assert_equal('foo', 'bar') -< Will result in a string to be added to |v:errors|: - test.vim line 12: Expected 'foo' but got 'bar' ~ - *assert_equalfile()* -assert_equalfile({fname-one}, {fname-two}) - When the files {fname-one} and {fname-two} do not contain - exactly the same text an error message is added to |v:errors|. - Also see |assert-return|. - When {fname-one} or {fname-two} does not exist the error will - mention that. - Mainly useful with |terminal-diff|. - -assert_exception({error} [, {msg}]) *assert_exception()* - When v:exception does not contain the string {error} an error - message is added to |v:errors|. Also see |assert-return|. - This can be used to assert that a command throws an exception. - Using the error number, followed by a colon, avoids problems - with translations: > - try - commandthatfails - call assert_false(1, 'command should have failed') - catch - call assert_exception('E492:') - endtry - -assert_fails({cmd} [, {error} [, {msg}]]) *assert_fails()* - Run {cmd} and add an error message to |v:errors| if it does - NOT produce an error. Also see |assert-return|. - When {error} is given it must match in |v:errmsg|. - Note that beeping is not considered an error, and some failing - commands only beep. Use |assert_beeps()| for those. - -assert_false({actual} [, {msg}]) *assert_false()* - When {actual} is not false an error message is added to - |v:errors|, like with |assert_equal()|. - Also see |assert-return|. - A value is false when it is zero. When {actual} is not a - number the assert fails. - When {msg} is omitted an error in the form - "Expected False but got {actual}" is produced. - -assert_inrange({lower}, {upper}, {actual} [, {msg}]) *assert_inrange()* - This asserts number and |Float| values. When {actual} is lower - than {lower} or higher than {upper} an error message is added - to |v:errors|. Also see |assert-return|. - When {msg} is omitted an error in the form - "Expected range {lower} - {upper}, but got {actual}" is - produced. - - *assert_match()* -assert_match({pattern}, {actual} [, {msg}]) - When {pattern} does not match {actual} an error message is - added to |v:errors|. Also see |assert-return|. - - {pattern} is used as with |=~|: The matching is always done - like 'magic' was set and 'cpoptions' is empty, no matter what - the actual value of 'magic' or 'cpoptions' is. - - {actual} is used as a string, automatic conversion applies. - Use "^" and "$" to match with the start and end of the text. - Use both to match the whole text. - - When {msg} is omitted an error in the form - "Pattern {pattern} does not match {actual}" is produced. - Example: > - assert_match('^f.*o$', 'foobar') -< Will result in a string to be added to |v:errors|: - test.vim line 12: Pattern '^f.*o$' does not match 'foobar' ~ - - *assert_notequal()* -assert_notequal({expected}, {actual} [, {msg}]) - The opposite of `assert_equal()`: add an error message to - |v:errors| when {expected} and {actual} are equal. - Also see |assert-return|. - - *assert_notmatch()* -assert_notmatch({pattern}, {actual} [, {msg}]) - The opposite of `assert_match()`: add an error message to - |v:errors| when {pattern} matches {actual}. - Also see |assert-return|. - -assert_report({msg}) *assert_report()* - Report a test failure directly, using {msg}. - Always returns one. - -assert_true({actual} [, {msg}]) *assert_true()* - When {actual} is not true an error message is added to - |v:errors|, like with |assert_equal()|. - Also see |assert-return|. - A value is TRUE when it is a non-zero number. When {actual} - is not a number the assert fails. - When {msg} is omitted an error in the form "Expected True but - got {actual}" is produced. +assert_ functions are documented here: |assert-functions| + asin({expr}) *asin()* Return the arc sine of {expr} measured in radians, as a |Float| @@ -3358,213 +3252,10 @@ ceil({expr}) *ceil()* < 4.0 {only available when compiled with the |+float| feature} -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. - - {only available when compiled with the |+channel| feature} -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_ functions are documented here: |channel-functions-details| - {only available when compiled with the |+channel| feature} -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. - - {only available when compiled with the |+channel| feature} - -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. - - {only available when compiled with the |+channel| feature} - -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|. - - {only available when compiled with the |+channel| feature} - -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. - {only available when compiled with the |+channel| feature} - -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". - - {only available when compiled with the |+channel| and - |+job| features} - -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|. - - {only available when compiled with the |+channel| feature} - -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|. - {only available when compiled with the |+channel| feature} - -ch_readblob({handle} [, {options}]) *ch_readblob()* - Like ch_read() but reads binary data and returns a |Blob|. - See |channel-more|. - {only available when compiled with the |+channel| feature} - -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|. - {only available when compiled with the |+channel| feature} - -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. - - {only available when compiled with the |+channel| feature} - -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|. - - {only available when compiled with the |+channel| feature} - -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"}) -< changenr() *changenr()* Return the number of the most recent change. This is the same number as what is displayed with |:undolist| and can be used @@ -6044,161 +5735,9 @@ items({dict}) *items()* echo key . ': ' . value endfor -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' -< - {only available when compiled with the |+job| feature} - -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|. - - {only available when compiled with the |+job| feature} - -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()|. - - {only available when compiled with the |+job| feature} - -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 |