mirror of
https://github.com/neovim/neovim.git
synced 2024-12-24 05:05:00 -07:00
vim-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.
ed997adaa1
Vim commit 5477506a9f01d40fad2e8f0555bc37adee30478f
contains the duplicate tag fix in runtime/doc/testing.txt.
This commit is contained in:
parent
fbe18d9ca4
commit
01a629ca03
@ -2641,122 +2641,7 @@ argv([{nr} [, {winid}])
|
||||
The {winid} argument specifies the window ID, see |argc()|.
|
||||
For the Vim command line arguments see |v:argv|.
|
||||
|
||||
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()|, |assert_nobeep()| 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} [, {msg}])
|
||||
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.
|
||||
|
||||
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 or |v:false|. When "{actual}"
|
||||
is not a number or |v:false| 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_nobeep({cmd}) *assert_nobeep()*
|
||||
Run {cmd} and add an error message to |v:errors| if it
|
||||
produces a beep or visual bell.
|
||||
Also see |assert_beeps()|.
|
||||
|
||||
*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 or |v:true|.
|
||||
When {actual} is not a number or |v:true| the assert fails.
|
||||
When {msg} is omitted an error in the form "Expected True but
|
||||
got {actual}" is produced.
|
||||
assert_ functions are documented here: |assert-functions-details|
|
||||
|
||||
asin({expr}) *asin()*
|
||||
Return the arc sine of {expr} measured in radians, as a |Float|
|
||||
@ -7938,355 +7823,8 @@ shiftwidth([{col}]) *shiftwidth()*
|
||||
'vartabstop' feature. If 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
|
||||
numhl highlight group used for 'number' column at the
|
||||
associated line. Overrides |hl-LineNr|,
|
||||
|hl-CursorLineNr|.
|
||||
|
||||
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
|
||||
numhl highlight group used for 'number' column at the
|
||||
associated line. Overrides |hl-LineNr|,
|
||||
|hl-CursorLineNr|.
|
||||
|
||||
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_place([
|
||||
\ {'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_place([
|
||||
\ {'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_unplace([{'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
|
||||
@ -9146,11 +8684,7 @@ termopen({cmd}[, {opts}]) *termopen()*
|
||||
|
||||
See |terminal| for more information.
|
||||
|
||||
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_ functions are documented here: |test-functions-details|
|
||||
|
||||
tan({expr}) *tan()*
|
||||
Return the tangent of {expr}, measured in radians, as a |Float|
|
||||
|
@ -132,6 +132,7 @@ Advanced editing ~
|
||||
|lua.txt| Lua API
|
||||
|
||||
Special issues ~
|
||||
|testing.txt| testing Vim and Vim scripts
|
||||
|print.txt| printing
|
||||
|remote.txt| using Vim as a server or client
|
||||
|
||||
|
@ -337,4 +337,363 @@ 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
|
||||
numhl highlight group used for 'number' column at the
|
||||
associated line. Overrides |hl-LineNr|,
|
||||
|hl-CursorLineNr|.
|
||||
|
||||
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
|
||||
numhl highlight group used for 'number' column at the
|
||||
associated line. Overrides |hl-LineNr|,
|
||||
|hl-CursorLineNr|.
|
||||
|
||||
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:
|
||||
|
169
runtime/doc/testing.txt
Normal file
169
runtime/doc/testing.txt
Normal file
@ -0,0 +1,169 @@
|
||||
*testing.txt* Nvim
|
||||
|
||||
|
||||
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-details|
|
||||
3. Assert funtions |assert-functions-details|
|
||||
|
||||
==============================================================================
|
||||
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-details*
|
||||
|
||||
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.
|
||||
|
||||
==============================================================================
|
||||
3. Assert functions *assert-functions-details*
|
||||
|
||||
|
||||
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()|, |assert_nobeep()| 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.
|
||||
|
||||
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_nobeep({cmd}) *assert_nobeep()*
|
||||
Run {cmd} and add an error message to |v:errors| if it
|
||||
produces a beep or visual bell.
|
||||
Also see |assert_beeps()|.
|
||||
|
||||
*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 or |v:true|.
|
||||
When {actual} is not a number or |v:true| 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:
|
@ -498,13 +498,22 @@ Test functions:
|
||||
test_alloc_fail()
|
||||
test_autochdir()
|
||||
test_disable_char_avail()
|
||||
test_feedinput()
|
||||
test_garbagecollect_soon
|
||||
test_getvalue()
|
||||
test_ignore_error()
|
||||
test_null_blob()
|
||||
test_null_channel()
|
||||
test_null_dict()
|
||||
test_null_job()
|
||||
test_null_list()
|
||||
test_null_partial()
|
||||
test_null_string()
|
||||
test_option_not_set()
|
||||
test_override()
|
||||
test_refcount()
|
||||
test_scrollbar()
|
||||
test_setmouse()
|
||||
test_settime()
|
||||
|
||||
TUI:
|
||||
|
Loading…
Reference in New Issue
Block a user