Shells support colored output. Some do so also during tab completion.
It can provide extra context like whether an issue is open (green) or closed (red).
Or reflect the color of labels:
Here is how this works and how it is done in carapace...
ANSI escape sequences
Text style is set in the shell using an escape sequence like \e[31;42m
.
This instructs the terminal that the text following it is red (31) with a green background (41).
It consists of
-
\e
escape. -
[
an opening square bracket. -
31;42
a semicolon-separated list of escape codes. -
m
the letter m.
A common approach is to restore the default style using \e[0m
afterwards.
echo "\e[1;2;4;35mdim bold underlined magenta\e[0m" # you might need `echo -e` for this
There are basic foreground colors (30-37), background colors (40-47),
modes (1-9) and reset (0) to restore the default. 256-colors
and RGB are also possible.
You can find a full list at ANSI Escape Sequences.
Elvish
This one is easy.
Styled
Elvish provides an abstraction for escape sequences using a list of human-readable keywords.
echo (styled "dim bold underlined magenta" dim bold underlined magenta)
You can read more about this at styled.
Complex candidate
Adding colors to tab completion is thus pretty easy with edit:complex-candidate.
set edit:completion:arg-completer[example] = {|@args|
edit:complex-candidate true &display=(styled true green)' (true in green)'
edit:complex-candidate false &display=(styled false red)' (false in red)'
}
Powershell
This one is a bit tricky.
Backtick
First of all, the escape character is different in Powershell.
It uses backtick instead of backslash.
echo "`e[1;2;4;35mdim bold underlined magenta`e[0m"
Completion result
CompletionResult allows escape sequences in the ListItemText
to add color.
Function _example_completer {
[CompletionResult]::new("false", "`e[31mfalse`e[0m", [CompletionResultType]::ParameterValue, "false in red")
[CompletionResult]::new("true", "`e[32mtrue`e[0m", [CompletionResultType]::ParameterValue, "true in green")
}
Register-ArgumentCompleter -Native -CommandName 'example' -ScriptBlock (Get-Item "Function:_example_completer").ScriptBlock
By default, it uses tooltips to show the descriptions.
But the value by itself often gives no sign of what it represents.
ListItemText
Luckily, we can add the description to the ListItemText
ourselves.
Function _example_completer {
[CompletionResult]::new("false", "`e[31mfalse`e[0m (false in red)", [CompletionResultType]::ParameterValue, " ")
[CompletionResult]::new("true", "`e[32mtrue`e[0m (true in green)", [CompletionResultType]::ParameterValue, " ")
}
Register-ArgumentCompleter -Native -CommandName 'example' -ScriptBlock (Get-Item "Function:_example_completer").ScriptBlock
Tooltip must not be empty though, so we need to set it to a single space.
Selection
Fix the highlighting by setting Selection
to inverse.
Set-PSReadLineOption -Colors @{ "Selection" = "`e[7m" }
Description
And add some finishing touches to the description.
Function _example_completer {
[CompletionResult]::new("false", "`e[21;22;23;24;25;29m`e[31mfalse`e[21;22;23;24;25;29;39;49m`e[2m `e[2m(false in red)`e[21;22;23;24;25;29;39;49m`e[0m", [CompletionResultType]::ParameterValue, " ")
[CompletionResult]::new("true", "`e[21;22;23;24;25;29m`e[32mtrue`e[21;22;23;24;25;29;39;49m`e[2m `e[2m(true in green)`e[21;22;23;24;25;29;39;49m`e[0m", [CompletionResultType]::ParameterValue, " ")
}
Register-ArgumentCompleter -Native -CommandName 'example' -ScriptBlock (Get-Item "Function:_example_completer").ScriptBlock
Zsh
This one is hard.
Arrangement
First, let's have a look at how Zsh arranges values for tab completion.
- Values without a description are arranged side-by-side.
- Values with a description have it appended in the format
-- description
It is also aligned with other entries. - Values with the same description are also arranged side-by-side in front of the description.
Zstyle
Colors are set using the zstyle list-colors
.
With ${curcontext}
we can configure it for the current context during tab completion.
zstyle ":completion:${curcontext}:*" list-colors "{...}"
List Colors
It contains a colon-separated list of patterns and formats.
Formats are the semicolon-separated escape codes from ANSI escape sequences.
There is a simple and a complex way to specify the patterns.
-
=pattern=format
to apply one format. -
=(#b)(pattern1)(pattern2)=format0=format1=format2
to apply many formats.
See here for a good explanation.
Pattern
Given the value "true", three patterns are relevant.
-
=(#b)(true)=0=32
Set "true" to green (32). -
=(#b)(true)([ ]## -- *)=0=32=2
Set "true" to green (32) and the description to dim (2). -
=(#b)(-- *)=0=2
Set the description to dim for everything else.
Take this with a grain of salt, but there was an edge case in regards to the arrangement.
So it's best to set both the pattern for with and without a description for each value.
Compdef
Putting it all together.
#compdef example
function _example_completion {
zstyle ":completion:${curcontext}:*" list-colors "=(#b)(false)([ ]## -- *)=0=31=2:=(#b)(false)=0=31:=(#b)(true)([ ]## -- *)=0=32=2:=(#b)(true)=0=32:=(#b)(-- *)=0=2"
vals=('true:true in green' 'false:false in red')
_describe 'values' vals
}
compquote '' 2>/dev/null && _example_completion
compdef _example_completion example
Carapace
Now to how carapace simplifies the above.
Style
Styles are adopted from Elvish.
There are colors like style.Red
, modes like style.Dim
and style.Of
to combine them.
Action
They can be set directly with ActionStyledValues and ActionStyledValuesDescribed.
carapace.ActionStyledValues(
"true", style.Green,
"false", style.Red,
)
carapace.ActionStyledValuesDescribed(
"true", "true in green", style.Green,
"false", "false in red", style.Red,
)
Modifier
Or with the modifiers Style, StyleR and StyleF.
carapace.ActionValues(
"1",
"true",
).Style(style.Green)
carapace.ActionValues(
"0",
"false",
).StyleR(&style.Carapace.KeywordNegative)
carapace.ActionValues(
"true",
"false",
"unknown",
).StyleF(func(s string, sc style.Context) string {
switch s {
case "true":
return style.Green
case "false":
return style.Red
default:
return style.Default
}
})
Style functions
The following functions can be passed to StyleF for common highlighting tasks:
-
ForPath highlights paths using the
LS_COLORS
environment variable.
- ForPathExt does the same, but by extension only.
- ForLogLevel highlights log levels.
- ForKeyword highlights common keywords like true and false.
That's all
Enjoy the rainbow!
Top comments (0)