diff --git a/.gitignore b/.gitignore index fb2e708..18fa5ec 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ *.zwc* .pc/ +docs/all.md diff --git a/Makefile b/Makefile index a11cce5..0d01896 100644 --- a/Makefile +++ b/Makefile @@ -6,11 +6,13 @@ SHARE_DIR?=$(DESTDIR)$(PREFIX)/share/$(NAME) DOC_DIR?=$(DESTDIR)$(PREFIX)/share/doc/$(NAME) ZSH?=zsh # zsh binary to run tests with -# Have the default target do nothing. all: - @ : + cd docs && \ + cp highlighters.md all.md && \ + printf '\n\nIndividual highlighters documentation\n=====================================' >> all.md && \ + for doc in highlighters/*.md; do printf '\n\n'; cat "$$doc"; done >> all.md -install: +install: all $(INSTALL) -d $(SHARE_DIR) $(INSTALL) -d $(DOC_DIR) cp .version zsh-syntax-highlighting.zsh $(SHARE_DIR) @@ -25,10 +27,12 @@ install: # equivalent of) NONOMATCH in effect, and highlighters/*.zsh has no matches. for dirname in highlighters highlighters/*/ ; do \ $(INSTALL) -d $(SHARE_DIR)/"$$dirname"; \ - $(INSTALL) -d $(DOC_DIR)/"$$dirname"; \ for fname in "$$dirname"/*.zsh ; do [ -e "$$fname" ] && cp "$$fname" $(SHARE_DIR)"/$$dirname"; done; \ - for fname in "$$dirname"/*.md ; do [ -e "$$fname" ] && cp "$$fname" $(DOC_DIR)"/$$dirname"; done; \ done + cp -R docs/* $(DOC_DIR) + +clean: + rm -f docs/all.md test: @result=0; \ @@ -52,4 +56,4 @@ perf: done; \ exit $$result -.PHONY: all install test perf +.PHONY: all install clean test perf diff --git a/docs/highlighters.md b/docs/highlighters.md new file mode 100644 index 0000000..4c6b950 --- /dev/null +++ b/docs/highlighters.md @@ -0,0 +1,59 @@ +zsh-syntax-highlighting / highlighters +====================================== + +Syntax highlighting is done by pluggable highlighters: + +* `main` - the base highlighter, and the only one active by default. +* `brackets` - matches brackets and parenthesis. +* `pattern` - matches user-defined patterns. +* `cursor` - matches the cursor position. +* `root` - triggered if the current user is root. +* `line` - applied to the whole command line + + +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) + + +How to tweak highlighters +------------------------- + +Highlighters look up styles from the `ZSH_HIGHLIGHT_STYLES` array. +Navigate into each highlighter directory to see what styles it defines +and how to configure it. + + +How to implement a new highlighter +---------------------------------- + +To create your own `myhighlighter` highlighter: + +* Create your script at + `highlighters/${myhighlighter}/${myhighlighter}-highlighter.zsh`. + +* Implement the `_zsh_highlight_myhighlighter_highlighter_predicate` function. + This function must return 0 when the highlighter needs to be called and + non-zero otherwise, for example: + + _zsh_highlight_myhighlighter_highlighter_predicate() { + # Call this highlighter in SVN repositories + [[ -d .svn ]] + } + +* Implement the `_zsh_highlight_myhighlighter_highlighter` function. + This function does the actual syntax highlighting, by modifying + `region_highlight`, for example: + + _zsh_highlight_myhighlighter_highlighter() { + # Colorize the whole buffer with blue background + region_highlight+=(0 $#BUFFER bg=blue) + } + +* Activate your highlighter in `~/.zshrc`: + + ZSH_HIGHLIGHT_HIGHLIGHTERS+=(myhighlighter) diff --git a/docs/highlighters/brackets.md b/docs/highlighters/brackets.md new file mode 100644 index 0000000..df47d8c --- /dev/null +++ b/docs/highlighters/brackets.md @@ -0,0 +1,26 @@ +zsh-syntax-highlighting / highlighters / brackets +------------------------------------------------- + +This is the `brackets` highlighter, that highlights brackets and parentheses, and +matches them. + + +### How to tweak it + +This highlighter defines the following styles: + +* `bracket-error` - unmatched brackets +* `bracket-level-N` - brackets with nest level N +* `cursor-matchingbracket` - the matching bracket, if cursor is on a bracket + +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' + +The syntax for declaring styles is documented in [the `zshzle(1)` manual +page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135). diff --git a/docs/highlighters/cursor.md b/docs/highlighters/cursor.md new file mode 100644 index 0000000..3ff6c8e --- /dev/null +++ b/docs/highlighters/cursor.md @@ -0,0 +1,19 @@ +zsh-syntax-highlighting / highlighters / cursor +----------------------------------------------- + +This is the `cursor` highlighter, that highlights the cursor. + + +### How to tweak it + +This highlighter defines the following styles: + +* `cursor` - the style for the current cursor position + +To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`, +for example in `~/.zshrc`: + + ZSH_HIGHLIGHT_STYLES[cursor]='bg=blue' + +The syntax for declaring styles is documented in [the `zshzle(1)` manual +page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135). diff --git a/docs/highlighters/line.md b/docs/highlighters/line.md new file mode 100644 index 0000000..ac69f68 --- /dev/null +++ b/docs/highlighters/line.md @@ -0,0 +1,19 @@ +zsh-syntax-highlighting / highlighters / line +--------------------------------------------- + +This is the `line` highlighter, that highlights the whole line. + + +### How to tweak it + +This highlighter defines the following styles: + +* `line` - the style for the whole line + +To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`, +for example in `~/.zshrc`: + + ZSH_HIGHLIGHT_STYLES[line]='bold' + +The syntax for declaring styles is documented in [the `zshzle(1)` manual +page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135). diff --git a/docs/highlighters/main.md b/docs/highlighters/main.md new file mode 100644 index 0000000..bbf87ce --- /dev/null +++ b/docs/highlighters/main.md @@ -0,0 +1,63 @@ +zsh-syntax-highlighting / highlighters / main +--------------------------------------------- + +This is the `main` highlighter, that highlights: + +* Commands +* Options +* Arguments +* Paths +* Strings + +This highlighter is active by default. + + +### How to tweak it + +This highlighter defines the following styles: + +* `unknown-token` - unknown tokens / errors +* `reserved-word` - shell reserved words (`if`, `for`) +* `alias` - aliases +* `suffix-alias` - suffix aliases (requires zsh 5.1.1 or newer) +* `builtin` - shell builtin commands (`shift`, `pwd`, `zstyle`) +* `function` - function names +* `command` - command names +* `precommand` - precommand modifiers (e.g., `noglob`, `builtin`) +* `commandseparator` - command separation tokens (`;`, `&&`) +* `hashed-command` - hashed commands +* `path` - existing filenames +* `path_prefix` - prefixes of existing filenames +* `globbing` - globbing expressions (`*.txt`) +* `history-expansion` - history expansion expressions (`!foo` and `^foo^bar`) +* `single-hyphen-option` - single hyphen options (`-o`) +* `double-hyphen-option` - double hyphen options (`--option`) +* `back-quoted-argument` - backquoted expressions (`` `foo` ``) +* `single-quoted-argument` - single quoted arguments (`` 'foo' ``) +* `double-quoted-argument` - double quoted arguments (`` "foo" ``) +* `dollar-quoted-argument` - dollar quoted arguments (`` $'foo' ``) +* `dollar-double-quoted-argument` - parameter expansion inside double quotes (`$foo` inside `""`) +* `back-double-quoted-argument` - back double quoted arguments (`\x` inside `""`) +* `back-dollar-quoted-argument` - back dollar quoted arguments (`\x` inside `$''`) +* `assign` - parameter assignments +* `redirection` - redirection operators (`<`, `>`, etc) +* `comment` - comments, when `setopt INTERACTIVE_COMMENTS` is in effect (`echo # foo`) +* `default` - everything else + +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 + + # 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 declaring styles is documented in [the `zshzle(1)` manual +page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135). diff --git a/docs/highlighters/pattern.md b/docs/highlighters/pattern.md new file mode 100644 index 0000000..b0b2b90 --- /dev/null +++ b/docs/highlighters/pattern.md @@ -0,0 +1,16 @@ +zsh-syntax-highlighting / highlighters / pattern +------------------------------------------------ + +This is the `pattern` highlighter, that highlights user defined patterns. + + +### How to tweak it + +To use this highlighter, associate patterns with styles in the +`ZSH_HIGHLIGHT_PATTERNS` array, for example in `~/.zshrc`: + + # To have commands starting with `rm -rf` in red: + ZSH_HIGHLIGHT_PATTERNS+=('rm -rf *' 'fg=white,bold,bg=red') + +The syntax for declaring styles is documented in [the `zshzle(1)` manual +page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135). diff --git a/docs/highlighters/root.md b/docs/highlighters/root.md new file mode 100644 index 0000000..0b1f217 --- /dev/null +++ b/docs/highlighters/root.md @@ -0,0 +1,20 @@ +zsh-syntax-highlighting / highlighters / root +--------------------------------------------- + +This is the `root` highlighter, that highlights the whole line if the current +user is root. + + +### How to tweak it + +This highlighter defines the following styles: + +* `root` - the style for the whole line if the current user is root. + +To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`, +for example in `~/.zshrc`: + + ZSH_HIGHLIGHT_STYLES[root]='bg=red' + +The syntax for declaring styles is documented in [the `zshzle(1)` manual +page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135). diff --git a/highlighters/README.md b/highlighters/README.md deleted file mode 100644 index 0d104cd..0000000 --- a/highlighters/README.md +++ /dev/null @@ -1,59 +0,0 @@ -zsh-syntax-highlighting / highlighters -====================================== - -Syntax highlighting is done by pluggable highlighters: - -* [`main`](main) - the base highlighter, and the only one active by default. -* [`brackets`](brackets) - matches brackets and parenthesis. -* [`pattern`](pattern) - matches user-defined patterns. -* [`cursor`](cursor) - matches the cursor position. -* [`root`](root) - triggered if the current user is root. -* [`line`](line) - applied to the whole command line - - -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) - - -How to tweak highlighters -------------------------- - -Highlighters look up styles from the `ZSH_HIGHLIGHT_STYLES` array. -Navigate into each highlighter directory to see what styles it defines -and how to configure it. - - -How to implement a new highlighter ----------------------------------- - -To create your own `myhighlighter` highlighter: - -* Create your script at - `highlighters/${myhighlighter}/${myhighlighter}-highlighter.zsh`. - -* Implement the `_zsh_highlight_myhighlighter_highlighter_predicate` function. - This function must return 0 when the highlighter needs to be called and - non-zero otherwise, for example: - - _zsh_highlight_myhighlighter_highlighter_predicate() { - # Call this highlighter in SVN repositories - [[ -d .svn ]] - } - -* Implement the `_zsh_highlight_myhighlighter_highlighter` function. - This function does the actual syntax highlighting, by modifying - `region_highlight`, for example: - - _zsh_highlight_myhighlighter_highlighter() { - # Colorize the whole buffer with blue background - region_highlight+=(0 $#BUFFER bg=blue) - } - -* Activate your highlighter in `~/.zshrc`: - - ZSH_HIGHLIGHT_HIGHLIGHTERS+=(myhighlighter) diff --git a/highlighters/README.md b/highlighters/README.md new file mode 120000 index 0000000..7b048c0 --- /dev/null +++ b/highlighters/README.md @@ -0,0 +1 @@ +../docs/highlighters.md \ No newline at end of file diff --git a/highlighters/brackets/README.md b/highlighters/brackets/README.md deleted file mode 100644 index 4bb37f4..0000000 --- a/highlighters/brackets/README.md +++ /dev/null @@ -1,35 +0,0 @@ -zsh-syntax-highlighting / highlighters / brackets -================================================= - -This is the `brackets` highlighter, that highlights brackets and parentheses, and -matches them. - - -How to activate it ------------------- - -To activate it, add it to `ZSH_HIGHLIGHT_HIGHLIGHTERS`: - - ZSH_HIGHLIGHT_HIGHLIGHTERS=( [...] brackets) - - -How to tweak it ---------------- - -This highlighter defines the following styles: - -* `bracket-error` - unmatched brackets -* `bracket-level-N` - brackets with nest level N -* `cursor-matchingbracket` - the matching bracket, if cursor is on a bracket - -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' - -The syntax for declaring styles is documented in [the `zshzle(1)` manual -page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135). diff --git a/highlighters/brackets/README.md b/highlighters/brackets/README.md new file mode 120000 index 0000000..d8f3a5a --- /dev/null +++ b/highlighters/brackets/README.md @@ -0,0 +1 @@ +../docs/highlighters/brackets.md \ No newline at end of file diff --git a/highlighters/cursor/README.md b/highlighters/cursor/README.md deleted file mode 100644 index 470dd0d..0000000 --- a/highlighters/cursor/README.md +++ /dev/null @@ -1,28 +0,0 @@ -zsh-syntax-highlighting / highlighters / cursor -=============================================== - -This is the `cursor` highlighter, that highlights the cursor. - - -How to activate it ------------------- - -To activate it, add it to `ZSH_HIGHLIGHT_HIGHLIGHTERS`: - - ZSH_HIGHLIGHT_HIGHLIGHTERS=( [...] cursor) - - -How to tweak it ---------------- - -This highlighter defines the following styles: - -* `cursor` - the style for the current cursor position - -To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`, -for example in `~/.zshrc`: - - ZSH_HIGHLIGHT_STYLES[cursor]='bg=blue' - -The syntax for declaring styles is documented in [the `zshzle(1)` manual -page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135). diff --git a/highlighters/cursor/README.md b/highlighters/cursor/README.md new file mode 120000 index 0000000..13f58ef --- /dev/null +++ b/highlighters/cursor/README.md @@ -0,0 +1 @@ +../docs/highlighters/cursor.md \ No newline at end of file diff --git a/highlighters/line/README.md b/highlighters/line/README.md deleted file mode 100644 index 781cf26..0000000 --- a/highlighters/line/README.md +++ /dev/null @@ -1,28 +0,0 @@ -zsh-syntax-highlighting / highlighters / line -============================================= - -This is the `line` highlighter, that highlights the whole line. - - -How to activate it ------------------- - -To activate it, add it to `ZSH_HIGHLIGHT_HIGHLIGHTERS`: - - ZSH_HIGHLIGHT_HIGHLIGHTERS=( [...] line) - - -How to tweak it ---------------- - -This highlighter defines the following styles: - -* `line` - the style for the whole line - -To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`, -for example in `~/.zshrc`: - - ZSH_HIGHLIGHT_STYLES[line]='bold' - -The syntax for declaring styles is documented in [the `zshzle(1)` manual -page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135). diff --git a/highlighters/line/README.md b/highlighters/line/README.md new file mode 120000 index 0000000..80edd29 --- /dev/null +++ b/highlighters/line/README.md @@ -0,0 +1 @@ +../docs/highlighters/line.md \ No newline at end of file diff --git a/highlighters/main/README.md b/highlighters/main/README.md deleted file mode 100644 index d450ed9..0000000 --- a/highlighters/main/README.md +++ /dev/null @@ -1,71 +0,0 @@ -zsh-syntax-highlighting / highlighters / main -============================================= - -This is the `main` highlighter, that highlights: - -* Commands -* Options -* Arguments -* Paths -* Strings - -How to activate it ------------------- - -To activate it, add it to `ZSH_HIGHLIGHT_HIGHLIGHTERS`: - - ZSH_HIGHLIGHT_HIGHLIGHTERS=( [...] main) - -This highlighter is active by default. - - -How to tweak it ---------------- - -This highlighter defines the following styles: - -* `unknown-token` - unknown tokens / errors -* `reserved-word` - shell reserved words (`if`, `for`) -* `alias` - aliases -* `suffix-alias` - suffix aliases (requires zsh 5.1.1 or newer) -* `builtin` - shell builtin commands (`shift`, `pwd`, `zstyle`) -* `function` - function names -* `command` - command names -* `precommand` - precommand modifiers (e.g., `noglob`, `builtin`) -* `commandseparator` - command separation tokens (`;`, `&&`) -* `hashed-command` - hashed commands -* `path` - existing filenames -* `path_prefix` - prefixes of existing filenames -* `globbing` - globbing expressions (`*.txt`) -* `history-expansion` - history expansion expressions (`!foo` and `^foo^bar`) -* `single-hyphen-option` - single hyphen options (`-o`) -* `double-hyphen-option` - double hyphen options (`--option`) -* `back-quoted-argument` - backquoted expressions (`` `foo` ``) -* `single-quoted-argument` - single quoted arguments (`` 'foo' ``) -* `double-quoted-argument` - double quoted arguments (`` "foo" ``) -* `dollar-quoted-argument` - dollar quoted arguments (`` $'foo' ``) -* `dollar-double-quoted-argument` - parameter expansion inside double quotes (`$foo` inside `""`) -* `back-double-quoted-argument` - back double quoted arguments (`\x` inside `""`) -* `back-dollar-quoted-argument` - back dollar quoted arguments (`\x` inside `$''`) -* `assign` - parameter assignments -* `redirection` - redirection operators (`<`, `>`, etc) -* `comment` - comments, when `setopt INTERACTIVE_COMMENTS` is in effect (`echo # foo`) -* `default` - everything else - -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 - - # 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 declaring styles is documented in [the `zshzle(1)` manual -page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135). diff --git a/highlighters/main/README.md b/highlighters/main/README.md new file mode 120000 index 0000000..e99df2e --- /dev/null +++ b/highlighters/main/README.md @@ -0,0 +1 @@ +../docs/highlighters/main.md \ No newline at end of file diff --git a/highlighters/pattern/README.md b/highlighters/pattern/README.md deleted file mode 100644 index 75290f4..0000000 --- a/highlighters/pattern/README.md +++ /dev/null @@ -1,25 +0,0 @@ -zsh-syntax-highlighting / highlighters / pattern -================================================ - -This is the `pattern` highlighter, that highlights user defined patterns. - - -How to activate it ------------------- - -To activate it, add it to `ZSH_HIGHLIGHT_HIGHLIGHTERS`: - - ZSH_HIGHLIGHT_HIGHLIGHTERS=( [...] pattern) - - -How to tweak it ---------------- - -To use this highlighter, associate patterns with styles in the -`ZSH_HIGHLIGHT_PATTERNS` array, for example in `~/.zshrc`: - - # To have commands starting with `rm -rf` in red: - ZSH_HIGHLIGHT_PATTERNS+=('rm -rf *' 'fg=white,bold,bg=red') - -The syntax for declaring styles is documented in [the `zshzle(1)` manual -page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135). diff --git a/highlighters/pattern/README.md b/highlighters/pattern/README.md new file mode 120000 index 0000000..edaff5a --- /dev/null +++ b/highlighters/pattern/README.md @@ -0,0 +1 @@ +../docs/highlighters/pattern.md \ No newline at end of file diff --git a/highlighters/root/README.md b/highlighters/root/README.md deleted file mode 100644 index 8592ef7..0000000 --- a/highlighters/root/README.md +++ /dev/null @@ -1,29 +0,0 @@ -zsh-syntax-highlighting / highlighters / root -============================================= - -This is the `root` highlighter, that highlights the whole line if the current -user is root. - - -How to activate it ------------------- - -To activate it, add it to `ZSH_HIGHLIGHT_HIGHLIGHTERS`: - - ZSH_HIGHLIGHT_HIGHLIGHTERS=( [...] root) - - -How to tweak it ---------------- - -This highlighter defines the following styles: - -* `root` - the style for the whole line if the current user is root. - -To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`, -for example in `~/.zshrc`: - - ZSH_HIGHLIGHT_STYLES[root]='bg=red' - -The syntax for declaring styles is documented in [the `zshzle(1)` manual -page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135). diff --git a/highlighters/root/README.md b/highlighters/root/README.md new file mode 120000 index 0000000..2f69e4a --- /dev/null +++ b/highlighters/root/README.md @@ -0,0 +1 @@ +../docs/highlighters/root.md \ No newline at end of file