patch 8.2.3578: manipulating highlighting is complicated
Problem: Manipulating highlighting is complicated.
Solution: Add the hlget() and hlset() functions. (Yegappan Lakshmanan,
closes #9039)
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 418aee9..2bd953a 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -2718,6 +2718,8 @@
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 @@
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 1c20659..9d4ea39 100644
--- a/runtime/doc/syntax.txt
+++ b/runtime/doc/syntax.txt
@@ -4849,6 +4849,7 @@
: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 4ea51f9..89bd542 100644
--- a/runtime/doc/usr_41.txt
+++ b/runtime/doc/usr_41.txt
@@ -925,6 +925,8 @@
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 cd39dac..c288377 100644
--- a/runtime/doc/windows.txt
+++ b/runtime/doc/windows.txt
@@ -1358,6 +1358,7 @@
< 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: >