.zsh/zsh-syntax-highlighting/HACKING.md

   1 Hacking on zsh-syntax-highlighting itself
   2 =========================================
   3
   4 This document includes information for people working on z-sy-h itself: on the
   5 core driver (`zsh-syntax-highlighting.zsh`), on the highlighters in the
   6 distribution, and on the test suite.  It does not target third-party
   7 highlighter authors (although they may find it an interesting read).
   8
   9 The `main` highlighter
  10 ----------------------
  11
  12 The following function `pz` is useful when working on the `main` highlighting:
  13
  14     pq() {
  15       (( $#argv )) || return 0
  16       print -r -l -- ${(qqqq)argv}
  17     }
  18     pz() {
  19       local arg
  20       for arg; do
  21         pq ${(z)arg}
  22       done
  23     }
  24
  25 It prints, for each argument, its token breakdown, similar to how the main
  26 loop of the `main` highlighter sees it.
  27
  28 Testing the `brackets` highlighter
  29 ----------------------------------
  30
  31 Since the test harness empties `ZSH_HIGHLIGHT_STYLES` and the `brackets`
  32 highlighter interrogates `ZSH_HIGHLIGHT_STYLES` to determine how to highlight,
  33 tests must set the `bracket-level-#` keys themselves.  For example:
  34
  35     ZSH_HIGHLIGHT_STYLES[bracket-level-1]=
  36     ZSH_HIGHLIGHT_STYLES[bracket-level-2]=
  37
  38     BUFFER='echo ({x})'
  39
  40     expected_region_highlight=(
  41       "6  6  bracket-level-1" # (
  42       "7  7  bracket-level-2" # {
  43       "9  9  bracket-level-2" # }
  44       "10 10 bracket-level-1" # )
  45     )
  46
  47 Testing the `pattern` and `regexp` highlighters
  48 -----------------------------------------------
  49
  50 Because the `pattern` and `regexp` highlighters modifies `region_highlight`
  51 directly instead of using `_zsh_highlight_add_highlight`, the test harness
  52 cannot get the `ZSH_HIGHLIGHT_STYLES` keys.  Therefore, when writing tests, use
  53 the style itself as third word (cf. the
  54 [documentation for `expected_region_highlight`](docs/highlighters.md)).  For example:
  55
  56     ZSH_HIGHLIGHT_PATTERNS+=('rm -rf *' 'fg=white,bold,bg=red')
  57
  58     BUFFER='rm -rf /'
  59
  60     expected_region_highlight=(
  61       "1 8 fg=white,bold,bg=red" # rm -rf /
  62     )
  63
  64 Miscellany
  65 ----------
  66
  67 If you work on the driver (`zsh-syntax-highlighting.zsh`), you may find the following zstyle useful:
  68
  69     zstyle ':completion:*:*:*:*:globbed-files' ignored-patterns {'*/',}zsh-syntax-highlighting.plugin.zsh
  70
  71 IRC channel
  72 -----------
  73
  74 We're on #zsh-syntax-highlighting on freenode.
  75