patch 8.2.3578: manipulating highlighting is complicatedv8.2.3578

Problem:    Manipulating highlighting is complicated.
Solution:   Add the hlget() and hlset() functions. (Yegappan Lakshmanan,
            closes #9039)

4 files changed, 93 insertions, 0 deletions

diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 418aee9ceb..2bd953a430 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -2718,6 +2718,8 @@ histget({history} [, {index}])	String	get the item {index} from a history
 histnr({history})		Number	highest index of a history
 hlID({name})			Number	syntax ID of highlight group {name}
 hlexists({name})		Number	|TRUE| if highlight group {name} exists
+hlget([{name} [, {resolve}]])	List	get highlight group attributes
+hlset({list})			Number	set highlight group attributes
 hostname()			String	name of the machine Vim is running on
 iconv({expr}, {from}, {to})	String	convert encoding of {expr}
 indent({lnum})			Number	indent of line {lnum}
@@ -6717,6 +6719,93 @@ hlexists({name})					*hlexists()*
 		Can also be used as a |method|: >
 			GetName()->hlexists()
 <
+hlget([{name} [, {resolve}]])				*hlget()*
+		Returns a List of all the highlight group attributes.  If the
+		optional {name} is specified, then returns a List with only
+		the attributes of the specified highlight group.  Returns an
+		empty List if the highlight group {name} is not present.
+
+		If the optional {resolve} argument is set to v:true and the
+		highlight group {name} is linked to another group, then the
+		link is resolved recursively and the attributes of the
+		resolved highlight group are returned.
+
+		Each entry in the returned List is a Dictionary with the
+		following items:
+			cleared	Boolean flag, set to v:true if the highlight
+				group attributes are cleared or not yet
+				specified.  See |highlight-clear|.
+			cterm	cterm attributes. See |highlight-cterm|.
+			ctermbg	cterm background color.
+				See |highlight-ctermbg|.
+			ctermfg	cterm foreground color.
+				See |highlight-ctermfg|.
+			ctermul	cterm underline color.  See |highlight-ctermul|.
+			font	highlight group font.  See |highlight-font|.
+			gui	gui attributes. See |highlight-gui|.
+			guibg	gui background color.  See |highlight-guibg|.
+			guifg	gui foreground color.  See |highlight-guifg|.
+			guisp	gui special color.  See |highlight-guisp|.
+			id	highlight group ID.
+			linksto	linked highlight group name.
+				See |:highlight-link|.
+			name	highlight group name. See |group-name|.
+			start	start terminal keycode.  See |highlight-start|.
+			stop	stop terminal keycode.  See |highlight-stop|.
+			term	term attributes.  See |highlight-term|.
+
+		The 'term', 'cterm' and 'gui' items in the above Dictionary
+		have a dictionary value with the following optional boolean
+		items: 'bold', 'standout', 'underline', 'undercurl', 'italic',
+		'reverse', 'inverse' and 'strikethrough'.
+
+		Example(s): >
+			:echo hlget()
+			:echo hlget('ModeMsg')
+			:echo hlget('Number', v:true)
+<
+		Can also be used as a |method|: >
+			GetName()->hlget()
+<
+hlset({list})						*hlset()*
+		Creates or modifies the attributes of a List of highlight
+		groups.  Each item in {list} is a dictionary containing the
+		attributes of a highlight group. See |hlget()| for the list of
+		supported items in this dictionary.
+
+		The highlight group is identified using the 'name' item and
+		the 'id' item (if supplied) is ignored.  If a highlight group
+		with a specified name doesn't exist, then it is created.
+		Otherwise the attributes of an existing highlight group are
+		modified.
+
+		If an empty dictionary value is used for the 'term' or 'cterm'
+		or 'gui' entries, then the corresponding attributes are
+		cleared.  If the 'cleared' item is set to v:true, then all the
+		attributes of the highlight group are cleared.
+
+		The 'linksto' item can be used to link a highlight group to
+		another highlight group.  See |:highlight-link|.
+
+		Returns zero for success, -1 for failure.
+
+		Example(s): >
+			" add bold attribute to the Visual highlight group
+			:call hlset([#{name: 'Visual',
+					\ term: #{reverse: 1 , bold: 1}}])
+			:call hlset([#{name: 'Type', guifg: 'DarkGreen'}])
+			:let l = hlget()
+			:call hlset(l)
+			" clear the Search highlight group
+			:call hlset([#{name: 'Search', cleared: v:true}])
+			" clear the 'term' attributes for a highlight group
+			:call hlset([#{name: 'Title', term: {}}])
+			" create the MyHlg group linking it to DiffAdd
+			:call hlset([#{name: 'MyHlg', linksto: 'DiffAdd'}])
+<
+		Can also be used as a |method|: >
+			GetAttrList()->hlset()
+<
 							*hlID()*
 hlID({name})	The result is a Number, which is the ID of the highlight group
 		with name {name}.  When the highlight group doesn't exist,
diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt
index 1c20659acf..9d4ea39ec7 100644
--- a/runtime/doc/syntax.txt
+++ b/runtime/doc/syntax.txt
@@ -4849,6 +4849,7 @@ in their own color.
 :hi[ghlight] {group-name}
 			List one highlight group.
 
+						*highlight-clear*
 :hi[ghlight] clear	Reset all highlighting to the defaults.  Removes all
 			highlighting for groups added by the user!
 			Uses the current value of 'background' to decide which
diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt
index 4ea51f986c..89bd542825 100644
--- a/runtime/doc/usr_41.txt
+++ b/runtime/doc/usr_41.txt
@@ -925,6 +925,8 @@ Syntax and highlighting:	  *syntax-functions* *highlighting-functions*
 	getmatches()		get all matches defined by |matchadd()| and
 				the |:match| commands
 	hlexists()		check if a highlight group exists
+	hlget()			get highlight group attributes
+	hlset()			set highlight group attributes
 	hlID()			get ID of a highlight group
 	synID()			get syntax ID at a specific position
 	synIDattr()		get a specific attribute of a syntax ID
diff --git a/runtime/doc/windows.txt b/runtime/doc/windows.txt
index cd39dac975..c288377caa 100644
--- a/runtime/doc/windows.txt
+++ b/runtime/doc/windows.txt
@@ -1358,6 +1358,7 @@ directory	Displays directory contents.  Can be used by a file explorer
 <		The buffer name is the name of the directory and is adjusted
 		when using the |:cd| command.
 
+						*scratch-buffer*
 scratch		Contains text that can be discarded at any time.  It is kept
 		when closing the window, it must be deleted explicitly.
 		Settings: >