README.md (35976B)
1 [ Languages: **English** | [日本語](README-ja_JP.md) (Japanese) ] 2 3 <h1 align="center"><ruby>ble.sh<rp> (</rp><rt>/blɛʃ/</rt><rp>)</rp></ruby> ―Bash Line Editor―</h1> 4 <p align="center"> 5 [ <b>README</b> | <a href="https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A71-Introduction">Manual</a> | 6 <a href="https://github.com/akinomyoga/ble.sh/wiki/Q&A">Q&A</a> | 7 <a href="https://github.com/akinomyoga/blesh-contrib"><code>contrib</code></a> | 8 <a href="https://github.com/akinomyoga/ble.sh/wiki/Recipes">Recipes</a> ] 9 </p> 10 11 *Bash Line Editor* (`ble.sh`) is a command line editor written in pure Bash which replaces the default GNU Readline. 12 13 Current devel version is 0.4. 14 This script supports Bash 3.0 or higher although we recommend to use `ble.sh` with release versions of **Bash 4.0 or higher**. 15 Currently, only `UTF-8` encoding is supported for non-ASCII characters. 16 This script is provided under the [**BSD License**](LICENSE.md) (3-clause BSD license). 17 18 Disclaimer: The core part of the line editor is written in **pure Bash**, but 19 `ble.sh` relies on POSIX `stty` to set up TTY states before and after the execution of user commands. 20 It also uses other POSIX utilities for acceleration 21 in some part of initialization and cleanup code, 22 processing of large data in completions, paste of large data, etc. 23 24 Pronunciation: The easiest pronunciation of `ble.sh` that users use is /blɛʃ/, but you can actually pronounce it as you like. 25 I do not specify the canonical way of pronoucing `ble.sh`. 26 In fact, I personally call it simply /biːɛliː/ or verbosely read it as /biːɛliː dɑt ɛseɪtʃ/ in my head. 27 28 ## Quick instructions 29 30 To use `ble.sh`, Bash 3.0+ and POSIX standard utilities are required. 31 <!-- In macOS, you might additionally need to install `gawk`, `nawk`, or `mawk` since macOS `/usr/bin/awk` (awk-32 and later) seems to have a problem with some multibyte charsets. --> 32 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`. 33 For the detailed descriptions, see [Sec 1.1](#get-from-source) and [Sec 1.2](#get-from-tarball) for trial/installation, 34 and [Sec 1.3](#set-up-bashrc) for the setup of your `~/.bashrc`. 35 36 <details open><summary><b>Download and generate <code>ble.sh</code> using <code>git</code></b></summary> 37 38 This requires the commands `git`, `make` (GNU make), and `gawk` (GNU awk). 39 In the following, please replace `make` with `gmake` if your system provides GNU make as `gmake` (such as in BSD). 40 41 ```bash 42 # TRIAL without installation 43 44 git clone --recursive --depth 1 --shallow-submodules https://github.com/akinomyoga/ble.sh.git 45 make -C ble.sh 46 source ble.sh/out/ble.sh 47 48 # Quick INSTALL to BASHRC (If this doesn't work, please follow Sec 1.3) 49 50 git clone --recursive --depth 1 --shallow-submodules https://github.com/akinomyoga/ble.sh.git 51 make -C ble.sh install PREFIX=~/.local 52 echo 'source ~/.local/share/blesh/ble.sh' >> ~/.bashrc 53 ``` 54 55 The build process integrates multiple Bash script files into a single Bash script `ble.sh` with pre-processing, 56 place other module files in appropriate places, and strip code comments for shorter initialization time. 57 58 Note: This does not involve any C/C++/Fortran compilations and generating binaries, so C/C++/Fortran compilers are not needed. 59 Some people seem to bilindly believe that one always need to use `make` with C/C++/Fortran compilers to generate binaries. 60 They complain about `ble.sh`'s make process, but it comes from the lack of knowledge on the general principle of `make`. 61 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. 62 The generated table is included in the repository: 63 [`canvas.GraphemeClusterBreak.sh`](https://github.com/akinomyoga/ble.sh/blob/master/src/canvas.GraphemeClusterBreak.sh), 64 [`canvas.c2w.musl.sh`](https://github.com/akinomyoga/ble.sh/blob/master/src/canvas.c2w.musl.sh), 65 [`canvas.c2w.sh`](https://github.com/akinomyoga/ble.sh/blob/master/src/canvas.c2w.sh), 66 and [`canvas.emoji.sh`](https://github.com/akinomyoga/ble.sh/blob/master/src/canvas.emoji.sh), 67 so there is no need to run these C/C++ programs in the build process. 68 Another C file is used as an adapter in a old system MSYS1, 69 which is used with an old compiler toolchain in Windows, but it will never be used in Unix-like systems. 70 Each file used in the build process is explained in [`make/README.md`](make/README.md). 71 </details> 72 73 <details><summary><b>Download the nightly build with <code>curl</code></b></summary> 74 75 This requires the commands `curl`, `tar` (with the support for the `J` flag), and `xz` (XZ Utils). 76 77 ```bash 78 # TRIAL without installation 79 80 curl -L https://github.com/akinomyoga/ble.sh/releases/download/nightly/ble-nightly.tar.xz | tar xJf - 81 source ble-nightly/ble.sh 82 83 # Quick INSTALL to BASHRC (If this doesn't work, please follow Sec 1.3) 84 85 curl -L https://github.com/akinomyoga/ble.sh/releases/download/nightly/ble-nightly.tar.xz | tar xJf - 86 mkdir -p ~/.local/share/blesh 87 cp -Rf ble-nightly/* ~/.local/share/blesh/ 88 rm -rf ble-nightly 89 echo 'source ~/.local/share/blesh/ble.sh' >> ~/.bashrc 90 ``` 91 </details> 92 93 <details><summary><b>Download the nightly build with <code>wget</code></b></summary> 94 95 This requires the commands `wget`, `tar` (with the support for the `J` flag), and `xz` (XZ Utils). 96 97 ```bash 98 # TRIAL without installation 99 100 wget -O - https://github.com/akinomyoga/ble.sh/releases/download/nightly/ble-nightly.tar.xz | tar xJf - 101 source ble-nightly/ble.sh 102 103 # Quick INSTALL to BASHRC (If this doesn't work, please follow Sec 1.3) 104 105 wget -O - https://github.com/akinomyoga/ble.sh/releases/download/nightly/ble-nightly.tar.xz | tar xJf - 106 mkdir -p ~/.local/share/blesh 107 cp -Rf ble-nightly/* ~/.local/share/blesh/ 108 rm -rf ble-nightly 109 echo 'source ~/.local/share/blesh/ble.sh' >> ~/.bashrc 110 ``` 111 </details> 112 113 <details open><summary><b>Install a package using a package manager</b> (currently only a few packages)</summary> 114 115 This only requires the corresponding package manager. 116 117 - [AUR (Arch Linux)](https://github.com/akinomyoga/ble.sh/wiki/Manual-A1-Installation#user-content-AUR) `blesh-git` (devel), `blesh` (stable 0.3.4) 118 - [NixOS (nixpkgs)](https://github.com/akinomyoga/ble.sh/wiki/Manual-A1-Installation#user-content-nixpkgs) `blesh` (devel) 119 - [Guix](https://packages.guix.gnu.org/packages/blesh) `blesh` (devel) 120 </details> 121 122 <details open><summary><b>Update an existing copy of <code>ble.sh</code></b></summary> 123 124 ```bash 125 # UPDATE (in a ble.sh session) 126 127 ble-update 128 129 # UPDATE (outside ble.sh sessions) 130 131 bash /path/to/ble.sh --update 132 ``` 133 </details> 134 135 <details><summary><b>Create a package of <code>ble.sh</code></b></summary> 136 137 Since `ble.sh` is just a set of shell scripts and do not contain any binary (i.e., "`noarch`"), 138 you may just download the pre-built tarball from release pages and put the extracted contents in e.g. `/tmp/blesh-package/usr/local`. 139 Nevertheless, if you need to build the package from the source, please use the following commands. 140 Note that the git repository (`.git`) is required for the build. 141 142 ```bash 143 # BUILD & PACKAGE (for package maintainers) 144 145 git clone --recursive https://github.com/akinomyoga/ble.sh.git 146 make -C ble.sh install DESTDIR=/tmp/blesh-package PREFIX=/usr/local 147 ``` 148 149 When you would like to tell `ble.sh` the way to update the package for `ble-update`, 150 you can place `_package.bash` at `${prefix}/share/blesh/lib/_package.bash`. 151 The file `_package.bash` is supposed to define a shell variable and a shell function 152 as illustrated in the following example (please replace `XXX` with the package management system): 153 154 ```bash 155 # ${prefix}/share/blesh/lib/_package.bash 156 157 _ble_base_package_type=XXX 158 159 function ble/base/package:XXX/update { 160 update-the-package-in-a-proper-way 161 return 0 162 } 163 ``` 164 165 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. 166 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. 167 When the shell function returns exit status 125, the default `ble.sh` update procedure is attempted. 168 Otherwise, the updating procedure is canceled, where any message explaining situation should be output by the shell function. 169 An example `_package.bash` for `AUR` can be found [here](https://aur.archlinux.org/cgit/aur.git/tree/blesh-update.sh?h=blesh-git). 170 </details> 171 172 ## Features 173 174 - **Syntax highlighting**: Highlight command lines input by users as in `fish` and `zsh-syntax-highlighting`. 175 Unlike the simple highlighting in `zsh-syntax-highlighting`, `ble.sh` performs syntactic analysis 176 to enable the correct highlighting of complex structures such as nested command substitutions, multiple here documents, etc. 177 Highlighting colors and styles are [fully configurable](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A72-Graphics). 178 - **Enhanced completion**: 179 Extend [completion](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A77-Completion) 180 by **syntax-aware completion**, completion with quotes and parameter expansions in prefix texts, **ambiguous candidate generation**, etc. 181 Also, [**menu-complete**](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A77-Completion#user-content-sec-menu-complete) 182 supports selection of candidates in menu (candidate list) by cursor keys, <kbd>TAB</kbd> and <kbd>S-TAB</kbd>. 183 The feature [**auto-complete**](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A77-Completion#user-content-sec-auto-complete) 184 supports the automatic suggestion of completed texts as in `fish` and `zsh-autosuggestions` (with Bash 4.0+). 185 The feature [**menu-filter**](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A77-Completion#user-content-sec-menu-filter) 186 integrates automatic filtering of candidates into menu completion (with Bash 4.0+). 187 There are other functionalities such as 188 [**dabbrev**](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A77-Completion#user-content-sec-dabbrev) and 189 [**sabbrev**](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A77-Completion#user-content-sec-sabbrev) like 190 [*zsh abbreviations*](https://unix.stackexchange.com/questions/6152/zsh-alias-expansion) or [`zsh-abbr`](https://github.com/olets/zsh-abbr). 191 - **Vim editing mode**: Enhance `readline`'s vi editing mode available with `set -o vi`. 192 Vim editing mode supports various vim modes such as char/line/block visual/select mode, replace mode, 193 command mode, operator pending mode as well as insert mode and normal mode. 194 Vim editing mode supports various operators, text objects, registers, keyboard macros, marks, etc. 195 It also provides `vim-surround` as an option. 196 - Other interesting features include 197 [**status line**](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A74-Editing#user-content-bleopt-prompt_status_line), 198 [**history share**](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A74-Editing#user-content-bleopt-history_share), 199 [**right prompt**](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A74-Editing#user-content-bleopt-prompt_rps1), 200 [**transient prompt**](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A74-Editing#user-content-bleopt-prompt_ps1_transient), 201 [**xterm title**](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A74-Editing#user-content-bleopt-prompt_xterm_title), etc. 202 203 Note: ble.sh does not provide specific settings of the prompt, aliases, functions, etc. 204 ble.sh provides a more fundamental infrastructure so that users can set up their own prompt, aliases, functions, etc. 205 Of course ble.sh can be used in combination with other Bash configurations such as [`bash-it`](https://github.com/Bash-it/bash-it) and [`oh-my-bash`](https://github.com/ohmybash/oh-my-bash). 206 207 > Demo (version 0.2) 208 > 209 >  210 211 ## History and roadmap 212 213 My little experiment has took place in one corner of my `bashrc` in the end of May, 2013 after I enjoyed some article on `zsh-syntax-highlighting`. 214 I initially thought something can be achieved by writing a few hundred of lines of codes 215 but soon realized that everything needs to be re-implemented for the authentic support of syntax highlighting in Bash. 216 I decided to make it as an independent script `ble.sh`. 217 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 shell script. 218 I'm occasinally asked about the pronunciation of `ble.sh`, but you can actually pronounce it as you like. 219 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. 220 The real efforts of improving the prototype implementation for the real uses was started in Feburuary, 2015. 221 I released the initial version in the next December. Until then, the basic part of the line editor was completed. 222 The implementation of vim mode has been started in September, 2017 and completed in the next March. 223 I started working on the enhancement of the completion in August, 2018 and released it in the next February. 224 225 - 2013-06 v0.0 -- prototype 226 - 2015-12 v0.1 -- Syntax highlighting [[v0.1.15](https://github.com/akinomyoga/ble.sh/releases/tag/v0.1.15)] 227 - 2018-03 v0.2 -- Vim mode [[v0.2.7](https://github.com/akinomyoga/ble.sh/releases/tag/v0.2.7)] 228 - 2019-02 v0.3 -- Enhanced completion [[v0.3.4](https://github.com/akinomyoga/ble.sh/releases/tag/v0.3.4)] 229 - 20xx-xx v0.4 (plan) -- programmable highlighting [[nightly build](https://github.com/akinomyoga/ble.sh/releases/tag/nightly)] 230 - 20xx-xx v0.5 (plan) -- TUI configuration 231 - 20xx-xx v0.6 (plan) -- error diagnostics? 232 233 ## Limitations 234 235 There are some limitations due to the way `ble.sh` is implemented. 236 Also some user configurations or other Bash frameworks may conflict with ble.sh. 237 For example, 238 239 - `ble.sh` does not set `PIPESTATUS` for the previous command line by default because it adds extra execution costs. 240 Instead, the array `BLE_PIPESTATUS` contains the values of `PIPESTATUS` of the previous command line. 241 If you need to access the values directly through the variable `PIPESTATUS`, please use the option `bleopt exec_restore_pipestatus=1`. 242 - `ble.sh` assumes that common variable names and environment variables (such as `LC_*`) are not used for the global readonly variables. 243 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 have the same name as a global readonly variable. 244 This is not the problem specific to `ble.sh`, but any Bash framework may suffer from the global readonly variables. 245 It is generally not recommended to define global readonly variables in Bash except for the security reasoning 246 (Refs. [[1]](https://lists.gnu.org/archive/html/bug-bash/2019-03/threads.html#00150), [[2]](https://lists.gnu.org/archive/html/bug-bash/2020-04/threads.html#00200), [[3]](https://mywiki.wooledge.org/BashProgramming?highlight=%28%22readonly%22%20flag,%20or%20an%20%22integer%22%20flag,%20but%20these%20are%20mostly%20useless,%20and%20serious%20scripts%20shouldn%27t%20be%20using%20them%29#Variables)). 247 Also, `ble.sh` overrides the builtin `readonly` with a shell function to prevent it from making global variables readonly. 248 It allows only uppercase global variables and `_*` to become readonly except `_ble_*`, `__ble_*`, and some special uppercase variables. 249 - `ble.sh` overrides Bash's built-in commands (`trap`, `readonly`, `bind`, `history`, `read`, and `exit`) with shell functions to adjust the behavior of each built-in command and prevent them from interfering with `ble.sh`. 250 If the user or another framework directly calls the original builtins through `builtin BUILTIN`, or if the user or another framework replaces the shell functions, the behavior is undefined. 251 252 # 1 Usage 253 254 ## 1.1 Try `ble.sh` generated from source (version ble-0.4 devel)<sup><a id="get-from-source" href="#get-from-source">†</a></sup> 255 256 ### Generate 257 258 To generate `ble.sh`, `gawk` (GNU awk) and `gmake` (GNU make) (in addition to Bash and POSIX standard utilities) is required. 259 The file `ble.sh` can be generated using the following commands. 260 If you have GNU make installed on `gmake`, please use `gmake` instead of `make`. 261 ```bash 262 git clone --recursive https://github.com/akinomyoga/ble.sh.git 263 cd ble.sh 264 make 265 ``` 266 267 A script file `ble.sh` will be generated in the directory `ble.sh/out`. 268 269 ### Try 270 271 Then, you can load `ble.sh` in the Bash session using the `source` command: 272 ```bash 273 source out/ble.sh 274 ``` 275 276 ### Install 277 278 To install `ble.sh` in a specified directory, use `make install`. 279 280 ```bash 281 # INSTALL to ~/.local/share/blesh 282 make install 283 284 # INSTALL to a specified directory 285 make install INSDIR=/path/to/blesh 286 287 # PACKAGE (for package maintainers) 288 make install DESTDIR=/tmp/blesh-package PREFIX=/usr/local 289 ``` 290 291 If either the make variables `DESTDIR` or `PREFIX` is supplied, `ble.sh` will be copied to `$DESTDIR/$PREFIX/share/blesh`. 292 Otherwise, if the make variables `INSDIR` is specified, it will be installed directly on `$INSDIR`. 293 Otherwise, if the environment variable `$XDG_DATA_HOME` is defined, the install location will be `$XDG_DATA_HOME/blesh`. 294 If none of these variables are specified, the default install location is `~/.local/share/blesh`. 295 296 The comment lines and blank lines in the script files are stripped in the installation process. 297 If you would like to keep these lines in the script files, please specify the argument `strip_comment=no` to `make`. 298 299 To set up `.bashrc` see [Sec. 1.3](#set-up-bashrc). 300 301 ## 1.2 Or, use a tar ball of `ble.sh` obtained from GitHub releases<sup><a id="get-from-tarball" href="#get-from-tarball">†</a></sup> 302 303 For download, trial and install, see the description at each release page. 304 The stable versions are significantly old compared to the devel version, so many features are unavailable. 305 306 - Devel [v0.4.0-devel3](https://github.com/akinomyoga/ble.sh/releases/tag/v0.4.0-devel3) (2020-12), [nightly build](https://github.com/akinomyoga/ble.sh/releases/tag/nightly) 307 - Stable [v0.3.4](https://github.com/akinomyoga/ble.sh/releases/tag/v0.3.4) (2019-02 fork) Enhanced completions 308 - Stable [v0.2.7](https://github.com/akinomyoga/ble.sh/releases/tag/v0.2.7) (2018-03 fork) Vim mode 309 - Stable [v0.1.15](https://github.com/akinomyoga/ble.sh/releases/tag/v0.1.15) (2015-12 fork) Syntax highlighting 310 311 ## 1.3 Set up `.bashrc`<sup><a id="set-up-bashrc" href="#set-up-bashrc">†</a></sup> 312 313 If you want to load `ble.sh` in interactive sessions of `bash` by default, usually one can just source `ble.sh` in `~/.bashrc`, 314 but more reliable way is to add the following codes to your `.bashrc` file: 315 316 ```bash 317 # bashrc 318 319 # Add this lines at the top of .bashrc: 320 [[ $- == *i* ]] && source /path/to/blesh/ble.sh --noattach 321 322 # your bashrc settings come here... 323 324 # Add this line at the end of .bashrc: 325 [[ ${BLE_VERSION-} ]] && ble-attach 326 ``` 327 328 Basically, when `source /path/to/ble.sh` and `ble-attach` are performed, 329 standard streams (`stdin`, `stdout`, and `stderr`) should not be redirected but should be connected to the controlling TTY of the current session. 330 Also, please avoid calling `source /path/to/ble.sh` in shell functions. 331 The detailed conditions that we need the above *more reliable setup* are explained in [an answer in Discussion #254](https://github.com/akinomyoga/ble.sh/discussions/254#discussioncomment-4284757). 332 333 ## 1.4 User settings `~/.blerc` 334 335 User settings can be placed in the init script `~/.blerc` (or `${XDG_CONFIG_HOME:-$HOME/.config}/blesh/init.sh` if `~/.blerc` is not available) 336 whose template is available as the file [`blerc.template`](https://github.com/akinomyoga/ble.sh/blob/master/blerc.template) in the repository. 337 The init script is a Bash script which will be sourced during the load of `ble.sh`, so any shell commands can be used in `~/.blerc`. 338 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: 339 340 ```bash 341 # in bashrc 342 343 # Example 1: ~/.blerc will be used by default 344 [[ $- == *i* ]] && source /path/to/blesh/ble.sh --noattach 345 346 # Example 2: /path/to/your/blerc will be used 347 [[ $- == *i* ]] && source /path/to/blesh/ble.sh --noattach --rcfile /path/to/your/blerc 348 ``` 349 350 ## 1.5 Update 351 352 You need Git (`git`), GNU awk (`gawk`) and GNU make (`make`). 353 For `ble-0.3+`, you can run `ble-update` in the session with `ble.sh` loaded: 354 355 ```bash 356 $ ble-update 357 ``` 358 359 For `ble.0.4+`, you can also update it outside the `ble.sh` session using 360 361 ```bash 362 $ bash /path/to/ble.sh --update 363 ``` 364 365 You can instead download the latest version by `git pull` and install it: 366 367 ```bash 368 cd ble.sh # <-- enter the git repository you already have 369 git pull 370 git submodule update --recursive --remote 371 make 372 make INSDIR="$HOME/.local/share/blesh" install 373 ``` 374 375 ## 1.6 Uninstall 376 377 Basically you can simply delete the installed directory and the settings that the user added. 378 379 - Close all the `ble.sh` sessions (the Bash interactive sessions with `ble.sh`) 380 - Remove the added lines in `.bashrc`. 381 - Remove `blerc` files (`~/.blerc` or `~/.config/blesh/init.sh`) if any. 382 - Remove the installed directory. 383 - Remove the cache directory `~/.cache/blesh` if any. 384 - Remove the state directory `~/.local/state/blesh` if any. 385 - Remove the temporary directory `/tmp/blesh` if any [ Only needed when your system does not automatically clears `/tmp` ]. 386 387 # 2 Basic settings 388 389 Here, some of the settings for `~/.blerc` are picked up. 390 You can find useful settings also in [Q\&A](https://github.com/akinomyoga/ble.sh/wiki/Q&A), 391 [Recipes](https://github.com/akinomyoga/ble.sh/wiki/Recipes) 392 and [`contrib` repository](https://github.com/akinomyoga/blesh-contrib). 393 The complete list of setting items can be found in the file [`blerc.template`](https://github.com/akinomyoga/ble.sh/blob/master/blerc.template). 394 For detailed explanations please refer to [Manual](https://github.com/akinomyoga/ble.sh/wiki). 395 396 ## 2.1 Vim mode 397 398 For the vi/vim mode, check [the wiki page](https://github.com/akinomyoga/ble.sh/wiki/Vi-(Vim)-editing-mode). 399 400 ## 2.2 Disable features 401 402 One of frequently asked questions is the way to disable a specific feature that `ble.sh` adds. 403 Here the settings for disabling features are summarized. 404 405 ```bash 406 # Disable syntax highlighting 407 bleopt highlight_syntax= 408 409 # Disable highlighting based on filenames 410 bleopt highlight_filename= 411 412 # Disable highlighting based on variable types 413 bleopt highlight_variable= 414 415 # Disable auto-complete (Note: auto-complete is enabled by default in bash-4.0+) 416 bleopt complete_auto_complete= 417 # Tip: you may instead specify the delay of auto-complete in millisecond 418 bleopt complete_auto_delay=300 419 420 # Disable auto-complete based on the command history 421 bleopt complete_auto_history= 422 423 # Disable ambiguous completion 424 bleopt complete_ambiguous= 425 426 # Disable menu-complete by TAB 427 bleopt complete_menu_complete= 428 429 # Disable menu filtering (Note: auto-complete is enabled by default in bash-4.0+) 430 bleopt complete_menu_filter= 431 432 # Disable EOF marker like "[ble: EOF]" 433 bleopt prompt_eol_mark='' 434 # Tip: you may instead specify another string: 435 bleopt prompt_eol_mark='⏎' 436 437 # Disable error exit marker like "[ble: exit %d]" 438 bleopt exec_errexit_mark= 439 # Tip: you may instead specify another string: 440 bleopt exec_errexit_mark=$'\e[91m[error %d]\e[m' 441 442 # Disable elapsed-time marker like "[ble: elapsed 1.203s (CPU 0.4%)]" 443 bleopt exec_elapsed_mark= 444 # Tip: you may instead specify another string 445 bleopt exec_elapsed_mark=$'\e[94m[%ss (%s %%)]\e[m' 446 # Tip: you may instead change the threshold of showing the mark 447 bleopt exec_elapsed_enabled='sys+usr>=10*60*1000' # e.g. ten minutes for total CPU usage 448 ``` 449 450 ## 2.3 CJK Width 451 452 The option `char_width_mode` controls the width of the Unicode characters with `East_Asian_Width=A` (Ambiguous characters). 453 Currently four values `emacs`, `west`, `east`, and `auto` are supported. With the value `emacs`, the default width in emacs is used. 454 With `west` all the ambiguous characters have width 1 (Hankaku). With `east` all the ambiguous characters have width 2 (Zenkaku). 455 With `auto` the width mode `west` or `east` is automatically chosen based on the terminal behavior. 456 The default value is `auto`. Appropriate value should be chosen in accordance with your terminal behavior. 457 For example, the value can be changed to `west` as: 458 459 ```bash 460 bleopt char_width_mode='west' 461 ``` 462 463 ## 2.4 Input Encoding 464 465 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: 466 467 ```bash 468 bleopt input_encoding='C' 469 ``` 470 471 ## 2.5 Bell 472 473 The options `edit_abell` and `edit_vbell` control the behavior of the edit function `bell`. If `edit_abell` is a non-empty string, audible bell is enabled, i.e. ASCII Control Character `BEL` (0x07) will be written to `stderr`. If `edit_vbell` is a non-empty string, visual bell is enabled. By default, the audible bell is enabled while the visual bell is disabled. 474 475 The option `vbell_default_message` specifies the message shown as the visual bell. The default value is `' Wuff, -- Wuff!! '`. The option `vbell_duration` specifies the display duration of the visual-bell message. The unit is millisecond. The default value is `2000`. 476 477 For example, the visual bell can be enabled as: 478 ``` 479 bleopt edit_vbell=1 vbell_default_message=' BEL ' vbell_duration=3000 480 ``` 481 482 For another instance, the audible bell is disabled as: 483 ``` 484 bleopt edit_abell= 485 ``` 486 487 ## 2.6 Highlight Colors 488 489 The colors and attributes used in the syntax highlighting are controlled by `ble-face` function. The following code reproduces the default configuration: 490 ```bash 491 # highlighting related to editing 492 ble-face -s region bg=60,fg=white 493 ble-face -s region_target bg=153,fg=black 494 ble-face -s region_match bg=55,fg=white 495 ble-face -s region_insert fg=12,bg=252 496 ble-face -s disabled fg=242 497 ble-face -s overwrite_mode fg=black,bg=51 498 ble-face -s auto_complete fg=238,bg=254 499 ble-face -s menu_filter_fixed bold 500 ble-face -s menu_filter_input fg=16,bg=229 501 ble-face -s vbell reverse 502 ble-face -s vbell_erase bg=252 503 ble-face -s vbell_flash fg=green,reverse 504 ble-face -s prompt_status_line fg=231,bg=240 505 506 # syntax highlighting 507 ble-face -s syntax_default none 508 ble-face -s syntax_command fg=brown 509 ble-face -s syntax_quoted fg=green 510 ble-face -s syntax_quotation fg=green,bold 511 ble-face -s syntax_escape fg=magenta 512 ble-face -s syntax_expr fg=26 513 ble-face -s syntax_error bg=203,fg=231 514 ble-face -s syntax_varname fg=202 515 ble-face -s syntax_delimiter bold 516 ble-face -s syntax_param_expansion fg=purple 517 ble-face -s syntax_history_expansion bg=94,fg=231 518 ble-face -s syntax_function_name fg=92,bold 519 ble-face -s syntax_comment fg=242 520 ble-face -s syntax_glob fg=198,bold 521 ble-face -s syntax_brace fg=37,bold 522 ble-face -s syntax_tilde fg=navy,bold 523 ble-face -s syntax_document fg=94 524 ble-face -s syntax_document_begin fg=94,bold 525 ble-face -s command_builtin_dot fg=red,bold 526 ble-face -s command_builtin fg=red 527 ble-face -s command_alias fg=teal 528 ble-face -s command_function fg=92 529 ble-face -s command_file fg=green 530 ble-face -s command_keyword fg=blue 531 ble-face -s command_jobs fg=red 532 ble-face -s command_directory fg=26,underline 533 ble-face -s filename_directory underline,fg=26 534 ble-face -s filename_directory_sticky underline,fg=white,bg=26 535 ble-face -s filename_link underline,fg=teal 536 ble-face -s filename_orphan underline,fg=teal,bg=224 537 ble-face -s filename_executable underline,fg=green 538 ble-face -s filename_setuid underline,fg=black,bg=220 539 ble-face -s filename_setgid underline,fg=black,bg=191 540 ble-face -s filename_other underline 541 ble-face -s filename_socket underline,fg=cyan,bg=black 542 ble-face -s filename_pipe underline,fg=lime,bg=black 543 ble-face -s filename_character underline,fg=white,bg=black 544 ble-face -s filename_block underline,fg=yellow,bg=black 545 ble-face -s filename_warning underline,fg=red 546 ble-face -s filename_url underline,fg=blue 547 ble-face -s filename_ls_colors underline 548 ble-face -s varname_array fg=orange,bold 549 ble-face -s varname_empty fg=31 550 ble-face -s varname_export fg=200,bold 551 ble-face -s varname_expr fg=92,bold 552 ble-face -s varname_hash fg=70,bold 553 ble-face -s varname_number fg=64 554 ble-face -s varname_readonly fg=200 555 ble-face -s varname_transform fg=29,bold 556 ble-face -s varname_unset fg=124 557 ble-face -s argument_option fg=teal 558 ble-face -s argument_error fg=black,bg=225 559 560 ``` 561 562 The current list of faces can be obtained by the following command (`ble-face` without arguments): 563 ```console 564 $ ble-face 565 ``` 566 567 The color codes can be checked in output of the function `ble-color-show` (defined in `ble.sh`): 568 ```console 569 $ ble-color-show 570 ``` 571 572 ## 2.7 Key Bindings 573 574 Key bindings can be controlled with the shell function, `ble-bind`. 575 For example, with the following setting, "Hello, world!" will be inserted on typing <kbd>C-x h</kbd> 576 ```bash 577 ble-bind -f 'C-x h' 'insert-string "Hello, world!"' 578 ``` 579 580 The details on the key representation, such as <kbd>C-x h</kbd> in the above example, 581 are described in [Manual §3.1](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A73-Key-Binding#user-content-sec-kspecs). 582 The representations of <kbd>Space</kbd>, <kbd>Tab</kbd>, <kbd>Enter</kbd>, <kbd>Backspace</kbd>, <kbd>Escape</kbd>, etc. are described 583 in [Manual §3.1.1](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A73-Key-Binding#user-content-sec-kspecs-ret): 584 The space is represented as <kbd>SP</kbd>, 585 the tab key is represented as <kbd>C-i</kbd> or <kbd>TAB</kbd> depending on the terminal, 586 the enter/return key is represented as <kbd>C-m</kbd> or <kbd>RET</kbd> depending on the terminal, 587 and the backspace key is represented as <kbd>C-?</kbd>, <kbd>DEL</kbd>, <kbd>C-h</kbd>, or <kbd>BS</kbd> depending on the terminal. 588 The representations of modified special keys such as <kbd>Ctrl+Return</kbd> and <kbd>Shift+Return</kbd> are described 589 in [Manual §3.6.4](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A73-Key-Binding#user-content-sec-modifyOtherKeys-manual): 590 If your terminal does not support `modifyOtherKeys`, you need to manually configure the escape sequences of modified special keys. 591 592 593 For another example, if you want to invoke a command on typing <kbd>M-c</kbd>, you can write it as follows: 594 595 ```bash 596 ble-bind -c 'M-c' 'my-command' 597 ``` 598 599 Or, if you want to invoke a edit function (designed for Bash `bind -x`) on typing <kbd>C-r</kbd>, you can write it as follows: 600 601 ```bash 602 ble-bind -x 'C-r' 'my-edit-function' 603 ``` 604 605 The existing key bindings are shown by the following command: 606 ```console 607 $ ble-bind -P 608 ``` 609 610 The list of widgets is shown by the following command: 611 ```console 612 $ ble-bind -L 613 ``` 614 615 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` 616 as illustrated in the following example. 617 It is highly recommended to prefix the widget name with `YOUR_NAME/`, `my/`, `blerc/`, `dotfiles/`, etc. 618 in order not to conflict with the names of the existing standard widgets. 619 620 ```bash 621 # Example of calling multiple widgets with the key C-t 622 function ble/widget/my/example1 { 623 ble/widget/beginning-of-logical-line 624 ble/widget/insert-string 'echo $(' 625 ble/widget/end-of-logical-line 626 ble/widget/insert-string ')' 627 } 628 ble-bind -f C-t my/example1 629 ``` 630 631 ## 2.8 fzf integration 632 633 If you would like to use `fzf` in combination with `ble.sh`, you need to configure `fzf` using [the `contrib/fzf` integration](https://github.com/akinomyoga/blesh-contrib#pencil-fzf-integration). 634 Please follow the instructions in the link for the detailed description. 635 636 ```bash 637 # blerc 638 639 # Note: If you want to combine fzf-completion with bash_completion, you need to 640 # load bash_completion earilier than fzf-completion. 641 source /etc/profile.d/bash_completion.sh 642 643 ble-import -d integration/fzf-completion 644 ble-import -d integration/fzf-key-bindings 645 ``` 646 647 # 3 Tips 648 649 ## 3.1 Use multiline mode 650 651 When the command line string contains a newline character, `ble.sh` enters the MULTILINE mode. 652 653 By typing <kbd>C-v C-j</kbd> or <kbd>C-q C-j</kbd>, you can insert a newline character in the command line string. 654 In the MULTILINE mode, <kbd>RET</kbd> (<kbd>C-m</kbd>) causes insertion of a new newline character. 655 In the MULTILINE mode, the command can be executed by typing <kbd>C-j</kbd>. 656 657 When the shell option `shopt -s cmdhist` is set (which is the default), 658 <kbd>RET</kbd> (<kbd>C-m</kbd>) inserts a newline if the current command line string is syntactically incomplete. 659 660 ## 3.2 Use vim editing mode 661 662 If `set -o vi` is specified in `.bashrc` or `set editing-mode vi` is specified in `.inputrc`, the vim mode is enabled. 663 For details, please check [the wiki page](https://github.com/akinomyoga/ble.sh/wiki/Vi-(Vim)-editing-mode). 664 665 ## 3.3 Use `auto-complete` 666 667 The feature `auto-complete` is available in Bash 4.0 or later. `auto-complete` automatically suggests a possible completion on user input. 668 The suggested contents can be inserted by typing <kbd>S-RET</kbd> 669 (when the cursor is at the end of the command line, you can also use <kbd>right</kbd>, <kbd>C-f</kbd> or <kbd>end</kbd> to insert the suggestion). 670 If you want to insert only first word of the suggested contents, you can use <kbd>M-right</kbd> or <kbd>M-f</kbd>. 671 If you want to accept the suggestion and immediately run the command, you can use <kbd>C-RET</kbd> 672 (if your terminal does not support special key combinations like <kbd>C-RET</kbd>, please check 673 [Manual §3.6.4](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A73-Key-Binding#user-content-sec-modifyOtherKeys-manual)). 674 675 ## 3.4 Use `sabbrev` (static abbrev expansions) 676 677 By registering words to `sabbrev`, the words can be expanded to predefined strings. 678 When the cursor is just after a registered word, typing <kbd>SP</kbd> causes the `sabbrev` expansion. 679 For example, with the following settings, when you type <kbd>SP</kbd> after the string `command L`, the command line will be expanded to `command | less`. 680 681 ```bash 682 # blerc 683 ble-sabbrev L='| less' 684 ``` 685 686 The sabbrev names that starts with `\` plus alphabetical letters are also recommended since it is unlikely to conflict with real words that are a part of the executed command. 687 688 ```bash 689 # blerc 690 ble-sabbrev '\L'='| less' 691 ``` 692 693 694 # 4 Contributors 695 696 I received many feedbacks from many people in GitHub Issues/PRs. 697 I thank all such people for supporting the project. 698 Among them, the following people have made particularly significant contributions. 699 700 - [`@cmplstofB`](https://github.com/cmplstofB) helped me implementing vim-mode by testing it and giving me a lot of suggestions. 701 - [`@dylankb`](https://github.com/dylankb) reported many issues for fzf-integration, initialization, etc. 702 - [`@rux616`](https://github.com/rux616) reported several issues and created a PR for fixing the default path of `.blerc` 703 - [`@timjrd`](https://github.com/timjrd) suggested and contributed to performance improvements in completion. 704 - [`@3ximus`](https://github.com/3ximus) reported many issues for a wide variety of problems. 705 - [`@SuperSandro2000`](https://github.com/SuperSandro2000) reported many issues related to NixOS and others