sign.txt ForVim version 9.1. Last change: 2024 Jul 07VIM REFERENCE MANUAL by Gordon Prieur andBramMoolenaarSign Support Featuressign-support1. Introductionsign-intro2. Commandssign-commands3. Functionssign-functions-details{only available when compiled with the |+signs| feature}==============================================================================1. Introductionsign-introsignsWhena debugger or other IDE toolis driving an editorit needs to be ableto give specific highlights which quickly tell the user useful informationabout the file. One example of this would bea debugger which had an iconin the left-hand column denotinga breakpoint. Another example might be anarrow representing the Program Counter (PC). The sign features allow bothplacement ofa sign, or icon, in the left-hand side of thewindow anddefinition ofa highlight which will be applied to that line. Displaying thesignas an imageis most likely only feasible ingvim (although SunMicrosystem's dtterm does support this it's the onlyterminal emulatorI knowof which does).A text sign and the highlight should be feasible in any colorterminal emulator.Signs and highlights are not useful just for debuggers. Sun'sVisualWorkShop usessigns and highlights tomark builderrors and SourceBrowserhits. Additionally, the debugger supports 8 to 10 differentsigns andhighlight colors, seeNetBeans.There are two steps in using signs:1. Define the sign. Thisspecifies the image, text and highlighting. For example, you can definea "break" sign with an image ofa stop roadsign and text "!!".2. Place the sign. Thisspecifies the file and line number where the signis displayed.A defined sign can be placed several times in different lines and files.sign-columnWhensigns are defined fora file, Vim will automatically adda column of twocharacters to display them in. When the last signis unplaced the columndisappears again. This behavior can be changed with the'signcolumn' option.The color of the columnis set with the SignColumn highlight grouphl-SignColumn. Example to set the color::highlight SignColumn guibg=darkgreyIf'cursorline'is enabled, then the CursorLineSign highlight groupis usedhl-CursorLineSign.sign-identifierEach placed signis identified bya number called the sign identifier. Thisidentifieris used to jump to the sign or to remove the sign. The identifieris assigned when placing the sign using the:sign-place command or thesign_place() function. Each sign identifier should bea unique number. Ifmultiple placedsigns use the same identifier, then jumping to or removingasign becomes unpredictable. To avoid overlapping identifiers, sign groups canbe used. Thesign_place() function can be called witha zero sign identifierto allocate the next available identifier.sign-groupEach placed sign can be assigned to either the global group ora named group.When placinga sign, ifa group nameis not supplied, or an emptystringisused, then the signis placed in the global group. Otherwise the signisplaced in the named group. The sign identifieris unique withina group. Thesign group allows Vim plugins to use uniquesigns without interfering withother plugins using signs.To placea sign inapopupwindow the group namemust start with "PopUp".Othersigns will not show inapopup window. The group name "PopUpMenu"isused bypopupwindows where'cursorline'is set.sign-priorityEach placed signis assigneda priority value. When multiplesigns are placedon the same line, the attributes of the sign with the highest priorityis usedindependently of the sign group. The default priority fora signis 10, thisvalue can be changed for differentsigns by specifyinga different valueatdefinition time. The priorityis assignedat the time of placinga sign.When twosigns with the same priority are present, and one has an icon or textin the signcolumn while the other has line highlighting, then both aredisplayed.When the line on which the signis placedis deleted, the signis moved to thenext line (or the last line of the buffer, if thereis no next line). Whenthe deleteis undone the sign does not move back.Whena sign with line highlighting and'cursorline' highlighting are bothpresent, if the priorityis 100 or more then the sign highlighting takesprecedence, otherwise the'cursorline' highlighting.==============================================================================2. Commandssign-commands:sig:signHereis an example that placesa sign "piet", displayed with the text ">>", inline 23 of the current file::sign define piet text=>> texthl=Search:exe ":sign place 2 line=23 name=piet file=" .. expand("%:p")And hereis the command to deleteit again::sign unplace 2Note that the ":sign" command cannot be followed by another command oracomment. If youdo need that, use the:execute command.DEFINING A SIGN.:sign-defineE255E160E612Seesign_define() for the equivalent Vimscript function.:sign define{name}{argument}...Definea new sign or set attributes for an existing sign.The{name} can either bea number (all digits) ora namestarting witha non-digit. Leading zeros are ignored, thus"0012", "012" and "12" are considered the same name.About 120 differentsigns can be defined.Accepted arguments:icon={bitmap}Define the file name where the bitmap can be found. Should bea full path. The bitmap should fit in the place of twocharacters. Thisis not checked. If the bitmapis too bigitwill cause redraw problems. OnlyGTK 2 can scale the bitmapto fit thespace available.toolkitsupportsGTK 1pixmap (.xpm)GTK 2manyMotifpixmap (.xpm)Win32.bmp, .ico, .curpixmap (.xpm)+xpm_w32priority={prio}Default priority for the sign, seesign-priority.linehl={group}Highlighting group used for the whole line the signis placedin. Most usefulis defininga background color.numhl={group}Highlighting group used for the line number on the line wherethe signis placed. Overrideshl-LineNr,hl-LineNrAbove,hl-LineNrBelow, andhl-CursorLineNr.text={text}E239Define the text thatis displayed when thereis no icon or theGUIis not being used. Only printable characters are allowedand theymust occupy one or two display cells.texthl={group}Highlighting group used for the text item.culhl={group}Highlighting group used for the text item when the cursorison the same lineas the sign and'cursorline'is enabled.Example::sign define MySign text=>> texthl=Search linehl=DiffTextDELETING A SIGN:sign-undefineE155Seesign_undefine() for the equivalent Vimscript function.:sign undefine{name}Deletesa previously defined sign. Ifsigns with this{name}are still placed this will cause trouble.Example::sign undefine MySignLISTING SIGNS:sign-listE156Seesign_getdefined() for the equivalent Vimscript function.:signlistLists all definedsigns and their attributes.:signlist{name}Lists one defined sign and its attributes.PLACING SIGNS:sign-placeE158Seesign_place() for the equivalent Vimscript function.:sign place{id} line={lnum} name={name} file={fname}Place sign definedas{name}at line{lnum} in file{fname}.:sign-fnameThe file{fname}must already be loaded ina buffer. Theexact file namemust be used, wildcards, $ENV and~ are notexpanded, whitespacemust not be escaped. Trailing whitespaceis ignored.The signis remembered under{id}, this can be used forfurther manipulation.{id}must bea number.It's up to the user to make sure the{id}is used only once ineach file (if it's used several times unplacing will also haveto be done several times and making changes may not workasexpected).The following optional sign attributes can be specified before"file=":group={group}Place sign in sign group{group}priority={prio}Assign priority{prio} to signBy default, the signis placed in the global sign group.By default, the signis assigneda default priority of 10,unless specified otherwise by the sign definition. To assignadifferent priority value, use "priority={prio}" to specifyavalue. The priorityis used to determine the sign thatisdisplayed when multiplesigns 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}. If the buffer argumentis notgiven, place the sign in the current buffer.Example::sign place 10 line=99 name=sign3:sign place 10 line=99 name=sign3 buffer=3E885:sign place{id} name={name} file={fname}Change the placed sign{id} in file{fname} to use the definedsign{name}. See remark above about{fname}:sign-fname.This can be used to change the displayed sign without movingit (e.g., when the debugger has stoppedata breakpoint).The optional "group={group}" attribute can be used before"file=" to selecta sign ina particular group. The optional"priority={prio}" attribute can be used to change the priorityof an existing sign.Example::sign place 23 name=sign1 file=/path/to/edit.py:sign place{id} name={name} [buffer={nr}]Same, but use buffer{nr}. If the buffer argumentis notgiven, use the current buffer.Example::sign place 23 name=sign1:sign place 23 name=sign1 buffer=7REMOVING SIGNS:sign-unplaceE159Seesign_unplace() for the equivalent Vimscript 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 placedsigns in file{fname}.:sign unplace * group={group} file={fname}Remove all placedsigns in group{group} from file{fname}.:sign unplace * group=* file={fname}Remove all placedsigns 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} frombuffer{nr}.:sign unplace{id} group=* buffer={nr}Remove the previously placed sign{id} in all the groups frombuffer{nr}.:sign unplace * buffer={nr}Remove all placedsigns in buffer{nr}.:sign unplace * group={group} buffer={nr}Remove all placedsigns in group{group} from buffer{nr}.:sign unplace * group=* buffer={nr}Remove all placedsigns in all the groups from buffer{nr}.:sign unplace{id}Remove the previously placed sign{id} from all filesitappears in.:sign unplace{id} group={group}Remove the previously placed sign{id} in group{group} fromall filesit appears in.:sign unplace{id} group=*Remove the previously placed sign{id} in all the groups fromall the filesit appears in.:sign unplace *Remove all placedsigns in the global group from all the files.:sign unplace * group={group}Remove all placedsigns in group{group} from all the files.:sign unplace * group=*Remove all placedsigns in all the groups from all the files.:sign unplaceRemovea placed signat the cursor position. If multiplesignsare placed in the line, then only oneis removed.:sign unplace group={group}Removea placed sign in group{group}at the cursorposition.:sign unplace group=*Removea placed sign in any groupat the cursor position.LISTING PLACED SIGNS:sign-place-listSeesign_getplaced() for the equivalent Vimscript function.:sign place file={fname}Listsigns placed in file{fname}.See remark above about{fname}:sign-fname.:sign place group={group} file={fname}Listsigns in group{group} placed in file{fname}.:sign place group=* file={fname}Listsigns in all the groups placed in file{fname}.:sign place buffer={nr}Listsigns placed in buffer{nr}.:sign place group={group} buffer={nr}Listsigns in group{group} placed in buffer{nr}.:sign place group=* buffer={nr}Listsigns in all the groups placed in buffer{nr}.:sign placeList placedsigns in the global group in all files.:sign place group={group}List placedsigns with sign group{group} in all files.:sign place group=*List placedsigns in all sign groups in all files.JUMPING TO A SIGN:sign-jumpE157Seesign_jump() for the equivalent Vimscript function.:sign jump{id} file={fname}Open the file{fname} or jump to thewindow that contains{fname} and position the cursorat sign{id}.See remark above about{fname}:sign-fname.If the file isn't displayed inwindow and the current file cannot beabandoned this fails.:sign jump{id} group={group} file={fname}Same but jump to the sign in group{group}:sign jump{id} [buffer={nr}]E934Same, but use buffer{nr}. This fails if buffer{nr} does nothavea name. If the buffer argumentis not given, use thecurrent buffer.:sign jump{id} group={group} [buffer={nr}]Same but jump to the sign in group{group}==============================================================================3. Functionssign-functions-detailssign_define({name} [,{dict}])sign_define()sign_define({list})Definea new sign named{name} or modify the attributes of anexisting sign. Thisis similar to the:sign-define command.Prefix{name} witha unique text to avoid name collisions.Thereis no{group} like with placing signs.The{name} can beaString ora Number. The optional{dict}argumentspecifies the sign attributes. The following valuesare supported: iconfull path to the bitmap file for the sign. linehlhighlight group used for the whole line thesignis placed in. prioritydefault priority value of the sign numhlhighlight group used for the line number wherethe signis placed. texttext thatis displayed when thereis no iconor theGUIis not being used. texthlhighlight group used for the text item culhlhighlight group used for the text item whenthe cursoris on the same lineas the sign and'cursorline'is enabled.If the sign named{name} already exists, then the attributesof the sign are updated.The one argument{list} can be used to definealist of signs.Eachlist itemisa dictionary with the above items in{dict}anda "name" item for the sign name.Returns0 on success and -1 on failure. When the one argument{list}is used, then returnsaList of values one for eachdefined sign.Examples:call sign_define("mySign", {\ "text" : "=>",\ "texthl" : "Error",\ "linehl" : "Search"})call sign_define([\ {'name' : 'sign1',\ 'text' : '=>'},\ {'name' : 'sign2',\ 'text' : '!!'}\ ])Can also be usedasamethod:GetSignList()->sign_define()Return type:Numbersign_getdefined([{name}])sign_getdefined()Getalist of definedsigns and their attributes.Thisis similar to the:sign-list command.If the{name}is not supplied, thenalist of all the definedsignsis returned. Otherwise the attribute of the specifiedsignis returned.Eachlist item in the returned valueisa dictionary with thefollowing entries: iconfull path to the bitmap file of the sign linehlhighlight group used for the whole line thesignis placed in; not present if not set namename of the sign prioritydefault priority value of the sign numhlhighlight group used for the line number wherethe signis placed; not present if not set texttext thatis displayed when thereis no iconor theGUIis not being used. texthlhighlight group used for the text item; notpresent if not set culhlhighlight group used for the text item whenthe cursoris on the same lineas the sign and'cursorline'is enabled; not present if notsetReturns an emptyList if there are nosigns and when{name}isnot found.Examples:" Get a list of all the defined signsecho sign_getdefined()" Get the attribute of the sign named mySignecho sign_getdefined("mySign")Can also be usedasamethod:GetSignList()->sign_getdefined()Return type: list<dict<string>> or list<any>sign_getplaced([{buf} [,{dict}]])sign_getplaced()Returnalist ofsigns placed ina buffer or all the buffers.Thisis similar to the:sign-place-list command.If the optional buffer name{buf}is specified, then only thelist ofsigns placed in that bufferis returned. For the useof{buf}, seebufname(). The optional{dict} can containthe following entries: groupselect onlysigns in this group idselect sign with this identifier lnumselectsigns placed in this line. For the useof{lnum}, seeline().If{group}is'*', thensigns in all the groups including theglobal group are returned. If{group}is not supplied oris anempty string, then onlysigns in the global group arereturned. If no arguments are supplied, thensigns in theglobal group placed in all thebuffers are returned.Seesign-group.Eachlist item in the returned valueisa dictionary with thefollowing entries:bufnrnumber of the buffer with the signsignslist ofsigns placed in{bufnr}. Eachlistitemisa dictionary with the below listedentriesThe dictionary for each sign contains the following entries:group sign group. Set to'' for the global group.id identifier of the signlnum line number where the signis placedname name of the defined signpriority sign priorityThe returnedsigns ina buffer are ordered by their linenumber and priority.Returns an emptylist on failure or if there are no placedsigns.Examples:" Get a List of signs placed in eval.c in the" global groupecho sign_getplaced("eval.c")" Get a List of signs in group 'g1' placed in eval.cecho sign_getplaced("eval.c", {'group' : 'g1'})" Get a List of signs placed at line 10 in eval.cecho sign_getplaced("eval.c", {'lnum' : 10})" Get sign with identifier 10 placed in a.pyecho sign_getplaced("a.py", {'id' : 10})" Get sign with id 20 in group 'g1' placed in a.pyecho sign_getplaced("a.py", {'group' : 'g1',\ 'id' : 20})" Get a List of all the placed signsecho sign_getplaced()Can also be usedasamethod:GetBufname()->sign_getplaced()Return type: list<dict<any>>sign_jump({id},{group},{buf})sign_jump()Open the buffer{buf} or jump to thewindow that contains{buf} and position the cursorat sign{id} in group{group}.Thisis similar to the:sign-jump command.If{group}is an empty string, then the global groupis used.For the use of{buf}, seebufname().Returns the line number of the sign. Returns -1 if thearguments are invalid.Example:" Jump to sign 10 in the current buffercall sign_jump(10, '', '')Can also be usedasamethod:GetSignid()->sign_jump()Return type:Numbersign_place()sign_place({id},{group},{name},{buf} [,{dict}])Place the sign definedas{name}at line{lnum} in file orbuffer{buf} and assign{id} and{group} to sign. Thisissimilar to the:sign-place command.If the sign identifier{id}is zero, thena new identifierisallocated. Otherwise the specified numberis used.{group}isthe sign group name. To use the global sign group, use anempty string.{group}functionsasa namespace for{id}, thustwo groups can use the same IDs. Refer tosign-identifierandsign-group for more information.{name} refers toa defined sign.{buf} refers toa buffer name or number. For the acceptedvalues, seebufname().The optional{dict} argument supports the following entries:lnumline number in the file or buffer{buf} where the signis to be placed.For the accepted values, seeline().prioritypriority of the sign. Seesign-priority for more information.If the optional{dict}is not specified, thenit modifies theplaced 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.ccall sign_place(5, '', 'sign1', 'json.c',\ {'lnum' : 20})" Updates sign 5 in buffer json.c to use sign2call sign_place(5, '', 'sign2', 'json.c')" Place a sign named sign3 at line 30 in" buffer json.c with a new identifierlet 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 90call sign_place(10, 'g3', 'sign4', 'json.c',\ {'lnum' : 40, 'priority' : 90})Can also be usedasamethod:GetSignid()->sign_place(group, name, expr)Return type:Numbersign_placelist({list})sign_placelist()Place one or more signs. Thisis similar to thesign_place() function. The{list} argumentspecifies theList ofsigns to place. Eachlist itemisadict with thefollowing sign attributes: bufferBuffer name or number. For the acceptedvalues, seebufname(). groupSign group.{group}functionsasa namespacefor{id}, thus two groups can use the sameIDs. If not specified or set to an emptystring, then the global groupis used. Seesign-group for more information. idSign identifier. If not specified or zero,thena new unique identifieris allocated.Otherwise the specified numberis used. Seesign-identifier for more information. lnumLine number in the buffer where the signis tobe placed. For the accepted values, seeline(). nameName of the sign to place. Seesign_define()for more information. priorityPriority of the sign. When multiplesigns areplaced ona line, the sign with the highestpriorityis used. If not specified, thedefault value of 10is used, unless specifiedotherwise by the sign definition. Seesign-priority for more information.If{id} refers to an existing sign, then the existing signismodified to use the specified{name} and/or{priority}.ReturnsaList of sign identifiers. If failed to placeasign, the correspondinglist itemis set to -1.Examples:" Place sign s1 with id 5 at line 20 and id 10 at line" 30 in buffer a.clet [n1, n2] = sign_placelist([\ {'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 identifierslet [n1, n2] = sign_placelist([\ {'name' : 's1',\ 'buffer' : 'a.c',\ 'lnum' : 40},\ {'name' : 's1',\ 'buffer' : 'a.c',\ 'lnum' : 50}\ ])Can also be usedasamethod:GetSignlist()->sign_placelist()Return type:Numbersign_undefine([{name}])sign_undefine()sign_undefine({list})Deletesa previously defined sign{name}. Thisis similar tothe:sign-undefine command. If{name}is not supplied, thendeletes all the defined signs.The one argument{list} can be used to undefinealist ofsigns. Eachlist itemis the name ofa sign.Returns0 on success and -1 on failure. For the one argument{list} call, returnsalist of values one for each undefinedsign.Examples:" Delete a sign named mySigncall sign_undefine("mySign")" Delete signs 'sign1' and 'sign2'call sign_undefine(["sign1", "sign2"])" Delete all the signscall sign_undefine()Can also be usedasamethod:GetSignlist()->sign_undefine()Return type:Numbersign_unplace({group} [,{dict}])sign_unplace()Removea previously placed sign in one or more buffers. Thisis 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 thegroups including the global group are used.Thesigns in{group} are selected based on the entries in{dict}. The following optional entries in{dict} aresupported:bufferbuffer name or number. Seebufname().idsign identifierIf{dict}is not supplied, then all thesigns in{group} areremoved.Returns0 on success and -1 on failure.Examples:" Remove sign 10 from buffer a.vimcall sign_unplace('', {'buffer' : "a.vim", 'id' : 10})" Remove sign 20 in group 'g1' from buffer 3call sign_unplace('g1', {'buffer' : 3, 'id' : 20})" Remove all the signs in group 'g2' from buffer 10call sign_unplace('g2', {'buffer' : 10})" Remove sign 30 in group 'g3' from all the bufferscall sign_unplace('g3', {'id' : 30})" Remove all the signs placed in buffer 5call sign_unplace('*', {'buffer' : 5})" Remove the signs in group 'g4' from all the bufferscall sign_unplace('g4')" Remove sign 40 from all the bufferscall sign_unplace('*', {'id' : 40})" Remove all the placed signs from all the bufferscall sign_unplace('*')Can also be usedasamethod:GetSigngroup()->sign_unplace()Return type:Numbersign_unplacelist({list})sign_unplacelist()Remove previously placedsigns from one or more buffers. Thisis similar to thesign_unplace() function.The{list} argumentspecifies theList ofsigns to remove.Eachlist itemisadict with the following sign attributes: bufferbuffer name or number. For the acceptedvalues, seebufname(). If not specified,then the specified signis removed from allthe buffers. groupsign group name. If not specified or set to anempty string, then the global sign groupisused. If set to'*', then all the groupsincluding the global group are used. idsign identifier. If not specified, then allthesigns in the specified group are removed.ReturnsaList where an entryis set to0 if the correspondingsign 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.vimcall sign_unplacelist([\ {'id' : 10, 'buffer' : "a.vim"},\ {'id' : 20, 'buffer' : 'b.vim'},\ ])Can also be usedasamethod:GetSignlist()->sign_unplacelist()Return type: list<number> or list<any> vim:tw=78:ts=8:noet:ft=help:norl: