Manual §2 Graphics - akinomyoga/ble.sh GitHub Wiki

[ 日本語 | English ] ≫ Manual [§1 Intro | §2 Color | §3 Bind | §4 Edit | §5 Emacs | §6 Vim | §7 Comp | §8 Misc | Index]

2. Graphics settings

2.1 Graphics specifier (gspec)

The graphics specifier (gspec) is a string which describes a style of the graphic rendition such as highlighting, underline and other text decorations. gspec is a list of single specifiers separated by comma. 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 is 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 is 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 is 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-face

2.2.1.1 Set face

ble-face FACEPAT=[TYPE:]SPEC
ble-face -s FACEPAT [TYPE:]SPEC

# ble-0.3 or before
ble-color-setface FACE=GSPEC

This command can be used to set up graphics settings for faces specified by FACEPAT. FACEPAT can contain a wildcard character @, which matches with an arbitrary non-empty string, to set multiple faces at once. 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-face region='bg=60,fg=white'

2.2.1.2 Define new faces (v0.4)

ble-face FACE:=[TYPE:]SPEC
ble-face -d FACE [TYPE:]SPEC

New faces can be defined by users. FACE specifies the new face name. The wildcard @ cannot be used in FACE. [TYPE:]SPEC specifies the default setting. When the face is already defined, this has no effect.

2.2.1.3 Show settings of faces (v0.4)

ble-face [-u | --color[=WHEN]]... [FACEPAT...]

This command prints the current state of the specified faces. When no faces are specified, the state of all the currently-defined faces are printed. When -u option is specified, only the faces that have different values from the default are shown. The --color[=WHEN] option can be used to control the highlighting of output. When --color or --color=always is used, the output is always highlighted. When --color=never is used, the output will never be highlighted. When --color=auto is used, the output is highlighted when the standard output is a terminal device. The default behavior is --color=auto.

2.2.1.4 Reset faces (v0.4)

ble-face -r [FACEPAT...]

This resets the specified faces to the default state. When no faces are specified, all the faces will be reset.

2.3 Basic faces

In this section, basic faces are explained. Other faces are defined by modules, which are described in the corresponding sections.

2.3.1 Face region

The face for the selection.

# default
ble-face region='bg=60,fg=white'

2.3.2 Face region_target (v0.2)

The face for the affected region of the current command.

# default
ble-face region_target='bg=153,fg=black'

2.3.3 Face region_match (v0.3)

The face for the matched range of searches.

# default
ble-face region_match='bg=55,fg=white'

2.3.4 Face region_insert (v0.4)

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

# default
ble-face region_insert='fg=12,bg=252'

2.3.5 Face disabled

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

# default
ble-face disabled='fg=242'

2.3.6 Face overwrite_mode

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

# default
ble-face overwrite_mode='fg=black,bg=51'

2.3.7 Face syntax_default

The default face for the syntax highlighting.

# default
ble-face syntax_default=none

2.3.8 Face syntax_command

The default face for the commands.

# default
ble-face syntax_command='fg=brown'

2.3.9 Face syntax_quoted

The face for the content of the quotation.

# default
ble-face syntax_quoted='fg=green'

2.3.10 Face syntax_quotation

The face for the quotation marks.

# default
ble-face syntax_quotation='fg=green,bold'

2.3.11 Face syntax_escape (v0.4)

The face for the escape of the form \?.

# default
ble-face syntax_escape='fg=magenta'

2.3.12 Face syntax_expr

The face for the arithmetic expressions.

# default
ble-face syntax_expr='fg=26'

2.3.13 Face syntax_error

The face for the syntax errors.

# default
ble-face syntax_error='bg=203,fg=231'

2.3.14 Face syntax_varname

The face for the variable names.

# default
ble-face syntax_varname='fg=202'

2.3.15 Face syntax_delimiter

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

# default
ble-face syntax_delimiter=bold

2.3.16 Face syntax_param_expansion

The face for the parameter expansions.

# default
ble-face syntax_param_expansion='fg=purple'

2.3.17 Face syntax_history_expansion

The face for the history expansions.

# default
ble-face syntax_history_expansion='bg=94,fg=231'

2.3.18 Face syntax_function_name

The face for the function names in the function definition.

# default
ble-face syntax_function_name='fg=92,bold'

2.3.19 Face syntax_comment

The face for the comments.

# default
ble-face syntax_comment='fg=242'

2.3.20 Face syntax_glob (v0.2)

The face for the operators in glob patterns.

# default
ble-face syntax_glob='fg=198,bold'

2.3.21 Face syntax_brace (v0.2)

The face for the brace expansions.

# default
ble-face syntax_brace='fg=37,bold'

2.3.22 Face syntax_tilde (v0.2)

The face for the tilde expansions.

# default
ble-face syntax_tilde='fg=navy,bold'

2.3.23 Face syntax_document (v0.2)

The face for the contents of the here documents.

# default
ble-face syntax_document='fg=94'

2.3.24 Face syntax_document_begin (v0.2)

The face for the ending words of the here documents.

# default
ble-face syntax_document_begin='fg=94,bold'

2.3.25 Face command_builtin_dot

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

# default
ble-face command_builtin_dot='fg=red,bold'

2.3.26 Face command_builtin

The face for the other builtin commands in command highlighting.

# default
ble-face command_builtin='fg=red'

2.3.27 Face command_alias

The face for the aliases in command highlighting.

# default
ble-face command_alias='fg=teal'

2.3.28 Face command_function

The face for the function names in command highlighting.

# default
ble-face command_function='fg=92'

2.3.29 Face command_file

The face for the file commands in command highlighting.

# default
ble-face command_file='fg=green'

2.3.30 Face command_keyword

The face for the keywords in command highlighting.

# default
ble-face command_keyword='fg=blue'

2.3.31 Face command_jobs

The face for the job specs in command highlighting.

# default
ble-face command_jobs='fg=red'

2.3.32 Face command_directory

The face for the directory names in command highlighting.

# default
ble-face command_directory='fg=26,underline'

2.3.33 Face command_suffix (v0.4)

The face for the filenames matching suffix sabbrevs in command highlighting.

# default
ble-face command_suffix='fg=white,bg=green'

2.3.34 Face command_suffix_new (v0.4)

The face for the non-existent filenames matching suffix sabbrevs in command highlighting.

# default
ble-face command_suffix_new='fg=white,bg=green'

2.3.35 Face argument_option (v0.4)

The face for the option names such as -h and --help.

# default
ble-face argument_option='fg=teal'

2.3.36 Face argument_error (v0.4)

The face for the errors of the command-line arguments.

# default
ble-face argument_error='fg=black,bg=225

2.3.37 Face filename_directory

The face for the directory names in filename highlighting.

# default
ble-face filename_directory='underline,fg=26'

2.3.38 Face filename_directory_sticky (v0.3)

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

# default
ble-face filename_directory_sticky='underline,fg=white,bg=26'

2.3.39 Face filename_link

The face for the symbolic links in filename highlighting.

# default
ble-face filename_link='underline,fg=teal'

2.3.40 Face filename_orphan (v0.3)

The face for the dangling symbolic links in filename highlighting.

# default
ble-face filename_orphan='underline,fg=teal,bg=224'

2.3.41 Face filename_setuid (v0.3)

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

# default
ble-face filename_setuid='underline,fg=black,bg=220'

2.3.42 Face filename_setgid (v0.3)

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

# default
ble-face filename_setgid='underline,fg=black,bg=191'

2.3.43 Face filename_executable

The face for the executable files in filename highlighting

# default
ble-face filename_executable='underline,fg=green'

2.3.44 Face filename_other

The default face for the files in filename highlighting.

# default
ble-face filename_other=underline

2.3.45 Face filename_socket (v0.2)

The face for the sockets in filename highlighting.

# default
ble-face filename_socket='underline,fg=cyan,bg=black'

2.3.46 Face filename_pipe (v0.2)

The face for the named pipes in filename highlighting.

# default
ble-face filename_pipe='underline,fg=lime,bg=black'

2.3.47 Face filename_character (v0.2)

The face for the character devices in filename highlighting.

# default
ble-face filename_character='underline,fg=white,bg=black'

2.3.48 Face filename_block (v0.2)

The face for the block devices in filename highlighting.

# default
ble-face filename_block='underline,fg=yellow,bg=black'

2.3.49 Face filename_warning (v0.2)

The face for the filenames with warnings in filename highlighting.

# default
ble-face filename_warning='underline,fg=red'

2.3.50 Face filename_url (v0.4)

The face for the URLs in filename highlighting.

# default
ble-face filename_url='underline,fg=blue'

2.3.51 Face filename_ls_colors (v0.3)

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

# default
ble-face filename_ls_colors=underline

2.3.52 Face varname_unset (v0.4)

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

# default
ble-face varname_unset='fg=124'

2.3.53 Face varname_export (v0.4)

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

# default
ble-face varname_export='fg=200,bold'

2.3.54 Face varname_array (v0.4)

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

ble-face varname_array='fg=orange,bold'

2.3.55 Face varname_hash (v0.4)

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

# default
ble-face varname_hash='fg=70,bold'

2.3.56 Face varname_number (v0.4)

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

# default
ble-face varname_number='fg=64'

2.3.57 Face varname_readonly (v0.4)

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

# default
ble-face varname_readonly='fg=200'

2.3.58 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-face varname_transform='fg=29,bold'

2.3.59 Face varname_empty (v0.4)

The face for the empty variables in variable name highlighting.

# default
ble-face varname_empty='fg=31'

2.3.60 Face varname_expr (v0.4)

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

# default
ble-face varname_expr='fg=92,bold'

2.4 Settings related to layout and rendering

2.4.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.4.2 Bleopt char_width_version (Version) (v0.4)

# default
bleopt char_width_version=auto

This option specifies the Unicode version that char width determination bases on. When auto is specified, ble.sh automatically tests the behavior of the terminal on startup and try to determine the appropriate version. Supported versions are 4.1, 5.0, 5.2, 6.0, 6.1, 6.2, 6.3, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0, 12.1, 13.0, and 14.0. The default value is auto.

2.4.3 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.4.4 Bleopt emoji_version (Version) (v0.4)

# default
bleopt emoji_version=14.0

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 0.6, 0.7, 1.0, 2.0, 3.0, 4.0, 5.0, 11.0, 12.0, 12.1, 13.0, 13.1, and 14.0.

2.4.5 Bleopt emoji_opts (opts) (v0.4)

# default
bleopt emoji_opts=ri

This option specifies a colon-separated list of emoji features supported by the terminal. The field ri means Regional_Indicator. The fields tpvs and epvs mean text-presentation variation selector (TPVS/VS15/U+FE0E) and emoji-presentation variation selector (EPVS/VS16/U+FE0F), respectively. The field zwj means ZERO-WIDTH JOINER. The field unqualified means that unqualified emoji sequences are also treated as emojis. The field min=U+XXXX, where XXXX is a hexcode, means that only emojis that have codes larger or equal to XXXX are treated as emojis.

2.4.6 Bleopt grapheme_cluster (Empty/Enumerate) (v0.4)

# default
bleopt grapheme_cluster=extended

This option specifies the type of the supported grapheme cluster of the terminal. The empty string indicates that the terminal does not support the grapheme clusters. The values extended and legacy indicate that the terminal supports the extended and legacy grapheme clusters, respectively.

2.4.7 Bleopt canvas_winch_action (Enumerate) (v0.4)

# default
bleopt canvas_winch_action=redraw-here

This option controls the behavior when ble.sh receives SIGWINCH. When the value redraw-safe is specified, ble.sh redraws the new prompt starting from the line of the current cursor position. When the value redraw-prev is specified, ble.sh tries to go to the beginning of the current prompt and overwrite the current one. This is similar to the behavior of GNU Readline. This possibly erases the output of the previous command because ble.sh tries to go to the beginning of the current prompt assuming that the number of lines of the prompt does not change on the terminal resize. When the value redraw-here is specified, ble.sh tries to determine the number of lines that can be safely erased and go to the beginning of the safe lines before the redraw. This is the default behavior. In principle, this can also erase the previous outputs, but it would be supposed to be rarely happen as far as the text reflowing of the terminal behaves in a reasonable way. When the value clear is specified, the terminal content is erased and the new prompt will be drawn at the top of the terminal. The previous terminal contents including the command outputs will be lost.

2.4.8 Bleopt term_index_colors (Enumerate/Arithmetic) (v0.3)

# default (v0.4 or later)
bleopt term_index_colors=auto

# default (v0.3)
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

This option specifies the number of index colors that ble.sh uses to set foreground and background colors of terminals. When the index colors are enabled, the terminal is supposed to support the color settings with the escape sequences SGR(38;5;ColorIndex) and SGR(48;5;ColorIndex).

  • When this option has the value auto, the number of index colors are determined based on the terminfo database and the shell variable TERM on the startup of ble.sh: the result is 256 if TERM matches [xk]term*|*256color, 88 if TERM matches *88color, or otherwise the result of tput colors.
  • Otherwise the value is evaluated as an arithmetic expression.

When the result is 256, the index colors are assumed to be xterm 256-color palette (16 basic + 6x6x6 color cube + 24 gray scale). When the result is 88, the index colors are assumed to be xterm 88-color palette (16 basic + 4x4x4 color cube + 8 gray scale). When the result is 0, ble.sh will never use the index colors to set colors. When the result is other integers, the value specifies the maximum available index.

2.4.9 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.4.10 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.4.11 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.4.12 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.4.13 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.4.14 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.4.15 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.4.16 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.5 Settings related to notifications

2.5.1 Bleopt edit_bell (Colon-separated list)

The option edit_bell controls the behavior of the bell in the line editing by a colon-separated list of values. When abell, vbell, and visual are contained, the audible bells, the visible bells, and the visual bells are enabled. The audible bell sends BEL (0x07) to the terminal. The visible bell is the GNU-Screen style bell and shows the message on the terminal display. The visual bell flashes the terminal screen by turning on DECSCNM in a short moment.

The old settings edit_vbell and edit_abell for ble-0.3 should be updated to use edit_bell.

# default
bleopt edit_bell=abell # ble >= 0.4
bleopt edit_abell=1    # ble < 0.3
bleopt edit_vbell=     # ble < 0.3

# Example (disable audible bell and enable visible bell)
bleopt edit_bell=vbell

2.5.2 Bleopt vbell_default_message

This option specifies the default message of the visible bell.

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

# Example
bleopt vbell_default_message=' BEL '

2.5.3 Bleopt vbell_duration (Arithmetic)

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

# default
bleopt vbell_duration=2000

# Example
bleopt vbell_duration=3000

2.5.4 Bleopt vbell_align (Colon-separated list) (v0.3)

This option controls the position of the visible bell with a colon-separated list of values. The values left, center, and right control the horizontal position, where the default is right. When the value panel (>= v0.4) is specified, the visible bell is shown below the command line within the line-editor interface as far as the line editor is active in the current context.

# default
bleopt vbell_align=right

# Example
bleopt vbell_align=left

2.5.5 Face vbell

This face specifies the graphics setting for the visible bell.

# default
ble-face vbell=reverse

2.5.6 Face vbell_flash

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

# default
ble-face vbell_flash='reverse,fg=green'

2.5.7 Face vbell_erase

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

# default
ble-face vbell_erase='bg=252'

[ 日本語 | English ] ≫ Manual [§1 Intro | §2 Color | §3 Bind | §4 Edit | §5 Emacs | §6 Vim | §7 Comp | §8 Misc | Index]

⚠️ **GitHub.com Fallback** ⚠️