Manual §2 Graphics

2. Graphics settings

2.1 Graphics specifier (gspec)

The graphics specifier (gspec) is a string which describes the style of graphic rendition such as highlighting, underline and other text decorations. gspec is a list of single specifiers separated by commas. A single specifier has one of the following forms.

Specifier	Attribute
`bold`	Bold (high intensity in some terminals)
`underline`	Underline
`blink`	Blink (low intensity foreground or high intensity background in some terminals)
`invis`	Invisible characters
`reverse`	Reversed video (exchange foreground and background in some terminals)
`strike`	Strike line
`italic`	Italic shape
`standout`	Emphasize. This is synonym for `bold,reverse`
`fg=name`	Set foreground color, where `name` specifies the color as described next
`bg=name`	Set background color, where `name` specifies the color as described next
`none`	No attribute (preceding attributes are ignored)

The following color names can be specified for name in the above table.

Color name	Color	Color name	Color
`default`	Default	`transparent`	Default
`black`	Black (low intensity)	`gray`	Black (high intensity)
`brown`	Red (low intensity)	`red`	Red (high intensity)
`green`	Green (low intensity)	`lime`	Green (high intensity)
`olive`	Yellow (low intensity)	`yellow`	Yellow (high intensity)
`navy`	Blue (low intensity)	`blue`	Blue (high intensity)
`purple`	Magenta (low intensity)	`magenta`	Magenta (high intensity)
`teal`	Cyan (low intensity)	`cyan`	Cyan (high intensity)
`silver`	White (low intensity)	`white`	White (high intensity)
`orange`	Orange

The color name can also be specified by the following form based on color spaces.

Color name	Color space	Arguments
`I`	256 index color	I is an integer in the range 0-255 (16 basic colors + 6x6x6 RGB cube + 24 grayscale)
`#RGB`	RGB	R, G and B are 1 digit hexadecimal numbers
`#RRGGBB`	RGB	RR, GG and BB are 2 digit hexadecimal numbers
`rgb:R/G/B`	RGB	each of R, G and B are an integer in the range 0-255 or a percentile in the range 0%-100%
`cmy:C/M/Y`	CMY	each of C, M and Y are an integer in the range 0-255 or a percentile in the range 0%-100%
`cmyk:C/M/Y/K`	CMYK	each of C, M, Y and K are a decimal number in the range 0-255 or a percentile in the range 0%-100%
`hsl:H/S%/L%`	HSL	H is an integer (with modulo 360), and S and L are integers in the range 0-100
`hsb:H/S%/B%`	HSB, HSV	H is an integer (with modulo 360), and S and B are integers in the range 0-100

For example, gspec bg=black,fg=white,bold,underline reprensents a graphic rendition of "underlined white bold characters on the black background".

Terminal capabilities

To correctly render the styles such as italic, blink, strike, etc., your terminal (and terminal multiplexer if any) needs to support the feature. If you want to use the feature, you can find another terminal that supports it or consult with the developer of the terminal.

If you are using tmux, you need to set the tmux option default-terminal (i.e., the default value for the environment variable TERM) to tmux-256color or xterm-256color. you can put the following line in .tmux.conf to enable all the feature:

# .tmux.conf

# Option 1: set default TERM as tmux-256color
set-option -g default-terminal tmux-256color

# Option 2: set default TERM as xterm-256color
set-option -g default-terminal xterm-256color

2.2 Face (face)

A face (face) is a named graphic setting for which a gspec can be assigned. Various faces are used in ble.sh to draw various texts with syntax highlighting, etc.

2.2.1 Function `ble-color-setface`^†

2.2.1.1 Set face

ble-color-setface face_name [type:]spec

This command can be used to specify a graphics setting for face_name. The prefix type, which is available in ble-0.4 or later, can be used to select the type of the graphics specification.

`type`	`spec`
`gspec` (default)	Set graphics setting specified by graphics specifier gspec
`g`	Set graphics setting specified by integer value gvalue
`ref`	Create reference to a face specified by its name or index
`copy`	Copy a graphics setting from a face specified by its name or index
`sgrspec`	Set graphics setting specified by SGR parameters
`ansi`	Construct graphics setting from ANSI Escape sequences

# Example

ble-color-setface region bg=60,fg=white

2.2.1.2 List faces (v0.4)

ble-color-setface

When ble-color-setface is called without arguments, a list of the currently available faces is printed.

2.2.2 Face `region`^†

The face for the selection.

# default
ble-color-setface region bg=60,fg=white

2.2.3 Face `region_target` (v0.2)^†

The face for the affected region of the current command.

# default
ble-color-setface region_target bg=153,fg=black

2.2.4 Face `region_match` (v0.3)^†

The face for the matched range of searches.

# default
ble-color-setface region_match bg=55,fg=white

2.2.5 Face `region_insert` (v0.4)^†

The face for the temporarily inserted texts for dabbrev and menu-completion.

# default
ble-color-setface region_insert fg=12,bg=252

2.2.6 Face `disabled`^†

The face for the inactive or suspended texts such as cancelled commands.

# default
ble-color-setface disabled fg=242

2.2.7 Face `overwrite_mode`^†

The face for the character which will be overwritten by the next input.

# default
ble-color-setface overwrite_mode fg=black,bg=51

2.2.8 Face `syntax_default`^†

The default face for the syntax highlighting.

# default
ble-color-setface syntax_default none

2.2.9 Face `syntax_command`^†

The default face for the commands.

# default
ble-color-setface syntax_command fg=brown

2.2.10 Face `syntax_quoted`^†

The face for the content of the quotation.

# default
ble-color-setface syntax_quoted fg=green

2.2.11 Face `syntax_quotation`^†

The face for the quotation marks.

# default
ble-color-setface syntax_quotation fg=green,bold

2.2.12 Face `syntax_expr`^†

The face for the arithmetic expressions.

# default
ble-color-setface syntax_expr fg=26

2.2.13 Face `syntax_error`^†

The face for the syntax errors.

# default
ble-color-setface syntax_error bg=203,fg=231

2.2.14 Face `syntax_varname`^†

The face for the variable names.

# default
ble-color-setface syntax_varname fg=202

2.2.15 Face `syntax_delimiter`^†

The face for the delimiters such as ;, &, pipes and redirections.

# default
ble-color-setface syntax_delimiter bold

2.2.16 Face `syntax_param_expansion`^†

The face for the parameter expansions.

# default
ble-color-setface syntax_param_expansion fg=purple

2.2.17 Face `syntax_history_expansion`^†

The face for the history expansions.

# default
ble-color-setface syntax_history_expansion bg=94,fg=231

2.2.18 Face `syntax_function_name`^†

The face for the function names in the function definition.

# default
ble-color-setface syntax_function_name fg=92,bold

2.2.19 Face `syntax_comment`^†

The face for the comments.

# default
ble-color-setface syntax_comment fg=242

2.2.20 Face `syntax_glob` (v0.2)^†

The face for the operators in glob patterns.

# default
ble-color-setface syntax_glob fg=198,bold

2.2.21 Face `syntax_brace` (v0.2)^†

The face for the brace expansions.

# default
ble-color-setface syntax_brace fg=37,bold

2.2.22 Face `syntax_tilde` (v0.2)^†

The face for the tilde expansions.

# default
ble-color-setface syntax_tilde fg=navy,bold

2.2.23 Face `syntax_document` (v0.2)^†

The face for the contents of the here documents.

# default
ble-color-setface syntax_document fg=94

2.2.24 Face `syntax_document_begin` (v0.2)^†

The face for the ending words of the here documents.

# default
ble-color-setface syntax_document_begin fg=94,bold

2.2.25 Face `command_builtin_dot`^†

The face for the builtin command . (dot) in command highlighting.

# default
ble-color-setface command_builtin_dot fg=red,bold

2.2.26 Face `command_builtin`^†

The face for the other builtin commands in command highlighting.

# default
ble-color-setface command_builtin fg=red

2.2.27 Face `command_alias`^†

The face for the aliases in command highlighting.

# default
ble-color-setface command_alias fg=teal

2.2.28 Face `command_function`^†

The face for the function names in command highlighting.

# default
ble-color-setface command_function fg=92

2.2.29 Face `command_file`^†

The face for the file commands in command highlighting.

# default
ble-color-setface command_file fg=green

2.2.30 Face `command_keyword`^†

The face for the keywords in command highlighting.

# default
ble-color-setface command_keyword fg=blue

2.2.31 Face `command_jobs`^†

The face for the job specs in command highlighting.

# default
ble-color-setface command_jobs fg=red

2.2.32 Face `command_directory`^†

The face for the directory names in command highlighting.

# default
ble-color-setface command_directory fg=26,underline

2.2.33 Face `filename_directory`^†

The face for the directory names in filename highlighting.

# default
ble-color-setface filename_directory underline,fg=26

2.2.34 Face `filename_directory_sticky` (v0.3)^†

The face for the directory with sticky bits in filename highlighting.

# default
ble-color-setface filename_directory_sticky underline,fg=white,bg=26

2.2.35 Face `filename_link`^†

The face for the symbolic links in filename highlighting.

# default
ble-color-setface filename_link underline,fg=teal

2.2.36 Face `filename_orphan` (v0.3)^†

The face for the dangling symbolic links in filename highlighting.

# default
ble-color-setface filename_orphan           underline,fg=teal,bg=224

2.2.37 Face `filename_setuid` (v0.3)^†

The face for the files with the setuid bit in filename highlighting.

# default
ble-color-setface filename_setuid           underline,fg=black,bg=220

2.2.38 Face `filename_setgid` (v0.3)^†

The face for the files with the segid bit in filename highlighting.

# default
ble-color-setface filename_setgid           underline,fg=black,bg=191

2.2.39 Face `filename_executable`^†

The face for the executable files in filename highlighting

# default
ble-color-setface filename_executable underline,fg=green

2.2.40 Face `filename_other`^†

The default face for the files in filename highlighting.

# default
ble-color-setface filename_other underline

2.2.41 Face `filename_socket` (v0.2)^†

The face for the sockets in filename highlighting.

# default
ble-color-setface filename_socket underline,fg=cyan,bg=black

2.2.42 Face `filename_pipe` (v0.2)^†

The face for the named pipes in filename highlighting.

# default
ble-color-setface filename_pipe underline,fg=lime,bg=black

2.2.43 Face `filename_character` (v0.2)^†

The face for the character devices in filename highlighting.

# default
ble-color-setface filename_character underline,fg=white,bg=black

2.2.44 Face `filename_block` (v0.2)^†

The face for the block devices in filename highlighting.

# default
ble-color-setface filename_block underline,fg=yellow,bg=black

2.2.45 Face `filename_warning` (v0.2)^†

The face for the filenames with warnings in filename highlighting.

# default
ble-color-setface filename_warning underline,fg=red

2.2.46 Face `filename_url` (v0.4)^†

The face for the URLs in filename highlighting.

# default
ble-color-setface filename_url underline,fg=blue

2.2.47 Face `filename_ls_colors` (v0.3)^†

The additional graphic attributes for the bleopt variable filename_ls_colors in filename highlighting.

# default
ble-color-setface filename_ls_colors underline

2.2.48 Face `varname_unset` (v0.4)^†

The face for the unset variable names in variable name highlighting.

# default
ble-color-setface varname_unset fg=124

2.2.49 Face `varname_export` (v0.4)^†

The face for the environment variables (with attribute -x) in variable name highlighting.

# default
ble-color-setface varname_export fg=200,bold

2.2.50 Face `varname_array` (v0.4)^†

The face for the array names (with attribute -a) in variable name highlighting.

ble-color-setface varname_array fg=orange,bold

2.2.51 Face `varname_hash` (v0.4)^†

The face for the hash table names (with attribute -A) in variable name highlighting.

# default
ble-color-setface varname_hash fg=70,bold

2.2.52 Face `varname_number` (v0.4)^†

The face for the integer variables (with attribute -i) in variable name highlighting.

# default
ble-color-setface varname_number fg=64

2.2.53 Face `varname_readonly` (v0.4)^†

The face for the readonly variables (with attribute -r) in variable name highlighting.

# default
ble-color-setface varname_readonly fg=200

2.2.54 Face `varname_transform` (v0.4)^†

The face for the variables with uppercase attribute (-u), lowercase attribute (-l) or capitalization attribute (-c) in variable name highlighting.

# default
ble-color-setface varname_transform fg=29,bold

2.2.55 Face `varname_empty` (v0.4)^†

The face for the empty variables in variable name highlighting.

# default
ble-color-setface varname_empty fg=31

2.2.56 Face `varname_expr` (v0.4)^†

The face for the variables names in arithmetic expressions whose contents are arithmetic expressions.

# default
ble-color-setface varname_expr fg=92,bold

2.3 Settings related to layout and rendering

2.3.1 Bleopt `tab_width` (Empty/Integer) (v0.2)^†

# default
bleopt tab_width=

This option sets the displayed width of tabs on the screen. When the empty value is specified, the default value from terminfo tput it is used.

2.3.2 Bleopt `emoji_width` (Empty/Integer) (v0.2)^†

# default
bleopt emoji_width=2

This option sets the displayed width of emoji on your terminal. If the value is empty, the default width based on Unicode East_Asian_Width property is used. The value should be set in accordance of the behavior of your terminal because this value is used to calculate the coordinates and layouts in ble.sh.

2.3.3 Bleopt `emoji_version` (Version) (v0.4)^†

# default
bleopt emoji_version=13.1

This options sets the version of Unicode Emoji to specify the set of emoji code points. Since the set of emoji depends on the Emoji verion, the Emoji version that your terminal supports needs to be specified. Currently available values are 1.0, 2.0, 3.0, 4.0, 5.0, 11.0, 12.0, 12.1, 13.0, and 13.1.

2.3.4 Bleopt `term_index_colors` (Arithmetic) (v0.3)^†

# default
bleopt term_index_colors='256'   # If TERM == [xk]term*|*256color on loading ble.sh
bleopt term_index_colors='88'    # If TERM == *88color            on loading ble.sh
bleopt term_index_colors=        # Otherwise

When this option has an integer value, the terminal is assumed to support the color settings with the escape sequences SGR(38;5;ColorIndex) and SGR(48;5;ColorIndex). The value specifies the number of available colors. When this option is empty or 0, the terminal is considered not to support the color specification by the color index. The default value is set by a guess based on TERM.

2.3.5 Bleopt `term_true_colors` (Empty/colon/semicolon) (v0.4)^†

# default
bleopt term_true_colors=semicolon

The value semicolon implies that the terminal supports the color setting with the escape sequences of the form SGR(38;2;R;G;B). The value colon implies that the terminal supports the form SGR(38:2:R:G:B). The empty value implies that the terminal does not support 24 bit color specification. In this case, ble.sh reduces colors to represent it with the closest colors in 256, 88, 16 or 8 colors based on the terminal color support. The default value is semicolon. The 24 bit colors are not reduced (if any 24 bit colors are specified for faces).

2.3.6 Bleopt `filename_ls_colors` (v0.3)^†

# default
bleopt filename_ls_colors=

With this option, the filename highlighting can be configured with LS_COLORS format.

# Example
bleopt filename_ls_colors="$LS_COLORS"

The value is a colon-separated list of specifiers of the form key=value. SGR parameters can be specified to value. The following table summarizes the supported key, and corresponding faces overwritten by this setting. When filename_ls_colors contains these settings, the setting of the corresponding face is overridden and ignored. Only the pattern of the form *.ext is supported for filename patterns. If the filename matches with several patterns, such as *.tar.gz and *.gz, the longer specification is selected. Unrecognized key is just ignored.

key	Corresponding face
`di`	`filename_directory`
`st`	`filename_directory_sticky`
`ln`	`filename_link`
`or`	`filename_orphan`
`fi`	`filename_other`
`su`	`filename_setuid`
`sg`	`filename_setgid`
`ex`	`filename_executable`
`cd`	`filename_characater`
`pi`	`filename_pipe`
`so`	`filename_socket`
`bd`	`filename_block`
`.`ext*	`filename_other` (files which have the extension ext)

2.3.7 Bleopt `highlight_syntax` (Empty/Non-empty) (v0.4)^†

# default
bleopt highlight_syntax=1

When a non-empty value is set, highlighting based on shell syntax is activated.

2.3.8 Bleopt `highlight_filename` (Empty/Non-empty) (v0.4)^†

# default
bleopt highlight_filename=1

When a non-empty value is set, highlighting based on the filename and command name is enabled as a part of the syntax highlighting. The syntax highlighting needs to be activated by bleopt highlight_syntax.

2.3.9 Bleopt `highlight_variable` (Empty/Non-empty) (v0.4)^†

# default
bleopt highlight_variable=1

When a non-empty value is set, highlighting based on the variable type is enabled as a part of the syntax highlighting. The syntax highlighting needs to be activated by bleopt highlight_syntax.

2.3.10 Bleopt `highlight_timeout_sync` (Arithmetic/Empty) (v0.4)^†

# default
bleopt highlight_timeout_sync=500

This setting controls the timeout for the pathname expansions performed in the foreground syntax highlighting. When the word contains a glob pattern that takes a long time to evaluate the pathname expansion, the foreground syntax highlighting based on the filename is deferred to the background syntax highlighting based on this setting. The value specifies the timeout duration in milliseconds. When the value is empty, the timeout is disabled.

2.3.11 Bleopt `highlight_timeout_async` (Arithmetic/Empty) (v0.4)^†

# default
bleopt highlight_timeout_async=5000

This setting controls the timeout for the pathname expansions performed in the background syntax highlighting. When the word contains a glob pattern that takes a long time to evaluate the pathname expansion, the background syntax highlighting based on the filename is canceled based on this setting. The value specifies the timeout duration in milliseconds. When the value is empty, the timeout is disabled.

2.3.12 Bleopt `syntax_eval_polling_interval` (Arithmetic/Empty) (v0.4)^†

# default
bleopt syntax_eval_polling_interval=50

This setting controls the interval of the user-input checking for the user-input cancellation of the pathname expansions for the syntax highlighting. The value specifies the interval in milliseconds. When the value is empty, the interval 100 is used.

2.4 Settings related to notifications

2.4.1 Bleopt `edit_abell` (Empty/Non-empty)^†

The options edit_abell and edit_vbell control the behavior of the widget bell. When edit_abell has a non-empty value, the audible bell is enabled, i.e., the control character BEL (0x07) is sent to standard error. Defaultly the audible bell is enabled. The audible bell can be disabled by the following example.

# default
bleopt edit_abell=1

# Example (disable audible bell)
bleopt edit_abell=

2.4.2 Bleopt `edit_vbell` (Empty/Non-empty)^†

When this option has a non-empty value, the visual bell is enabled. Defaultly the visual bell is disabled.

# default
bleopt edit_vbell=

# Example (enable visual bell)
bleopt edit_vbell=1

2.4.3 Bleopt `vbell_default_message`^†

This option specifies the default message of the visual bell.

# default
bleopt vbell_default_message=' Wuff, -- Wuff!! '

# Example
bleopt vbell_default_message=' BEL '

2.4.4 Bleopt `vbell_duration` (Arithmetic)^†

This option specifies the time duration of showing the visual bell. The unit is millisecond.

# default
bleopt vbell_duration=2000

# Example
bleopt vbell_duration=3000

2.4.5 Bleopt `vbell_align` (v0.3)^†

This option controls the position of the visual bell. The value is one of left, center and right.

# default
bleopt vbell_duration=right

# Example
bleopt vbell_duration=left

2.4.6 Face `vbell`^†

This face specifies the graphics setting for the visual bell.

# default
ble-color-setface vbell reverse

2.4.7 Face `vbell_flash`^†

This face specifies the initial graphics setting for the visual bell.

# default
ble-color-setface vbell_flash reverse,fg=green

2.4.8 Face `vbell_erase`^†

This face specifies the graphics setting to erase the visual bell.

# default
ble-color-setface vbell_erase bg=252

ble.sh Wiki Home

Manual / 説明書

Appendix

Index / 索引

Devel / 開発資料

Design widgets / 編集関数の作成

Manual §2 Graphics

2. Graphics settings

2.1 Graphics specifier (gspec)

Terminal capabilities

2.2 Face (face)

2.2.1 Function ble-color-setface†

2.2.1.1 Set face

2.2.1.2 List faces (v0.4)

2.2.2 Face region†

2.2.3 Face region_target (v0.2)†

2.2.4 Face region_match (v0.3)†

2.2.5 Face region_insert (v0.4)†

2.2.6 Face disabled†

2.2.7 Face overwrite_mode†

2.2.8 Face syntax_default†

2.2.9 Face syntax_command†

2.2.10 Face syntax_quoted†

2.2.11 Face syntax_quotation†

2.2.12 Face syntax_expr†

2.2.13 Face syntax_error†

2.2.14 Face syntax_varname†

2.2.15 Face syntax_delimiter†

2.2.16 Face syntax_param_expansion†

2.2.17 Face syntax_history_expansion†

2.2.18 Face syntax_function_name†

2.2.19 Face syntax_comment†

2.2.20 Face syntax_glob (v0.2)†

2.2.21 Face syntax_brace (v0.2)†

2.2.22 Face syntax_tilde (v0.2)†

2.2.23 Face syntax_document (v0.2)†

2.2.24 Face syntax_document_begin (v0.2)†

2.2.25 Face command_builtin_dot†

2.2.26 Face command_builtin†

2.2.27 Face command_alias†

2.2.28 Face command_function†

2.2.29 Face command_file†

2.2.30 Face command_keyword†

2.2.31 Face command_jobs†

2.2.32 Face command_directory†

2.2.33 Face filename_directory†

2.2.34 Face filename_directory_sticky (v0.3)†

2.2.35 Face filename_link†

2.2.36 Face filename_orphan (v0.3)†

2.2.37 Face filename_setuid (v0.3)†

2.2.38 Face filename_setgid (v0.3)†

2.2.39 Face filename_executable†

2.2.40 Face filename_other†

2.2.41 Face filename_socket (v0.2)†

2.2.42 Face filename_pipe (v0.2)†

2.2.43 Face filename_character (v0.2)†

2.2.44 Face filename_block (v0.2)†

2.2.45 Face filename_warning (v0.2)†

2.2.46 Face filename_url (v0.4)†

2.2.47 Face filename_ls_colors (v0.3)†

2.2.48 Face varname_unset (v0.4)†

2.2.49 Face varname_export (v0.4)†

2.2.50 Face varname_array (v0.4)†

2.2.51 Face varname_hash (v0.4)†

2.2.52 Face varname_number (v0.4)†

2.2.53 Face varname_readonly (v0.4)†

2.2.54 Face varname_transform (v0.4)†

2.2.55 Face varname_empty (v0.4)†

2.2.56 Face varname_expr (v0.4)†