Re: PATCH: alternate views on .zle.hlgroups

[Oliver Kiddle <opk@zsh.org>]

Bart Schaefer wrote:
> I don't do much with zle_highlight so I have only general comments ...

Thanks. That gave me a few more ideas of things to test, none of which
triggered outcomes that appeared iffy.

I've attached a doc patch though some things remain that may need
addressing in the code. In particular resetting attributes after %H
in a prompt and whether the layers and rules for merging attributes
are sufficient for the needs of plugins like zsh-syntax-highlighting.
Probing the tty for background colour is something that'll probably need
testing privately for a while first.

Oliver

diff --git a/Doc/Makefile.in b/Doc/Makefile.in
index dabe11fe3..d9be182e9 100644
--- a/Doc/Makefile.in
+++ b/Doc/Makefile.in
@@ -63,7 +63,8 @@ Zsh/mod_attr.yo Zsh/mod_cap.yo Zsh/mod_clone.yo \
 Zsh/mod_compctl.yo Zsh/mod_complete.yo Zsh/mod_complist.yo \
 Zsh/mod_computil.yo Zsh/mod_curses.yo \
 Zsh/mod_datetime.yo Zsh/mod_db_gdbm.yo Zsh/mod_deltochar.yo \
-Zsh/mod_example.yo Zsh/mod_files.yo Zsh/mod_langinfo.yo \
+Zsh/mod_example.yo Zsh/mod_files.yo \
+Zsh/mod_hlgroup.yo Zsh/mod_langinfo.yo \
 Zsh/mod_ksh93.yo Zsh/mod_mapfile.yo Zsh/mod_mathfunc.yo \
 Zsh/mod_nearcolor.yo Zsh/mod_newuser.yo \
 Zsh/mod_parameter.yo Zsh/mod_pcre.yo Zsh/mod_private.yo \
diff --git a/Doc/Zsh/mod_hlgroup.yo b/Doc/Zsh/mod_hlgroup.yo
new file mode 100644
index 000000000..efe8934a1
--- /dev/null
+++ b/Doc/Zsh/mod_hlgroup.yo
@@ -0,0 +1,25 @@
+COMMENT(!MOD!zsh/hlgroup
+Alternative views of highlighting groups
+!MOD!)
+The tt(zsh/hlgroup) module defines special parameters that represent
+highlighting groups in different forms to ease the use of the groups when
+configuring other tools.
+
+In each case, these are readonly associative arrays where accessing elements
+uses values from the underlying tt(.zle.hlgroups) variable.
+
+startitem()
+vindex(.zle.esc)
+item(tt(.zle.esc))(
+This associative array contains the literal escape sequences used to apply the
+highlighting for each group. An example use would be when setting the
+tt(LESS_TERMCAP_xx) environment variables for the tt(less) pager.
+)
+vindex(.zle.sgr)
+item(tt(.zle.sgr))(
+Where highlighting makes use of CSI escape sequences, this parameter contains
+the "Select Graphic Rendition" number sequence. This is useful with, for
+example the tt(GREP_COLORS) and tt(LSCOLORS) environment variables and the
+tt(list-colors) style.
+)
+enditem()
diff --git a/Doc/Zsh/prompt.yo b/Doc/Zsh/prompt.yo
index 909012c8e..de988ab7c 100644
--- a/Doc/Zsh/prompt.yo
+++ b/Doc/Zsh/prompt.yo
@@ -246,6 +246,14 @@ item(tt(%K) LPAR()tt(%k)RPAR())(
 Start (stop) using a different bacKground colour.  The syntax is
 identical to that for tt(%F) and tt(%f).
 )
+item(tt(%H))(
+Change all character visual attributes using a highlighting specification from
+the tt(.zle.hlgroups) associative array. The key is specified in following
+braces so, for example tt(%H{error}) will use the highlighting specification
+for the `error' group.  If the key is not found in the associative array then
+it has no effect.  Highlighting specifications are in the same format as for
+the tt(zle_highlight) parameter.
+)
 item(tt(%{)...tt(%}))(
 Include a string as a literal escape sequence.
 The string within the braces should not change the cursor
diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo
index 495bd86a8..31eb3f3ba 100644
--- a/Doc/Zsh/zle.yo
+++ b/Doc/Zsh/zle.yo
@@ -2807,6 +2807,17 @@ item(tt(italic))(
 The characters in the given context are shown in a italic font.
 Not all terminals support italic fonts.
 )
+item(tt(hl=)var(group))(
+Use the specified highlighting group.  The var(group) is used as a key into
+the associative array tt(.zle.hlgroups) to determine the actual highlighting.
+)
+item(tt(layer=)var(layer))(
+The layer is used to determine precedence when multiple highlighting regions
+overlap. The var(layer) is a decimal integer, with higher numbers taking
+precedence over lower numbers. The default layer is 10 with 30 used as the
+default for tt(special), 20 for tt(region) and tt(isearch) and 15 for
+tt(paste).
+)
 enditem()
 
 The characters described above as `special' are as follows.  The
diff --git a/NEWS b/NEWS
index 4d4699f7e..d0a8584e2 100644
--- a/NEWS
+++ b/NEWS
@@ -10,6 +10,12 @@ Changes since 5.9
 In region_highlight and zle_highlight, italic and faint can be
 specified as font attributes for terminals that support them.
 
+Highlighting groups can be referenced in region_highlight and
+zle_highlight for common attribute combinations and a layer can be
+specified to indicate precedence where highlighted regions overlap.
+Highlighting groups are also supported in the prompt via a new %H
+prompt escape.
+
 Ellipsis markers shown by the line editor to indicate where the line
 doesn't fit in the terminal can be highlighted.