Update zsh-syntax-highlighting plugin
[zsh.git] / .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