diff --git a/README.md b/README.md index d7fc4ad..59919f6 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,13 @@ zsh-syntax-highlighting ======================= -**[Fish shell](http://www.fishshell.com) like syntax highlighting for [Zsh](http://www.zsh.org).** +**[Fish shell][fish]-like like syntax highlighting for [Zsh][zsh].** *Requirements: zsh 4.3.17+.* +[fish]: http://www.fishshell.com/ +[zsh]: http://www.zsh.org/ + This package provides syntax highlighing for the shell zsh. It enables highlighing of commands whilst they are typed at a zsh prompt into an interactive terminal. This helps in reviewing commands before running @@ -18,9 +21,15 @@ How to install ### Using packages -* Arch Linux: [community/zsh-syntax-highlighting](https://www.archlinux.org/packages/zsh-syntax-highlighting) / [AUR/zsh-syntax-highlighting-git](https://aur.archlinux.org/packages/zsh-syntax-highlighting-git) -* Gentoo: [mv overlay](http://gpo.zugaina.org/app-shells/zsh-syntax-highlighting) -* Mac OS X / Homebrew: [brew install zsh-syntax-highlighting](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/zsh-syntax-highlighting.rb) +* Arch Linux: [community/zsh-syntax-highlighting][arch-package] / [AUR/zsh-syntax-highlighting-git][AUR-package] +* Gentoo: [mv overlay][gentoo-overlay] +* Mac OS X / Homebrew: [brew install zsh-syntax-highlighting][brew-package] + +[arch-package]: https://www.archlinux.org/packages/zsh-syntax-highlighting +[AUR-package]: https://aur.archlinux.org/packages/zsh-syntax-highlighting-git +[gentoo-overlay]: http://gpo.zugaina.org/app-shells/zsh-syntax-highlighting +[brew-package]: https://github.com/Homebrew/homebrew/blob/master/Library/Formula/zsh-syntax-highlighting.rb + ### In your ~/.zshrc @@ -28,7 +37,10 @@ How to install git clone git://github.com/zsh-users/zsh-syntax-highlighting.git - (or [download a snapshot](https://github.com/zsh-users/zsh-syntax-highlighting/archive/master.tar.gz)) + If `git` is not installed, you could download a snapshot of the latest + development tree from: + + https://github.com/zsh-users/zsh-syntax-highlighting/archive/master.tar.gz * Source the script **at the end** of `~/.zshrc`: @@ -41,27 +53,34 @@ How to install ### With oh-my-zsh -* Download the script or clone this repository in [oh-my-zsh](http://github.com/robbyrussell/oh-my-zsh) plugins directory: +Oh-my-zsh is a zsh configuration framework. It lives at +. + +To install zsh-syntax-highlighting under oh-my-zsh: + +1. Clone this repository in oh-my-zsh's plugins directory: git clone git://github.com/zsh-users/zsh-syntax-highlighting.git ~/.oh-my-zsh/custom/plugins/zsh-syntax-highlighting -* Activate the plugin in `~/.zshrc`: +2. Activate the plugin in `~/.zshrc`: plugins=( [plugins...] zsh-syntax-highlighting) -* Source `~/.zshrc` to take changes into account: +3. Source `~/.zshrc` to take changes into account: source ~/.zshrc Note that `zsh-syntax-highlighting` must be the last plugin sourced, so make it the last element of the `$plugins` array. + ### System-wide installation -Either 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` and directing your users to -add `source /usr/local/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh` +Either 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` +and directing your users to add + `source /usr/local/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh` in their `.zshrc`s. @@ -77,13 +96,16 @@ syntax highlighting. ### How are new releases announced? -There is currently no "push" announcements channel. However, the following alternatives exist: +There is currently no "push" announcements channel. However, the following +alternatives exist: - GitHub's RSS feed of releases: https://github.com/zsh-users/zsh-syntax-highlighting/releases.atom - An anitya entry: https://release-monitoring.org/project/7552/ + How to tweak ------------ -Syntax highlighting is done by pluggable highlighter scripts, see the [highlighters directory](highlighters) -for documentation and configuration settings. +Syntax highlighting is done by pluggable highlighter scripts. See the +[`highlighters` directory](./highlighters) for documentation and configuration +settings. diff --git a/changelog.md b/changelog.md index 8d8855c..ad0a0f5 100644 --- a/changelog.md +++ b/changelog.md @@ -3,7 +3,7 @@ up to 1933de83be0bbfb41c44d182fe581ad85012b71a -# Changes in version 0.3.1 +# Changes in version 0.3.1 ## Added highlighting of: diff --git a/highlighters/README.md b/highlighters/README.md index 833b840..0d104cd 100644 --- a/highlighters/README.md +++ b/highlighters/README.md @@ -3,18 +3,19 @@ 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 +* [`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: +To activate an highlighter, add it to the `ZSH_HIGHLIGHT_HIGHLIGHTERS` array in +`~/.zshrc`, for example: ZSH_HIGHLIGHT_HIGHLIGHTERS=(main brackets pattern cursor) @@ -22,23 +23,31 @@ To activate an highlighter, add it to the `ZSH_HIGHLIGHT_HIGHLIGHTERS` array in 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. +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: +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: +* 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: +* 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 diff --git a/highlighters/brackets/README.md b/highlighters/brackets/README.md index 9fd4f96..4bb37f4 100644 --- a/highlighters/brackets/README.md +++ b/highlighters/brackets/README.md @@ -1,11 +1,13 @@ zsh-syntax-highlighting / highlighters / brackets ================================================= -This is the ***brackets*** highlighter, that highlights brackets, parenthesis and matches them. +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) @@ -13,13 +15,15 @@ To activate it, add it to `ZSH_HIGHLIGHT_HIGHLIGHTERS`: 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 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' @@ -27,4 +31,5 @@ To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`, for 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 here](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135). +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 index d28ac19..470dd0d 100644 --- a/highlighters/cursor/README.md +++ b/highlighters/cursor/README.md @@ -1,11 +1,12 @@ zsh-syntax-highlighting / highlighters / cursor -================================================= +=============================================== -This is the ***cursor*** highlighter, that highlights the 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) @@ -13,12 +14,15 @@ To activate it, add it to `ZSH_HIGHLIGHT_HIGHLIGHTERS`: 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`: +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 here](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135). +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 index 2be32a2..781cf26 100644 --- a/highlighters/line/README.md +++ b/highlighters/line/README.md @@ -1,11 +1,12 @@ zsh-syntax-highlighting / highlighters / line -================================================= +============================================= -This is the ***line*** highlighter, that highlights the whole 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) @@ -13,12 +14,15 @@ To activate it, add it to `ZSH_HIGHLIGHT_HIGHLIGHTERS`: 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`: +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 here](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135). +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 index 9e54669..d450ed9 100644 --- a/highlighters/main/README.md +++ b/highlighters/main/README.md @@ -1,7 +1,7 @@ zsh-syntax-highlighting / highlighters / main ============================================= -This is the ***main*** highlighter, that highlights: +This is the `main` highlighter, that highlights: * Commands * Options @@ -11,6 +11,7 @@ This is the ***main*** highlighter, that highlights: How to activate it ------------------ + To activate it, add it to `ZSH_HIGHLIGHT_HIGHLIGHTERS`: ZSH_HIGHLIGHT_HIGHLIGHTERS=( [...] main) @@ -20,6 +21,7 @@ This highlighter is active by default. How to tweak it --------------- + This highlighter defines the following styles: * `unknown-token` - unknown tokens / errors @@ -50,7 +52,8 @@ This highlighter defines the following styles: * `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`: +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 diff --git a/highlighters/pattern/README.md b/highlighters/pattern/README.md index 82a7c65..75290f4 100644 --- a/highlighters/pattern/README.md +++ b/highlighters/pattern/README.md @@ -1,11 +1,12 @@ zsh-syntax-highlighting / highlighters / pattern ================================================ -This is the ***pattern*** highlighter, that highlights user defined patterns. +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) @@ -13,9 +14,12 @@ To activate it, add it to `ZSH_HIGHLIGHT_HIGHLIGHTERS`: How to tweak it --------------- -To use this highlighter, associate patterns with styles in the `ZSH_HIGHLIGHT_PATTERNS` array, for example in `~/.zshrc`: + +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 here](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135). +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 index 53c871b..8592ef7 100644 --- a/highlighters/root/README.md +++ b/highlighters/root/README.md @@ -1,11 +1,13 @@ zsh-syntax-highlighting / highlighters / root -================================================= +============================================= -This is the ***root*** highlighter, that highlights the whole line if the current user is 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) @@ -13,12 +15,15 @@ To activate it, add it to `ZSH_HIGHLIGHT_HIGHLIGHTERS`: 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`: +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 here](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135). +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/tests/README.md b/tests/README.md index 7b17914..faaed1e 100644 --- a/tests/README.md +++ b/tests/README.md @@ -8,22 +8,28 @@ directory with test data files. See the [main highlighter](../highlighters/main/test-data) for examples. Each test should define the array parameter `$expected_region_highlight`. -The value of that parameter is a list of `"$i $j $style [$todo]"` strings. +The value of that parameter is a list of strings of the form `"$i $j $style"`. +or `"$i $j $style $todo"`. Each string specifies the highlighting that `$BUFFER[$i,$j]` should have; that is, `$i` and `$j` specify a range, 1-indexed, inclusive of both endpoints. -If `$todo` exists, the test point is marked as TODO (the failure of that test point will not fail the test), and `$todo` is used as the explanation. +If `$todo` exists, the test point is marked as TODO (the failure of that test +point will not fail the test), and `$todo` is used as the explanation. -_Note_: `$region_highlight` uses the same `"$i $j $style"` syntax but interprets the indexes differently. +**Note**: `$region_highlight` uses the same `"$i $j $style"` syntax but +interprets the indexes differently. -**Isolation**: Each test is run in a separate subshell, so any variables, aliases, functions, etc., -it defines will be visible to the tested code (that computes `$region_highlight`), but will not affect -subsequent tests. The current working directory of tests is set to a newly-created empty directory, +**Isolation**: Each test is run in a separate subshell, so any variables, +aliases, functions, etc., it defines will be visible to the tested code (that +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. -highlighting test +Highlighting test ----------------- -[`test-highlighting.zsh`](tests/test-highlighting.zsh) tests the correctness of the highlighting. Usage: + +[`test-highlighting.zsh`](tests/test-highlighting.zsh) tests the correctness of +the highlighting. Usage: zsh test-highlighting.zsh @@ -31,12 +37,16 @@ All tests may be run with make test -which will run all highlighting tests and report results in [TAP](http://testanything.org/) format. +which will run all highlighting tests and report results in [TAP format][TAP]. + +[TAP]: http://testanything.org/ -performance test +Performance test ---------------- -[`test-perfs.zsh`](tests/test-perfs.zsh) measures the time spent doing the highlighting. Usage: + +[`test-perfs.zsh`](tests/test-perfs.zsh) measures the time spent doing the +highlighting. Usage: zsh test-perfs.zsh