zsh-syntax-highlighting/HACKING.md

Hacking on zsh-syntax-highlighting itself

This document includes information for people working on z-sy-h itself: on the
core driver (zsh-syntax-highlighting.zsh), on the highlighters in the
distribution, and on the test suite. It does not target third-party
highlighter authors (although they may find it an interesting read).

The main highlighter

The following function pz is useful when working on the main highlighting:

pq() {
  (( $#argv )) || return 0
  print -r -l -- ${(qqqq)argv}
}
pz() {
  local arg
  for arg; do
    pq ${(z)arg}
  done
}

It prints, for each argument, its token breakdown, similar to how the main
loop of the main highlighter sees it.

Testing the brackets highlighter

Since the test harness empties ZSH_HIGHLIGHT_STYLES and the brackets
highlighter interrogates ZSH_HIGHLIGHT_STYLES to determine how to highlight,
tests must set the bracket-level-# keys themselves. For example:

ZSH_HIGHLIGHT_STYLES[bracket-level-1]=
ZSH_HIGHLIGHT_STYLES[bracket-level-2]=

BUFFER='echo ({x})'

expected_region_highlight=(
  "6  6  bracket-level-1" # (
  "7  7  bracket-level-2" # {
  "9  9  bracket-level-2" # }
  "10 10 bracket-level-1" # )
)

Testing the pattern highlighter

Because the pattern highlighter modifies region_highlight directly instead
of using _zsh_highlight_add_highlight, the test harness cannot get the
ZSH_HIGHLIGHT_STYLES keys. Therefore, when writing tests, use the style
itself as third word (cf. the [documentation for expected_region_highlight]
(docs/highlighters.md)). For example:

ZSH_HIGHLIGHT_PATTERNS+=('rm -rf *' 'fg=white,bold,bg=red')

BUFFER='rm -rf /'

expected_region_highlight=(
  "1 8 fg=white,bold,bg=red" # rm -rf /
)

IRC channel

We're on #zsh-syntax-highlighting on freenode.