stonewareslord/zsh-syntax-highlighting
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

docs: Enable Syntax Highlighting for Code Snippits

Browse Source
This commit is contained in:
Sean Wei 2019-01-13 16:12:41 +08:00
parent 693757bfd7
commit 4fb570e104
No known key found for this signature in database
GPG Key ID: 9C5AA07E398D2783
12 changed files with 234 additions and 124 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
HACKING.md
View File

@ -11,16 +11,18 @@ 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
}
```zsh
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.
@ -32,17 +34,19 @@ 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]=
```zsh
ZSH_HIGHLIGHT_STYLES[bracket-level-1]=
ZSH_HIGHLIGHT_STYLES[bracket-level-2]=
BUFFER='echo ({x})'
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" # )
)
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` and `regexp` highlighters
-----------------------------------------------
@ -53,20 +57,24 @@ 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')
```zsh
ZSH_HIGHLIGHT_PATTERNS+=('rm -rf *' 'fg=white,bold,bg=red')
BUFFER='rm -rf /'
BUFFER='rm -rf /'
expected_region_highlight=(
"1 8 fg=white,bold,bg=red" # 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
```zsh
zstyle ':completion:*:*:*:*:globbed-files' ignored-patterns {'*/',}zsh-syntax-highlighting.plugin.zsh
```
IRC channel
-----------

30
INSTALL.md
View File

@ -33,17 +33,23 @@ See also [repology's cross-distro index](https://repology.org/metapackage/zsh-sy
Simply clone this repository and source the script:
git clone https://github.com/zsh-users/zsh-syntax-highlighting.git
echo "source ${(q-)PWD}/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh" >> ${ZDOTDIR:-$HOME}/.zshrc
```zsh
git clone https://github.com/zsh-users/zsh-syntax-highlighting.git
echo "source ${(q-)PWD}/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh" >> ${ZDOTDIR:-$HOME}/.zshrc
```
Then, enable syntax highlighting in the current interactive shell:
source ./zsh-syntax-highlighting/zsh-syntax-highlighting.zsh
```zsh
source ./zsh-syntax-highlighting/zsh-syntax-highlighting.zsh
```
If `git` is not installed, download and extract a snapshot of the latest
development tree from:
https://github.com/zsh-users/zsh-syntax-highlighting/archive/master.tar.gz
```
https://github.com/zsh-users/zsh-syntax-highlighting/archive/master.tar.gz
```
Note the `source` command must be **at the end** of `~/.zshrc`.
@ -69,11 +75,15 @@ your `.zshrc`.
1. Clone this repository in oh-my-zsh's plugins directory:
% git clone https://github.com/zsh-users/zsh-syntax-highlighting.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting
```zsh
git clone https://github.com/zsh-users/zsh-syntax-highlighting.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting
```
2. Activate the plugin in `~/.zshrc`:
plugins=( [plugins...] zsh-syntax-highlighting)
```zsh
plugins=( [plugins...] zsh-syntax-highlighting)
```
3. Restart zsh (such as by opening a new instance of your terminal emulator).
@ -104,10 +114,14 @@ Any of the above methods is suitable for a single-user installation,
which requires no special privileges. If, however, you desire to install
zsh-syntax-highlighting system-wide, you may do so by running
make install
```zsh
make install
```
and directing your users to add
source /usr/local/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh
```zsh
source /usr/local/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh
```
to their `.zshrc`s.

130
changelog.md
View File

@ -309,50 +309,66 @@ in this area.
- incomplete sudo commands
(a3047a912100, 2f05620b19ae)
sudo;
sudo -u;
```zsh
sudo;
sudo -u;
```
- command words following reserved words
(#207, #222, b397b12ac139 et seq, 6fbd2aa9579b et seq, 8b4adbd991b0)
if ls; then ls; else ls; fi
repeat 10 do ls; done
```zsh
if ls; then ls; else ls; fi
repeat 10 do ls; done
```
(The `ls` are now highlighted as a command.)
- comments (when `INTERACTIVE_COMMENTS` is set)
(#163, #167, 693de99a9030)
echo Hello # comment
```zsh
echo Hello # comment
```
- closing brackets of arithmetic expansion, subshells, and blocks
(#226, a59f442d2d34, et seq)
(( foo ))
( foo )
{ foo }
```zsh
(( foo ))
( foo )
{ foo }
```
- command names enabled by the `PATH_DIRS` option
(#228, 96ee5116b182)
# When ~/bin/foo/bar exists, is executable, ~/bin is in $PATH,
# and 'setopt PATH_DIRS' is in effect
foo/bar
```zsh
# When ~/bin/foo/bar exists, is executable, ~/bin is in $PATH,
# and 'setopt PATH_DIRS' is in effect
foo/bar
```
- parameter expansions with braces inside double quotes
(#186, 6e3720f39d84)
echo "${foo}"
```zsh
echo "${foo}"
```
- parameter expansions in command word
(#101, 4fcfb15913a2)
x=/bin/ls
$x -l
```zsh
x=/bin/ls
$x -l
```
- the command separators '|&', '&!', '&|'
- the command separators '\|&', '&!', '&\|'
view file.pdf &! ls
```zsh
view file.pdf &! ls
```
## Fixed highlighting of:
@ -360,23 +376,31 @@ in this area.
- precommand modifiers at non-command-word position
(#209, 2c9f8c8c95fa)
ls command foo
```zsh
ls command foo
```
- sudo commands with infix redirections
(#221, be006aded590, 86e924970911)
sudo -u >/tmp/foo.out user ls
```zsh
sudo -u >/tmp/foo.out user ls
```
- subshells; anonymous functions
(#166, #194, 0d1bfbcbfa67, 9e178f9f3948)
(true)
() { true }
```zsh
(true)
() { true }
```
- parameter assignment statements with no command
(#205, 01d7eeb3c713)
A=1;
```zsh
A=1;
```
(The semicolon used to be highlighted as a mistake)
@ -467,69 +491,95 @@ in this area.
- suffix aliases (requires zsh 5.1.1 or newer):
alias -s png=display
foo.png
```zsh
alias -s png=display
foo.png
```
- prefix redirections:
<foo.txt cat
```zsh
<foo.txt cat
```
- redirection operators:
echo > foo.txt
```zsh
echo > foo.txt
```
- arithmetic evaluations:
(( 42 ))
```zsh
(( 42 ))
```
- $'' strings, including \x/\octal/\u/\U escapes
: $'foo\u0040bar'
```zsh
: $'foo\u0040bar'
```
- multiline strings:
% echo "line 1
line 2"
```zsh
% echo "line 1
line 2"
```
- string literals that haven't been finished:
% echo "Hello, world
```zsh
% echo "Hello, world
```
- command words that involve tilde expansion:
% ~/bin/foo
```zsh
% ~/bin/foo
```
## Fixed highlighting of:
- quoted command words:
% \ls
```zsh
% \ls
```
- backslash escapes in "" strings:
% echo "\x41"
```zsh
% echo "\x41"
```
- noglob after command separator:
% :; noglob echo *
```zsh
% :; noglob echo *
```
- glob after command separator, when the first command starts with 'noglob':
% noglob true; echo *
```zsh
% noglob true; echo *
```
- the region (vi visual mode / set-mark-command) (issue #165)
- redirection and command separators that would be highlighted as `path_approx`
% echo foo;‸
% echo <‸
```zsh
% echo foo;‸
% echo <‸
```
(where `‸` represents the cursor location)
- escaped globbing (outside quotes)
% echo \*
```zsh
% echo \*
```
## Other changes:

34
docs/highlighters.md
View File

@ -24,7 +24,9 @@ How to activate highlighters
To activate an highlighter, add it to the `ZSH_HIGHLIGHT_HIGHLIGHTERS` array in
`~/.zshrc`, for example:
ZSH_HIGHLIGHT_HIGHLIGHTERS=(main brackets pattern cursor)
```zsh
ZSH_HIGHLIGHT_HIGHLIGHTERS=(main brackets pattern cursor)
```
By default, `$ZSH_HIGHLIGHT_HIGHLIGHTERS` is unset and only the `main`
highlighter is active.
@ -58,10 +60,12 @@ To create your own `acme` highlighter:
This function must return 0 when the highlighter needs to be called and
non-zero otherwise, for example:
_zsh_highlight_highlighter_acme_predicate() {
# Call this highlighter in SVN working copies
[[ -d .svn ]]
}
```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
@ -71,18 +75,22 @@ To create your own `acme` highlighter:
`: ${ZSH_HIGHLIGHT_STYLES[key]:=value}`, being sure to prefix
the key with your highlighter name and a colon. For example:
: ${ZSH_HIGHLIGHT_STYLES[acme:aurora]:=fg=green}
```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
}
_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:
[[ ${zsyh_user_options[ignoreclosebraces]:-off} == on ]]
```zsh
[[ ${zsyh_user_options[ignoreclosebraces]:-off} == on ]]
```
The option name must be all lowercase with no underscores and not an alias.
@ -100,6 +108,8 @@ To create your own `acme` highlighter:
* Activate your highlighter in `~/.zshrc`:
ZSH_HIGHLIGHT_HIGHLIGHTERS+=(acme)
```zsh
ZSH_HIGHLIGHT_HIGHLIGHTERS+=(acme)
```
* [Write tests](../tests/README.md).

12
docs/highlighters/brackets.md
View File

@ -16,11 +16,13 @@ This highlighter defines the following styles:
To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`,
for example in `~/.zshrc`:
# To define styles for nested brackets up to level 4
ZSH_HIGHLIGHT_STYLES[bracket-level-1]='fg=blue,bold'
ZSH_HIGHLIGHT_STYLES[bracket-level-2]='fg=red,bold'
ZSH_HIGHLIGHT_STYLES[bracket-level-3]='fg=yellow,bold'
ZSH_HIGHLIGHT_STYLES[bracket-level-4]='fg=magenta,bold'
```zsh
# To define styles for nested brackets up to level 4
ZSH_HIGHLIGHT_STYLES[bracket-level-1]='fg=blue,bold'
ZSH_HIGHLIGHT_STYLES[bracket-level-2]='fg=red,bold'
ZSH_HIGHLIGHT_STYLES[bracket-level-3]='fg=yellow,bold'
ZSH_HIGHLIGHT_STYLES[bracket-level-4]='fg=magenta,bold'
```
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)`

4
docs/highlighters/cursor.md
View File

@ -13,7 +13,9 @@ This highlighter defines the following styles:
To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`,
for example in `~/.zshrc`:
ZSH_HIGHLIGHT_STYLES[cursor]='bg=blue'
```zsh
ZSH_HIGHLIGHT_STYLES[cursor]='bg=blue'
```
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)`

4
docs/highlighters/line.md
View File

@ -13,7 +13,9 @@ This highlighter defines the following styles:
To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`,
for example in `~/.zshrc`:
ZSH_HIGHLIGHT_STYLES[line]='bold'
```zsh
ZSH_HIGHLIGHT_STYLES[line]='bold'
```
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)`

22
docs/highlighters/main.md
View File

@ -65,17 +65,19 @@ This highlighter defines the following styles:
To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`,
for example in `~/.zshrc`:
# Declare the variable
typeset -A ZSH_HIGHLIGHT_STYLES
```zsh
# Declare the variable
typeset -A ZSH_HIGHLIGHT_STYLES
# To differentiate aliases from other command types
ZSH_HIGHLIGHT_STYLES[alias]='fg=magenta,bold'
# To differentiate aliases from other command types
ZSH_HIGHLIGHT_STYLES[alias]='fg=magenta,bold'
# To have paths colored instead of underlined
ZSH_HIGHLIGHT_STYLES[path]='fg=cyan'
# To have paths colored instead of underlined
ZSH_HIGHLIGHT_STYLES[path]='fg=cyan'
# To disable highlighting of globbing expressions
ZSH_HIGHLIGHT_STYLES[globbing]='none'
# To disable highlighting of globbing expressions
ZSH_HIGHLIGHT_STYLES[globbing]='none'
```
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)`
@ -86,7 +88,9 @@ manual page][zshzle-Character-Highlighting].
To avoid partial path lookups on a path, add the path to the `X_ZSH_HIGHLIGHT_DIRS_BLACKLIST` array.
This interface is still experimental.
X_ZSH_HIGHLIGHT_DIRS_BLACKLIST+=(/mnt/slow_share)
```zsh
X_ZSH_HIGHLIGHT_DIRS_BLACKLIST+=(/mnt/slow_share)
```
### Useless trivia

10
docs/highlighters/pattern.md
View File

@ -9,11 +9,13 @@ This is the `pattern` highlighter, that highlights user-defined patterns.
To use this highlighter, associate patterns with styles in the
`ZSH_HIGHLIGHT_PATTERNS` associative array, for example in `~/.zshrc`:
# Declare the variable
typeset -A ZSH_HIGHLIGHT_PATTERNS
```zsh
# Declare the variable
typeset -A ZSH_HIGHLIGHT_PATTERNS
# To have commands starting with `rm -rf` in red:
ZSH_HIGHLIGHT_PATTERNS+=('rm -rf *' 'fg=white,bold,bg=red')
# To have commands starting with `rm -rf` in red:
ZSH_HIGHLIGHT_PATTERNS+=('rm -rf *' 'fg=white,bold,bg=red')
```
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)`

6
docs/highlighters/regexp.md
View File

@ -10,8 +10,10 @@ patterns.
To use this highlighter, associate regular expressions with styles in the
`ZSH_HIGHLIGHT_REGEXP` associative array, for example in `~/.zshrc`:
typeset -A ZSH_HIGHLIGHT_PATTERNS
ZSH_HIGHLIGHT_REGEXP+=('\bsudo\b' fg=123,bold)
```zsh
typeset -A ZSH_HIGHLIGHT_PATTERNS
ZSH_HIGHLIGHT_REGEXP+=('\bsudo\b' fg=123,bold)
```
This will highlight "sudo" only as a complete word, i.e., "sudo cmd", but not
"sudoedit"

4
docs/highlighters/root.md
View File

@ -14,7 +14,9 @@ This highlighter defines the following styles:
To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`,
for example in `~/.zshrc`:
ZSH_HIGHLIGHT_STYLES[root]='bg=red'
```zsh
ZSH_HIGHLIGHT_STYLES[root]='bg=red'
```
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)`

40
tests/README.md
View File

@ -38,17 +38,19 @@ computes `$region_highlight`), but will not affect subsequent tests. The
current working directory of tests is set to a newly-created empty directory,
which is automatically cleaned up after the test exits. For example:
setopt PATH_DIRS
mkdir -p foo/bar
touch foo/bar/testing-issue-228
chmod +x foo/bar/testing-issue-228
path+=( "$PWD"/foo )
```zsh
setopt PATH_DIRS
mkdir -p foo/bar
touch foo/bar/testing-issue-228
chmod +x foo/bar/testing-issue-228
path+=( "$PWD"/foo )
BUFFER='bar/testing-issue-228'
BUFFER='bar/testing-issue-228'
expected_region_highlight=(
"1 21 command" # bar/testing-issue-228
)
expected_region_highlight=(
"1 21 command" # bar/testing-issue-228
)
```
Writing new tests
@ -56,7 +58,9 @@ Writing new tests
An experimental tool is available to generate test files:
zsh -f tests/generate.zsh 'ls -x' acme newfile
```zsh
zsh -f tests/generate.zsh 'ls -x' acme newfile
```
This generates a `highlighters/acme/test-data/newfile.zsh` test file based on
the current highlighting of the given `$BUFFER` (in this case, `ls -x`).
@ -71,11 +75,15 @@ Highlighting test
[`test-highlighting.zsh`](tests/test-highlighting.zsh) tests the correctness of
the highlighting. Usage:
zsh test-highlighting.zsh <HIGHLIGHTER NAME>
```zsh
zsh test-highlighting.zsh <HIGHLIGHTER NAME>
```
All tests may be run with
make test
```zsh
make test
```
which will run all highlighting tests and report results in [TAP format][TAP].
By default, the results of all tests will be printed; to show only "interesting"
@ -91,8 +99,12 @@ Performance test
[`test-perfs.zsh`](tests/test-perfs.zsh) measures the time spent doing the
highlighting. Usage:
zsh test-perfs.zsh <HIGHLIGHTER NAME>
```zsh
zsh test-perfs.zsh <HIGHLIGHTER NAME>
```
All tests may be run with
make perf
```zsh
make perf
```