File: HACKING.md

package info (click to toggle)
zsh-syntax-highlighting 0.6.0-3
  • links: PTS, VCS
  • area: main
  • in suites: buster, sid
  • size: 904 kB
  • sloc: sh: 498; makefile: 79; perl: 8
file content (75 lines) | stat: -rw-r--r-- 2,254 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
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 /
    )

Miscellany
----------

If you work on the driver (`zsh-syntax-highlighting.zsh`), you may find the following zstyle useful:

    zstyle ':completion:*:*:*:*:globbed-files' ignored-patterns {'*/',}zsh-syntax-highlighting.plugin.zsh

IRC channel
-----------

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