Fast Syntax Highlighting (F-Sy-H)

A chroma function (or chroma) is a plugin-function used to create detailed, custom highlighting for specific programs (e.g., git, grep, awk).

The Lifecycle

1. The main highlighting engine (the "big loop") processes the command line token by token.
2. When the engine encounters a command with an associated chroma, it enters a "chroma" state.
3. The engine calls the associated chroma function for the current token.
4. The chroma function manages the highlighting for that token and ensures the "chroma" state persists for subsequent tokens.
5. The chroma function controls whether the engine continues to use the chroma or falls back to standard highlighting by returning specific values:
   • Return 0: Requests that the engine performs no further processing for this token (the chroma handles everything).
   • Return 1: Requests that the current token be passed back to the engine's "big loop" for standard highlighting.
   • Return 2: (Implicitly used in examples) Signals the end of the chroma-enabled command sequence (e.g., when a new command starts).

To create custom highlighting for a specific command, implement a Zsh function that accepts the four arguments described in the Chroma-Function Arguments Reference and uses the reply array to add highlight entries.

Key Implementation Details:

• State Management: Use the FAST_HIGHLIGHT hash array to store state (like counters) between calls without polluting global variables. Always reset your state when $1 (the first call) is detected.
• Highlighting via reply: To apply color, add an entry to the reply array in the format: "start_index end_index style_name". The style name should be derived from ${FAST_THEME_NAME}style_name.
• Advancing the Buffer: After processing a token, you must advance the internal pointers by setting _start_pos=$_end_pos and updating this_word to the next_word.
• Passing to Big Loop: If a token (like a quoted string) should be handled by the standard highlighter, return 1.

# Example chroma function implementation
# Colorizes first two arguments as 'builtin' and subsequent as 'globbing'

(( 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
} || {
    [[ "$__arg_type" = 3 ]] && return 2

    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
            if [[ "$__wrd" = \"* ]]; then
                return 1
            else
                __style=${FAST_THEME_NAME}builtin
            fi
        else
            __style=${FAST_THEME_NAME}globbing
        fi
    fi
}

[[ -n "$__style" ]] && (( __start=__start_pos-${#PREBUFFER}, __end=__end_pos-${#PREBUFFER}, __start >= 0 )) && reply+=("$__start $__end ${FAST_HIGHLIGHT_STYLES[$__style]}")

(( this_word = next_word ))
_start_pos=$_end_pos

return 0