aboutsummaryrefslogtreecommitdiff
path: root/runtime/doc/eval.txt
diff options
context:
space:
mode:
Diffstat (limited to 'runtime/doc/eval.txt')
-rw-r--r--runtime/doc/eval.txt157
1 files changed, 135 insertions, 22 deletions
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 78c7a8a69f..00b1be013a 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -2395,6 +2395,7 @@ shellescape({string} [, {special}])
command argument
shiftwidth([{col}]) Number effective value of 'shiftwidth'
sign_define({name} [, {dict}]) Number define or update a sign
+sign_define({list}) List define or update a list of signs
sign_getdefined([{name}]) List get a list of defined signs
sign_getplaced([{expr} [, {dict}]])
List get a list of placed signs
@@ -2402,9 +2403,12 @@ sign_jump({id}, {group}, {expr})
Number jump to a sign
sign_place({id}, {group}, {name}, {expr} [, {dict}])
Number place a sign
+sign_placelist({list}) List place a list of signs
sign_undefine([{name}]) Number undefine a sign
+sign_undefine({list}) List undefine a list of signs
sign_unplace({group} [, {dict}])
Number unplace a sign
+sign_unplacelist({list}) List unplace a list of signs
simplify({filename}) String simplify filename as much as possible
sin({expr}) Float sine of {expr}
sinh({expr}) Float hyperbolic sine of {expr}
@@ -7927,6 +7931,7 @@ shiftwidth([{col}]) *shiftwidth()*
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.
@@ -7936,24 +7941,38 @@ sign_define({name} [, {dict}]) *sign_define()*
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
+ 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
+ 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
+ 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.
- Returns 0 on success and -1 on failure.
+ 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("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.
@@ -7965,14 +7984,14 @@ sign_getdefined([{name}]) *sign_getdefined()*
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
+ 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
+ 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
+ texthl highlight group used for the text item
+ numhl highlight group used for 'number' column at the
associated line. Overrides |hl-LineNr|,
|hl-CursorLineNr|.
@@ -8063,25 +8082,25 @@ sign_jump({id}, {group}, {expr})
<
*sign_place()*
sign_place({id}, {group}, {name}, {expr} [, {dict}])
- Place the sign defined as {name} at line {lnum} in file {expr}
- and assign {id} and {group} to sign. This is similar to the
- |:sign-place| command.
+ 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|
- for more information.
+ 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 buffer {expr} where
- the sign is to be placed. For the
- accepted values, see |line()|.
+ 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.
@@ -8110,17 +8129,85 @@ sign_place({id}, {group}, {name}, {expr} [, {dict}])
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.
- Returns 0 on success and -1 on failure.
+ 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()
<
@@ -8166,6 +8253,32 @@ sign_unplace({group} [, {dict}]) *sign_unplace()*
" 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