Mercurial > vim
changeset 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 | 4ae435e21326 |
| children | 3a368ff28a0b |
| files | runtime/doc/Makefile runtime/doc/channel.txt runtime/doc/eval.txt runtime/doc/help.txt runtime/doc/sign.txt runtime/doc/tags runtime/doc/testing.txt runtime/doc/textprop.txt src/version.c |
| diffstat | 9 files changed, 1366 insertions(+), 1276 deletions(-) [+] |
line wrap: on
line diff
--- 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 \
--- 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.
--- 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 @@ 10. Vim script version |vimscript-versi 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. - - {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"}) -< + +ch_ functions are documented here: |channel-functions-details| + + 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: - "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. - - {only available when compiled with the |+job| feature} + +job_ functions are documented here: |job-functions-details| + join({list} [, {sep}]) *join()* Join the items in {list} together into one String. @@ -7333,201 +6872,7 @@ prompt_setprompt({buf}, {text}) *prom "prompt". Example: > call prompt_setprompt(bufnr(''), 'command: ') < - *prop_add()* *E965* -prop_add({lnum}, {col}, {props}) - Attach a text property at position {lnum}, {col}. {col} is - counted in bytes, use one for the first column. - If {lnum} is invalid an error is given. *E966* - If {col} is invalid an error is given. *E964* - - {props} is a dictionary with these fields: - length length of text in bytes, can only be used - for a property that does not continue in - another line; can be zero - end_lnum line number for the end of text - end_col column just after the text; not used when - "length" is present; when {col} and "end_col" - are equal, and "end_lnum" is omitted or equal - to {lnum}, this is a zero-width text property - bufnr buffer to add the property to; when omitted - the current buffer is used - id user defined ID for the property; when omitted - zero is used - type name of the text property type - All fields except "type" are optional. - - It is an error when both "length" and "end_lnum" or "end_col" - are given. Either use "length" or "end_col" for a property - within one line, or use "end_lnum" and "end_col" for a - property that spans more than one line. - When neither "length" nor "end_col" are given the property - will be zero-width. That means it will not be highlighted but - will move with the text, as a kind of mark. - The property can end exactly at the last character of the - text, or just after it. In the last case, if text is appended - to the line, the text property size will increase, also when - the property type does not have "end_incl" set. - - "type" will first be looked up in the buffer the property is - added to. When not found, the global property types are used. - If not found an error is given. - - See |text-properties| for information about text properties. - - -prop_clear({lnum} [, {lnum-end} [, {props}]]) *prop_clear()* - Remove all text properties from line {lnum}. - When {lnum-end} is given, remove all text properties from line - {lnum} to {lnum-end} (inclusive). - - When {props} contains a "bufnr" item use this buffer, - otherwise use the current buffer. - - See |text-properties| for information about text properties. - - *prop_find()* -prop_find({props} [, {direction}]) - NOT IMPLEMENTED YET - Search for a text property as specified with {props}: - id property with this ID - type property with this type name - bufnr buffer to search in; when present a - start position with "lnum" and "col" - must be given; when omitted the - current buffer is used - lnum start in this line (when omitted start - at the cursor) - col start at this column (when omitted - and "lnum" is given: use column 1, - otherwise start at the cursor) - skipstart do not look for a match at the start - position - - {direction} can be "f" for forward and "b" for backward. When - omitted forward search is performed. - - If a match is found then a Dict is returned with the entries - as with prop_list(), and additionally an "lnum" entry. - If no match is found then an empty Dict is returned. - - See |text-properties| for information about text properties. - - -prop_list({lnum} [, {props}]) *prop_list()* - Return a List with all text properties in line {lnum}. - - When {props} contains a "bufnr" item, use this buffer instead - of the current buffer. - - The properties are ordered by starting column and priority. - Each property is a Dict with these entries: - col starting column - length length in bytes, one more if line break is - included - id property ID - type name of the property type, omitted if - the type was deleted - start when TRUE property starts in this line - end when TRUE property ends in this line - - When "start" is zero the property started in a previous line, - the current one is a continuation. - When "end" is zero the property continues in the next line. - The line break after this line is included. - - See |text-properties| for information about text properties. - - - *prop_remove()* *E968* -prop_remove({props} [, {lnum} [, {lnum-end}]]) - Remove a matching text property from line {lnum}. When - {lnum-end} is given, remove matching text properties from line - {lnum} to {lnum-end} (inclusive). - When {lnum} is omitted remove matching text properties from - all lines. - - {props} is a dictionary with these fields: - id remove text properties with this ID - type remove text properties with this type name - bufnr use this buffer instead of the current one - all when TRUE remove all matching text properties, - not just the first one - A property matches when either "id" or "type" matches. - If buffer "bufnr" does not exist you get an error message. - If buffer "bufnr" is not loaded then nothing happens. - - Returns the number of properties that were removed. - - See |text-properties| for information about text properties. - - -prop_type_add({name}, {props}) *prop_type_add()* *E969* *E970* - Add a text property type {name}. If a property type with this - name already exists an error is given. - {props} is a dictionary with these optional fields: - bufnr define the property only for this buffer; this - avoids name collisions and automatically - clears the property types when the buffer is - deleted. - highlight name of highlight group to use - priority when a character has multiple text - properties the one with the highest priority - will be used; negative values can be used, the - default priority is zero - combine when TRUE combine the highlight with any - syntax highlight; when omitted or FALSE syntax - highlight will not be used - start_incl when TRUE inserts at the start position will - be included in the text property - end_incl when TRUE inserts at the end position will be - included in the text property - - See |text-properties| for information about text properties. - - -prop_type_change({name}, {props}) *prop_type_change()* - Change properties of an existing text property type. If a - property with this name does not exist an error is given. - The {props} argument is just like |prop_type_add()|. - - See |text-properties| for information about text properties. - - -prop_type_delete({name} [, {props}]) *prop_type_delete()* - Remove the text property type {name}. When text properties - using the type {name} are still in place, they will not have - an effect and can no longer be removed by name. - - {props} can contain a "bufnr" item. When it is given, delete - a property type from this buffer instead of from the global - property types. - - When text property type {name} is not found there is no error. - - See |text-properties| for information about text properties. - - -prop_type_get([{name} [, {props}]) *prop_type_get()* - Returns the properties of property type {name}. This is a - dictionary with the same fields as was given to - prop_type_add(). - When the property type {name} does not exist, an empty - dictionary is returned. - - {props} can contain a "bufnr" item. When it is given, use - this buffer instead of the global property types. - - See |text-properties| for information about text properties. - - -prop_type_list([{props}]) *prop_type_list()* - Returns a list with all property type names. - - {props} can contain a "bufnr" item. When it is given, use - this buffer instead of the global property types. - - See |text-properties| for information about text properties. - +prop_ functions are documented here: |text-prop-functions|. pumvisible() *pumvisible()* Returns non-zero when the popup menu is visible, zero @@ -8637,351 +7982,9 @@ shiftwidth([{col}]) *shiftwidth()* 'vartabstop' feature. If the 'vartabstop' setting is enabled and no {col} argument is given, column 1 will be assumed. -sign_define({name} [, {dict}]) *sign_define()* -sign_define({list}) - Define a new sign named {name} or modify the attributes of an - existing sign. This is similar to the |:sign-define| command. - - Prefix {name} with a unique text to avoid name collisions. - There is no {group} like with placing signs. - - The {name} can be a String or a Number. The optional {dict} - argument specifies the sign attributes. The following values - are supported: - icon full path to the bitmap file for the sign. - linehl highlight group used for the whole line the - sign is placed in. - text text that is displayed when there is no icon - or the GUI is not being used. - texthl highlight group used for the text item - - If the sign named {name} already exists, then the attributes - of the sign are updated. - - The one argument {list} can be used to define a list of signs. - Each list item is a dictionary with the above items in {dict} - and a 'name' item for the sign name. - - Returns 0 on success and -1 on failure. When the one argument - {list} is used, then returns a List of values one for each - defined sign. - - Examples: > - call sign_define("mySign", { - \ "text" : "=>", - \ "texthl" : "Error", - \ "linehl" : "Search"}) - call sign_define([ - \ {'name' : 'sign1', - \ 'text' : '=>'}, - \ {'name' : 'sign2', - \ 'text' : '!!'} - \ ]) -< -sign_getdefined([{name}]) *sign_getdefined()* - Get a list of defined signs and their attributes. - This is similar to the |:sign-list| command. - - If the {name} is not supplied, then a list of all the defined - signs is returned. Otherwise the attribute of the specified - sign is returned. - - Each list item in the returned value is a dictionary with the - following entries: - icon full path to the bitmap file of the sign - linehl highlight group used for the whole line the - sign is placed in. - name name of the sign - text text that is displayed when there is no icon - or the GUI is not being used. - texthl highlight group used for the text item - - Returns an empty List if there are no signs and when {name} is - not found. - - Examples: > - " Get a list of all the defined signs - echo sign_getdefined() - - " Get the attribute of the sign named mySign - echo sign_getdefined("mySign") -< -sign_getplaced([{expr} [, {dict}]]) *sign_getplaced()* - Return a list of signs placed in a buffer or all the buffers. - This is similar to the |:sign-place-list| command. - - If the optional buffer name {expr} is specified, then only the - list of signs placed in that buffer is returned. For the use - of {expr}, see |bufname()|. The optional {dict} can contain - the following entries: - group select only signs in this group - id select sign with this identifier - lnum select signs placed in this line. For the use - of {lnum}, see |line()|. - If {group} is '*', then signs in all the groups including the - global group are returned. If {group} is not supplied or is an - empty string, then only signs in the global group are - returned. If no arguments are supplied, then signs in the - global group placed in all the buffers are returned. - See |sign-group|. - - Each list item in the returned value is a dictionary with the - following entries: - bufnr number of the buffer with the sign - signs list of signs placed in {bufnr}. Each list - item is a dictionary with the below listed - entries - - The dictionary for each sign contains the following entries: - group sign group. Set to '' for the global group. - id identifier of the sign - lnum line number where the sign is placed - name name of the defined sign - priority sign priority - - The returned signs in a buffer are ordered by their line - number and priority. - - Returns an empty list on failure or if there are no placed - signs. - - Examples: > - " Get a List of signs placed in eval.c in the - " global group - echo sign_getplaced("eval.c") - - " Get a List of signs in group 'g1' placed in eval.c - echo sign_getplaced("eval.c", {'group' : 'g1'}) - - " Get a List of signs placed at line 10 in eval.c - echo sign_getplaced("eval.c", {'lnum' : 10}) - - " Get sign with identifier 10 placed in a.py - echo sign_getplaced("a.py", {'id' : 10}) - - " Get sign with id 20 in group 'g1' placed in a.py - echo sign_getplaced("a.py", {'group' : 'g1', - \ 'id' : 20}) - - " Get a List of all the placed signs - echo sign_getplaced() -< - *sign_jump()* -sign_jump({id}, {group}, {expr}) - Open the buffer {expr} or jump to the window that contains - {expr} and position the cursor at sign {id} in group {group}. - This is similar to the |:sign-jump| command. - - For the use of {expr}, see |bufname()|. - - Returns the line number of the sign. Returns -1 if the - arguments are invalid. - - Example: > - " Jump to sign 10 in the current buffer - call sign_jump(10, '', '') -< - *sign_place()* -sign_place({id}, {group}, {name}, {expr} [, {dict}]) - Place the sign defined as {name} at line {lnum} in file or - buffer {expr} and assign {id} and {group} to sign. This is - similar to the |:sign-place| command. - - If the sign identifier {id} is zero, then a new identifier is - allocated. Otherwise the specified number is used. {group} is - the sign group name. To use the global sign group, use an - empty string. {group} functions as a namespace for {id}, thus - two groups can use the same IDs. Refer to |sign-identifier| - and |sign-group| for more information. - - {name} refers to a defined sign. - {expr} refers to a buffer name or number. For the accepted - values, see |bufname()|. - - The optional {dict} argument supports the following entries: - lnum line number in the file or buffer - {expr} where the sign is to be placed. - For the accepted values, see |line()|. - priority priority of the sign. See - |sign-priority| for more information. - - If the optional {dict} is not specified, then it modifies the - placed sign {id} in group {group} to use the defined sign - {name}. - - Returns the sign identifier on success and -1 on failure. - - Examples: > - " Place a sign named sign1 with id 5 at line 20 in - " buffer json.c - call sign_place(5, '', 'sign1', 'json.c', - \ {'lnum' : 20}) - - " Updates sign 5 in buffer json.c to use sign2 - call sign_place(5, '', 'sign2', 'json.c') - - " Place a sign named sign3 at line 30 in - " buffer json.c with a new identifier - let id = sign_place(0, '', 'sign3', 'json.c', - \ {'lnum' : 30}) - - " Place a sign named sign4 with id 10 in group 'g3' - " at line 40 in buffer json.c with priority 90 - call sign_place(10, 'g3', 'sign4', 'json.c', - \ {'lnum' : 40, 'priority' : 90}) -< - *sign_placelist()* -sign_placelist({list}) - Place one or more signs. This is similar to the - |sign_place()| function. The {list} argument specifies the - List of signs to place. Each list item is a dict with the - following sign attributes: - buffer buffer name or number. For the accepted - values, see |bufname()|. - group sign group. {group} functions as a namespace - for {id}, thus two groups can use the same - IDs. If not specified or set to an empty - string, then the global group is used. See - |sign-group| for more information. - id sign identifier. If not specified or zero, - then a new unique identifier is allocated. - Otherwise the specified number is used. See - |sign-identifier| for more information. - lnum line number in the buffer {expr} where the - sign is to be placed. For the accepted values, - see |line()|. - name name of the sign to place. See |sign_define()| - for more information. - priority priority of the sign. When multiple signs are - placed on a line, the sign with the highest - priority is used. If not specified, the - default value of 10 is used. See - |sign-priority| for more information. - - If {id} refers to an existing sign, then the existing sign is - modified to use the specified {name} and/or {priority}. - - Returns a List of sign identifiers. If failed to place a - sign, the corresponding list item is set to -1. - - Examples: > - " Place sign s1 with id 5 at line 20 and id 10 at line - " 30 in buffer a.c - let [n1, n2] = sign_placelist([ - \ {'id' : 5, - \ 'name' : 's1', - \ 'buffer' : 'a.c', - \ 'lnum' : 20}, - \ {'id' : 10, - \ 'name' : 's1', - \ 'buffer' : 'a.c', - \ 'lnum' : 30} - \ ]) - - " Place sign s1 in buffer a.c at line 40 and 50 - " with auto-generated identifiers - let [n1, n2] = sign_placelist([ - \ {'name' : 's1', - \ 'buffer' : 'a.c', - \ 'lnum' : 40}, - \ {'name' : 's1', - \ 'buffer' : 'a.c', - \ 'lnum' : 50} - \ ]) -< -sign_undefine([{name}]) *sign_undefine()* -sign_undefine({list}) - Deletes a previously defined sign {name}. This is similar to - the |:sign-undefine| command. If {name} is not supplied, then - deletes all the defined signs. - - The one argument {list} can be used to undefine a list of - signs. Each list item is the name of a sign. - - Returns 0 on success and -1 on failure. For the one argument - {list} call, returns a list of values one for each undefined - sign. - - Examples: > - " Delete a sign named mySign - call sign_undefine("mySign") - - " Delete signs 'sign1' and 'sign2' - call sign_undefine(["sign1", "sign2"]) - - " Delete all the signs - call sign_undefine() -< -sign_unplace({group} [, {dict}]) *sign_unplace()* - Remove a previously placed sign in one or more buffers. This - is similar to the |:sign-unplace| command. - - {group} is the sign group name. To use the global sign group, - use an empty string. If {group} is set to '*', then all the - groups including the global group are used. - The signs in {group} are selected based on the entries in - {dict}. The following optional entries in {dict} are - supported: - buffer buffer name or number. See |bufname()|. - id sign identifier - If {dict} is not supplied, then all the signs in {group} are - removed. - - Returns 0 on success and -1 on failure. - - Examples: > - " Remove sign 10 from buffer a.vim - call sign_unplace('', {'buffer' : "a.vim", 'id' : 10}) - - " Remove sign 20 in group 'g1' from buffer 3 - call sign_unplace('g1', {'buffer' : 3, 'id' : 20}) - - " Remove all the signs in group 'g2' from buffer 10 - call sign_unplace('g2', {'buffer' : 10}) - - " Remove sign 30 in group 'g3' from all the buffers - call sign_unplace('g3', {'id' : 30}) - - " Remove all the signs placed in buffer 5 - call sign_unplace('*', {'buffer' : 5}) - - " Remove the signs in group 'g4' from all the buffers - call sign_unplace('g4') - - " Remove sign 40 from all the buffers - call sign_unplace('*', {'id' : 40}) - - " Remove all the placed signs from all the buffers - call sign_unplace('*') -< -sign_unplacelist({list}) *sign_unplacelist()* - Remove previously placed signs from one or more buffers. This - is similar to the |sign_unplace()| function. - - The {list} argument specifies the List of signs to remove. - Each list item is a dict with the following sign attributes: - buffer buffer name or number. For the accepted - values, see |bufname()|. If not specified, - then the specified sign is removed from all - the buffers. - group sign group name. If not specified or set to an - empty string, then the global sign group is - used. If set to '*', then all the groups - including the global group are used. - id sign identifier. If not specified, then all - the signs in the specified group are removed. - - Returns a List where an entry is set to 0 if the corresponding - sign was successfully removed or -1 on failure. - - Example: > - " Remove sign with id 10 from buffer a.vim and sign - " with id 20 from buffer b.vim - call sign_unplacelist([ - \ {'id' : 10, 'buffer' : "a.vim"}, - \ {'id' : 20, 'buffer' : 'b.vim'}, - \ ]) -< +sign_ functions are documented here: |sign-functions-details| + + simplify({filename}) *simplify()* Simplify the file name as much as possible without changing the meaning. Shortcuts (on MS-Windows) or symbolic links (on @@ -9822,147 +8825,11 @@ tempname() *tempname()* *temp-file-n For MS-Windows forward slashes are used when the 'shellslash' option is set or when 'shellcmdflag' starts with '-'. + term_ functions are documented here: |terminal-function-details| -test_alloc_fail({id}, {countdown}, {repeat}) *test_alloc_fail()* - This is for testing: If the memory allocation with {id} is - called, then decrement {countdown}, and when it reaches zero - let memory allocation fail {repeat} times. When {repeat} is - smaller than one it fails one time. - -test_autochdir() *test_autochdir()* - Set a flag to enable the effect of 'autochdir' before Vim - startup has finished. - -test_feedinput({string}) *test_feedinput()* - Characters in {string} are queued for processing as if they - were typed by the user. This uses a low level input buffer. - This function works only when with |+unix| or GUI is running. - -test_garbagecollect_now() *test_garbagecollect_now()* - Like garbagecollect(), but executed right away. This must - only be called directly to avoid any structure to exist - internally, and |v:testing| must have been set before calling - any function. - -test_garbagecollect_soon() *test_garbagecollect_soon()* - Set the flag to call the garbagecollector as if in the main - loop. Only to be used in tests. - -test_getvalue({name}) *test_getvalue()* - Get the value of an internal variable. These values for - {name} are supported: - need_fileinfo - -test_ignore_error({expr}) *test_ignore_error()* - Ignore any error containing {expr}. A normal message is given - instead. - This is only meant to be used in tests, where catching the - error with try/catch cannot be used (because it skips over - following code). - {expr} is used literally, not as a pattern. - When the {expr} is the string "RESET" then the list of ignored - errors is made empty. - -test_null_blob() *test_null_blob()* - Return a |Blob| that is null. Only useful for testing. - -test_null_channel() *test_null_channel()* - Return a |Channel| that is null. Only useful for testing. - {only available when compiled with the +channel feature} - -test_null_dict() *test_null_dict()* - Return a |Dict| that is null. Only useful for testing. - -test_null_job() *test_null_job()* - Return a |Job| that is null. Only useful for testing. - {only available when compiled with the +job feature} - -test_null_list() *test_null_list()* - Return a |List| that is null. Only useful for testing. - -test_null_partial() *test_null_partial()* - Return a |Partial| that is null. Only useful for testing. - -test_null_string() *test_null_string()* - Return a |String| that is null. Only useful for testing. - -test_option_not_set({name}) *test_option_not_set()* - Reset the flag that indicates option {name} was set. Thus it - looks like it still has the default value. Use like this: > - set ambiwidth=double - call test_option_not_set('ambiwidth') -< Now the 'ambiwidth' option behaves like it was never changed, - even though the value is "double". - Only to be used for testing! - -test_override({name}, {val}) *test_override()* - Overrides certain parts of Vim's internal processing to be able - to run tests. Only to be used for testing Vim! - The override is enabled when {val} is non-zero and removed - when {val} is zero. - Current supported values for name are: - - name effect when {val} is non-zero ~ - redraw disable the redrawing() function - redraw_flag ignore the RedrawingDisabled flag - char_avail disable the char_avail() function - starting reset the "starting" variable, see below - nfa_fail makes the NFA regexp engine fail to force a - fallback to the old engine - no_query_mouse do not query the mouse position for "dec" - terminals - no_wait_return set the "no_wait_return" flag. Not restored - with "ALL". - ALL clear all overrides ({val} is not used) - - "starting" is to be used when a test should behave like - startup was done. Since the tests are run by sourcing a - script the "starting" variable is non-zero. This is usually a - good thing (tests run faster), but sometimes changes behavior - in a way that the test doesn't work properly. - When using: > - call test_override('starting', 1) -< The value of "starting" is saved. It is restored by: > - call test_override('starting', 0) - -test_refcount({expr}) *test_refcount()* - Return the reference count of {expr}. When {expr} is of a - type that does not have a reference count, returns -1. Only - to be used for testing. - -test_scrollbar({which}, {value}, {dragging}) *test_scrollbar()* - Pretend using scrollbar {which} to move it to position - {value}. {which} can be: - left Left scrollbar of the current window - right Right scrollbar of the current window - hor Horizontal scrollbar - - For the vertical scrollbars {value} can be 1 to the - line-count of the buffer. For the horizontal scrollbar the - {value} can be between 1 and the maximum line length, assuming - 'wrap' is not set. - - When {dragging} is non-zero it's like dragging the scrollbar, - otherwise it's like clicking in the scrollbar. - Only works when the {which} scrollbar actually exists, - obviously only when using the GUI. - -test_setmouse({row}, {col}) *test_setmouse()* - Set the mouse position to be used for the next mouse action. - {row} and {col} are one based. - For example: > - call test_setmouse(4, 20) - call feedkeys("\<LeftMouse>", "xt") - -test_settime({expr}) *test_settime()* - Set the time Vim uses internally. Currently only used for - timestamps in the history, as they are used in viminfo, and - for undo. - Using a value of 1 makes Vim not sleep after a warning or - error message. - {expr} must evaluate to a number. When the value is zero the - normal behavior is restored. +test_ functions are documented here: |test-functions| + *timer_info()* timer_info([{id}]) @@ -13121,26 +11988,5 @@ This is not allowed when the textlock is - closing a window or quitting Vim - etc. -============================================================================== -14. Testing *testing* - -Vim can be tested after building it, usually with "make test". -The tests are located in the directory "src/testdir". - -There are several types of tests added over time: - test33.in oldest, don't add any more - test_something.in old style tests - test_something.vim new style tests - - *new-style-testing* -New tests should be added as new style tests. These use functions such as -|assert_equal()| to keep the test commands and the expected result in one -place. - *old-style-testing* -In some cases an old style test needs to be used. E.g. when testing Vim -without the |+eval| feature. - -Find more information in the file src/testdir/README.txt. - vim:tw=78:ts=8:noet:ft=help:norl:
--- a/runtime/doc/help.txt +++ b/runtime/doc/help.txt @@ -1,4 +1,4 @@ -*help.txt* For Vim version 8.1. Last change: 2019 May 12 +*help.txt* For Vim version 8.1. Last change: 2019 Jul 21 VIM - main help file k @@ -139,6 +139,7 @@ Advanced editing ~ |fold.txt| hide (fold) ranges of lines Special issues ~ +|testing.txt| testing Vim and Vim scripts |print.txt| printing |remote.txt| using Vim as a server or client |term.txt| using different terminals and mice
--- a/runtime/doc/sign.txt +++ b/runtime/doc/sign.txt @@ -1,4 +1,4 @@ -*sign.txt* For Vim version 8.1. Last change: 2019 Jun 04 +*sign.txt* For Vim version 8.1. Last change: 2019 Jul 21 VIM REFERENCE MANUAL by Gordon Prieur @@ -9,6 +9,7 @@ Sign Support Features *sign-support* 1. Introduction |sign-intro| 2. Commands |sign-commands| +3. Functions |sign-functions-details| {only available when compiled with the |+signs| feature} @@ -344,4 +345,357 @@ See |sign_jump()| for the equivalent Vim Same but jump to the sign in group {group} +============================================================================== +3. Functions *sign-functions-details* + +sign_define({name} [, {dict}]) *sign_define()* +sign_define({list}) + Define a new sign named {name} or modify the attributes of an + existing sign. This is similar to the |:sign-define| command. + + Prefix {name} with a unique text to avoid name collisions. + There is no {group} like with placing signs. + + The {name} can be a String or a Number. The optional {dict} + argument specifies the sign attributes. The following values + are supported: + icon full path to the bitmap file for the sign. + linehl highlight group used for the whole line the + sign is placed in. + text text that is displayed when there is no icon + or the GUI is not being used. + texthl highlight group used for the text item + + If the sign named {name} already exists, then the attributes + of the sign are updated. + + The one argument {list} can be used to define a list of signs. + Each list item is a dictionary with the above items in {dict} + and a 'name' item for the sign name. + + Returns 0 on success and -1 on failure. When the one argument + {list} is used, then returns a List of values one for each + defined sign. + + Examples: > + call sign_define("mySign", { + \ "text" : "=>", + \ "texthl" : "Error", + \ "linehl" : "Search"}) + call sign_define([ + \ {'name' : 'sign1', + \ 'text' : '=>'}, + \ {'name' : 'sign2', + \ 'text' : '!!'} + \ ]) +< +sign_getdefined([{name}]) *sign_getdefined()* + Get a list of defined signs and their attributes. + This is similar to the |:sign-list| command. + + If the {name} is not supplied, then a list of all the defined + signs is returned. Otherwise the attribute of the specified + sign is returned. + + Each list item in the returned value is a dictionary with the + following entries: + icon full path to the bitmap file of the sign + linehl highlight group used for the whole line the + sign is placed in. + name name of the sign + text text that is displayed when there is no icon + or the GUI is not being used. + texthl highlight group used for the text item + + Returns an empty List if there are no signs and when {name} is + not found. + + Examples: > + " Get a list of all the defined signs + echo sign_getdefined() + + " Get the attribute of the sign named mySign + echo sign_getdefined("mySign") +< +sign_getplaced([{expr} [, {dict}]]) *sign_getplaced()* + Return a list of signs placed in a buffer or all the buffers. + This is similar to the |:sign-place-list| command. + + If the optional buffer name {expr} is specified, then only the + list of signs placed in that buffer is returned. For the use + of {expr}, see |bufname()|. The optional {dict} can contain + the following entries: + group select only signs in this group + id select sign with this identifier + lnum select signs placed in this line. For the use + of {lnum}, see |line()|. + If {group} is '*', then signs in all the groups including the + global group are returned. If {group} is not supplied or is an + empty string, then only signs in the global group are + returned. If no arguments are supplied, then signs in the + global group placed in all the buffers are returned. + See |sign-group|. + + Each list item in the returned value is a dictionary with the + following entries: + bufnr number of the buffer with the sign + signs list of signs placed in {bufnr}. Each list + item is a dictionary with the below listed + entries + + The dictionary for each sign contains the following entries: + group sign group. Set to '' for the global group. + id identifier of the sign + lnum line number where the sign is placed + name name of the defined sign + priority sign priority + + The returned signs in a buffer are ordered by their line + number and priority. + + Returns an empty list on failure or if there are no placed + signs. + + Examples: > + " Get a List of signs placed in eval.c in the + " global group + echo sign_getplaced("eval.c") + + " Get a List of signs in group 'g1' placed in eval.c + echo sign_getplaced("eval.c", {'group' : 'g1'}) + + " Get a List of signs placed at line 10 in eval.c + echo sign_getplaced("eval.c", {'lnum' : 10}) + + " Get sign with identifier 10 placed in a.py + echo sign_getplaced("a.py", {'id' : 10}) + + " Get sign with id 20 in group 'g1' placed in a.py + echo sign_getplaced("a.py", {'group' : 'g1', + \ 'id' : 20}) + + " Get a List of all the placed signs + echo sign_getplaced() +< + *sign_jump()* +sign_jump({id}, {group}, {expr}) + Open the buffer {expr} or jump to the window that contains + {expr} and position the cursor at sign {id} in group {group}. + This is similar to the |:sign-jump| command. + + For the use of {expr}, see |bufname()|. + + Returns the line number of the sign. Returns -1 if the + arguments are invalid. + + Example: > + " Jump to sign 10 in the current buffer + call sign_jump(10, '', '') +< + + *sign_place()* +sign_place({id}, {group}, {name}, {expr} [, {dict}]) + Place the sign defined as {name} at line {lnum} in file or + buffer {expr} and assign {id} and {group} to sign. This is + similar to the |:sign-place| command. + + If the sign identifier {id} is zero, then a new identifier is + allocated. Otherwise the specified number is used. {group} is + the sign group name. To use the global sign group, use an + empty string. {group} functions as a namespace for {id}, thus + two groups can use the same IDs. Refer to |sign-identifier| + and |sign-group| for more information. + + {name} refers to a defined sign. + {expr} refers to a buffer name or number. For the accepted + values, see |bufname()|. + + The optional {dict} argument supports the following entries: + lnum line number in the file or buffer + {expr} where the sign is to be placed. + For the accepted values, see |line()|. + priority priority of the sign. See + |sign-priority| for more information. + + If the optional {dict} is not specified, then it modifies the + placed sign {id} in group {group} to use the defined sign + {name}. + + Returns the sign identifier on success and -1 on failure. + + Examples: > + " Place a sign named sign1 with id 5 at line 20 in + " buffer json.c + call sign_place(5, '', 'sign1', 'json.c', + \ {'lnum' : 20}) + + " Updates sign 5 in buffer json.c to use sign2 + call sign_place(5, '', 'sign2', 'json.c') + + " Place a sign named sign3 at line 30 in + " buffer json.c with a new identifier + let id = sign_place(0, '', 'sign3', 'json.c', + \ {'lnum' : 30}) + + " Place a sign named sign4 with id 10 in group 'g3' + " at line 40 in buffer json.c with priority 90 + call sign_place(10, 'g3', 'sign4', 'json.c', + \ {'lnum' : 40, 'priority' : 90}) +< + + *sign_placelist()* +sign_placelist({list}) + Place one or more signs. This is similar to the + |sign_place()| function. The {list} argument specifies the + List of signs to place. Each list item is a dict with the + following sign attributes: + buffer buffer name or number. For the accepted + values, see |bufname()|. + group sign group. {group} functions as a namespace + for {id}, thus two groups can use the same + IDs. If not specified or set to an empty + string, then the global group is used. See + |sign-group| for more information. + id sign identifier. If not specified or zero, + then a new unique identifier is allocated. + Otherwise the specified number is used. See + |sign-identifier| for more information. + lnum line number in the buffer {expr} where the + sign is to be placed. For the accepted values, + see |line()|. + name name of the sign to place. See |sign_define()| + for more information. + priority priority of the sign. When multiple signs are + placed on a line, the sign with the highest + priority is used. If not specified, the + default value of 10 is used. See + |sign-priority| for more information. + + If {id} refers to an existing sign, then the existing sign is + modified to use the specified {name} and/or {priority}. + + Returns a List of sign identifiers. If failed to place a + sign, the corresponding list item is set to -1. + + Examples: > + " Place sign s1 with id 5 at line 20 and id 10 at line + " 30 in buffer a.c + let [n1, n2] = sign_placelist([ + \ {'id' : 5, + \ 'name' : 's1', + \ 'buffer' : 'a.c', + \ 'lnum' : 20}, + \ {'id' : 10, + \ 'name' : 's1', + \ 'buffer' : 'a.c', + \ 'lnum' : 30} + \ ]) + + " Place sign s1 in buffer a.c at line 40 and 50 + " with auto-generated identifiers + let [n1, n2] = sign_placelist([ + \ {'name' : 's1', + \ 'buffer' : 'a.c', + \ 'lnum' : 40}, + \ {'name' : 's1', + \ 'buffer' : 'a.c', + \ 'lnum' : 50} + \ ]) +< + +sign_undefine([{name}]) *sign_undefine()* +sign_undefine({list}) + Deletes a previously defined sign {name}. This is similar to + the |:sign-undefine| command. If {name} is not supplied, then + deletes all the defined signs. + + The one argument {list} can be used to undefine a list of + signs. Each list item is the name of a sign. + + Returns 0 on success and -1 on failure. For the one argument + {list} call, returns a list of values one for each undefined + sign. + + Examples: > + " Delete a sign named mySign + call sign_undefine("mySign") + + " Delete signs 'sign1' and 'sign2' + call sign_undefine(["sign1", "sign2"]) + + " Delete all the signs + call sign_undefine() +< + +sign_unplace({group} [, {dict}]) *sign_unplace()* + Remove a previously placed sign in one or more buffers. This + is similar to the |:sign-unplace| command. + + {group} is the sign group name. To use the global sign group, + use an empty string. If {group} is set to '*', then all the + groups including the global group are used. + The signs in {group} are selected based on the entries in + {dict}. The following optional entries in {dict} are + supported: + buffer buffer name or number. See |bufname()|. + id sign identifier + If {dict} is not supplied, then all the signs in {group} are + removed. + + Returns 0 on success and -1 on failure. + + Examples: > + " Remove sign 10 from buffer a.vim + call sign_unplace('', {'buffer' : "a.vim", 'id' : 10}) + + " Remove sign 20 in group 'g1' from buffer 3 + call sign_unplace('g1', {'buffer' : 3, 'id' : 20}) + + " Remove all the signs in group 'g2' from buffer 10 + call sign_unplace('g2', {'buffer' : 10}) + + " Remove sign 30 in group 'g3' from all the buffers + call sign_unplace('g3', {'id' : 30}) + + " Remove all the signs placed in buffer 5 + call sign_unplace('*', {'buffer' : 5}) + + " Remove the signs in group 'g4' from all the buffers + call sign_unplace('g4') + + " Remove sign 40 from all the buffers + call sign_unplace('*', {'id' : 40}) + + " Remove all the placed signs from all the buffers + call sign_unplace('*') +< +sign_unplacelist({list}) *sign_unplacelist()* + Remove previously placed signs from one or more buffers. This + is similar to the |sign_unplace()| function. + + The {list} argument specifies the List of signs to remove. + Each list item is a dict with the following sign attributes: + buffer buffer name or number. For the accepted + values, see |bufname()|. If not specified, + then the specified sign is removed from all + the buffers. + group sign group name. If not specified or set to an + empty string, then the global sign group is + used. If set to '*', then all the groups + including the global group are used. + id sign identifier. If not specified, then all + the signs in the specified group are removed. + + Returns a List where an entry is set to 0 if the corresponding + sign was successfully removed or -1 on failure. + + Example: > + " Remove sign with id 10 from buffer a.vim and sign + " with id 20 from buffer b.vim + call sign_unplacelist([ + \ {'id' : 10, 'buffer' : "a.vim"}, + \ {'id' : 20, 'buffer' : 'b.vim'}, + \ ]) +< + vim:tw=78:ts=8:noet:ft=help:norl:
--- a/runtime/doc/tags +++ b/runtime/doc/tags @@ -3914,6 +3914,7 @@ E169 message.txt /*E169* E17 message.txt /*E17* E170 eval.txt /*E170* E171 eval.txt /*E171* +E172 eval.txt /*E172* E173 message.txt /*E173* E174 map.txt /*E174* E175 map.txt /*E175* @@ -3967,6 +3968,7 @@ E218 autocmd.txt /*E218* E219 message.txt /*E219* E22 message.txt /*E22* E220 message.txt /*E220* +E221 eval.txt /*E221* E222 message.txt /*E222* E223 options.txt /*E223* E224 map.txt /*E224* @@ -4683,12 +4685,12 @@ E909 eval.txt /*E909* E91 options.txt /*E91* E910 eval.txt /*E910* E911 eval.txt /*E911* -E912 eval.txt /*E912* +E912 channel.txt /*E912* E913 eval.txt /*E913* E914 eval.txt /*E914* E915 channel.txt /*E915* -E916 eval.txt /*E916* -E917 eval.txt /*E917* +E916 channel.txt /*E916* +E917 channel.txt /*E917* E918 channel.txt /*E918* E919 repeat.txt /*E919* E92 message.txt /*E92* @@ -4739,14 +4741,14 @@ E960 options.txt /*E960* E961 cmdline.txt /*E961* E962 eval.txt /*E962* E963 eval.txt /*E963* -E964 eval.txt /*E964* -E965 eval.txt /*E965* -E966 eval.txt /*E966* +E964 textprop.txt /*E964* +E965 textprop.txt /*E965* +E966 textprop.txt /*E966* E967 textprop.txt /*E967* -E968 eval.txt /*E968* -E969 eval.txt /*E969* +E968 textprop.txt /*E968* +E969 textprop.txt /*E969* E97 diff.txt /*E97* -E970 eval.txt /*E970* +E970 textprop.txt /*E970* E971 textprop.txt /*E971* E972 eval.txt /*E972* E973 eval.txt /*E973* @@ -5291,19 +5293,20 @@ asin() eval.txt /*asin()* asm.vim syntax.txt /*asm.vim* asm68k syntax.txt /*asm68k* asmh8300.vim syntax.txt /*asmh8300.vim* +assert-functions testing.txt /*assert-functions* assert-return eval.txt /*assert-return* -assert_beeps() eval.txt /*assert_beeps()* -assert_equal() eval.txt /*assert_equal()* -assert_equalfile() eval.txt /*assert_equalfile()* -assert_exception() eval.txt /*assert_exception()* -assert_fails() eval.txt /*assert_fails()* -assert_false() eval.txt /*assert_false()* -assert_inrange() eval.txt /*assert_inrange()* -assert_match() eval.txt /*assert_match()* -assert_notequal() eval.txt /*assert_notequal()* -assert_notmatch() eval.txt /*assert_notmatch()* -assert_report() eval.txt /*assert_report()* -assert_true() eval.txt /*assert_true()* +assert_beeps() testing.txt /*assert_beeps()* +assert_equal() testing.txt /*assert_equal()* +assert_equalfile() testing.txt /*assert_equalfile()* +assert_exception() testing.txt /*assert_exception()* +assert_fails() testing.txt /*assert_fails()* +assert_false() testing.txt /*assert_false()* +assert_inrange() testing.txt /*assert_inrange()* +assert_match() testing.txt /*assert_match()* +assert_notequal() testing.txt /*assert_notequal()* +assert_notmatch() testing.txt /*assert_notmatch()* +assert_report() testing.txt /*assert_report()* +assert_true() testing.txt /*assert_true()* at motion.txt /*at* atan() eval.txt /*atan()* atan2() eval.txt /*atan2()* @@ -5574,24 +5577,24 @@ cc change.txt /*cc* ceil() eval.txt /*ceil()* cfilter-plugin quickfix.txt /*cfilter-plugin* ch.vim syntax.txt /*ch.vim* -ch_canread() eval.txt /*ch_canread()* -ch_close() eval.txt /*ch_close()* -ch_close_in() eval.txt /*ch_close_in()* -ch_evalexpr() eval.txt /*ch_evalexpr()* -ch_evalraw() eval.txt /*ch_evalraw()* -ch_getbufnr() eval.txt /*ch_getbufnr()* -ch_getjob() eval.txt /*ch_getjob()* -ch_info() eval.txt /*ch_info()* -ch_log() eval.txt /*ch_log()* -ch_logfile() eval.txt /*ch_logfile()* -ch_open() eval.txt /*ch_open()* -ch_read() eval.txt /*ch_read()* -ch_readblob() eval.txt /*ch_readblob()* -ch_readraw() eval.txt /*ch_readraw()* -ch_sendexpr() eval.txt /*ch_sendexpr()* -ch_sendraw() eval.txt /*ch_sendraw()* -ch_setoptions() eval.txt /*ch_setoptions()* -ch_status() eval.txt /*ch_status()* +ch_canread() channel.txt /*ch_canread()* +ch_close() channel.txt /*ch_close()* +ch_close_in() channel.txt /*ch_close_in()* +ch_evalexpr() channel.txt /*ch_evalexpr()* +ch_evalraw() channel.txt /*ch_evalraw()* +ch_getbufnr() channel.txt /*ch_getbufnr()* +ch_getjob() channel.txt /*ch_getjob()* +ch_info() channel.txt /*ch_info()* +ch_log() channel.txt /*ch_log()* +ch_logfile() channel.txt /*ch_logfile()* +ch_open() channel.txt /*ch_open()* +ch_read() channel.txt /*ch_read()* +ch_readblob() channel.txt /*ch_readblob()* +ch_readraw() channel.txt /*ch_readraw()* +ch_sendexpr() channel.txt /*ch_sendexpr()* +ch_sendraw() channel.txt /*ch_sendraw()* +ch_setoptions() channel.txt /*ch_setoptions()* +ch_status() channel.txt /*ch_status()* change-list-jumps motion.txt /*change-list-jumps* change-name tips.txt /*change-name* change-tabs change.txt /*change-tabs* @@ -5626,6 +5629,7 @@ channel-commands channel.txt /*channel-c channel-demo channel.txt /*channel-demo* channel-drop channel.txt /*channel-drop* channel-functions usr_41.txt /*channel-functions* +channel-functions-details channel.txt /*channel-functions-details* channel-mode channel.txt /*channel-mode* channel-more channel.txt /*channel-more* channel-noblock channel.txt /*channel-noblock* @@ -7363,6 +7367,7 @@ job-err_cb channel.txt /*job-err_cb* job-err_io channel.txt /*job-err_io* job-exit_cb channel.txt /*job-exit_cb* job-functions usr_41.txt /*job-functions* +job-functions-details channel.txt /*job-functions-details* job-in_io channel.txt /*job-in_io* job-noblock channel.txt /*job-noblock* job-options channel.txt /*job-options* @@ -7374,12 +7379,12 @@ job-start-nochannel channel.txt /*job-st job-stoponexit channel.txt /*job-stoponexit* job-term channel.txt /*job-term* job-timeout channel.txt /*job-timeout* -job_getchannel() eval.txt /*job_getchannel()* -job_info() eval.txt /*job_info()* -job_setoptions() eval.txt /*job_setoptions()* -job_start() eval.txt /*job_start()* -job_status() eval.txt /*job_status()* -job_stop() eval.txt /*job_stop()* +job_getchannel() channel.txt /*job_getchannel()* +job_info() channel.txt /*job_info()* +job_setoptions() channel.txt /*job_setoptions()* +job_start() channel.txt /*job_start()* +job_status() channel.txt /*job_status()* +job_stop() channel.txt /*job_stop()* join() eval.txt /*join()* js_decode() eval.txt /*js_decode()* js_encode() eval.txt /*js_encode()* @@ -8036,7 +8041,7 @@ new-search-path version6.txt /*new-searc new-searchpat version6.txt /*new-searchpat* new-session-files version5.txt /*new-session-files* new-spell version7.txt /*new-spell* -new-style-testing eval.txt /*new-style-testing* +new-style-testing testing.txt /*new-style-testing* new-tab-pages version7.txt /*new-tab-pages* new-terminal-window version8.txt /*new-terminal-window* new-undo-branches version7.txt /*new-undo-branches* @@ -8084,7 +8089,7 @@ ocaml.vim syntax.txt /*ocaml.vim* octal eval.txt /*octal* octal-nrformats options.txt /*octal-nrformats* octal-number eval.txt /*octal-number* -old-style-testing eval.txt /*old-style-testing* +old-style-testing testing.txt /*old-style-testing* oldfiles-variable eval.txt /*oldfiles-variable* ole-activation if_ole.txt /*ole-activation* ole-eval if_ole.txt /*ole-eval* @@ -8321,16 +8326,16 @@ prompt_setinterrupt() eval.txt /*prompt_ prompt_setprompt() eval.txt /*prompt_setprompt()* promptbuffer-functions usr_41.txt /*promptbuffer-functions* pronounce intro.txt /*pronounce* -prop_add() eval.txt /*prop_add()* -prop_clear() eval.txt /*prop_clear()* -prop_find() eval.txt /*prop_find()* -prop_list() eval.txt /*prop_list()* -prop_remove() eval.txt /*prop_remove()* -prop_type_add() eval.txt /*prop_type_add()* -prop_type_change() eval.txt /*prop_type_change()* -prop_type_delete() eval.txt /*prop_type_delete()* -prop_type_get() eval.txt /*prop_type_get()* -prop_type_list() eval.txt /*prop_type_list()* +prop_add() textprop.txt /*prop_add()* +prop_clear() textprop.txt /*prop_clear()* +prop_find() textprop.txt /*prop_find()* +prop_list() textprop.txt /*prop_list()* +prop_remove() textprop.txt /*prop_remove()* +prop_type_add() textprop.txt /*prop_type_add()* +prop_type_change() textprop.txt /*prop_type_change()* +prop_type_delete() textprop.txt /*prop_type_delete()* +prop_type_get() textprop.txt /*prop_type_get()* +prop_type_list() textprop.txt /*prop_type_list()* psql ft_sql.txt /*psql* ptcap.vim syntax.txt /*ptcap.vim* pterm-mouse options.txt /*pterm-mouse* @@ -8692,21 +8697,22 @@ showing-menus gui.txt /*showing-menus* sign-column sign.txt /*sign-column* sign-commands sign.txt /*sign-commands* sign-functions usr_41.txt /*sign-functions* +sign-functions-details sign.txt /*sign-functions-details* sign-group sign.txt /*sign-group* sign-identifier sign.txt /*sign-identifier* sign-intro sign.txt /*sign-intro* sign-priority sign.txt /*sign-priority* sign-support sign.txt /*sign-support* sign.txt sign.txt /*sign.txt* -sign_define() eval.txt /*sign_define()* -sign_getdefined() eval.txt /*sign_getdefined()* -sign_getplaced() eval.txt /*sign_getplaced()* -sign_jump() eval.txt /*sign_jump()* -sign_place() eval.txt /*sign_place()* -sign_placelist() eval.txt /*sign_placelist()* -sign_undefine() eval.txt /*sign_undefine()* -sign_unplace() eval.txt /*sign_unplace()* -sign_unplacelist() eval.txt /*sign_unplacelist()* +sign_define() sign.txt /*sign_define()* +sign_getdefined() sign.txt /*sign_getdefined()* +sign_getplaced() sign.txt /*sign_getplaced()* +sign_jump() sign.txt /*sign_jump()* +sign_place() sign.txt /*sign_place()* +sign_placelist() sign.txt /*sign_placelist()* +sign_undefine() sign.txt /*sign_undefine()* +sign_unplace() sign.txt /*sign_unplace()* +sign_unplacelist() sign.txt /*sign_unplacelist()* signs sign.txt /*signs* simple-change change.txt /*simple-change* simplify() eval.txt /*simplify()* @@ -9357,29 +9363,32 @@ terminal-window terminal.txt /*terminal- terminal.txt terminal.txt /*terminal.txt* terminfo term.txt /*terminfo* termresponse-variable eval.txt /*termresponse-variable* +test-functions testing.txt /*test-functions* test-functions usr_41.txt /*test-functions* -test_alloc_fail() eval.txt /*test_alloc_fail()* -test_autochdir() eval.txt /*test_autochdir()* -test_feedinput() eval.txt /*test_feedinput()* -test_garbagecollect_now() eval.txt /*test_garbagecollect_now()* -test_garbagecollect_soon() eval.txt /*test_garbagecollect_soon()* -test_getvalue() eval.txt /*test_getvalue()* -test_ignore_error() eval.txt /*test_ignore_error()* -test_null_blob() eval.txt /*test_null_blob()* -test_null_channel() eval.txt /*test_null_channel()* -test_null_dict() eval.txt /*test_null_dict()* -test_null_job() eval.txt /*test_null_job()* -test_null_list() eval.txt /*test_null_list()* -test_null_partial() eval.txt /*test_null_partial()* -test_null_string() eval.txt /*test_null_string()* -test_option_not_set() eval.txt /*test_option_not_set()* -test_override() eval.txt /*test_override()* -test_refcount() eval.txt /*test_refcount()* -test_scrollbar() eval.txt /*test_scrollbar()* -test_setmouse() eval.txt /*test_setmouse()* -test_settime() eval.txt /*test_settime()* -testing eval.txt /*testing* +test_alloc_fail() testing.txt /*test_alloc_fail()* +test_autochdir() testing.txt /*test_autochdir()* +test_feedinput() testing.txt /*test_feedinput()* +test_garbagecollect_now() testing.txt /*test_garbagecollect_now()* +test_garbagecollect_soon() testing.txt /*test_garbagecollect_soon()* +test_getvalue() testing.txt /*test_getvalue()* +test_ignore_error() testing.txt /*test_ignore_error()* +test_null_blob() testing.txt /*test_null_blob()* +test_null_channel() testing.txt /*test_null_channel()* +test_null_dict() testing.txt /*test_null_dict()* +test_null_job() testing.txt /*test_null_job()* +test_null_list() testing.txt /*test_null_list()* +test_null_partial() testing.txt /*test_null_partial()* +test_null_string() testing.txt /*test_null_string()* +test_option_not_set() testing.txt /*test_option_not_set()* +test_override() testing.txt /*test_override()* +test_refcount() testing.txt /*test_refcount()* +test_scrollbar() testing.txt /*test_scrollbar()* +test_setmouse() testing.txt /*test_setmouse()* +test_settime() testing.txt /*test_settime()* +testing testing.txt /*testing* +testing-support testing.txt /*testing-support* testing-variable eval.txt /*testing-variable* +testing.txt testing.txt /*testing.txt* tex-cchar syntax.txt /*tex-cchar* tex-cole syntax.txt /*tex-cole* tex-conceal syntax.txt /*tex-conceal*
new file mode 100644 --- /dev/null +++ b/runtime/doc/testing.txt @@ -0,0 +1,317 @@ +*testing.txt* For Vim version 8.1. Last change: 2019 Jul 21 + + + VIM REFERENCE MANUAL by Bram Moolenaar + + +Testing Vim and Vim script *testing-support* + +Expression evaluation is explained in |eval.txt|. This file goes into details +about writing tests in Vim script. This can be used for testing Vim itself +and for testing plugins. + +1. Testing Vim |testing| +2. Test functions |test-functions| +3. Assert funtions |assert-functions| + +============================================================================== +1. Testing Vim *testing* + +Vim can be tested after building it, usually with "make test". +The tests are located in the directory "src/testdir". + +There are several types of tests added over time: + test33.in oldest, don't add any of these + test_something.in old style tests + test_something.vim new style tests + + *new-style-testing* +New tests should be added as new style tests. These use functions such as +|assert_equal()| to keep the test commands and the expected result in one +place. + *old-style-testing* +In some cases an old style test needs to be used. E.g. when testing Vim +without the |+eval| feature. + +Find more information in the file src/testdir/README.txt. + +============================================================================== +2. Test functions *test-functions* + +test_alloc_fail({id}, {countdown}, {repeat}) *test_alloc_fail()* + This is for testing: If the memory allocation with {id} is + called, then decrement {countdown}, and when it reaches zero + let memory allocation fail {repeat} times. When {repeat} is + smaller than one it fails one time. + + +test_autochdir() *test_autochdir()* + Set a flag to enable the effect of 'autochdir' before Vim + startup has finished. + + +test_feedinput({string}) *test_feedinput()* + Characters in {string} are queued for processing as if they + were typed by the user. This uses a low level input buffer. + This function works only when with |+unix| or GUI is running. + + +test_garbagecollect_now() *test_garbagecollect_now()* + Like garbagecollect(), but executed right away. This must + only be called directly to avoid any structure to exist + internally, and |v:testing| must have been set before calling + any function. + + +test_garbagecollect_soon() *test_garbagecollect_soon()* + Set the flag to call the garbagecollector as if in the main + loop. Only to be used in tests. + + +test_getvalue({name}) *test_getvalue()* + Get the value of an internal variable. These values for + {name} are supported: + need_fileinfo + + +test_ignore_error({expr}) *test_ignore_error()* + Ignore any error containing {expr}. A normal message is given + instead. + This is only meant to be used in tests, where catching the + error with try/catch cannot be used (because it skips over + following code). + {expr} is used literally, not as a pattern. + When the {expr} is the string "RESET" then the list of ignored + errors is made empty. + + +test_null_blob() *test_null_blob()* + Return a |Blob| that is null. Only useful for testing. + + +test_null_channel() *test_null_channel()* + Return a |Channel| that is null. Only useful for testing. + {only available when compiled with the +channel feature} + + +test_null_dict() *test_null_dict()* + Return a |Dict| that is null. Only useful for testing. + + +test_null_job() *test_null_job()* + Return a |Job| that is null. Only useful for testing. + {only available when compiled with the +job feature} + + +test_null_list() *test_null_list()* + Return a |List| that is null. Only useful for testing. + + +test_null_partial() *test_null_partial()* + Return a |Partial| that is null. Only useful for testing. + + +test_null_string() *test_null_string()* + Return a |String| that is null. Only useful for testing. + + +test_option_not_set({name}) *test_option_not_set()* + Reset the flag that indicates option {name} was set. Thus it + looks like it still has the default value. Use like this: > + set ambiwidth=double + call test_option_not_set('ambiwidth') +< Now the 'ambiwidth' option behaves like it was never changed, + even though the value is "double". + Only to be used for testing! + + +test_override({name}, {val}) *test_override()* + Overrides certain parts of Vim's internal processing to be able + to run tests. Only to be used for testing Vim! + The override is enabled when {val} is non-zero and removed + when {val} is zero. + Current supported values for name are: + + name effect when {val} is non-zero ~ + redraw disable the redrawing() function + redraw_flag ignore the RedrawingDisabled flag + char_avail disable the char_avail() function + starting reset the "starting" variable, see below + nfa_fail makes the NFA regexp engine fail to force a + fallback to the old engine + no_query_mouse do not query the mouse position for "dec" + terminals + no_wait_return set the "no_wait_return" flag. Not restored + with "ALL". + ALL clear all overrides ({val} is not used) + + "starting" is to be used when a test should behave like + startup was done. Since the tests are run by sourcing a + script the "starting" variable is non-zero. This is usually a + good thing (tests run faster), but sometimes changes behavior + in a way that the test doesn't work properly. + When using: > + call test_override('starting', 1) +< The value of "starting" is saved. It is restored by: > + call test_override('starting', 0) + + +test_refcount({expr}) *test_refcount()* + Return the reference count of {expr}. When {expr} is of a + type that does not have a reference count, returns -1. Only + to be used for testing. + + +test_scrollbar({which}, {value}, {dragging}) *test_scrollbar()* + Pretend using scrollbar {which} to move it to position + {value}. {which} can be: + left Left scrollbar of the current window + right Right scrollbar of the current window + hor Horizontal scrollbar + + For the vertical scrollbars {value} can be 1 to the + line-count of the buffer. For the horizontal scrollbar the + {value} can be between 1 and the maximum line length, assuming + 'wrap' is not set. + + When {dragging} is non-zero it's like dragging the scrollbar, + otherwise it's like clicking in the scrollbar. + Only works when the {which} scrollbar actually exists, + obviously only when using the GUI. + + +test_setmouse({row}, {col}) *test_setmouse()* + Set the mouse position to be used for the next mouse action. + {row} and {col} are one based. + For example: > + call test_setmouse(4, 20) + call feedkeys("\<LeftMouse>", "xt") + + +test_settime({expr}) *test_settime()* + Set the time Vim uses internally. Currently only used for + timestamps in the history, as they are used in viminfo, and + for undo. + Using a value of 1 makes Vim not sleep after a warning or + error message. + {expr} must evaluate to a number. When the value is zero the + normal behavior is restored. + +============================================================================== +3. Assert functions *assert-functions* + + +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. + + + vim:tw=78:ts=8:noet:ft=help:norl:
--- a/runtime/doc/textprop.txt +++ b/runtime/doc/textprop.txt @@ -1,4 +1,4 @@ -*textprop.txt* For Vim version 8.1. Last change: 2019 Jun 13 +*textprop.txt* For Vim version 8.1. Last change: 2019 Jul 20 VIM REFERENCE MANUAL by Bram Moolenaar @@ -116,6 +116,202 @@ prop_list({lnum} [, {props}) text pro prop_remove({props} [, {lnum} [, {lnum-end}]]) remove a text property + *prop_add()* *E965* +prop_add({lnum}, {col}, {props}) + Attach a text property at position {lnum}, {col}. {col} is + counted in bytes, use one for the first column. + If {lnum} is invalid an error is given. *E966* + If {col} is invalid an error is given. *E964* + + {props} is a dictionary with these fields: + length length of text in bytes, can only be used + for a property that does not continue in + another line; can be zero + end_lnum line number for the end of text + end_col column just after the text; not used when + "length" is present; when {col} and "end_col" + are equal, and "end_lnum" is omitted or equal + to {lnum}, this is a zero-width text property + bufnr buffer to add the property to; when omitted + the current buffer is used + id user defined ID for the property; when omitted + zero is used + type name of the text property type + All fields except "type" are optional. + + It is an error when both "length" and "end_lnum" or "end_col" + are given. Either use "length" or "end_col" for a property + within one line, or use "end_lnum" and "end_col" for a + property that spans more than one line. + When neither "length" nor "end_col" are given the property + will be zero-width. That means it will not be highlighted but + will move with the text, as a kind of mark. + The property can end exactly at the last character of the + text, or just after it. In the last case, if text is appended + to the line, the text property size will increase, also when + the property type does not have "end_incl" set. + + "type" will first be looked up in the buffer the property is + added to. When not found, the global property types are used. + If not found an error is given. + + See |text-properties| for information about text properties. + + +prop_clear({lnum} [, {lnum-end} [, {props}]]) *prop_clear()* + Remove all text properties from line {lnum}. + When {lnum-end} is given, remove all text properties from line + {lnum} to {lnum-end} (inclusive). + + When {props} contains a "bufnr" item use this buffer, + otherwise use the current buffer. + + See |text-properties| for information about text properties. + + *prop_find()* +prop_find({props} [, {direction}]) + NOT IMPLEMENTED YET + Search for a text property as specified with {props}: + id property with this ID + type property with this type name + bufnr buffer to search in; when present a + start position with "lnum" and "col" + must be given; when omitted the + current buffer is used + lnum start in this line (when omitted start + at the cursor) + col start at this column (when omitted + and "lnum" is given: use column 1, + otherwise start at the cursor) + skipstart do not look for a match at the start + position + + {direction} can be "f" for forward and "b" for backward. When + omitted forward search is performed. + + If a match is found then a Dict is returned with the entries + as with prop_list(), and additionally an "lnum" entry. + If no match is found then an empty Dict is returned. + + See |text-properties| for information about text properties. + + +prop_list({lnum} [, {props}]) *prop_list()* + Return a List with all text properties in line {lnum}. + + When {props} contains a "bufnr" item, use this buffer instead + of the current buffer. + + The properties are ordered by starting column and priority. + Each property is a Dict with these entries: + col starting column + length length in bytes, one more if line break is + included + id property ID + type name of the property type, omitted if + the type was deleted + start when TRUE property starts in this line + end when TRUE property ends in this line + + When "start" is zero the property started in a previous line, + the current one is a continuation. + When "end" is zero the property continues in the next line. + The line break after this line is included. + + See |text-properties| for information about text properties. + + + *prop_remove()* *E968* +prop_remove({props} [, {lnum} [, {lnum-end}]]) + Remove a matching text property from line {lnum}. When + {lnum-end} is given, remove matching text properties from line + {lnum} to {lnum-end} (inclusive). + When {lnum} is omitted remove matching text properties from + all lines. + + {props} is a dictionary with these fields: + id remove text properties with this ID + type remove text properties with this type name + bufnr use this buffer instead of the current one + all when TRUE remove all matching text properties, + not just the first one + A property matches when either "id" or "type" matches. + If buffer "bufnr" does not exist you get an error message. + If buffer "bufnr" is not loaded then nothing happens. + + Returns the number of properties that were removed. + + See |text-properties| for information about text properties. + + +prop_type_add({name}, {props}) *prop_type_add()* *E969* *E970* + Add a text property type {name}. If a property type with this + name already exists an error is given. + {props} is a dictionary with these optional fields: + bufnr define the property only for this buffer; this + avoids name collisions and automatically + clears the property types when the buffer is + deleted. + highlight name of highlight group to use + priority when a character has multiple text + properties the one with the highest priority + will be used; negative values can be used, the + default priority is zero + combine when TRUE combine the highlight with any + syntax highlight; when omitted or FALSE syntax + highlight will not be used + start_incl when TRUE inserts at the start position will + be included in the text property + end_incl when TRUE inserts at the end position will be + included in the text property + + See |text-properties| for information about text properties. + + +prop_type_change({name}, {props}) *prop_type_change()* + Change properties of an existing text property type. If a + property with this name does not exist an error is given. + The {props} argument is just like |prop_type_add()|. + + See |text-properties| for information about text properties. + + +prop_type_delete({name} [, {props}]) *prop_type_delete()* + Remove the text property type {name}. When text properties + using the type {name} are still in place, they will not have + an effect and can no longer be removed by name. + + {props} can contain a "bufnr" item. When it is given, delete + a property type from this buffer instead of from the global + property types. + + When text property type {name} is not found there is no error. + + See |text-properties| for information about text properties. + + +prop_type_get([{name} [, {props}]) *prop_type_get()* + Returns the properties of property type {name}. This is a + dictionary with the same fields as was given to + prop_type_add(). + When the property type {name} does not exist, an empty + dictionary is returned. + + {props} can contain a "bufnr" item. When it is given, use + this buffer instead of the global property types. + + See |text-properties| for information about text properties. + + +prop_type_list([{props}]) *prop_type_list()* + Returns a list with all property type names. + + {props} can contain a "bufnr" item. When it is given, use + this buffer instead of the global property types. + + See |text-properties| for information about text properties. + + ============================================================================== 3. When text changes *text-prop-changes*