conf2/zsh/.oh-my-zsh/custom/plugins/zsh-syntax-highlighting/HACKING.md

84 lines
2.2 KiB
Markdown
Raw Normal View History

2019-01-12 16:16:44 +00:00
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:
2019-10-24 19:09:05 +00:00
```zsh
pq() {
(( $#argv )) || return 0
print -r -l -- ${(qqqq)argv}
}
pz() {
local arg
for arg; do
pq ${(z)arg}
done
}
```
2019-01-12 16:16:44 +00:00
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:
2019-10-24 19:09:05 +00:00
```zsh
ZSH_HIGHLIGHT_STYLES[bracket-level-1]=
ZSH_HIGHLIGHT_STYLES[bracket-level-2]=
2019-01-12 16:16:44 +00:00
2019-10-24 19:09:05 +00:00
BUFFER='echo ({x})'
2019-01-12 16:16:44 +00:00
2019-10-24 19:09:05 +00:00
expected_region_highlight=(
"6 6 bracket-level-1" # (
"7 7 bracket-level-2" # {
"9 9 bracket-level-2" # }
"10 10 bracket-level-1" # )
)
```
2019-01-12 16:16:44 +00:00
Testing the `pattern` and `regexp` highlighters
-----------------------------------------------
Because the `pattern` and `regexp` highlighters 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:
2019-10-24 19:09:05 +00:00
```zsh
ZSH_HIGHLIGHT_PATTERNS+=('rm -rf *' 'fg=white,bold,bg=red')
2019-01-12 16:16:44 +00:00
2019-10-24 19:09:05 +00:00
BUFFER='rm -rf /'
2019-01-12 16:16:44 +00:00
2019-10-24 19:09:05 +00:00
expected_region_highlight=(
"1 8 fg=white,bold,bg=red" # rm -rf /
)
```
2019-01-12 16:16:44 +00:00
Miscellany
----------
If you work on the driver (`zsh-syntax-highlighting.zsh`), you may find the following zstyle useful:
2019-10-24 19:09:05 +00:00
```zsh
zstyle ':completion:*:*:*:*:globbed-files' ignored-patterns {'*/',}zsh-syntax-highlighting.plugin.zsh
```
2019-01-12 16:16:44 +00:00
IRC channel
-----------
We're on #zsh-syntax-highlighting on freenode.