vim-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 vim/vim#3652)
https://github.com/vim/vim/commit/162b71479bd4dcdb3a2ef9198a1444f6f99e6843

3 files changed, 329 insertions, 1 deletions

diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index dfffe33b1f..21846d4cbb 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -2289,6 +2289,15 @@ shellescape({string} [, {special}])
 				String	escape {string} for use as shell
 					command argument
 shiftwidth()			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}
@@ -7349,7 +7358,222 @@ shiftwidth()						*shiftwidth()*
 			endif
 <		And then use s:sw() instead of &sw.
 
+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
+		    numhl	highlight group used for 'number' column at the
+				associated line. Overrides |hl-LineNr|,
+				|hl-CursorLineNr|.
+
+		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
+			numhl	highlight group used for 'number' column at the
+				associated line. Overrides |hl-LineNr|,
+				|hl-CursorLineNr|.
+
+		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 273d2b984c..39c1c61da2 100644
--- a/runtime/doc/sign.txt
+++ b/runtime/doc/sign.txt
@@ -45,6 +45,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*
@@ -63,6 +77,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
@@ -99,13 +115,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}
@@ -114,6 +135,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*
@@ -129,6 +152,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}.
 
@@ -139,31 +181,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.
@@ -171,15 +255,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*
 
diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt
index 234aba1932..cfda4fdb31 100644
--- a/runtime/doc/usr_41.txt
+++ b/runtime/doc/usr_41.txt
@@ -916,6 +916,15 @@ Mappings:				    *mapping-functions*
 	maparg()		get rhs of a mapping
 	wildmenumode()		check if the wildmode is active
 
+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
+
+
 Testing:				    *test-functions*
 	assert_equal()		assert that two expressions values are equal
 	assert_notequal()	assert that two expressions values are not equal