diff options
Diffstat (limited to 'runtime/doc/eval.txt')
-rw-r--r-- | runtime/doc/eval.txt | 157 |
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 |