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.
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 6a44c9f..79c5409 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -1,4 +1,4 @@
-*eval.txt* For Vim version 8.1. Last change: 2019 Jul 19
+*eval.txt* For Vim version 8.1. Last change: 2019 Jul 21
VIM REFERENCE MANUAL by Bram Moolenaar
@@ -31,7 +31,9 @@
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 @@
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_ functions are documented here: |assert-functions|
- *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.
asin({expr}) *asin()*
Return the arc sine of {expr} measured in radians, as a |Float|
@@ -3358,213 +3252,10 @@
< 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_ functions are documented here: |channel-functions-details|
-ch_open({address} [, {options}]) *ch_open()*
- Open a channel to {address}. See |channel|.
- Returns a Channel. Use |ch_status()| to check for failure.
-
- {address} has the form "hostname:port", e.g.,
- "localhost:8765".
-
- If {options} is given it must be a |Dictionary|.
- See |channel-open-options|.
-
- {only available when compiled with the |+channel| feature}
-
-ch_read({handle} [, {options}]) *ch_read()*
- Read from {handle} and return the received message.
- {handle} can be a Channel or a Job that has a Channel.
- For a NL channel this waits for a NL to arrive, except when
- there is nothing more to read (channel was closed).
- See |channel-more|.
- {only available when compiled with the |+channel| feature}
-
-ch_readblob({handle} [, {options}]) *ch_readblob()*
- Like ch_read() but reads binary data and returns a |Blob|.
- See |channel-more|.
- {only available when compiled with the |+channel| feature}
-
-ch_readraw({handle} [, {options}]) *ch_readraw()*
- Like ch_read() but for a JS and JSON channel does not decode
- the message. For a NL channel it does not block waiting for
- the NL to arrive, but otherwise works like ch_read().
- See |channel-more|.
- {only available when compiled with the |+channel| feature}
-
-ch_sendexpr({handle}, {expr} [, {options}]) *ch_sendexpr()*
- Send {expr} over {handle}. The {expr} is encoded
- according to the type of channel. The function cannot be used
- with a raw channel.
- See |channel-use|. *E912*
- {handle} can be a Channel or a Job that has a Channel.
-
- {only available when compiled with the |+channel| feature}
-
-ch_sendraw({handle}, {expr} [, {options}]) *ch_sendraw()*
- Send |String| or |Blob| {expr} over {handle}.
- Works like |ch_sendexpr()|, but does not encode the request or
- decode the response. The caller is responsible for the
- correct contents. Also does not add a newline for a channel
- in NL mode, the caller must do that. The NL in the response
- is removed.
- See |channel-use|.
-
- {only available when compiled with the |+channel| feature}
-
-ch_setoptions({handle}, {options}) *ch_setoptions()*
- Set options on {handle}:
- "callback" the channel callback
- "timeout" default read timeout in msec
- "mode" mode for the whole channel
- See |ch_open()| for more explanation.
- {handle} can be a Channel or a Job that has a Channel.
-
- Note that changing the mode may cause queued messages to be
- lost.
-
- These options cannot be changed:
- "waittime" only applies to |ch_open()|
-
-ch_status({handle} [, {options}]) *ch_status()*
- Return the status of {handle}:
- "fail" failed to open the channel
- "open" channel can be used
- "buffered" channel can be read, not written to
- "closed" channel can not be used
- {handle} can be a Channel or a Job that has a Channel.
- "buffered" is used when the channel was closed but there is
- still data that can be obtained with |ch_read()|.
-
- If {options} is given it can contain a "part" entry to specify
- the part of the channel to return the status for: "out" or
- "err". For example, to get the error status: >
- ch_status(job, {"part": "err"})
-<
changenr() *changenr()*
Return the number of the most recent change. This is the same
number as what is displayed with |:undolist| and can be used
@@ -6044,161 +5735,9 @@
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|
+job_ functions are documented here: |job-functions-details|
- 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}
join({list} [, {sep}]) *join()*
Join the items in {list} together into one String.
@@ -7333,201 +6872,7 @@
"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 @@
'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.
+sign_ functions are documented here: |sign-functions-details|
- 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'},
- \ ])
-<
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 @@
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_ functions are documented here: |test-functions|
-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.
*timer_info()*
timer_info([{id}])
@@ -13121,26 +11988,5 @@
- 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: