Fast Syntax Highlighting

https://github.com/zdharma-continuum/fast-syntax-highlighting
Admin
Fast Syntax Highlighting is a feature-rich syntax highlighting plugin for Zsh that provides advanced...
Tokens:39,944
Snippets:217
Trust Score:9.7
License:BSD-3-Clause
Update:1 month ago
Show doc for...
Tokens:
Raw
### -fast-highlight-init usage example

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/_autodocs/api-reference/fast-highlight.md

Example of initializing the state before processing a buffer.

```zsh
-fast-highlight-init
-fast-highlight-process "" "echo \$HOME" 0
```

--------------------------------

### Error-handling example for -fast-highlight-check-path

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/_autodocs/api-reference/fast-highlight.md

Demonstrates how a nonexistent path results in a fallback to default styling.

```zsh
reply=(); __arg=/definitely/not/here; _start_pos=0; _end_pos=21; __PBUFLEN=0
if -fast-highlight-check-path noasync; then
  print -r -- "highlighted as $__style"
else
  print -r -- "not a path -> falls back to default styling"
fi
```

--------------------------------

### Manual Installation via Git

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/README.md

Clone the repository to a local directory and source the plugin file in your .zshrc.

```zsh
git clone https://github.com/zdharma-continuum/fast-syntax-highlighting ~/path/to/fsh
```

```zsh
source ~/path/to/fsh/fast-syntax-highlighting.plugin.zsh
```

--------------------------------

### Sync Zsh options example

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/_autodocs/api-reference/fast-highlight.md

Example of re-invoking the sync function after changing Zsh options.

```zsh
setopt interactive_comments
-fast-highlight-fill-option-variables
print -r -- $FAST_HIGHLIGHT[ointeractive_comments]   # 1
```

--------------------------------

### -fast-highlight-process basic usage

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/_autodocs/api-reference/fast-highlight.md

A basic example of calling the highlighting function and inspecting the resulting reply array.

```zsh
reply=()
PREBUFFER=""
BUFFER="ls /usr/bin"
-fast-highlight-process "$PREBUFFER" "$BUFFER" 0
print -r -- $reply
# 0 2 ${FAST_HIGHLIGHT_STYLES[${FAST_THEME_NAME}command]}
# 3 11 ${FAST_HIGHLIGHT_STYLES[${FAST_THEME_NAME}path-to-dir]}
```

--------------------------------

### -fast-highlight-init clean slate example

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/_autodocs/api-reference/fast-highlight.md

Ensures a clean slate before a fresh parse to prevent stale data leakage.

```zsh
-fast-highlight-init
reply=()
-fast-highlight-process "" "cd /tmp && ls" 0
```

--------------------------------

### Antigen Installation

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/README.md

Add the plugin to your .zshrc using the Antigen bundle command.

```zsh
antigen bundle zdharma-continuum/fast-syntax-highlighting
```

--------------------------------

### Unknown command error-handling example

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/_autodocs/api-reference/fast-highlight.md

Shows how to route commands that classify as none.

```zsh
-fast-highlight-main-type definitely-not-a-command
[[ $REPLY == none ]] && print -r -- "highlight as unknown-token"
```

--------------------------------

### Oh-My-Zsh Installation

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/README.md

Clone the repository into your Oh-My-Zsh custom plugins directory and enable it in your plugin list.

```zsh
git clone https://github.com/zdharma-continuum/fast-syntax-highlighting.git \
  ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/fast-syntax-highlighting
```

--------------------------------

### Usage example for `.fast-zts-read-all`

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/_autodocs/api-reference/helpers.md

Opens a file descriptor to the output of `ls /usr/bin`, reads it into a variable with `.fast-zts-read-all`, then prints the first 40 characters.

```zsh
exec {fd}< <(ls /usr/bin)
local content
.fast-zts-read-all $fd content
exec {fd}<&-
print -r -- $content[1,40]
```

--------------------------------

### Example chroma function invocation

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/CHROMA_GUIDE.adoc

Shows the arguments passed to a chroma function: first call flag, current token, start position, and end position.

```zsh
chroma/-example.ch 1 "grep" "$_start_pos" "$_end_pos"
```

--------------------------------

### Zinit Installation

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/README.md

Add the plugin to your .zshrc using Zinit. You can also use Turbo mode to load it in the background after the first prompt.

```zsh
zinit light zdharma-continuum/fast-syntax-highlighting
```

```zsh
zinit wait lucid for \
 atinit"ZINIT[COMPINIT_OPTS]=-C; zicompinit; zicdreplay" \
    zdharma-continuum/fast-syntax-highlighting \
 blockf \
    zsh-users/zsh-completions \
 atload"!_zsh_autosuggest_start" \
    zsh-users/zsh-autosuggestions
```

--------------------------------

### Classify command and branch example

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/_autodocs/api-reference/fast-highlight.md

Demonstrates how to classify a command and branch logic based on the returned REPLY value.

```zsh
-fast-highlight-main-type git
case $REPLY in
  command)    print -r -- "git: external command";;
  alias)      print -r -- "git: an alias (of ${aliases[git]})";;
  builtin)    print -r -- "git: shell builtin";;
esac
```

--------------------------------

### Secondary theme example (free.ini)

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/THEME_GUIDE.md

Each theme can define a 'secondary' key that specifies an alternate theme used for recursive highlighting of eval arguments and command substitution interiors.

```ini
; free.ini
[base]
default          = none
unknown-token    = red,bold
; ...
; ...
; ...
secondary        = zdharma

```

--------------------------------

### Zgen Installation

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/README.md

Add the plugin to your .zshrc alongside other zgen load calls.

```zsh
zgen load zdharma-continuum/fast-syntax-highlighting
```

--------------------------------

### -fast-highlight-process advanced usage

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/_autodocs/api-reference/fast-highlight.md

An example of calling the function with a multi-line buffer and async path checking enabled.

```zsh
autoload -Uz is-at-least
FAST_HIGHLIGHT[use_async]=1   # route path checks through the ZLE fd-handler
reply=()
PREBUFFER=""
BUFFER=$'ls /bin/df\n # a comment\nls /usr/bin'
-fast-highlight-process "$PREBUFFER" "$BUFFER" 0
```

--------------------------------

### Overlay theme example (overlay.ini)

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/THEME_GUIDE.md

Overlay files use the same INI format as full themes but define only a few styles that override the main theme. The filename overlay.ini is treated specially.

```ini
; overlay.ini
[base]
commandseparator = yellow,bold
comment          = 17

[command-point]
function       = green
command        = 180

```

--------------------------------

### Enable FAST_HIGHLIGHT options in ~/.zshrc

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/_autodocs/configuration.md

Example of enabling async path checking and brackets in ~/.zshrc before/after sourcing the plugin. The chroma-git entry is shown as the default; override it to disable. use_brackets is already the default.

```zsh
source ~/fast-syntax-highlighting/fast-syntax-highlighting.plugin.zsh
FAST_HIGHLIGHT[use_async]=1
FAST_HIGHLIGHT[use_brackets]=1     # already the default
FAST_HIGHLIGHT[chroma-git]=→chroma/main-chroma.ch%git   # default; override to disable
```

--------------------------------

### Path short-hands for fast-theme

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/THEME_GUIDE.md

Short-hands for specifying theme paths: XDG, LOCAL, HOME, and OPT. For example, 'fast-theme XDG:overlay' loads ~/.config/fsh/overlay.ini.

```text
XDG:    = ~/.config/fsh (respects $XDG_CONFIG_HOME env var)
LOCAL:  = /usr/local/share/fsh/
HOME:   = ~/.fsh/
OPT:    = /opt/local/share/fsh/

```

--------------------------------

### Example definition file excerpt from →chroma/-git.ch

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/_autodocs/api-reference/main-chroma.md

Shows the structure of an associative array fsh__git__chroma__def with keys like subcmd:NULL, subcommands, subcmd-hook, subcommands-blacklist, and per-subcommand option/argument sets. Values use || to separate option rows and <<>> to separate action and handler cells.

```zsh
typeset -gA fsh__git__chroma__def
fsh__git__chroma__def=(
    subcmd:NULL "NULL_0_opt"
    NULL_0_opt "(-C|--exec-path=|--git-dir=|--work-tree=|--namespace=|--super-prefix=)
                   <<>> NO-OP // ::→chroma/main-chroma-std-aopt-action
                   <<>> NO-OP // ::→chroma/main-chroma-std-aopt-ARG-action
            || -c
                    <<>> __style=\${FAST_THEME_NAME}single-hyphen-option // NO-OP
                    <<>> __style=\${FAST_THEME_NAME}optarg-string // NO-OP"

    "subcommands" "::→chroma/-git-get-subcommands"          # function run to obtain the list (via `reply')
    "subcmd-hook" "→chroma/-git-check-if-alias"
    "subcommands-blacklist" "mv,other"

    subcmd:fetch "FETCH_MULTIPLE_0_opt^ // FETCH_ALL_0_opt^ // FETCH_0_opt //
                  REMOTE_GR_1_arg // REF_#_arg // NO_MATCH_#_opt"

    "FETCH_MULTIPLE_0_opt^" "
                --multiple
                        <<>> __style=\${FAST_THEME_NAME}double-hyphen-option // NO-OP
                || --multiple:add
                        <<>> REMOTE_GR_#_arg
                || --multiple:del
                        <<>> REMOTE_GR_1_arg // REF_#_arg"

    REMOTE_GR_1_arg "NO-OP // ::→chroma/-git-verify-remote-or-group"
    "REF_#_arg" "NO-OP // ::→chroma/-git-verify-ref"
    NO_MATCH_\#_opt "* <<>> __style=\${FAST_THEME_NAME}incorrect-subtle // NO-OP"
)
```

--------------------------------

### Synchronous usage of -fast-highlight-check-path

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/_autodocs/api-reference/fast-highlight.md

Example of calling the path check function synchronously when FAST_HIGHLIGHT[use_async] is unset.

```zsh
if -fast-highlight-check-path noasync; then
  reply+=("$__start $__end ${FAST_HIGHLIGHT_STYLES[$__style]}")
fi
```

--------------------------------

### Source fast-string-highlight from plugin entry point

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/_autodocs/api-reference/fast-string-highlight.md

Loads the fast-string-highlight script from the plugin's directory. This is done after fast-highlight is sourced.

```zsh
source "${0:h}/fast-string-highlight"
```

--------------------------------

### Autoload chroma functions

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/_autodocs/api-reference/chromas.md

Autoloads all chroma functions at plugin start. The ellipsis indicates additional chroma files.

```zsh
autoload -Uz -- →chroma/-git.ch →chroma/-hub.ch … →chroma/main-chroma.ch …
```

--------------------------------

### Sourcing fast-highlight from plugin entry point

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/_autodocs/api-reference/fast-highlight.md

This command sources the `fast-highlight` file from the plugin's directory. It is used inside the `fast-syntax-highlighting.plugin.zsh` entry point. The file is not autoloaded, so it must be sourced explicitly. It can also be loaded standalone for headless use.

```zsh
source "${0:h}/fast-highlight"

```

--------------------------------

### Canonical chroma template from →chroma/-example.ch

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/_autodocs/api-reference/chromas.md

Template for creating a chroma in fast-syntax-highlighting. It keeps chroma-takever state until a semicolon, handles first and subsequent calls, returns 2 to end the chroma, returns 1 for pass-through, and emits region_highlight entries via the reply array. Register the file as chroma-example and autoload it to use.

```zsh
# Keep chroma-takever state meaning: until ;, handle highlighting via chroma.
(( next_word = 2 | 8192 ))

local __first_call="$1" __wrd="$2" __start_pos="$3" __end_pos="$4"
local __style
integer __idx1 __idx2

(( __first_call )) && {
    FAST_HIGHLIGHT[chroma-example-counter]=0
    __style=${FAST_THEME_NAME}command
} || {
    # Following call, i.e. not the first one
    [[ "$__arg_type" = 3 ]] && return 2          # chroma ends
    if (( in_redirection > 0 || this_word & 128 )) || [[ $__wrd == "<<<" ]]; then
        return 1                                 # pass through
    fi
    if [[ "$__wrd" = -* ]]; then
        [[ "$__wrd" = --* ]] && __style=${FAST_THEME_NAME}double-hyphen-option || \
                                __style=${FAST_THEME_NAME}single-hyphen-option
    else
        (( FAST_HIGHLIGHT[chroma-example-counter] += 1, __idx1 = FAST_HIGHLIGHT[chroma-example-counter] ))
        if (( FAST_HIGHLIGHT[chroma-example-counter] <= 2 )); then
            [[ "$__wrd" = \"* ]] && return 1     # strings: let main code highlight
            __style=${FAST_THEME_NAME}builtin
        else
            __style=${FAST_THEME_NAME}globbing
        fi
    fi
}

# The standard emit site: add region_highlight entry (via `reply').
[[ -n "$__style" ]] && (( __start=__start_pos-${#PREBUFFER}, __end=__end_pos-${#PREBUFFER}, __start >= 0 )) && reply+=("$__start $__end ${FAST_HIGHLIGHT_STYLES[$__style]}")

# We aren't passing-through, do obligatory things ourselves.
(( this_word = next_word ))
_start_pos=$_end_pos

return 0

```

--------------------------------

### Usage example for .fast-read-ini-file

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/_autodocs/api-reference/helpers.md

Parses an INI file into a named associative array and prints a value. The function returns 0 on success.

```zsh
typeset -A my_theme
if .fast-read-ini-file ~/.config/fsh/mytheme.ini my_theme ""; then
  print -r -- $my_theme[math_matherr]
fi
```

--------------------------------

### Load fast-syntax-highlighting plugin

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/_autodocs/api-reference/plugin-entry.md

Methods for sourcing the plugin directly or via common Zsh plugin managers.

```zsh
source ~/path/to/fsh/fast-syntax-highlighting.plugin.zsh
# zinit:  zinit light zdharma-continuum/fast-syntax-highlighting
# antigen: antigen bundle zdharma-continuum/fast-syntax-highlighting
# zgen:    zgen load zdharma-continuum/fast-syntax-highlighting
```

--------------------------------

### -fast-highlight-string

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/_autodocs/api-reference/fast-highlight.md

Highlights variables and backslash escapes inside double-quoted strings. Accepts an optional extra style string that gets glued into every added entry.

```APIDOC
## -fast-highlight-string

### Description
Highlights variables and backslash escapes inside double-quoted strings. Accepts an optional extra style string that gets glued into every added entry.

### Signature
`-fast-highlight-string [$1]`

### Parameters
- **$1** (string) - Optional - Extra style string to glue into every added entry (used with `here-string-var`).

### Usage
Operates on the loop variables `$__arg`, `$__idx`, `$_start_pos`, `$__PBUFLEN`; appends to `reply`. Matches `$var`, `${...var...}`, lone `$` and `\x` escapes; the default style used is `back-or-dollar-double-quoted-argument`.

### Example
```zsh
# within a chroma or the loop: highlight "text $var x" content
__arg='text $var and \$literal'
_start_pos=0; __PBUFLEN=0
-fast-highlight-string          # no extra glue style
-fast-highlight-string ${FAST_HIGHLIGHT_STYLES[${FAST_THEME_NAME}here-string-var]:#none}  # glued
```

### Non-trivial Usage
Let a chroma style the inner variable of a here-string by passing its var style as the glue argument (this is exactly what the here-string branch of `-fast-highlight-process` does, `fast-highlight:1118`):

```zsh
reply=(); __arg='$PATH text'; _start_pos=0; _end_pos=9; __PBUFLEN=0
-fast-highlight-string ${FAST_HIGHLIGHT_STYLES[${FAST_THEME_NAME}here-string-var]:#none}
print -r -- $reply[1]   # "0 6 <here-string-var style>"
```
```

--------------------------------

### Load custom theme and overlay

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/_autodocs/api-reference/fast-theme.md

Load a custom theme or overlay from the XDG configuration directory.

```zsh
fast-theme XDG:mytheme            # ~/.config/fsh/mytheme.ini as main theme
fast-theme XDG:overlay            # ~/.config/fsh/overlay.ini as overlay
```

--------------------------------

### Advanced call with complex brackets

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/_autodocs/api-reference/fast-string-highlight.md

Demonstrates how complex brackets (like '[[ ]]') are handled. When the two '[' characters are marked as complex, they are not counted as nesting levels, so only the closing ']]' gets a bracket-level entry.

```zsh
reply=()
_FAST_COMPLEX_BRACKETS=( 3 4 )     # the two "[" chars of "[["
-fast-highlight-string-process "" "[[ x ]]"
# only the closing "]]" at 6..8 gets a bracket-level entry; "[["
# contribute no level, exactly as recorded by -fast-highlight-process
```

--------------------------------

### -fast-highlight-init function definition

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/_autodocs/api-reference/fast-highlight.md

Resets the internal scratch state, including bracket and command-type caches.

```zsh
-fast-highlight-init() {
  _FAST_COMPLEX_BRACKETS=()
  __fast_highlight_main__command_type_cache=()
}
```

--------------------------------

### Invoke chroma function

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/_autodocs/api-reference/chromas.md

Calls a chroma with the required arguments: first-call flag, token, start position, and end position. The registry value may encode a handler with 'path/to.ch%handler'.

```zsh
${${FAST_HIGHLIGHT[chroma-${__list[1]}]}%\%*} ${(M)FAST_HIGHLIGHT[chroma-${__list[1]}]%\%*} 0 "$__arg" $_start_pos $_end_pos
```

--------------------------------

### Expand FAST_WORK_DIR shortcuts

Source: https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/_autodocs/configuration.md

This code snippet demonstrates how the plugin expands shortcut prefixes like XDG:, LOCAL:, HOME:, and OPT: within the FAST_WORK_DIR environment variable.

```zsh
map=( "XDG:"    "${XDG_CONFIG_HOME:-$HOME/.config}/fsh/"
      "LOCAL:"  "/usr/local/share/fsh/"
      "HOME:"   "$HOME/.fsh/"
      "OPT:"    "/opt/local/share/fsh/"
)
FAST_WORK_DIR=${${FAST_WORK_DIR/(#m)(#s)(XDG|LOCAL|HOME|OPT):(#c0,1)/${map[${MATCH%:}:]}}%/}
```
Tokens:
Raw