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
diff --git a/runtime/doc/sign.txt b/runtime/doc/sign.txt
index bd63ea9..115e1fa 100644
--- a/runtime/doc/sign.txt
+++ b/runtime/doc/sign.txt
@@ -1,4 +1,4 @@
-*sign.txt* For Vim version 8.1. Last change: 2016 Aug 17
+*sign.txt* For Vim version 8.1. Last change: 2018 Dec 21
VIM REFERENCE MANUAL by Gordon Prieur
@@ -51,6 +51,20 @@
Example to set the color: >
:highlight SignColumn guibg=darkgrey
+<
+ *sign-group*
+Each sign can be assigned to either the global group or a named group. When
+placing a sign, if a group name is not supplied, or an empty string is used,
+then the sign is placed in the global group. Otherwise the sign is placed in
+the named group. The sign identifier is unique within a group. The sign group
+allows Vim plugins to use unique signs without interfering with other plugins
+using signs.
+
+ *sign-priority*
+Each placed sign is assigned a priority value. When multiple signs are placed
+on the same line, the attributes of the sign with the highest priority is used
+independent of the sign group. The default priority for a sign is 10. The
+priority is assigned at the time of placing a sign.
==============================================================================
2. Commands *sign-commands* *:sig* *:sign*
@@ -69,6 +83,8 @@
DEFINING A SIGN. *:sign-define* *E255* *E160* *E612*
+See |sign_define()| for the equivalent Vim script function.
+
:sign define {name} {argument}...
Define a new sign or set attributes for an existing sign.
The {name} can either be a number (all digits) or a name
@@ -106,13 +122,18 @@
DELETING A SIGN *:sign-undefine* *E155*
+See |sign_undefine()| for the equivalent Vim script function.
+
:sign undefine {name}
Deletes a previously defined sign. If signs with this {name}
are still placed this will cause trouble.
+
LISTING SIGNS *:sign-list* *E156*
+See |sign_getdefined()| for the equivalent Vim script function.
+
:sign list Lists all defined signs and their attributes.
:sign list {name}
@@ -121,6 +142,8 @@
PLACING SIGNS *:sign-place* *E158*
+See |sign_place()| for the equivalent Vim script function.
+
:sign place {id} line={lnum} name={name} file={fname}
Place sign defined as {name} at line {lnum} in file {fname}.
*:sign-fname*
@@ -136,6 +159,25 @@
to be done several times and making changes may not work as
expected).
+ The following optional sign attributes can be specified before
+ "file=":
+ group={group} Place sign in sign group {group}
+ priority={prio} Assign priority {prio} to sign
+
+ By default, the sign is placed in the global sign group.
+
+ By default, the sign is assigned a default priority of 10. To
+ assign a different priority value, use "priority={prio}" to
+ specify a value. The priority is used to determine the
+ highlight group used when multiple signs are placed on the
+ same line.
+
+ Examples: >
+ :sign place 5 line=3 name=sign1 file=a.py
+ :sign place 6 group=g2 line=2 name=sign2 file=x.py
+ :sign place 9 group=g2 priority=50 line=5
+ \ name=sign1 file=a.py
+<
:sign place {id} line={lnum} name={name} buffer={nr}
Same, but use buffer {nr}.
@@ -146,31 +188,73 @@
This can be used to change the displayed sign without moving
it (e.g., when the debugger has stopped at a breakpoint).
+ The optional "group={group}" attribute can be used before
+ "file=" to select a sign in a particular group.
+
:sign place {id} name={name} buffer={nr}
Same, but use buffer {nr}.
REMOVING SIGNS *:sign-unplace* *E159*
+See |sign_unplace()| for the equivalent Vim script function.
+
:sign unplace {id} file={fname}
Remove the previously placed sign {id} from file {fname}.
See remark above about {fname} |:sign-fname|.
+:sign unplace {id} group={group} file={fname}
+ Same but remove the sign {id} in sign group {group}.
+
+:sign unplace {id} group=* file={fname}
+ Same but remove the sign {id} from all the sign groups.
+
:sign unplace * file={fname}
Remove all placed signs in file {fname}.
+:sign unplace * group={group} file={fname}
+ Remove all placed signs in group {group} from file {fname}.
+
+:sign unplace * group=* file={fname}
+ Remove all placed signs in all the groups from file {fname}.
+
:sign unplace {id} buffer={nr}
Remove the previously placed sign {id} from buffer {nr}.
+:sign unplace {id} group={group} buffer={nr}
+ Remove the previously placed sign {id} in group {group} from
+ buffer {nr}.
+
+:sign unplace {id} group=* buffer={nr}
+ Remove the previously placed sign {id} in all the groups from
+ buffer {nr}.
+
:sign unplace * buffer={nr}
Remove all placed signs in buffer {nr}.
+:sign unplace * group={group} buffer={nr}
+ Remove all placed signs in group {group} from buffer {nr}.
+
+:sign unplace * group=* buffer={nr}
+ Remove all placed signs in all the groups from buffer {nr}.
+
:sign unplace {id}
Remove the previously placed sign {id} from all files it
appears in.
+:sign unplace {id} group={group}
+ Remove the previously placed sign {id} in group {group} from
+ all files it appears in.
+
+:sign unplace {id} group=*
+ Remove the previously placed sign {id} in all the groups from
+ all the files it appears in.
+
:sign unplace *
- Remove all placed signs.
+ Remove all placed signs in the global group.
+
+:sign unplace * group=*
+ Remove all placed signs in all the groups.
:sign unplace
Remove the placed sign at the cursor position.
@@ -178,15 +262,26 @@
LISTING PLACED SIGNS *:sign-place-list*
+See |sign_getplaced()| for the equivalent Vim script function.
+
:sign place file={fname}
List signs placed in file {fname}.
See remark above about {fname} |:sign-fname|.
+:sign place group={group} file={fname}
+ List signs in group {group} placed in file {fname}.
+
:sign place buffer={nr}
List signs placed in buffer {nr}.
+:sign place group={group} buffer={nr}
+ List signs in group {group} placed in buffer {nr}.
+
:sign place List placed signs in all files.
+:sign place group={group}
+ List placed signs in all sign groups in all the files.
+
JUMPING TO A SIGN *:sign-jump* *E157*
diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt
index 1ad044b..343d476 100644
--- a/runtime/doc/usr_41.txt
+++ b/runtime/doc/usr_41.txt
@@ -983,6 +983,14 @@
job_info() get information about a job
job_setoptions() set options for a job
+Signs: *sign-functions*
+ sign_define() define or update a sign
+ sign_getdefined() get a list of defined signs
+ sign_getplaced() get a list of placed signs
+ sign_place() place a sign
+ sign_undefine() undefine a sign
+ sign_unplace() unplace a sign
+
Terminal window: *terminal-functions*
term_start() open a terminal window and run a job
term_list() get the list of terminal buffers