patch 8.1.0614: placing signs can be complicated
Problem: Placing signs can be complicated.
Solution: Add functions for defining and placing signs. Introduce a group
name to avoid different plugins using the same signs. (Yegappan
Lakshmanan, closes #3652)
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index afc4fe1..f76af38 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -2408,6 +2408,15 @@
String escape {string} for use as shell
command argument
shiftwidth([{col}]) Number effective value of 'shiftwidth'
+sign_define({name} [, {dict}]) Number define or update a sign
+sign_getdefined([{name}]) List get a list of defined signs
+sign_getplaced([{expr} [, {dict}]])
+ List get a list of placed signs
+sign_place({id}, {group}, {name}, {expr} [, {dict}])
+ Number place a sign
+sign_undefine([{name}]) Number undefine a sign
+sign_unplace({group} [, {dict}])
+ Number unplace a sign
simplify({filename}) String simplify filename as much as possible
sin({expr}) Float sine of {expr}
sinh({expr}) Float hyperbolic sine of {expr}
@@ -7858,7 +7867,217 @@
'vartabstop' feature. If the 'vartabstop' setting is enabled and
no {col} argument is given, column 1 will be assumed.
+sign_define({name} [, {dict}]) *sign_define()*
+ 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
+ For an existing sign, the attributes are updated.
+
+ Returns 0 on success and -1 on failure.
+
+ Examples: >
+ call sign_define("mySign", {"text" : "=>", "texthl" :
+ \ "Error", "linehl" : "Search"})
+<
+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, 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.
+
+ 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
+
+ Returns an empty list on failure.
+
+ 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_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.
+
+ 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.
+
+ {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()|.
+ 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_undefine([{name}]) *sign_undefine()*
+ 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.
+
+ Examples: >
+ " Delete a sign named mySign
+ call sign_undefine("mySign")
+
+ " 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('*')
+<
simplify({filename}) *simplify()*
Simplify the file name as much as possible without changing
the meaning. Shortcuts (on MS-Windows) or symbolic links (on