[ Languages: English | 日本語 (Japanese) ]
[ README | Manual |
Q&A |
contrib
|
Recipes ]
Bash Line Editor (ble.sh
) is a command line editor written in pure Bash which replaces the default GNU Readline.
The current devel version is 0.4.
This script supports Bash 3.0 or higher although we recommend using ble.sh
with release versions of Bash 4.0 or higher.
Currently, only UTF-8
encoding is supported for non-ASCII characters.
This script is provided under the BSD License (3-clause BSD license).
Disclaimer: The core part of the line editor is written in pure Bash, but
ble.sh
relies on POSIX stty
to set up TTY states before and after the execution of user commands.
It also uses other POSIX utilities for acceleration
in some parts of initialization and cleanup code,
processing of large data in completions, pasting large data, etc.
Pronunciation: The easiest pronunciation of ble.sh
that users use is /blɛʃ/, but you can pronounce it as you like.
I do not specify the canonical way of pronouncing ble.sh
.
In fact, I personally call it simply /biːɛliː/ or verbosely read it as /biːɛliː dɑt ɛseɪtʃ/ in my head.
To use ble.sh
, Bash 3.0+ and POSIX standard utilities are required.
There are two ways to get ble.sh
: to download and build ble.sh
using git
, or to download the nightly build using curl
or wget
.
For the detailed descriptions, see Sec 1.1 and Sec 1.2 for trial/installation,
and Sec 1.3 for the setup of your ~/.bashrc
.
Note
If you want to use fzf with ble.sh
, you need to check Sec
2.8.
Download and generate ble.sh
using git
This requires the commands git
, make
(GNU make), and gawk
(GNU awk).
In the following, please replace make
with gmake
if your system provides GNU make as gmake
(such as in BSD).
# TRIAL without installation
git clone --recursive --depth 1 --shallow-submodules https://github.com/akinomyoga/ble.sh.git
make -C ble.sh
source ble.sh/out/ble.sh
# Quick INSTALL to BASHRC (If this doesn't work, please follow Sec 1.3)
git clone --recursive --depth 1 --shallow-submodules https://github.com/akinomyoga/ble.sh.git
make -C ble.sh install PREFIX=~/.local
echo 'source ~/.local/share/blesh/ble.sh' >> ~/.bashrc
The build process integrates multiple Bash script files into a single Bash script ble.sh
with pre-processing,
places other module files in appropriate places, and strips code comments for a shorter initialization time.
Note: This does not involve any C/C++/Fortran compilations and generating binaries, so C/C++/Fortran compilers are not needed.
Some people seem to believe that one always needs to use make
with C/C++/Fortran compilers to generate binaries.
They complain about ble.sh
's make process, but it comes from the lack of knowledge on the general principle of make
.
You may find C/C++ programs in the repository, but they are used to update the Unicode character table from the Unicode database when a new Unicode standard appears.
The generated table is included in the repository:
canvas.GraphemeClusterBreak.sh
,
canvas.c2w.musl.sh
,
canvas.c2w.sh
,
and canvas.emoji.sh
,
so there is no need to run these C/C++ programs in the build process.
Another C file is used as an adapter in an old system MSYS1,
which is used with an old compiler toolchain in Windows, but it will never be used in Unix-like systems.
Each file used in the build process is explained in make/README.md
.
Download the nightly build with curl
This requires the commands curl
, tar
(with the support for the J
flag), and xz
(XZ Utils).
# TRIAL without installation
curl -L https://github.com/akinomyoga/ble.sh/releases/download/nightly/ble-nightly.tar.xz | tar xJf -
source ble-nightly/ble.sh
# Quick INSTALL to BASHRC (If this doesn't work, please follow Sec 1.3)
curl -L https://github.com/akinomyoga/ble.sh/releases/download/nightly/ble-nightly.tar.xz | tar xJf -
bash ble-nightly/ble.sh --install ~/.local/share
echo 'source ~/.local/share/blesh/ble.sh' >> ~/.bashrc
After the installation, the directory ble-nightly
can be removed.
Download the nightly build with wget
This requires the commands wget
, tar
(with the support for the J
flag), and xz
(XZ Utils).
# TRIAL without installation
wget -O - https://github.com/akinomyoga/ble.sh/releases/download/nightly/ble-nightly.tar.xz | tar xJf -
source ble-nightly/ble.sh
# Quick INSTALL to BASHRC (If this doesn't work, please follow Sec 1.3)
wget -O - https://github.com/akinomyoga/ble.sh/releases/download/nightly/ble-nightly.tar.xz | tar xJf -
bash ble-nightly/ble.sh --install ~/.local/share
echo 'source ~/.local/share/blesh/ble.sh' >> ~/.bashrc
After the installation, the directory ble-nightly
can be removed.
Install a package using a package manager (currently only a few packages)
This only requires the corresponding package manager.
- AUR (Arch Linux)
blesh-git
(devel),blesh
(stable 0.3.4) - NixOS (nixpkgs)
blesh
(devel) - Guix
blesh
(devel)
Update an existing copy of ble.sh
# UPDATE (in a ble.sh session)
ble-update
# UPDATE (outside ble.sh sessions)
bash /path/to/ble.sh --update
Create a package of ble.sh
Since ble.sh
is just a set of shell scripts and do not contain any binary (i.e., "noarch
"),
you may just download the pre-built tarball from release pages and put the extracted contents in e.g. /tmp/blesh-package/usr/local
.
Nevertheless, if you need to build the package from the source, please use the following commands.
Note that the git repository (.git
) is required for the build.
# BUILD & PACKAGE (for package maintainers)
git clone --recursive https://github.com/akinomyoga/ble.sh.git
make -C ble.sh install DESTDIR=/tmp/blesh-package PREFIX=/usr/local
When you would like to tell ble.sh
the way to update the package for ble-update
,
you can place _package.bash
at ${prefix}/share/blesh/lib/_package.bash
.
The file _package.bash
is supposed to define a shell variable and a shell function
as illustrated in the following example (please replace XXX
with the package management system):
# ${prefix}/share/blesh/lib/_package.bash
_ble_base_package_type=XXX
function ble/base/package:XXX/update {
update-the-package-in-a-proper-way
return 0
}
When the shell function returns exit status 0, it means that the update has been successfully done, and the reload of ble.sh
will be automatically happen.
When the shell function returns exit status 6, the timestamp of ble.sh
is checked, and the reload of ble.sh
only happens when ble.sh
is actually update.
When the shell function returns exit status 125, the default ble.sh
update procedure is attempted.
Otherwise, the updating procedure is canceled, where any message explaining situation should be output by the shell function.
An example _package.bash
for AUR
can be found here.
- Syntax highlighting: Highlight command lines input by users as in
fish
andzsh-syntax-highlighting
. Unlike the simple highlighting inzsh-syntax-highlighting
,ble.sh
performs syntactic analysis to enable the correct highlighting of complex structures such as nested command substitutions, multiple here documents, etc. Highlighting colors and styles are fully configurable. - Enhanced completion:
Extend completion
by syntax-aware completion, completion with quotes and parameter expansions in prefix texts, ambiguous candidate generation, etc.
Also, menu-complete
supports the selection of candidates in the menu (candidate list) by cursor keys, TAB, and S-TAB.
The feature auto-complete
supports the automatic suggestion of completed texts as in
fish
andzsh-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 orzsh-abbr
. - Vim editing mode: Enhance
readline
's vi editing mode available withset -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 providesvim-surround
as an option. - Other interesting features include status line, history share, right prompt, transient prompt, xterm title, etc.
Note: ble.sh does not provide specific settings of the prompt, aliases, functions, etc.
ble.sh provides a more fundamental infrastructure so that users can set up their own prompt, aliases, functions, etc.
Of course ble.sh can be used in combination with other Bash configurations such as bash-it
and oh-my-bash
.
Demo (version 0.2)
My little experiment took place in one corner of my bashrc
at the end of May 2013 after I enjoyed an article on zsh-syntax-highlighting
.
I initially thought something could be achieved by writing a few hundred lines of code
but soon realized that everything needs to be re-implemented for the authentic support of syntax highlighting in Bash.
I decided to make it as an independent script ble.sh
.
The name stemmed from that of Zsh's line editor, ZLE (Zsh Line Editor), but suffixed with .sh
for the implication of being written in a shell script.
I'm occasionally asked about the pronunciation of ble.sh
, but you can pronounce it as you like.
After the two-week experiment, I was satisfied with my conclusion that it is possible to implement a full-featured line editor in Bash that satisfies the actual daily uses.
The real efforts to improve the prototype implementation for real uses started in February 2015.
I released the initial version in the next December. Until then, the basic part of the line editor was completed.
The implementation of vim mode was started in September 2017 and completed in the next March.
I started working on the enhancement of the completion in August 2018 and released it in the next February.
- 2013-06 v0.0 -- prototype
- 2015-12 v0.1 -- Syntax highlighting [v0.1.15]
- 2018-03 v0.2 -- Vim mode [v0.2.7]
- 2019-02 v0.3 -- Enhanced completion [v0.3.4]
- 20xx-xx v0.4 (plan) -- programmable highlighting [nightly build]
- 20xx-xx v0.5 (plan) -- TUI configuration
- 20xx-xx v0.6 (plan) -- error diagnostics?
There are some limitations due to the way ble.sh
is implemented.
Also, some user configurations or other Bash frameworks may conflict with ble.sh.
For example,
- By default,
ble.sh
does not setPIPESTATUS
for the previous command line because it adds extra execution costs. Instead, the arrayBLE_PIPESTATUS
contains the values ofPIPESTATUS
of the previous command line. If you need to access the values directly through the variablePIPESTATUS
, please set the optionbleopt exec_restore_pipestatus=1
. - By default,
ble.sh
assumes thatPROMPT_COMMAND
andPRECMD
hooks do not change the cursor position and the layout in the terminal display to offer smooth rendering. If you have settings that output texts or changes the cursor position inPROMPT_COMMAND
andPRECMD
, please set the optionbleopt prompt_command_changes_layout=1
. ble.sh
assumes that common variable names and environment variables (such asLC_*
) are not used for the global readonly variables. In Bash, global readonly variables take effect in any scope including the local scope of the function, which means that we cannot even define a local variable that has the same name as a global readonly variable. This is not the problem specific toble.sh
, but any Bash framework may suffer from the global readonly variables. It is generally not recommended to define global readonly variables in Bash except for the security reasoning (Refs. [1], [2], [3]). Also,ble.sh
overrides the builtinreadonly
with a shell function to prevent it from making global variables readonly. It allows only uppercase global variables and_*
to become readonly except_ble_*
,__ble_*
, and some special uppercase variables.ble.sh
overrides Bash's built-in commands (trap
,readonly
,bind
,history
,read
, andexit
) with shell functions to adjust the behavior of each built-in command and prevent them from interfering withble.sh
. If the user or another framework directly calls the original builtins throughbuiltin BUILTIN
, or if the user or another framework replaces the shell functions, the behavior is undefined.- The shell and terminal settings for the line editor and the command execution
are different.
ble.sh
adjusts them for the line editor and try to restore the settings for the command execution. However, there are settings that cannot be restored or are intentionally not restored for various reasons. Some of them are summarlized on a wiki page.
1.1 Try ble.sh
generated from source (version ble-0.4 devel)†
To generate ble.sh
, gawk
(GNU awk) and gmake
(GNU make) (in addition to Bash and POSIX standard utilities) are required.
The file ble.sh
can be generated using the following commands.
If you have GNU make installed on gmake
, please use gmake
instead of make
.
git clone --recursive https://github.com/akinomyoga/ble.sh.git
cd ble.sh
make
A script file ble.sh
will be generated in the directory ble.sh/out
.
Then, you can load ble.sh
in the Bash session using the source
command:
source out/ble.sh
To install ble.sh
in a specified directory, use make install
.
# INSTALL to ~/.local/share/blesh
make install
# INSTALL to a specified directory
make install INSDIR=/path/to/blesh
# PACKAGE (for package maintainers)
make install DESTDIR=/tmp/blesh-package PREFIX=/usr/local
If either the make variables DESTDIR
or PREFIX
is supplied, ble.sh
will be copied to $DESTDIR/$PREFIX/share/blesh
.
Otherwise, if the make variables INSDIR
is specified, it will be installed directly on $INSDIR
.
Otherwise, if the environment variable $XDG_DATA_HOME
is defined, the install location will be $XDG_DATA_HOME/blesh
.
If none of these variables are specified, the default install location is ~/.local/share/blesh
.
The comment lines and blank lines in the script files are stripped in the installation process.
If you would like to keep these lines in the script files, please specify the argument strip_comment=no
to make
.
To set up .bashrc
see Sec. 1.3.
1.2 Or, use a tar ball of ble.sh
obtained from GitHub releases†
For download, trial and install, see the description at each release page. The stable versions are significantly old compared to the devel version, so many features are unavailable.
- Devel v0.4.0-devel3 (2020-12), nightly build
- Stable v0.3.4 (2019-02 fork) Enhanced completions
- Stable v0.2.7 (2018-03 fork) Vim mode
- Stable v0.1.15 (2015-12 fork) Syntax highlighting
1.3 Set up .bashrc
†
If you want to load ble.sh
in interactive sessions of bash
by default, usually one can just source ble.sh
in ~/.bashrc
,
but a more reliable way is to add the following codes to your .bashrc
file:
# bashrc
# Add this lines at the top of .bashrc:
[[ $- == *i* ]] && source /path/to/blesh/ble.sh --noattach
# your bashrc settings come here...
# Add this line at the end of .bashrc:
[[ ${BLE_VERSION-} ]] && ble-attach
Basically, when source /path/to/ble.sh
and ble-attach
are performed,
standard streams (stdin
, stdout
, and stderr
) should not be redirected but should be connected to the controlling TTY of the current session.
Also, please avoid calling source /path/to/ble.sh
in shell functions.
The detailed conditions where the above more reliable setup is needed are explained in an answer in Discussion #254.
User settings can be placed in the init script ~/.blerc
(or ${XDG_CONFIG_HOME:-$HOME/.config}/blesh/init.sh
if ~/.blerc
is not available)
whose template is available as the file blerc.template
in the repository.
The init script is a Bash script that is sourced during the load of ble.sh
, so any shell commands can be used in ~/.blerc
.
If you want to change the default path of the init script, you can add the option --rcfile INITFILE
to source ble.sh
as the following example:
# in bashrc
# Example 1: ~/.blerc will be used by default
[[ $- == *i* ]] && source /path/to/blesh/ble.sh --noattach
# Example 2: /path/to/your/blerc will be used
[[ $- == *i* ]] && source /path/to/blesh/ble.sh --noattach --rcfile /path/to/your/blerc
You need Git (git
), GNU awk (gawk
) and GNU make (make
).
For ble-0.3+
, you can run ble-update
in the session with ble.sh
loaded:
$ ble-update
For ble.0.4+
, you can also update it outside the ble.sh
session using
$ bash /path/to/ble.sh --update
You can instead download the latest version by git pull
and install it:
cd ble.sh # <-- enter the git repository you already have
git pull
git submodule update --recursive --remote
make
make INSDIR="$HOME/.local/share/blesh" install
Basically you can simply delete the installed directory and the settings that the user added.
- Close all the
ble.sh
sessions (the Bash interactive sessions withble.sh
) - Remove related user data. If you would like to keep them, you can skip these steps.
- Remove the added lines in
.bashrc
. - Remove
blerc
files (~/.blerc
or~/.config/blesh/init.sh
) if any. - Remove the state directory
~/.local/state/blesh
if any.
- Remove the added lines in
- Remove the directory where
ble.sh
is installed. When you useout/ble.sh
inside the working tree of the git repository, the installed directory is the directory of the repository. When you useble.sh
installed bymake install
, the installed directory is<PREFIX>/share/blesh
where<PREFIX>
(default:~/.local
) is the prefix specified tomake install
in the installation stage. When you use the version extracted from a tarball, the directory created by extracting the tarball is the installed directory. - Remove the cache directory
~/.cache/blesh
if any. - Remove the temporary directory
/tmp/blesh
if any [ Only needed when your system does not automatically clear/tmp
].
Here, some of the settings for ~/.blerc
are picked up.
You can find useful settings also in Q&A,
Recipes,
and contrib
repository.
The complete list of setting items can be found in the file blerc.template
.
For detailed explanations please refer to Manual.
For the vi/vim mode, check the wiki page.
One of frequently asked questions is the way to disable a specific feature that ble.sh
adds.
Here the settings for disabling features are summarized.
# Disable syntax highlighting
bleopt highlight_syntax=
# Disable highlighting based on filenames
bleopt highlight_filename=
# Disable highlighting based on variable types
bleopt highlight_variable=
# Disable auto-complete (Note: auto-complete is enabled by default in bash-4.0+)
bleopt complete_auto_complete=
# Tip: you may instead specify the delay of auto-complete in millisecond
bleopt complete_auto_delay=300
# Disable auto-complete based on the command history
bleopt complete_auto_history=
# Disable ambiguous completion
bleopt complete_ambiguous=
# Disable menu-complete by TAB
bleopt complete_menu_complete=
# Disable menu filtering (Note: auto-complete is enabled by default in bash-4.0+)
bleopt complete_menu_filter=
# Disable EOF marker like "[ble: EOF]"
bleopt prompt_eol_mark=''
# Tip: you may instead specify another string:
bleopt prompt_eol_mark='⏎'
# Disable error exit marker like "[ble: exit %d]"
bleopt exec_errexit_mark=
# Tip: you may instead specify another string:
bleopt exec_errexit_mark=$'\e[91m[error %d]\e[m'
# Disable elapsed-time marker like "[ble: elapsed 1.203s (CPU 0.4%)]"
bleopt exec_elapsed_mark=
# Tip: you may instead specify another string
bleopt exec_elapsed_mark=$'\e[94m[%ss (%s %%)]\e[m'
# Tip: you may instead change the threshold of showing the mark
bleopt exec_elapsed_enabled='sys+usr>=10*60*1000' # e.g. ten minutes for total CPU usage
# Disable exit marker like "[ble: exit]"
bleopt exec_exit_mark=
# Disable some other markers like "[ble: ...]"
bleopt edit_marker=
bleopt edit_marker_error=
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
. The 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'
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'
The option edit_bell
controls the behavior of the edit function (widget)
called bell
. It is a colon-separated list of the values vbell
, abell
,
and visual
. When a value is contained, the corresponding type of the bell is
enabled. The value abell
corresponds to the audible bell, which prints ASCII
Control Character BEL (0x07) will be written to stderr
. The value
vbell
corresponds to the visible bell, which shows the message in the
terminal display. The value visual
corresponds to the visual bell, which
flashes the terminal screen by turning on the DECSCNM mode for a
short moment. By default, only the audible bell is enabled.
The option vbell_default_message
specifies the default message shown by the
visual bell. The default value of this setting is ' Wuff, -- Wuff!! '
. The
option vbell_duration
specifies the display duration of the visual-bell
message. The unit is a millisecond. The default value is 2000
. The option
vbell_align
specifies the position of vbell
by left
, center
, or
right
.
For example, the audible bell can be disabled, and the visual bell can be set up as:
bleopt edit_bell=vbell vbell_{default_message=' BEL ',duration=3000,align=right}
The colors and attributes used in the syntax highlighting are controlled by the function ble-face
. The following code reproduces the default configuration:
# highlighting related to editing
ble-face -s region bg=60,fg=white
ble-face -s region_target bg=153,fg=black
ble-face -s region_match bg=55,fg=white
ble-face -s region_insert fg=12,bg=252
ble-face -s disabled fg=242
ble-face -s overwrite_mode fg=black,bg=51
ble-face -s vbell reverse
ble-face -s vbell_erase bg=252
ble-face -s vbell_flash fg=green,reverse
ble-face -s prompt_status_line fg=231,bg=240
# syntax highlighting
ble-face -s syntax_default none
ble-face -s syntax_command fg=brown
ble-face -s syntax_quoted fg=green
ble-face -s syntax_quotation fg=green,bold
ble-face -s syntax_escape fg=magenta
ble-face -s syntax_expr fg=26
ble-face -s syntax_error bg=203,fg=231
ble-face -s syntax_varname fg=202
ble-face -s syntax_delimiter bold
ble-face -s syntax_param_expansion fg=purple
ble-face -s syntax_history_expansion bg=94,fg=231
ble-face -s syntax_function_name fg=92,bold
ble-face -s syntax_comment fg=242
ble-face -s syntax_glob fg=198,bold
ble-face -s syntax_brace fg=37,bold
ble-face -s syntax_tilde fg=navy,bold
ble-face -s syntax_document fg=94
ble-face -s syntax_document_begin fg=94,bold
ble-face -s command_builtin_dot fg=red,bold
ble-face -s command_builtin fg=red
ble-face -s command_alias fg=teal
ble-face -s command_function fg=92
ble-face -s command_file fg=green
ble-face -s command_keyword fg=blue
ble-face -s command_jobs fg=red
ble-face -s command_directory fg=26,underline
ble-face -s command_suffix fg=white,bg=green
ble-face -s command_suffix_new fg=white,bg=brown
ble-face -s filename_directory underline,fg=26
ble-face -s filename_directory_sticky underline,fg=white,bg=26
ble-face -s filename_link underline,fg=teal
ble-face -s filename_orphan underline,fg=teal,bg=224
ble-face -s filename_executable underline,fg=green
ble-face -s filename_setuid underline,fg=black,bg=220
ble-face -s filename_setgid underline,fg=black,bg=191
ble-face -s filename_other underline
ble-face -s filename_socket underline,fg=cyan,bg=black
ble-face -s filename_pipe underline,fg=lime,bg=black
ble-face -s filename_character underline,fg=white,bg=black
ble-face -s filename_block underline,fg=yellow,bg=black
ble-face -s filename_warning underline,fg=red
ble-face -s filename_url underline,fg=blue
ble-face -s filename_ls_colors underline
ble-face -s varname_array fg=orange,bold
ble-face -s varname_empty fg=31
ble-face -s varname_export fg=200,bold
ble-face -s varname_expr fg=92,bold
ble-face -s varname_hash fg=70,bold
ble-face -s varname_number fg=64
ble-face -s varname_readonly fg=200
ble-face -s varname_transform fg=29,bold
ble-face -s varname_unset fg=124
ble-face -s argument_option fg=teal
ble-face -s argument_error fg=black,bg=225
# highlighting for completions
ble-face -s auto_complete fg=238,bg=254
ble-face -s menu_desc_default none
ble-face -s menu_desc_type ref:syntax_delimiter
ble-face -s menu_desc_quote ref:syntax_quoted
ble-face -s menu_filter_fixed bold
ble-face -s menu_filter_input fg=16,bg=229
The current list of faces can be obtained by the following command (ble-face
without arguments):
$ ble-face
The color codes can be checked in output of the function ble-color-show
(defined in ble.sh
):
$ ble-color-show
Key bindings can be controlled with the shell function, ble-bind
.
For example, with the following setting, "Hello, world!" will be inserted on typing C-x h
ble-bind -f 'C-x h' 'insert-string "Hello, world!"'
The details on the key representation, such as C-x h in the above example,
are described in Manual §3.1.
The representations of Space, Tab, Enter, Backspace, Escape, etc. are described
in Manual §3.1.1:
The space is represented as SP,
the tab key is represented as C-i or TAB depending on the terminal,
the enter/return key is represented as C-m or RET depending on the terminal,
and the backspace key is represented as C-?, DEL, C-h, or BS depending on the terminal.
The representations of modified special keys such as Ctrl+Return and Shift+Return are described
in Manual §3.6.4:
If your terminal does not support modifyOtherKeys
, you need to manually configure the escape sequences of modified special keys.
For another example, if you want to invoke a command on typing M-c, you can write it as follows:
ble-bind -c 'M-c' 'my-command'
Or, if you want to invoke a edit function (designed for Bash bind -x
) on typing C-r, you can write it as follows:
ble-bind -x 'C-r' 'my-edit-function'
The existing key bindings are shown by the following command:
$ ble-bind -P
The list of widgets is shown by the following command:
$ ble-bind -L
If you want to run multiple widgets with a key, you can define your own widget by creating a function of the name ble/widget/YOUR_WIDGET_NAME
as illustrated in the following example.
It is highly recommended to prefix the widget name with YOUR_NAME/
, my/
, blerc/
, dotfiles/
, etc.
in order not to conflict with the names of the existing standard widgets.
# Example of calling multiple widgets with the key C-t
function ble/widget/my/example1 {
ble/widget/beginning-of-logical-line
ble/widget/insert-string 'echo $('
ble/widget/end-of-logical-line
ble/widget/insert-string ')'
}
ble-bind -f C-t my/example1
2.8 fzf integration†
If you would like to use fzf
in combination with ble.sh
, you need to configure fzf
using the contrib/fzf
integration.
Please follow the instructions in the link for the detailed description.
# blerc
# Note: If you want to combine fzf-completion with bash_completion, you need to
# load bash_completion earilier than fzf-completion. This is required
# regardless of whether to use ble.sh or not.
source /etc/profile.d/bash_completion.sh
ble-import -d integration/fzf-completion
ble-import -d integration/fzf-key-bindings
The option -d
of ble-import
delays the initialization. In this way, the
fzf settings are loaded in background after the prompt is shown. See
ble-import
- Manual §8
for details. If you would like to additionally configure the fzf settings
after loading them, there are four options. The easiest way is to drop the
-d
option (Option 1 below). As another option, you may also delay the
additional settings with ble-import -d
[2] or ble/util/idle.push
[3]. Or,
you can hook into the loading of the fzf settings by ble-import -C
[4].
# [1] Drop -d
ble-import integration/fzf-completion
ble-import integration/fzf-key-bindings
<settings>
# [2] Use ble-import -d for additional settings
ble-import -d integration/fzf-completion
ble-import -d integration/fzf-key-bindings
ble-import -d '<filename containing the settings>'
# [3] Use "ble/util/idle.push" for additional settings
ble-import -d integration/fzf-completion
ble-import -d integration/fzf-key-bindings
ble/util/idle.push '<settings>'
# [4] Use "ble-import -C" for additional settings
ble-import -d integration/fzf-completion
ble-import -d integration/fzf-key-bindings
ble-import -C '<settings>' integration/fzf-key-bindings
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 the 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.
If set -o vi
is specified in .bashrc
or set editing-mode vi
is specified in .inputrc
, the vim mode is enabled.
For details, please check the wiki page.
The feature auto-complete
is available in Bash 4.0 or later. auto-complete
automatically suggests a possible completion on user input.
The suggested contents can be inserted by typing S-RET
(when the cursor is at the end of the command line, you can also use right, C-f, or end to insert the suggestion).
If you want to insert only the first word of the suggested contents, you can use M-right or M-f.
If you want to accept the suggestion and immediately run the command, you can use C-RET
(if your terminal does not support special key combinations like C-RET, please check
Manual §3.6.4).
By registering words to sabbrev
, the words can be expanded to predefined strings.
When the cursor is just after a registered word, typing SP causes the sabbrev
expansion.
For example, with the following settings, when you type SP after the string command L
, the command line will be expanded to command | less
.
# blerc
ble-sabbrev L='| less'
The sabbrev names that start with \
plus alphabetical letters are also recommended since it is unlikely to conflict with real words that are a part of the executed command.
# blerc
ble-sabbrev '\L'='| less'
The sabbrevs starting with ~
can be expanded also by /. This can be used to approximate Zsh's named directories.
For example, with the following settings, typing ~mybin/
expands it to e.g. /home/user/bin/
(where we assumed HOME=/home/user
).
# blerc
ble-sabbrev "~mybin=$HOME/bin"
I received many feedbacks from many people in GitHub Issues/PRs. I thank all such people for supporting the project. Among them, the following people have made particularly significant contributions.
@cmplstofB
helped me implement vim-mode by testing it and giving me a lot of suggestions.@dylankb
reported many issues with the fzf integration, initialization, etc.@rux616
reported several issues and created a PR for fixing the default path of.blerc
@timjrd
suggested and contributed to performance improvements in completion.@3ximus
reported many issues for a wide variety of problems.@SuperSandro2000
reported many issues related to NixOS and others