GitHub/vim
1
0
Fork 0
mirror of https://github.com/vim/vim synced 2025-07-15 16:51:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
Problem:    The eval.txt help file is too big.
Solution:   Split off testing support to testing.txt.  Move function details
            to where the functionality is explained.
This commit is contained in:
Bram Moolenaar
2019-07-21 16:42:00 +02:00
parent 663bbc09ba
commit ed997adaa1
9 changed files with 1356 additions and 1266 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
runtime/doc/Makefile
View File

@ -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 \

385
runtime/doc/channel.txt
View File

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

1176
runtime/doc/eval.txt
View File

File diff suppressed because it is too large Load Diff

3
runtime/doc/help.txt
View File

@ -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

356
runtime/doc/sign.txt
View File

@ -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 script function.
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:

183
runtime/doc/tags
View File

@ -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-commands*
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-start-nochannel*
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-search-path*
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_setinterrupt()*
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-window*
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*

317
runtime/doc/testing.txt Normal file
View File

@ -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:

198
runtime/doc/textprop.txt
View File

@ -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 properties in {lnum}
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*

2
src/version.c
View File

@ -777,6 +777,8 @@ static char *(features[]) =
static int included_patches[] =
{ /* Add new patch number below this line */
/**/
1726,
/**/
1725,
/**/