From 4fb570e1046fd39ee6703f45f7a6bf139c68bb69 Mon Sep 17 00:00:00 2001 From: Sean Wei Date: Sun, 13 Jan 2019 16:12:41 +0800 Subject: [PATCH] docs: Enable Syntax Highlighting for Code Snippits --- HACKING.md | 58 ++++++++------- INSTALL.md | 30 +++++--- changelog.md | 130 +++++++++++++++++++++++----------- docs/highlighters.md | 34 +++++---- docs/highlighters/brackets.md | 12 ++-- docs/highlighters/cursor.md | 4 +- docs/highlighters/line.md | 4 +- docs/highlighters/main.md | 26 ++++--- docs/highlighters/pattern.md | 10 +-- docs/highlighters/regexp.md | 6 +- docs/highlighters/root.md | 4 +- tests/README.md | 40 +++++++---- 12 files changed, 234 insertions(+), 124 deletions(-) diff --git a/HACKING.md b/HACKING.md index 5266a33..71d8a2e 100644 --- a/HACKING.md +++ b/HACKING.md @@ -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 ----------- diff --git a/INSTALL.md b/INSTALL.md index 6793d89..9a32646 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -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. diff --git a/changelog.md b/changelog.md index f20e69d..3a2d00b 100644 --- a/changelog.md +++ b/changelog.md @@ -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 + ```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: diff --git a/docs/highlighters.md b/docs/highlighters.md index 642d2bd..f6eba7f 100644 --- a/docs/highlighters.md +++ b/docs/highlighters.md @@ -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). diff --git a/docs/highlighters/brackets.md b/docs/highlighters/brackets.md index 9001074..8410135 100644 --- a/docs/highlighters/brackets.md +++ b/docs/highlighters/brackets.md @@ -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)` diff --git a/docs/highlighters/cursor.md b/docs/highlighters/cursor.md index 7295fd1..c4f22b8 100644 --- a/docs/highlighters/cursor.md +++ b/docs/highlighters/cursor.md @@ -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)` diff --git a/docs/highlighters/line.md b/docs/highlighters/line.md index 4ba14e9..1081fe1 100644 --- a/docs/highlighters/line.md +++ b/docs/highlighters/line.md @@ -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)` diff --git a/docs/highlighters/main.md b/docs/highlighters/main.md index 005fc4d..f4507d8 100644 --- a/docs/highlighters/main.md +++ b/docs/highlighters/main.md @@ -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 have paths colored instead of underlined - ZSH_HIGHLIGHT_STYLES[path]='fg=cyan' - - # To disable highlighting of globbing expressions - ZSH_HIGHLIGHT_STYLES[globbing]='none' +# 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 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 diff --git a/docs/highlighters/pattern.md b/docs/highlighters/pattern.md index 8853db0..e67d79f 100644 --- a/docs/highlighters/pattern.md +++ b/docs/highlighters/pattern.md @@ -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)` diff --git a/docs/highlighters/regexp.md b/docs/highlighters/regexp.md index 2078525..06b21ac 100644 --- a/docs/highlighters/regexp.md +++ b/docs/highlighters/regexp.md @@ -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" diff --git a/docs/highlighters/root.md b/docs/highlighters/root.md index 0b0d41f..d120d20 100644 --- a/docs/highlighters/root.md +++ b/docs/highlighters/root.md @@ -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)` diff --git a/tests/README.md b/tests/README.md index 2d87204..89aef14 100644 --- a/tests/README.md +++ b/tests/README.md @@ -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 +```zsh +zsh test-highlighting.zsh +``` 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 +```zsh +zsh test-perfs.zsh +``` All tests may be run with - make perf +```zsh +make perf +```