-
-
Notifications
You must be signed in to change notification settings - Fork 85
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" of user inputs 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 (space) | 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 themselves 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-modeThe 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 WIDGETThe function binds KSPECS to WIDGET,
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.2This 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.2This 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 builtin 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~ KSPECFt 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~' f1This setting is used when the character sequences are decoded into the key sequences.
ble-bind -k KSPECS KSPECThis makes the character sequence KSPECS be decoded to a key KSPEC.
# Example
ble-bind -k 'ESC O A' upble-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.2This 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.3When -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.2This prints the list of the names of the currently available widgets.
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.
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 0In 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'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 1Note 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.
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# default
bleopt decode_isolated_esc=autoWhen 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.
ble.sh uses the terminal feature modifyOtherKeys
to distinguish various key board inputs by users.
When the terminal supports this feature, modifyOtherKeys have three states.
The state 0 is the normal state in which the key inputs are sent to the terminal with the simplest modifications.
The state 1 is the one in which the escape sequence of normal character keys are modified by modifier keys
to allow terminal applications distinguish them.
The state 2 allows every inputs including RET key and TAB key
have distinguishable escape sequences with modifications by modifier keys.
ble.sh sends control sequences to attempt to change the terminal's modifyOtherKeys state.
The control sequences CSI > 4 m, CSI > 4 ; 1 m and CSI > 4 ; 2 m
are sent to turn the state to 0, 1 and 2, respectively.
The following options can be used to configure the modifyOtherKeys state
when ble.sh is waiting user inputs and when it is in another states.
# default
bleopt term_modifyOtherKeys_internal=autoThis setting controls how the terminal's modifyOtherKeys is updated
on entering the mode in which ble.sh waits the user inputs.
When the value is 0, 1 or 2, the state will be changed to the corresponding states, respectively.
When the value is auto, the terminal's DA2 response doesn't start with 1;, the state will be changed to 2.
If the terminal's DA2 response starts with 1;,
the terminal is possibly libvte which have bugs in parsing control sequences,
so no control sequences are sent for modifyOtherKeys.
When other values are set, no control sequences are sent.
# default
bleopt term_modifyOtherKeys_external=autoThis setting controls how the terminal's modifyOtherKeys is updated
when exiting the mode in which ble.sh waits the user inputs.
When the value is 0, 1 or 2, the state will be changed to the corresponding states, respectively.
When the value is auto, just like the case of term_modifyOtherKeys_internal
the state will be changed to 1 when the terminal's DA2 response doesn't start with 1;.
When other values are set, no control sequences are sent.
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 configure 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=28This setting specifies a byte code which can be used to cancel the processing of the massive inputs.
The default value is 28 which corresponds to C-\
# default
bleopt decode_error_char_abell= # ble-0.2以降
bleopt error_char_abell= # ble-0.1When this setting has a non-empty value, the audible bell is used to notify the reception of incorrectly encoded characters. Specifically it sends a control character BEL.
# default
bleopt decode_error_char_vbell=1 # ble-0.2以降
bleopt error_char_vbell=1 # ble-0.1When this setting has a non-empty value, a visual bell is used to notify the reception of incorrectly encoded characters.
# default
bleopt decode_error_char_discard= # ble-0.2以降
bleopt error_char_discard= # ble-0.1When this setting has a non-empty value, incorrectly encoded characters are removed from the character sequences. When this setting has the empty value, the incorrectly encoded characters are passed to the subsequent processes by ignoring the error.
# default
bleopt decode_error_cseq_abell=When this has a non-empty value, unrecognized CSI sequences trigger the audible bell.
# default
bleopt decode_error_cseq_vbell=1When this has a non-empty value, unrecognized CSI sequences trigger the visual bell.
# default
bleopt decode_error_cseq_discard=When this has a non-empty value, the entire unrecognized CSI sequences is ignored. When this has the empty value, the bytes consisting the CSI sequences are processed separately.
# default
bleopt decode_error_kseq_abell=1 # ble-0.2以降
bleopt error_kseq_abell=1 # ble-0.1When this has a non-empty value, the audible bell is used to notify that there are no binding corresponding to the received key sequences.
# default
bleopt decode_error_kseq_vbell=1 # ble-0.2以降
bleopt error_kseq_vbell=1 # ble-0.1When this has a non-empty value, the visual bell is used to notify that there are no binding corresponding to the received key sequences.
# default
bleopt decode_error_kseq_discard=1 # ble-0.2以降
bleopt error_kseq_discard=1 # ble-0.1When this has a non-empty value, the entire key sequence is discarded if there are no binding corresponding to the received key sequences. When this has the empty value, the first key is discarded, and the subsequent keys are used to search the next matching key sequences.
# default
bleopt default_keymap=autoThis setting controls the default editing mode.
The value auto means that the editing mode follows the Bash's editing mode.
When Bash is in Emacs editing mode (set -o emacs, default), Emacs editing mode of ble.sh is enabled.
When Bash is in Vi editing mode (set -o vi), Vim editing mode of ble.sh is enabled.
When the value emacs is set, Emacs editing mode of ble.sh is always used regardless of the state of Bash's editing mode.
When the value vi is set, Vim editing mode of ble.sh is always used.
[ 日本語 | English ] ≫ Manual [§1 Intro | §2 Color | §3 Bind | §4 Edit | §5 Emacs | §6 Vim | §7 Comp | §8 Misc