-
-
Notifications
You must be signed in to change notification settings - Fork 110
Manual §3 Key Binding
[ 日本語 | English ] ≫ Manual [§1 Intro | §2 Color | §3 Bind | §4 Edit | §5 Emacs | §6 Vim | §7 Comp | §8 Misc
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
".
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".
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__.
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.
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
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.
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
.
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.
# 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.
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
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
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.
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.
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.
ESC を受信した直後に次のバイトが受信されずにタイムアウトした時、 その ESC は「単独で受信された」と見なされます。 それ以外の場合は「後続のバイトと一緒に受信された」と見なされます。
後続のバイトと一緒に受信された ESC は、
常に次に受信するキーのメタ修飾 (M-) として解釈されます。
単独で受信された ESC の解釈は、
後述の設定変数 decode_isolated_esc
によって制御します。
タイムアウトの長さは端末からシェルまでの経路の各ステップの累積になります。 仮想端末ハンドラのタイムアウト、端末マルチプレクサーのタイムアウト、 GNU Readline のタイムアウトなどが考えられます。 それぞれのタイムアウトの設定方法は続く節を参照して下さい。 特に単独で ESC または C-[ を入力した時に端末から送信される ESC と、 Meta 修飾によって端末から送信される ESC を区別したい時は、 タイムアウトをできるだけ短く設定します。
stty
コマンドを使用して設定します。
通常は既定のタイムアウトは 0
なので設定を変更する必要はありません。
タイムアウトは以下のコマンドで変更できます。単位は 1/10 秒です。
# 例: ~/.bashrc または ~/.blerc にて
stty time 0
Bash 4.3 以降では、readline 変数 keyseq-timeout
を用いて Readline のタイムアウトを設定できます。
~/.bashrc
で設定を行うには組み込みコマンド bind
を使用します。単位はミリ秒です。
# 例: ~/.bashrc または ~/.blerc にて
bind 'set keyseq-timeout 1'
端末マルチプレクサ GNU Screen (screen
) を利用している場合は、
screen
のタイムアウトも設定する必要があります。
~/.screenrc
に以下の設定を記述することでタイムアウトを設定できます。
単位はミリ秒です。
# 例: ~/.screenrc にて
maptimeout 1
また、bindkey -t
によって ESC から始まるキーシーケンスを登録している場合は、
タイムアウトが無効化される事に注意が必要です。
この時 screen
は必ず後続のバイトを待つため、
ble.sh
は必ず後続のバイトと一緒に ESC を受信することになります。
単独の ESC を区別して受信したい時は bindkey -t
によって
ESC から始まるキーシーケンスを登録するべきではありません。
端末マルチプレクサ tmux
を利用している場合も、
同様にタイムアウトを設定する必要があります。
~/.tmux.conf
に次の設定を記述します。単位はミリ秒です。
# 例: ~/.tmux.conf にて
set -sg escape-time 1
# default
bleopt decode_isolated_esc=auto
この設定変数に esc
が設定されている場合、
単独で受信した ESC を C-[ として解釈します。
meta
が設定されている場合、
単独で受信した ESC は次に受信するキーの Meta 修飾 (M-) として解釈します。
auto
が設定されている場合、
現在有効なキー列の途中ではなくかつ現在のキーマップで C-[ が束縛されている時に
単独で受信した ESC を C-[ として解釈し、それ以外の時に Meta 修飾 M- として解釈します。
キーボードに Meta 修飾キーがなく ESC に続けてキーを入力することで
Meta 修飾の代わりとしているユーザは meta
を設定して下さい。
Meta 修飾キーを押しながら入力したキーと
ESC または C-[ を単独で入力した時で振る舞いを変えたいユーザは esc
を設定して下さい。
ble.sh
では様々なキー操作を区別する為に、
端末の modifyOtherKeys
機能を操作します。
端末が対応している場合、modifyOtherKeys
には3つの状態があります。
状態 0
は通常の状態で、様々なキー入力はそのまま端末から送信されます。
状態 1
は修飾キーと一緒に通常の文字を入力した時に、
修飾が判別できるように特別なシーケンスとして端末から送信されます。
状態 2
は RET キーや TAB キーも含めて、
全ての入力が修飾の状態を持った特別なシーケンスとして端末から送信されます。
ble.sh
は端末の modifyOtherKeys
を変更するために制御シーケンスを端末に送信します。
状態 0
にする時は CSI > 4 m を、
状態 1
にする時は CSI > 4 ; 1 m を、
状態 2
にする時は CSI > 4 ; 2 m を送信します。
以下に説明する設定変数を用いて、ble.sh
がキー入力を待つ時の modifyOtherKeys
の状態と、
それ以外 (コマンド実行時など) の modifyOtherKeys
の状態をそれぞれ設定することができます。
# default
bleopt term_modifyOtherKeys_internal=auto
ble.sh
がキー入力を待つ状態に入る時に、端末の modifyOtherKeys
をどう変更するかを設定します。
この設定変数に 0
または 1
または 2
が設定されている場合、その状態に変更します。
この設定変数に auto
が設定されている場合、
端末の DA2 応答が 1;
で始まっている場合を除いて状態 2
にします。
DA2 応答が 1;
で始まっている場合は、
制御シーケンスに対応していない libvte
の可能性があるので状態を変更しません (制御シーケンスは送りません)。
それ以外の値が設定されている場合、状態を変更しません (制御シーケンスは送りません)。
# default
bleopt term_modifyOtherKeys_external=auto
コマンド実行時など ble.sh
以外がキー入力を受け取る可能性がある状態に入る時に、
端末の modifyOtherKeys
をどう変更するかを設定します。
この設定変数に 0
または 1
または 2
が設定されている場合、その状態に変更します。
端末の modifyOtherKeys
をその状態に変更します。
この設定変数に auto
が設定されている場合、
term_modifyOtherKeys_internal
と同様に、
端末の DA2 応答が 1;
で始まっている場合を除いて状態 1
にします。
それ以外の値が設定されている場合、状態を変更しません (制御シーケンスは送りません)。
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 |
# default
bleopt decode_abort_char=28
この変数は大量の入力を処理している時にそれを中断する為に使う入力のバイト値を指定します。
既定で C-\ に対応する 28
が設定されています。
# default
bleopt decode_error_char_abell= # ble-0.2以降
bleopt error_char_abell= # ble-0.1
この設定変数に非空文字列が設定されている場合、 不正に符号化された文字を受け取った時にベルを鳴らします (BEL を送信します)。
# default
bleopt decode_error_char_vbell=1 # ble-0.2以降
bleopt error_char_vbell=1 # ble-0.1
この設定変数に非空文字列が設定されている場合、 不正に符号化された文字を受け取った時にビジュアルベルを表示します。
# default
bleopt decode_error_char_discard= # ble-0.2以降
bleopt error_char_discard= # ble-0.1
この設定変数に非空文字列が設定されている場合、 不正に符号化された文字を受信した文字の列から除去します。 空文字列が設定されている場合は、 エラーを無視して復元された文字を続く処理に渡します。
# default
bleopt decode_error_cseq_abell=
この設定変数に非空文字列が設定されている場合、 認識できない CSI シーケンスを受け取った時にベルを鳴らします (BEL を送信します)。
# default
bleopt decode_error_cseq_vbell=1
この設定変数に非空文字列が設定されている場合、 認識できない CSI シーケンスを受け取った時にビジュアルベルを表示します。
# default
bleopt decode_error_cseq_discard=
この設定変数に非空文字列が設定されている場合、 認識できない CSI シーケンスを無視します。 空文字列が設定されている場合は、 改めて CSI シーケンスを構成する一つ一つの文字を解釈します。
# default
bleopt decode_error_kseq_abell=1 # ble-0.2以降
bleopt error_kseq_abell=1 # ble-0.1
この設定変数に非空文字列が設定されている場合、 受信したキー列に対応する束縛が存在しない時にベルを鳴らします (BEL を送信します)。
# default
bleopt decode_error_kseq_vbell=1 # ble-0.2以降
bleopt error_kseq_vbell=1 # ble-0.1
この設定変数に非空文字列が設定されている場合、 受信したキー列に対応する束縛が存在しない時にビジュアルベルを表示します。
# default
bleopt decode_error_kseq_discard=1 # ble-0.2以降
bleopt error_kseq_discard=1 # ble-0.1
この設定変数に非空文字列が設定されている場合、 受信したキー列に対応する束縛が存在しない時にそれまで読み取った全てのキーを廃棄します。 空文字列が設定されている場合は、 最初のキーだけを除去して2つ目以降のキーから再解釈します。
# 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