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.

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 [email protected]: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_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, 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

# 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 (after 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	N/A	Called after a command is executed
ERR	N/A	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

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 four values emacs, west, east, and auto are supported. With the value emacs, the default width in emacs is used. With west all the ambiguous characters have width 1 (Hankaku). With east all the ambiguous characters have width 2 (Zenkaku). With auto the width mode west or east 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 are, for example, emacs -nw, vim or 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 RET or C-q RET, 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]