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
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
zsh-syntax-highlighting / highlighters
======================================
Syntax highlighting is done by pluggable highlighters:
* `main` - the base highlighter, and the only one [active by default][main].
* `brackets` - [matches brackets][brackets] and parenthesis.
* `pattern` - matches [user-defined patterns][pattern].
* `regexp` - matches [user-defined regular expressions][regexp].
* `cursor` - matches [the cursor position][cursor].
* `root` - highlights the whole command line [if the current user is root][root].
* `line` - applied to [the whole command line][line].
[main]: highlighters/main.md
[brackets]: highlighters/brackets.md
[pattern]: highlighters/pattern.md
[regexp]: highlighters/regexp.md
[cursor]: highlighters/cursor.md
[root]: highlighters/root.md
[line]: highlighters/line.md
Highlighter-independent settings
--------------------------------
By default, all command lines are highlighted. However, it is possible to
prevent command lines longer than a fixed number of characters from being
highlighted by setting the variable `${ZSH_HIGHLIGHT_MAXLENGTH}` to the maximum
length (in characters) of command lines to be highlighter. This is useful when
editing very long command lines (for example, with the [`fned`][fned] utility
function). Example:
[fned]: https://zsh.sourceforge.io/Doc/Release/User-Contributions.html#index-zed
```zsh
ZSH_HIGHLIGHT_MAXLENGTH=512
```
How to activate highlighters
----------------------------
To activate an highlighter, add it to the `ZSH_HIGHLIGHT_HIGHLIGHTERS` array.
By default `ZSH_HIGHLIGHT_HIGHLIGHTERS` is `(main)`. For example to activate
`brackets`, `pattern`, and `cursor` highlighters, in `~/.zshrc` do:
```zsh
ZSH_HIGHLIGHT_HIGHLIGHTERS+=(brackets pattern cursor)
```
How to tweak highlighters
-------------------------
Highlighters look up styles from the `ZSH_HIGHLIGHT_STYLES` associative array.
Navigate into the [individual highlighters' documentation](highlighters/) to
see what styles (keys) each highlighter defines; the syntax for values is the
same as the syntax of "types of highlighting" of the zsh builtin
`$zle_highlight` array, which is documented in [the `zshzle(1)` manual
page][zshzle-Character-Highlighting].
[zshzle-Character-Highlighting]: https://zsh.sourceforge.io/Doc/Release/Zsh-Line-Editor.html#Character-Highlighting
Some highlighters support additional configuration parameters; see each
highlighter's documentation for details and examples.
How to implement a new highlighter
----------------------------------
To create your own `acme` highlighter:
* Create your script at
`highlighters/acme/acme-highlighter.zsh`.
* Implement the `_zsh_highlight_highlighter_acme_predicate` function.
This function must return 0 when the highlighter needs to be called and
non-zero otherwise, for example:
```zsh
_zsh_highlight_highlighter_acme_predicate() {
# Call this highlighter in SVN working copies
[[ -d .svn ]]
}
```
* Implement the `_zsh_highlight_highlighter_acme_paint` function.
This function does the actual syntax highlighting, by calling
`_zsh_highlight_add_highlight` with the start and end of the region to
be highlighted and the `ZSH_HIGHLIGHT_STYLES` key to use. Define the default
style for that key in the highlighter script outside of any function with
`: ${ZSH_HIGHLIGHT_STYLES[key]:=value}`, being sure to prefix
the key with your highlighter name and a colon. For example:
```zsh
: ${ZSH_HIGHLIGHT_STYLES[acme:aurora]:=fg=green}
_zsh_highlight_highlighter_acme_paint() {
# Colorize the whole buffer with the 'aurora' style
_zsh_highlight_add_highlight 0 $#BUFFER acme:aurora
}
```
If you need to test which options the user has set, test `zsyh_user_options`
with a sensible default if the option is not present in supported zsh
versions. For example:
```zsh
[[ ${zsyh_user_options[ignoreclosebraces]:-off} == on ]]
```
The option name must be all lowercase with no underscores and not an alias.
* Name your own functions and global variables `_zsh_highlight_acme_*`.
- In zsh-syntax-highlighting 0.4.0 and earlier, the entrypoints
`_zsh_highlight_highlighter_acme_predicate` and
`_zsh_highlight_highlighter_acme_paint`
were named
`_zsh_highlight_acme_highlighter_predicate` and
`_zsh_highlight_highlighter_acme_paint` respectively.
These names are still supported for backwards compatibility;
however, support for them will be removed in a future major or minor release (v0.x.0 or v1.0.0).
* Activate your highlighter in `~/.zshrc`:
```zsh
ZSH_HIGHLIGHT_HIGHLIGHTERS+=(acme)
```
* [Write tests](../tests/README.md).
|
