Manual §1 Introduction

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

1. Introduction to ble.sh

ble.sh - Bash Line Editor (version 0.4)

ble.sh is a line editor written in pure Bash scripts as a Bash configuration which can be sourced from .bashrc. This replaces the default line editor of Bash, GNU Readline, to provide various features.

• Syntax highlighting: Highlight command lines input by users as in fish and zsh-syntax-highlighting. Unlike the simple highlighting in zsh-syntax-highlighting, ble.sh performs syntactic analysis to enable the correct highlighting of complex structures such as nested command substitutions, multiple here documents, etc.
• Enhanced completion: Support syntax-aware completion, completion with quotes and parameter expansions in prefix texts, ambiguous candidate generation, etc. Also menu-complete supports selection of candidates in menu (candidate list) by cursor keys, TAB and S-TAB. The feature auto-complete supports the automatic suggestion of completed texts as in fish and zsh-autosuggestions (with Bash 4.0+). The feature menu-filter integrates automatic filtering of candidates into menu completion (with Bash 4.0+). There are other functionalities such as dabbrev and sabbrev like zsh-abbreviations.
• Vim editing mode: Enhance readline's vi editing mode available with set -o vi. Vim editing mode supports various vim modes such as char/line/block visual/select mode, replace mode, command mode, operator pending mode as well as insert mode and normal mode. Vim editing mode supports various operators, text objects, registers, keyboard macros, marks, etc. It also provides vim-surround as an option.

1.1 Install & Update

The ble.sh is available from the repository on GitHub under 3-Clause BSD License. In the following description, please replace $HOME/.local/share/blesh with the directory path you like to install the blesh. You can also install ble.sh from AUR in Arch Linux.

Option 1: When you do not have GitHub account, or have not registered SSH public keys

Requirements: git, GNU make and GNU awk

git clone --recursive https://github.com/akinomyoga/ble.sh.git
cd ble.sh
make
make INSDIR="$HOME/.local/share/blesh" install

Option 2: When you have registered SSH public keys to your GitHub account

Requirements: git, GNU make and GNU awk

git clone --recursive git@github.com:akinomyoga/ble.sh.git
cd ble.sh
make
make INSDIR="$HOME/.local/share/blesh" install

Option 3: Use curl to get generated ble.sh v0.3 (the release version)

Requirements: curl, xz and GNU tar

curl -LO https://github.com/akinomyoga/ble.sh/releases/download/v0.3.2/ble-0.3.1.tar.xz
tar xJf ble-0.3.1.tar.xz
cp -r ble-0.3.1 "$HOME/.local/share/blesh"

Option 4: Use wget to get generate ble.sh v0.3 (the latest release)

Requirements: wget, xz and GNU tar

wget https://github.com/akinomyoga/ble.sh/releases/download/v0.3.2/ble-0.3.1.tar.xz
tar xJf ble-0.3.1.tar.xz
cp -r ble-0.3.1 "$HOME/.local/share/blesh"

Update

Requirements: git, GNU make and GNU awk

In the session with ble.sh loaded, please run the command ble-update (for ble-0.3 and later).

ble-update   # ble-0.3+

Or, if you have already the clone of the git repository, you can update ble.sh by the following commands.

cd ble.sh   # Enter the directory of the repository of ble.sh
git pull
git submodule update --recursive --remote
make
make INSDIR="$HOME/.local/share/blesh" install

1.2 Set up ble.sh in ~/.bashrc

This is an example of settings. Add the settings lines in ~/.bashrc.

# bashrc

# Write the following line near the top of .bashrc
[[ $- == *i* ]] &&
  source "$HOME/.local/share/blesh/ble.sh" --rcfile "$HOME/.blerc"

# Normal settings can be placed in between.

# Write the following line at the bottom of .bashrc
[[ ${BLE_VERSION-} ]] && ble-attach

# Note: In ble-0.2 or before, use the following instead:
#((_ble_bash)) && ble-attach

The settings for ble.sh can be written in the file ~/.blerc or ~/.config/blesh/init.sh. For example, you can put the setting commands as follows. The file ~/.blerc is sourced as a Bash script, so common commands and control statements such as if, while, function, etc., can be used in ~/.bashrc.

# blerc (Example)

bleopt char_width_mode=east
bleopt input_encoding=UTF-8
bleopt edit_abell=1
bleopt edit_vbell= vbell_default_message=' Wuff, -- Wuff!! ' vbell_duration=2000

1.2.1 Function bleopt [name[=value|:=value]...] ―Set bleopt variables―^†

This function shows or changes the current setting variables (bleopt variables). When this function is called without arguments, it prints a list of the bleopt variables. When an argument of the form name=value is provided, it sets value to the existing bleopt variable name. If the bleopt variable name does not exist, the command fails. If an invalid value is specified to value, the command fails. When an argument of the form name:=value is provided, it sets value to the bleopt variable name after creating the new variable if needed. When an argument of the form name is provided, it prints the current setting of the bleopt variable name. If the bleopt variable name does not exist, the command fails.

Some basic bleopt variables are described in the next section 1.3. The other bleopt variables are described in related sections.

1.2.2 Function blehook [hook_name+=shell-command] (v0.4) ―Set hooks―^†

This function registers a handler to the specified hook. When no argument is provided, the list of the current hooks and handlers are printed.

# Register handler
blehook hook_name+=shell-command

# Delete handler
blehook hook_name-=shell-command

# Register handler if not registered
blehook hook_name!=shell-command

# Remove duplicates and append the handler
blehook hook_name-+=shell-command

# Remove duplicates and prepend the handler
blehook hook_name+-=shell-command

# Overwrite handler (remove existing handlers)
blehook hook_name=shell-command

# List hooks and handlers
blehook

ble.sh provides the following basic hooks.

Hook name	Argument	Description
PRECMD	N/A	Called before updating prompt (immediately before execution of PROMPT_COMMAND)
ADDHISTORY	command	Called when a command is added to the command history. If the handler fails the command will not be added to the history.
PREEXEC	command	Called before a command is executed
POSTEXEC	command	Called after a command is executed
ERREXEC	command	Called after a command is executed if the command failed
CHPWD	N/A	Called after a command is executed if the current directory has been changed
EXIT	N/A	Called before Bash exits
ATTACH	N/A	Before ble.sh attaches
DETACH	N/A	After ble.sh detached

In the hooks PRECMD, PREEXEC, POSTEXEC, and ERREXEC, the array BLE_PIPESTATUS, which contains the value of PIPESTATUS for the previous command, is available.

[ Note: ERR has been renamed to ERREXEC in ble-0.4-devel3 (2022-08-22). ]

For example, if one wants to cancel the addition of the current command in the command history, ADDHISTORY hook may be configured in the following way:

# blerc

function my/addhistory.hook {
  local command=$1 pattern='<some pattern>'     # <-- Here, <some pattern> is an exclude glob pattern for the command
  [[ $command != $pattern ]]
}
blehook ADDHISTORY=my/addhistory.hook

If one wants to register a transformed command instead of the real command that has been executed, one can cancel the addition and instead manually add a history entry:

# blerc

function my/addhistory.hook {
  local command=$1
  history -s "$(transform "$command")"      # <-- Manually registers a string, where "transform" is an appropriate command to transform the command
  return 1                                  # <-- Always cancels the automatic registration
}
blehook ADDHISTORY=my/addhistory.hook

1.3 Basic settings

1.3.1 Bleopt char_width_mode ―East_Asian_Width―^†

# default

bleopt char_width_mode=auto # ble-0.3 and later
bleopt char_width_mode=east # ble-0.2 and before

The option char_width_mode controls the width of the Unicode characters with East_Asian_Width=A (Ambiguous characters). Currently five values west, east, musl, emacs and auto are supported. With west all the ambiguous characters have width 1 (Hankaku). With east all the ambiguous characters have width 2 (Zenkaku). With the value emacs, the default width in Emacs is used. With the value musl, the table for wcwidth of musl C library in 2014 is used [Note: recent versions of musl library is more conforming to Unicode so favor west or east]. With auto the width mode, the mode is automatically chosen based on the terminal behavior. The default value is auto. Appropriate value should be chosen in accordance with your terminal behavior. For example, the value can be changed to west as

bleopt char_width_mode='west'

1.3.2 Bleopt input_encoding ―Character encoding―^†

The option input_encoding controls the encoding scheme used in the decode of input. Currently UTF-8 and C are available. With the value C, byte values are directly interpreted as character codes. The default value is UTF-8. For example, the value can be changed to C as:

bleopt input_encoding='C'

1.3.3 Bleopt pager (v0.2)^†

# default
bleopt pager=

This option specifies the pager which is used when ble.sh show some information. When this value is empty, the value of the shell variable PAGER is used. When PAGER is empty as well, ble.sh tries to use the commands less, pager, more and cat in order.

1.3.4 Bleopt editor (v0.4)^†

# default
bleopt editor=

The option specifies the editor used for the widget edit-and-execute (C-x C-e) and editor for bleopt line_limit_type=editor. Possible values include, for example, emacs -nw, vim and nano. When this value is empty, the value of the shell variable VISUAL is used. When VISUAL is also empty, the value of the shell variable EDITOR is used. When EDITOR is also empty, commands emacs -nw, vim or nano are selected if available. If nothing is available, vi will be tried.

1.4 Tips

1.4.1 Multiline mode

When the command line string contains a newline character, ble.sh enters the MULTILINE mode.

By typing C-v C-j or C-q C-j, you can insert a newline character in the command line string. In the MULTILINE mode, RET (C-m) causes insertion of a new newline character. In the MULTILINE mode, the command can be executed by typing C-j.

When the shell option shopt -s cmdhist is set (which is the default), RET (C-m) inserts a newline if the current command line string is syntactically incomplete.

1.4.2 Vim editing mode

ble.sh has two editing modes, Emacs editing mode (default) and Vim editing mode, like GNU Readline. If set -o vi is specified in .bashrc (or in .blerc), or set editing-mode vi is specified in .inputrc, the vim mode is enabled. For details, please check the Wiki page.

---

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