thac0/vim
1
0
Fork 0
forked from aniani/vim
Code Activity

patch 8.1.0614: placing signs can be complicated

Browse Source 
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)
This commit is contained in:
Bram Moolenaar
2018-12-21 15:17:36 +01:00
parent 48f377a476
commit 162b71479b
19 changed files with 2082 additions and 296 deletions
Download Patch File Download Diff File Expand all files Collapse all files

219
runtime/doc/eval.txt
View File

@@ -2408,6 +2408,15 @@ shellescape({string} [, {special}])
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 @@ shiftwidth([{col}]) *shiftwidth()*
'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

99
runtime/doc/sign.txt
View File

@@ -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 @@ The color of the column is set with the SignColumn group |hl-SignColumn|.
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 @@ comment. If you do need that, use the |:execute| command.
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 @@ DEFINING A SIGN. *:sign-define* *E255* *E160* *E612*
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 @@ LISTING SIGNS *:sign-list* *E156*
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 @@ PLACING SIGNS *:sign-place* *E158*
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 @@ PLACING SIGNS *:sign-place* *E158*
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 @@ REMOVING SIGNS *:sign-unplace* *E159*
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*

8
runtime/doc/usr_41.txt
View File

@@ -983,6 +983,14 @@ Jobs: *job-functions*
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