Skip to content

Manual §3 Key Binding

Koichi Murase edited this page Jan 13, 2020 · 31 revisions

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

3. Key Binding

3.1 Key specifier (kspec) / Keyseq specifier (kspecs)

In ble.sh, received "byte sequences" are decoded into "character sequences", and then they are decoded into "key sequences". Key specifier (kspec) is a common text representation of a byte, a character or a key. The key specifier has the form with a key name (keyname) preceded by zero or more modifiers such as C- and M-. The modifiers have the form "(a character) + -". The available modifiers are listed in the following table.

Modifier spec Modifier key
S- Shift key
C- Control key
M- Meta key
A- Alter key
s- Super key
H- Hyper key

Note that Alter, Super and Hyper modifiers are usually not used because most terminals does not support them. Even if the keyboard has an alter key, usually it is treated as a Meta key by terminals.

keyname is a non-empty string composed of non-space characters that represents a character input or a key input. When keyname is a single character, it represents the input of that character. For example, C-M-- represents the input "Control + Meta + -". When keyname is a string with more than one character, it represents a special character, a control character or a function key.

The following table shows keynames for special characters.

keyname Char code keyname Char code
SP 32 (空白) DEL 127

keynames for C0 control characters are summarized in the following table. HT and CR are treated as aliases of TAB and RET, respectively. These control characters (originally received as characters) are converted to keys C-@, C-a...C-z, C-[ C-\, C-], C-^, C-_ during decoding to key sequences, so normally they cannot appear directly in key sequences.

keyname Char code keyname Char code
NUL 0 DLE 16
SOH 1 DC1 17
STX 2 DC2 18
ETX 3 DC3 19
EOT 4 DC4 20
ENQ 5 NAK 21
ACK 6 SYN 22
BEL 7 ETB 23
BS 8 CAN 24
HT, TAB 9 EM 25
LF 10 SUB 26
VT 11 ESC 27
FF 12 FS 28
CR, RET 13 GS 29
SO 14 RS 30
SI 15 US 31

keynames for C1 control characters are shown below.

keyname Char code keyname Char code
PAD 128 DCS 144
HOP 129 PU1 145
BPH 130 PU2 146
NBH 131 STS 147
IND 132 CCH 148
NEL 133 MW 149
SSA 134 SPA 150
ESA 135 EPA 151
HTS 136 SOS 152
HTJ 137 SGCI 153
VTS 138 SCI 154
PLD 139 CSI 155
PLU 140 ST 156
RI 141 OSC 157
SS2 142 PM 158
SS3 143 APC 159

keynames which represent the modifier keys themself are shown in the following table.

keyname Description
shift Shift key
control Control key
meta Meta key
alter Alter key
super Super key
hyper Hyper key

keynames which represent other function keys are listed in the following table.

keyname Description
insert Insert key
delete Delete key
home Home key
end End key
prior PageUp key
next PageDown key
up ↑ (Up) key
down ↓ (Down) key
left ← (Left) key
right → (Right) key
f1-f20 Function key
paste_begin Bracketed Paste Mode Begin
paste_end Bracketed Paste Mode End

keynames for the special keys internally used in ble.sh is shown in the following table.

keyname Description
__defchar__ (See the section of Keymap)
__default__ (See the section of Keymap)
__batch_char__ (See the section of Keymap)
__before_widget__ (See the section of Keymap)
__after_widget__ (See the section of Keymap)
__attach__ (See the section of Keymap)
__ignore__ (Internal) Already processed. Ignored later
__error__ (Internal) Unrecognized CSI sequences

Key sequence specifier (kspecs) is a string that represents a sequence of key inputs. The keyseq specifier contains one or more key specifiers (kspec) separated by spaces. For example, the kspecs "C-x C-r" means the inputs of "Control + x followed by Control + r".

3.2 Widget (widget)

In ble.sh, every user inputs are eventually handled by executing corresponding widgets. Each widget has a name and implemented as a shell function ble/widget/WidgetName where WidgetName is the name of the widget. Each widget will be explained in related sections. If you want to design your own widgets, please see also "Design widgets".

3.3 Keymap (keymap)

Keymap is a dictionary containing the mapping from a key sequence (kspecs) to a widget which should be called for that key sequence. Each mode has a corresponding keymap. Each keymap has a name which has the form of C identifier. In the following table, basic keymaps are listed.

Keymap name Description Load hook
emacs (Emacs editing mode) Base keymap hook:keymap_emacs_load
vi_imap (Vim editing mode) Base keymap (Insert mode) hook:keymap_vi_load
vi_nmap (Vim editing mode) Normal mode keymap hook:keymap_vi_load
vi_omap (Vim editing mode) Operator-pending mode keymap hook:keymap_vi_load
vi_xmap (Vim editing mode) Visual mode keymap hook:keymap_vi_load
vi_smap (Vim editing mode) Select mode keymap hook:keymap_vi_load
vi_cmap (Vim editing mode) Command-line mode keymap hook:keymap_vi_load
vi_digraph (Vim editing mode) Keymap for digraph input hook:keymap_vi_load
safe Base keymap for emergency
isearch Keymap for incremental search
nsearch Keymap for non-incremental search
read Keymap for read -e implemented by ble.sh
lastarg Keymap for insert-last-argument
auto_complete Keymap for auto-complete hook:complete_load
menu_complete Keymap for menu-complete hook:complete_load
dabbrev Keymap for dabbrev expansion hook:complete_load

The load of the keymaps for which load hooks are specified are delayed, so the modification (by ble-bind in the next section) to the keymap has to be performed through such load hooks.

# Example

# 1. Prepare a shell function to configure Vim editing mode
function my-keymap-settings-for-vim-mode {
  ble-bind -m vi_imap -f 'C-^' 'bell'
  ble-bind -m vi_omap -f 'a' 'vi-command/text-object'
}

# 2. Register the function to the hook "keymap_vi_load"
blehook/eval-after-load keymap_vi my-keymap-settings-for-vim-mode
# ble-0.3 or before
# ble/array#push _ble_keymap_vi_load_hook my-keymap-settings-for-vim-mode

The following special kspecs, which are generated for special situations, are also available.

keyname Situation in which the key is triggered
__defchar__ When ble.sh received a unbounded character input
__default__ When ble.sh received a unbounded key/character input
__batch_char__ When ble.sh received many unbounded character inputs
__before_widget__ Before a widget is called for the keymap
__after_widget__ After a widget is called for the keymap
__attach__ When the keymap becomes the base keymap

Note that when unbounded character is processed by __defchar__, __default__ will not be triggered by that character. __before_widget__ and __after_widget__ will not be generated before/after the widgets invoked through __before_widget__ and __after_widget__.

3.4 Function ble-bind

3.4.1 Bind key sequences to widgets

ble-bind [-m KEYMAP] -f KSPECS WIDGET

The function binds KSPECS to WIDGERT, i.e., registers the WIDGET as the widget to be called when the kspecs KSPECS is received. KEYMAP specifies a keymap in which the binding is registered. If KEYMAP is omitted, the base keymap for the current editing mode will be used.

3.4.2 Bind key sequences to user-defined editing functions

ble-bind [-m KEYMAP] -x KSPECS SHELL-COMMAND

# Use the following form for ble-0.2 and before
ble-bind [-m KEYMAP] -xf KSPECS SHELL-COMMAND   # ble-0.2

This binds KSPECS to a user-defined editing function SHELL-COMMAND. The user-defined editing function can be implemented just in the same way for Bash's bash -x 'kseq: SHELL-COMMAND'. ble.sh sets the current editing string to READLINE_LINE and the current cursor point (in the character numbers) to READLINE_POINT, before executing SHELL-COMMAND. The current line will be updated using READLINE_LINE and READLINE_POINT after the execution of SHELL-COMMAND

3.4.3 Bind key sequences to commands

ble-bind [-m KEYMAP] -c KSPECS SHELL-COMMAND

# Use the following form for ble-0.2 and before
ble-bind [-m KEYMAP] -cf KSPECS SHELL-COMMAND   # ble-0.2

This binds KSPECS to an external command SHELL-COMMAND. The editing is temporarily stopped, and SHELL-COMMAND is executed. After the execution, the editing is resumed with the original state.

3.4.4 Bind key sequences to keyboard macros

ble-bind [-m KEYMAP] -s KSPECS KEYSEQ

# 互換性: ble-0.3 以降で利用可能

This binds KSPECS to a keyboard macro KEYSEQ specified with the form used in the keyseq for the Bash buitin bind.

3.4.5 Removing binding

ble-bind [-m KEYMAP] [-fxc] KSPECS ''
ble-bind [-m KEYMAP] [-fxc] KSPECS -

When an empty string or - is specified as a widget or a command, the binding is removed. Regardless of the specified type of the binding -f, -x and -c, any type of the existing binding is removed.

3.4.6 Set timeouts

# Set timeout
ble-bind [-m KEYMAP] -T KSPECS TIMEOUT

# Remove timeout
ble-bind [-m KEYMAP] -T KSPECS ''

This sets a timeout for the specified KSPECS. When ble.sh receives the sequence KSPECS for which a timeout is set and the binding is not complete nor uniquely determined, if there is no subsequent inputs within the timeout, KSPECS are processed without waiting the succeeding inputs.

3.4.7 Register CSI sequences of keys

This setting is used when the character sequences are decoded into the key sequences.

ble-bind --csi Ft KSPEC
ble-bind --csi Ps~ KSPEC

Ft or Ps~ specifies a string which will be received after CSI. Ft is a Ft character (in the range @...~). Ps~ is a integer parameter Ps followed by a tilde ~. The specified CSI sequence and its variants with Function-key modifications are bound to KSPEC and its variants with modifiers, respectively.

# Example
ble-bind --csi A up
ble-bind --csi '11~' f1

3.4.8 Register byte sequences for keys

This setting is used when the character sequences are decoded into the key sequences.

ble-bind -k KSPECS KSPEC

This makes the character sequence KSPECS be decoded to a key KSPEC.

# Example
ble-bind -k 'ESC O A' up

3.4.9 Show current bindings

ble-bind [-m KEYMAP]... -P        # ≧ ble-0.3
ble-bind [-m KEYMAP]... --print   # ≧ ble-0.3

# Use the following form for ble-0.2 and before
ble-bind -d   # ≦ ble-0.2

This prints the list of bindings currently registered to the keymaps specified by -m KEYMAP. When no KEYMAP is specified, it prints the bindings for all the keymaps currently loaded.

3.4.10 Dump current bindings with the internal format

ble-bind [-m KEYMAP]... -D
ble-bind [-m KEYMAP]... --dump   # ≧ ble-0.3

When -D is used instead of -P, it prints the current bindings in the internal format. When keymaps is specified, the data for the keymaps is output. When no keymaps is specified, all the data currently loaded is output.

3.4.11 List available widgets

ble-bind -L
ble-bind --list-widgets     # ≧ ble-0.3

# 互換性: ble-0.2 以前では以下の形式で確認します
ble-bind -L
ble-bind --list-functions   # ≦ ble-0.2

This prints the list of the names of the currently available widgets.

3.5 Reception and interpretation of ESC

When ble.sh received ESC, the ESC is regarded as "isolated ESC" if the next byte is not arrived within the timeout, or otherwise it is regarded as "modifier ESC".

The modifier ESC is always treated as the Meta modifier to the next key, i.e., M-. The treatment of the isolated ESC is determined by the bleopt setting decode_isolated_esc described later.

The effective timeout is the accumulation of timeouts in each step of the route from the terminal to the shell. The possible timeouts include the timeouts of pseudo-terminal handler, terminal multiplexer, and GNU Readline. The setting of each timeout is described in the subsequent sections. If you want to distinguish the direct key input of ESC or C-[ from ESC generated by the Meta key, the timeout should be as short as possible but not zero.

3.5.1 Timeout of pseudo terminal handler (stty)

The command stty can be used to configure the timeout of pseudo-terminal handler. Normally the timeout is 0 by default, so the special setting is not needed. The timeout can be changed by the following command. The unit is 1/10 second.

# Example: in ~/.bashrc or ~/.blerc

stty time 0

3.5.2 Timeout of GNU Readline (bind)

In Bash 4.3 and later, a readline variable keyseq-timeout is available for setting the timeout of Readline. To configure in ~/.bashrc, the builtin command bind can be used as follows. The unit is millisecond.

# Example: in ~/.bashrc or ~/.blerc

bind 'set keyseq-timeout 1'

3.5.3 Time out of the terminal multiplexer GNU Screen (~/.screenrc)

When the terminal multiplexer GNU Screen (screen) is in use, the timeout of screen should also be configured properly. The timeout can be specified in ~/.screenrc as follows. The unit is millisecond.

# Example: in ~/.screenrc

maptimeout 1

Note that the timeout is disabled when there are GNU Screen's bindings for the sequence starting from ESC with Screen's command bindkey -t. In this case screen always wait the subsequent byte without timeouts, so ble.sh receives ESC always accompanied by the next byte. If you want to distinguish "isolated ESC" from "modifier ESC", please avoid to use Screen's command bindkey -t for the key sequences starting from ESC.

3.5.4 Timeout of the terminal multiplexter tmux (~/.tmux.conf)

When the terminal multiplexer tmax is in use, the timeout should be configured as well. The following setting can be added in ~/.tmux.conf. The unit is millisecond.

# Example: in ~/.tmux.conf

set -sg escape-time 1

3.5.5 Bleopt decode_isolated_esc (v0.2)

# default
bleopt decode_isolated_esc=auto

When the value is esc, an isolated ESC is treated as C-[. When the value is meta, an isolated ESC is treated as the Meta modifier to the next key. When the value is auto, an isolated ESC is treated as C-[ if there are no pending key inputs waiting the next key and also the current keymap has a binding for C-[. Otherwise the isolated ESC is treated as the Meta modifier.

If your keyboard does not have the Meta modifier key or you want to input Meta modifier by pressing ESC by hand, the setting meta is useful. If you want to distinguish the Meta modifier by the Meta key and directly input ESC or C-[, the setting esc or auto is useful.

3.6 Settings for modifyOtherKeys

ble.sh では様々なキー操作を区別する為に、 端末の modifyOtherKeys 機能を操作します。 端末が対応している場合、modifyOtherKeys には3つの状態があります。 状態 0 は通常の状態で、様々なキー入力はそのまま端末から送信されます。 状態 1 は修飾キーと一緒に通常の文字を入力した時に、 修飾が判別できるように特別なシーケンスとして端末から送信されます。 状態 2RET キーや TAB キーも含めて、 全ての入力が修飾の状態を持った特別なシーケンスとして端末から送信されます。 ble.sh は端末の modifyOtherKeys を変更するために制御シーケンスを端末に送信します。 状態 0 にする時は CSI > 4 m を、 状態 1 にする時は CSI > 4 ; 1 m を、 状態 2 にする時は CSI > 4 ; 2 m を送信します。

以下に説明する設定変数を用いて、ble.sh がキー入力を待つ時の modifyOtherKeys の状態と、 それ以外 (コマンド実行時など) の modifyOtherKeys の状態をそれぞれ設定することができます。

3.6.1 Bleopt term_modifyOtherKeys_internal (v0.3)

# default
bleopt term_modifyOtherKeys_internal=auto

ble.sh がキー入力を待つ状態に入る時に、端末の modifyOtherKeys をどう変更するかを設定します。 この設定変数に 0 または 1 または 2 が設定されている場合、その状態に変更します。 この設定変数に auto が設定されている場合、 端末の DA2 応答が 1; で始まっている場合を除いて状態 2 にします。 DA2 応答が 1; で始まっている場合は、 制御シーケンスに対応していない libvte の可能性があるので状態を変更しません (制御シーケンスは送りません)。 それ以外の値が設定されている場合、状態を変更しません (制御シーケンスは送りません)。

3.6.2 Bleopt term_modifyOtherKeys_external (v0.3)

# default
bleopt term_modifyOtherKeys_external=auto

コマンド実行時など ble.sh 以外がキー入力を受け取る可能性がある状態に入る時に、 端末の modifyOtherKeys をどう変更するかを設定します。 この設定変数に 0 または 1 または 2 が設定されている場合、その状態に変更します。 端末の modifyOtherKeys をその状態に変更します。 この設定変数に auto が設定されている場合、 term_modifyOtherKeys_internal と同様に、 端末の DA2 応答が 1; で始まっている場合を除いて状態 1 にします。 それ以外の値が設定されている場合、状態を変更しません (制御シーケンスは送りません)。

3.6.3 Settings for terminals without modifyOtherKeys feature

ble.sh can be used without problems even if your terminal does not support modifyOtherKeys.

However, there will be restrictions of the terminal that a special key combination, such as C-1, C-S-a, S-TAB and C-RET, cannot be sent from the terminal. If the terminal allows the configuration of escape sequences for each key combination, please configura so that the key combination sends an escape sequence of the form ESC [ code ; mod u, where code is the integer that represents Unicode of the character in decimal number, and mod is "1 + (the sum of the values of modifiers)" in decimal numbers. The value of each modifier is summarized below.

Modifier Value
S- 1
M- 2
C- 4
s- 8
H- 16
A- 32

Here is examples of escape sequences.

Key combination Escape sequences Key combination Escape sequences
S-RET ESC [ 1 3 ; 2 u C-0 ESC [ 4 8 ; 5 u
C-RET ESC [ 1 3 ; 5 u C-1 ESC [ 4 9 ; 5 u
C-S-RET ESC [ 1 3 ; 6 u C-2 ESC [ 5 0 ; 5 u
S-TAB ESC [ 9 ; 2 u C-3 ESC [ 5 1 ; 5 u
C-TAB ESC [ 9 ; 5 u C-4 ESC [ 5 2 ; 5 u
C-S-TAB ESC [ 9 ; 6 u C-5 ESC [ 5 3 ; 5 u
S-SP ESC [ 3 2 ; 2 u C-6 ESC [ 5 4 ; 5 u
C-S-SP ESC [ 3 2 ; 6 u C-7 ESC [ 5 5 ; 5 u
S-BS ESC [ 8 ; 2 u C-8 ESC [ 5 6 ; 5 u
C-S-BS ESC [ 8 ; 6 u C-9 ESC [ 5 7 ; 5 u
C-S-a ESC [ 9 7 ; 6 u C-S-z ESC [ 1 2 2 ; 6 u

3.7 Input settings

3.7.1 Bleopt decode_abort_char (Integer) (v0.3)

# default
bleopt decode_abort_char=28

この変数は大量の入力を処理している時にそれを中断する為に使う入力のバイト値を指定します。 既定で C-\ に対応する 28 が設定されています。

3.7.2 Bleopt decode_error_char_abell (空/非空)

# default
bleopt decode_error_char_abell=     # ble-0.2以降
bleopt error_char_abell=            # ble-0.1

この設定変数に非空文字列が設定されている場合、 不正に符号化された文字を受け取った時にベルを鳴らします (BEL を送信します)。

3.7.3 Bleopt decode_error_char_vbell (Empty/Non-empty)

# default
bleopt decode_error_char_vbell=1    # ble-0.2以降
bleopt error_char_vbell=1           # ble-0.1

この設定変数に非空文字列が設定されている場合、 不正に符号化された文字を受け取った時にビジュアルベルを表示します。

3.7.4 Bleopt decode_error_char_discard (Empty/Non-empty)

# default
bleopt decode_error_char_discard=   # ble-0.2以降
bleopt error_char_discard=          # ble-0.1

この設定変数に非空文字列が設定されている場合、 不正に符号化された文字を受信した文字の列から除去します。 空文字列が設定されている場合は、 エラーを無視して復元された文字を続く処理に渡します。

3.7.5 Bleopt decode_error_cseq_abell (Empty/Non-empty) (v0.3)

# default
bleopt decode_error_cseq_abell=

この設定変数に非空文字列が設定されている場合、 認識できない CSI シーケンスを受け取った時にベルを鳴らします (BEL を送信します)。

3.7.6 Bleopt decode_error_cseq_vbell (Empty/Non-empty) (v0.3)

# default
bleopt decode_error_cseq_vbell=1

この設定変数に非空文字列が設定されている場合、 認識できない CSI シーケンスを受け取った時にビジュアルベルを表示します。

3.7.7 Bleopt decode_error_cseq_discard (Empty/Non-empty) (v0.3)

# default
bleopt decode_error_cseq_discard=

この設定変数に非空文字列が設定されている場合、 認識できない CSI シーケンスを無視します。 空文字列が設定されている場合は、 改めて CSI シーケンスを構成する一つ一つの文字を解釈します。

3.7.8 Bleopt decode_error_kseq_abell (Empty/Non-empty)

# default
bleopt decode_error_kseq_abell=1    # ble-0.2以降
bleopt error_kseq_abell=1           # ble-0.1

この設定変数に非空文字列が設定されている場合、 受信したキー列に対応する束縛が存在しない時にベルを鳴らします (BEL を送信します)。

3.7.9 Bleopt decode_error_kseq_vbell (Empty/Non-empty)

# default
bleopt decode_error_kseq_vbell=1    # ble-0.2以降
bleopt error_kseq_vbell=1           # ble-0.1

この設定変数に非空文字列が設定されている場合、 受信したキー列に対応する束縛が存在しない時にビジュアルベルを表示します。

3.7.10 Bleopt decode_error_kseq_discard (Empty/Non-empty)

# default
bleopt decode_error_kseq_discard=1  # ble-0.2以降
bleopt error_kseq_discard=1         # ble-0.1

この設定変数に非空文字列が設定されている場合、 受信したキー列に対応する束縛が存在しない時にそれまで読み取った全てのキーを廃棄します。 空文字列が設定されている場合は、 最初のキーだけを除去して2つ目以降のキーから再解釈します。

3.7.11 Bleopt default_keymap

# default
bleopt default_keymap=auto

この設定変数は既定の編集モードを設定します。 値 auto は、Bash の編集モードに応じて切り替えることを意味します。 Bash が Emacs 編集モード (set -o emacs 既定) の時、ble.sh の Emacs 編集モードが有効になります。 Bash が Vi 編集モード (set -o vi) の時、ble.sh の Vim 編集モードが有効になります。 値 emacs を指定した時は、Bash の編集モードによらずに、常に ble.sh の Emacs 編集モードを使用します。 値 vi を指定した時は、常に ble.sh の Vim 編集モードを使用します。


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

Clone this wiki locally