Manual §3 Key Binding

[ 日本語 | 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)

ble.sh ではユーザの入力操作に対する処理は全て編集関数 (widget) を実行する事によって実施されます。 各編集関数には名前があり、ble/widget/編集関数名 というシェル関数として実装されます。 個別の編集関数については後の関連する項目の中で説明します。 新しい編集関数の開発方法は "編集関数の作成" を参照して下さい。

3.3 Keymap (keymap)

キーマップとはどのキー入力 kspecs に対してどの編集関数が呼ばれるかを設定する表で、モード毎にキーマップが存在します。 各キーマップには名前が存在し、名前はCの識別子と同じ形式でなければなりません。 以下は基本的なキーマップの一覧です。

Keymap name	Description	Load hook
emacs	(Emacs 編集モード) 基底キーマップ	hook:keymap_emacs_load
vi_imap	(Vim 編集モード) 基底キーマップ (挿入モード)	hook:keymap_vi_load
vi_nmap	(Vim 編集モード) ノーマルモードのキーマップ	hook:keymap_vi_load
vi_omap	(Vim 編集モード) オペレータ待機モードのキーマップ	hook:keymap_vi_load
vi_xmap	(Vim 編集モード) ビジュアルモードのキーマップ	hook:keymap_vi_load
vi_smap	(Vim 編集モード) 選択モードのキーマップ	hook:keymap_vi_load
vi_cmap	(Vim 編集モード) コマンドモードのキーマップ	hook:keymap_vi_load
vi_digraph	(Vim 編集モード) ダイグラフ入力用のキーマップ	hook:keymap_vi_load
safe	異常時の基底キーマップ
isearch	インクリメンタルサーチのキーマップ
nsearch	非インクリメンタルサーチのキーマップ
read	ble.sh の提供する read -e のキーマップ
lastarg	insert-last-argument で用いられるキーマップ
auto_complete	自動補完で用いられるキーマップ	hook:complete_load
menu_complete	メニュー補完で用いられるキーマップ	hook:complete_load
dabbrev	動的略語展開で用いられるキーマップ	hook:complete_load

上の表でロードフックが指定されているキーマップは初期化が遅延されるため、 それらのキーマップに対する操作 (後述の ble-bind による操作) はロードフックを通じて実行する必要があります。

# 例

# Vim 編集モード初期化用のシェル関数を作ります。
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'
}

# 作成した関数を keymap_vi_load に登録(追加)します。
blehook/eval-after-load keymap_vi my-keymap-settings-for-vim-mode
# ble-0.3以前
# ble/array#push _ble_keymap_vi_load_hook my-keymap-settings-for-vim-mode

特別な kspecs として以下の物が利用できます。 これらは特別な状況で呼び出される編集関数を設定するのに使います。

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

但し、束縛がない文字が __defchar__ で処理された場合は、 その文字に対して __default__ は呼び出されません。 __before_widget__, __after_widget__ は、 これらの束縛自体によって呼び出される編集関数の前後には適用されません。

3.4 Function ble-bind

3.4.1 Bind key sequences to widgets

ble-bind [-m keymap] -f kspecs widget

キー列指定子 kspecs が入力された時に呼び出される編集関数として widget を登録します。 この事を「kspecs を widget に束縛する」と表現します。 keymap はキーマップを指定します。 省略した場合はその時の編集モードの基底キーマップに対して束縛が実行されます。

3.4.2 Bind key sequences to user-defined editing functions

ble-bind [-m keymap] -x kspecs shell-command

# 互換性: ble-0.2 以前では以下の形式で束縛します
ble-bind [-m keymap] -xf kspecs shell-command   # ble-0.2

kspecs をユーザ定義編集関数 shell-command に束縛します。 ユーザ定義編集関数は Bash の bash -x 'kseq: shell-command' で使えるものと同様に実装します。 つまり、ble.sh は READLINE_LINE に現在の編集文字列を設定し、 READLINE_POINT に現在のカーソル位置を設定して、ユーザ定義編集関数を呼び出します。 ユーザ定義編集関数の呼び出し後の READLINE_LINE と READLINE_POINT の値を用いて、 現在の編集内容を更新します。

3.4.3 Bind key sequences to commands

ble-bind [-m keymap] -c kspecs shell-command

# 互換性: ble-0.2 以前では以下の形式で束縛します
ble-bind [-m keymap] -cf kspecs shell-command   # ble-0.2

kspecs を外部コマンド shell-command に束縛します。 一旦、入力を中断して外部コマンド shell-command を呼び出し、 外部コマンドが終了した後に再び入力を再開します。

3.4.4 Bind key sequences to keyboard macros

ble-bind [-m keymap] -s kspecs keyseq

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

keyseq には Bash 組み込みの bind で使用する keyseq の形式で指定します。

3.4.5 Removing binding

ble-bind [-m keymap] [-fxc] kspecs ''
ble-bind [-m keymap] [-fxc] kspecs -

束縛を削除する場合は編集関数名・コマンド名として - または空文字列を指定します。 -f, -x, -c の何れを用いても、 束縛されている関数・コマンドの種類によらず削除を実行します。

3.4.6 Set timeouts

# タイムアウトの設定
ble-bind [-m keymap] -T kspecs timeout

# タイムアウトの削除
ble-bind [-m keymap] -T kspecs ''

指定した kspecs に対するタイムアウトを設定します。 kspecs が入力された時に未だ一意確定でなく更にその kspecs にタイムアウトが設定されている場合、 指定したタイムアウトが経過しても続きの入力がない時にその時点で kspecs を処理します。

3.4.7 Register CSI sequences of keys

これは文字の列からキーの列にデコードする時に参照される設定です。

ble-bind --csi Ft kspec
ble-bind --csi Ps~ kspec

Ft または Ps~ は CSI に引き続いて受信される文字列です。 Ft は Ft 文字 (@ - ~ の文字) 1つです。 Ps~ は Ps (整数) にチルダ ~ を繋げた文字列です。 登録されたシーケンスとそれを Function キー修飾したものを、 それぞれ kspec 及び kspec を修飾したものにデコードする様に設定します。

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

3.4.8 Register byte sequences for keys

これは文字の列からキーの列にデコードする時に参照される設定です。

ble-bind -k kspecs kspec

文字の列 kspecs をキー kspec にデコードする様に設定します。

# 例
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

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

指定した keymap に登録されている束縛を出力します。 keymap が一つも指定されていない場合は、 現在ロードされている全てのキーマップについて束縛を出力します。

3.4.10 Dump current bindings with the internal format

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

-P の代わりに -D を使用すると、内部で使用している形式で現在の束縛のデータを出力することができます。 keymap が一つ以上指定されている時、指定された keymap のデータを出力します。 keymap が一つも指定されていない時、現在ロードされている全データを出力します。

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

現在定義されている編集関数名の一覧を出力します。

3.5 Reception and interpretation of ESC

ESC を受信した直後に次のバイトが受信されずにタイムアウトした時、 その ESC は「単独で受信された」と見なされます。 それ以外の場合は「後続のバイトと一緒に受信された」と見なされます。

後続のバイトと一緒に受信された ESC は、 常に次に受信するキーのメタ修飾 (M-) として解釈されます。 単独で受信された ESC の解釈は、 後述の設定変数 decode_isolated_esc によって制御します。

タイムアウトの長さは端末からシェルまでの経路の各ステップの累積になります。 仮想端末ハンドラのタイムアウト、端末マルチプレクサーのタイムアウト、 GNU Readline のタイムアウトなどが考えられます。 それぞれのタイムアウトの設定方法は続く節を参照して下さい。 特に単独で ESC または C-[ を入力した時に端末から送信される ESC と、 Meta 修飾によって端末から送信される ESC を区別したい時は、 タイムアウトをできるだけ短く設定します。

3.5.1 Timeout of pseudo terminal handler (stty)

stty コマンドを使用して設定します。 通常は既定のタイムアウトは 0 なので設定を変更する必要はありません。 タイムアウトは以下のコマンドで変更できます。単位は 1/10 秒です。

# 例: ~/.bashrc または ~/.blerc にて

stty time 0

3.5.2 Timeout of GNU Readline (bind)

Bash 4.3 以降では、readline 変数 keyseq-timeout を用いて Readline のタイムアウトを設定できます。 ~/.bashrc で設定を行うには組み込みコマンド bind を使用します。単位はミリ秒です。

# 例: ~/.bashrc または ~/.blerc にて

bind 'set keyseq-timeout 1'

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

端末マルチプレクサ GNU Screen (screen) を利用している場合は、 screen のタイムアウトも設定する必要があります。 ~/.screenrc に以下の設定を記述することでタイムアウトを設定できます。 単位はミリ秒です。

# 例: ~/.screenrc にて

maptimeout 1

また、bindkey -t によって ESC から始まるキーシーケンスを登録している場合は、 タイムアウトが無効化される事に注意が必要です。 この時 screen は必ず後続のバイトを待つため、 ble.sh は必ず後続のバイトと一緒に ESC を受信することになります。 単独の ESC を区別して受信したい時は bindkey -t によって ESC から始まるキーシーケンスを登録するべきではありません。

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

端末マルチプレクサ tmux を利用している場合も、 同様にタイムアウトを設定する必要があります。 ~/.tmux.conf に次の設定を記述します。単位はミリ秒です。

# 例: ~/.tmux.conf にて

set -sg escape-time 1

3.5.5 Bleopt decode_isolated_esc (v0.2)

# 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 を設定して下さい。

3.6 Settings for modifyOtherKeys

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 の状態をそれぞれ設定することができます。

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