dotfiles/bash
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

addet blesh

Browse source
This commit is contained in:
pika 2024-08-18 03:40:38 +02:00
parent 58205a50b9
commit 8c8d8e9962
302 changed files with 74275 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

348
.local/share/blesh/doc/CONTRIBUTING.md Normal file
View file

@ -0,0 +1,348 @@
# Contribution Guide
## How to contribute
### Issues
You can freely create an issue using the following links:
- Report and fixes for bugs and performance issues [[Here]](https://github.com/akinomyoga/ble.sh/issues/new?template=bug_report.md)
- Questions on usage [[Here]](https://github.com/akinomyoga/ble.sh/issues/new?template=feature_request.md)
- Feature request [[Here]](https://github.com/akinomyoga/ble.sh/issues/new?template=help.md)
- Others (suggestions, projects, discussion, complaints, news, information or anything) [[Here]](https://github.com/akinomyoga/ble.sh/issues/new?template=free_style.md)
### Pull requests
We always welcome the following types of pull requests. Any changes will be considered to be provided under the BSD 3-Clause License.
If you do not know whether your changes would be appropriate for merge, please feel free to create a pull request and let us talk with each other!
- Better translation to English, typo fixes
- Fixes, optimization, test cases
- New features
- New color themes ... We accept new themes in [`contrib`](https://github.com/akinomyoga/blesh-contrib/pulls) repository.
- Others
### Wiki
You can freely edit [wiki pages](https://github.com/akinomyoga/ble.sh/wiki).
- Translations
- Typo fixes
- Create new pages
## For package maintainers
If you are a package maintainer for a repository of Linux distribution, etc.
you may provide a package-specific setting by preparing
a file `/path/to/blesh/lib/_package.sh` (e.g. `/usr/share/blesh/lib/_package.sh`)
which will be sourced after the load of `ble.sh` just before sourcing user's configuration (`~/.blerc`).
- In the file, the shell variable `_ble_base_package_type=TYPE` should be
set up to have a repository-specific name (such as `AUR`).
- The function named `ble/base/package:TYPE/update` (where `TYPE`
matches with a value assigned to `_ble_base_package_type`) may be
provided to define a custom updating procedure. The exit status of the function can be
- `0` ... when the update succeeded
- `6` ... when the update was skipped because the package was up to date.
- `125` ... when it wants to fall back to the built-in updating procedure of `ble.sh`.
- Other ... when the update failed
An example `lib/_package.sh` might be
```bash
_ble_base_package_type=apt
function ble/base/package:apt/update {
sudo apt upgrade blesh
}
```
You can also find a real example for AUR (Arch User Repository) [here](https://aur.archlinux.org/cgit/aur.git/tree/blesh-update.sh?h=blesh-git).
## Summary of codebase
The core script file `ble.sh` is generated by combining the following files:
- `ble.pp` ... Basic initialiation
- `src/def.sh` ... Prototype definitions
- `src/util.sh` ... Basic utility functions
- `src/decode.sh` ... User-input decoder and keybindings
- `src/color.sh` ... Terminal graphic attributes
- `src/canvas.sh` ... Terminal layout engine
- `src/canvas.emoji.sh` ... Emoji database
- `src/history.sh` ... Command history management
- `src/edit.sh` ... Line editor
- `src/benchmark.sh` ... Measure processing time
- `lib/core-completion.sh` ... Prototype definition for completions
- `lib/core-syntax.sh` ... Prototype definitions for syntax analyzer
Useful features are implemented in separate modules:
- `lib/keymap.vi.sh` ... Vim mode
- `lib/vim-arpeggio.sh` ... `vim-arpeggio`-like plugin
- `lib/vim-surround.sh` ... `vim-surround`-like plugin
- `lib/keymap.emacs.sh` ... Emacs mode
- `lib/core-syntax.sh` ... Shell parser and syntax highlighting
- `lib/core-syntax-ctx.def` ... Definition of parser states
- `lib/core-complete.sh` ... Completions including `menu-complete`, `auto-complete`, `menu-filter`, `dabbrev`, `sabbrev`, etc.
The following files are initialization scripts:
- `lib/init-term.sh` ... Initialize terminal escape sequences (host-to-terminal, i.e. control sequences)
- `lib/init-cmap.sh` ... Initialize terminal escape sequences (terminal-to-host, i.e. key sequences)
- `lib/init-bind.sh` ... Initialize readline attacher
- `lib/init-msys1.sh` ... Workaround for MSYS1 with broken pipes
- `lib/init-msys1-helper.c` ... Helper C program for the workaround of broken pipes
The contrib repository contains configurations built on top of the `ble.sh` framework
- `contrib/config/*.bash` are specific configurations whose details may depend on the user's preferences. These are expected to work just by `ble-import` but at the same time serve as examples for the user's personal versions.
- `contrib/sample/*.bash` are examples to explain interfaces for configurations. These are just explanation of the interface so would not actually function.
- `contrib/airline/*.bash` are the themes for `vim-airline`.
- `contrib/integration/*.bash` are codes needed for the adjustments with other framework.
- `contrib/*.bash` are other miscellaneous configurations. Usually one needs additional configuration after `ble-import`. These files may be moved to another directory in the future.
## Tests
Tests can be run by one of the following commands:
```bash
$ make check
$ make check-all
$ bash out/ble.sh --test
```
Currently, test coverage is very small
partly because the testing for interactive behavior and terminal rendering results is hard.
Nevertheless, the tests are defined in the following files:
- `lib/core-test.sh` ... Library for tests
- `lib/test-bash.sh`
- `lib/test-main.sh`
- `lib/test-util.sh`
- `lib/test-canvas.sh`
- `lib/test-edit.sh`
- `lib/test-complete.sh`
- `lib/test-syntax.sh`
## Coding styles
These styles are not required for the initial PR as these are too complicated.
The maintainer(s) will apply the styles before merging.
Nevertheless, it would be useful to follow the styles when you are going to submit PRs many times.
### Naming convention for functions
The function names roughly have the following structure, but the rule is ambiguous to some extent, and there are also many exceptions in the codebase.
```ebnf
function_name = (namespace '/')* function_basename ;
namespace = function_basename ;
function_basename = name ext? (* namespace function *)
| class '.' name ext? (* class method *)
| class '#' name ext? (* instance method *)
| class '#' class '::' name ext? (* instance method (override) *)
| type ':' name ext? ; (* customization point *)
name = hyphenated_name (* public *)
| '.' hyphenated_name ; (* private *)
ext = '.hook' (* hook functions for blehook *)
| '.draw' (* function operating on DRAW_BUFF *)
| '.fib' (* worker for ble/util/fiberchain *)
| '.proc' (* callback functions *)
| '.impl' ; (* internal implementation *)
(* ... (and more extensions) *)
class = name ;
type = hyphenated_name ;
hyphenated_name = (word '-')* word ;
word = /[_a-zA-Z0-9]+/ ;
```
The function names are basically hyphenated words (such as `foo-bar-baz` instead of `foo_bar_baz`, `fooBarBaz`, or `FooBarBaz`).
**Namespace**--The function names can be prefixed by namespaces of the form `<namespace>/`.
Except for the functions intended to be called from the command line or the user configuration, all the functions should be defined in a namespace.
The interface of the functions defined in a namespace is subject to change in the future.
A function name can also be used as the namespace name for the helper functions to implement the function.
For the functions defined in external modules, the following namespace should be used to avoid conflicts:
| Types | Namespace |
|:----------------------------------------------------|----------------------------------------|
| `contrib/*.bash` | `ble/contrib/<modulename>` |
| `contrib/config/*.bash` | `ble/contrib/config:<modulename>` |
| `contrib/integration/*.bash` | `ble/contrib/integration:<modulename>` |
| User's public config | e.g. `<user>` |
| User's private config | e.g. `<user>` or `my` |
| User's private config in Bash initialization file | e.g. `<user>`, `my` or `bashrc` |
| User's private config in ble.sh initialization file | e.g. `<user>`, `my` or `blerc` |
**Private**--The function basename started with `.` is considered private within the namespace. All the other functions are public.
**Method**--The function basename of the form `<class>#<name>` is considered an instance method.
The function basename of the form `<class>.<name>` is considered a class method.
The difference between the two is the latter assumes a single global state while the former assumes that an instance is specified by the first argument or by other means.
The way to specify the instance depends on the class.
For example, `ble/array#*` receives the variable name as the first argument while `ble/string#*` directly receives the string value as the first argument.
For `ble/textarea#*`, the target instance is selected by the shell variable `_ble_textarea_panel`.
The function basename of the form `<class1>#<class2>::<name>` is used to define a virtual function called by the base class `<class2>` at the side of the derived class `<class1>`.
**Customization point**--The function basename of the form `<type>:<name>` is used to provide the customization point for dynamic values.
This function is typically called as `<type>:"$var"` with `var` contains a value that depends on the context including the currently selected class, user configuration, etc.
**Extension**--The extension `<ext>` can be used to mark the specific types of functions.
### Naming convention for variables
The variable names roughly have the following structure.
```ebnf
local_variable_name = varname
| '__ble_' varname
| '_ble_local_' varname ;
global_variable_name = ('_' namespace)* '_' varname ;
namespace = word ;
varname = (word '_')* word ;
word = /[a-zA-Z0-9]+/ ;
```
The variable names are basically lowercase underscored words such as `foo_bar_baz` (instead of `fooBarBaz` or `FooBarBaz`).
Some global constants and the exported variables have all-uppercase names, but the lowercase should be basically used.
**Local variables**--The local variables that are only used in the declared function should be basically unprefixed by an underscore.
When the function reads/returns a value through an arbitrary name of <i>in</i>/<i>out</i> variables,
the local variable declared within the function should be prefixed by `__ble_` or `_ble_local_` to avoid the name conflicts between the local and in/out variables.
**Global variables**--All the global variables, except for the variables that are intended to be directly modified from the command line, should be prefixed by `_`.
Currently, there are no variables intended to be directly modified from the command line<sup><b>[Note 1]</b></sup>.
The variables defined in external modules should be namespaced by the module name.
The variables in modules in the `contrib` repository should have the prefix `_ble_contrib_<module_name>_`
- <sup><b>[Note 1]</b></sup> In the initial implementation of ble.sh, the ble.sh options are provided as shell variables `bleopt_*`.
As remnant or for backward compatibility, the values of ble.sh options are still stored in the variables of the name `bleopt_*`,
but these variables for the ble.sh options will be renamed in the future.
### Function interface
The success/failure states should be returned by the exit status.
**`ret`**--All the other values should be basically returned through shell variables.
This is because, if a function returned its result through the standard output,
the caller would need to capture the results by a command substitution which involves a fork of a subshell and thus is slow.
Here, efficiency is the primary interest, so there are exceptions where the standard output can be more efficient:
For example, when the output needs to be saved to a file for later use or to be passed to a different process,
or when the output needs to be processed by the external commands that read the standard input.
The variable name to return a value should be basically `ret` unless the purpose of the function is to store values.
When the function basename has the form `get-<name>`, one should consider returning the result through the shell variable named `<name>`.
When a function returning multiple values is called from many places, the function may receive an array name as the first argument and store the result in the specified array.
When the <i>out</i> variable names are specified in the arguments, they should come first in the list of the arguments.
**`opts`**--The argument position should be basically fixed (e.g., never shifted by optional arguments like `-f` or `-o name`).
The optional arguments can be specified by colon-separated fields (like `SHELLOPTS` or `BASHOPTS`)
instead of the Unix-style flags and options like `-f` and `-o optarg`.
This is because the parsing of the Unix-style arguments (with or without `getopts`) is usually slow.
The local variable that receives the colon-separated option typically has the name `opts` or `*opts` (e.g. `local opts=$2`).
A single option has the form `name` or `name=value`,
where `name` should be hyphenated words like `foo-bar-baz`.
The former form without the value is called a flag option.
One can test a flag option by `[[ :$opts: == *:flag-name:* ]]`.
An option of the form `name=value` can be matched by `ble/opts#extract-first-optarg`, `ble/opts#extract-last-optarg`, or `ble/opts#extract-all-optargs`.
The function `ble/opts#has` can be used to test if either `name` or `name=value` is contained
**`$*`**--The functions that receive a string should not allow a variable number of arguments that are joined inside the function.
A variable number of arguments should be used only when each argument is really processed separately.
If necessary, the joining should be performed at the caller side.
This is because `IFS` in the caller context affects the joining `$*`, so the handling of `IFS` should be properly done at the caller side.
Another reason is for the future extension, e.g., to add another optional argument.
### Variable declarations
Local variables should be declared by `local` (instead of `declare` or `typeset`).
Variables should be always initialized before referencing their values. This is because uninitialized variables can have random values when `shopt -s localvar_inherit` is turned on.
The declaration and the initialization of an array variable should be separated as far as the initializer values contain any expansions or spaces.
There is a bug in Bash 3.0 that the values are separated by whitespaces even when the values are quoted.
When the declaration and the initialization of an array variable are made in a single command, the option `-a` needs to be specified.
Without `-a`, the entire list `(...)` including the surrounding parens will be treated as a scalar string in Bash 3.0.
```bash
local v; v=("$var")
local -a v=()
# The following may not work as expected
# local v=() # Bash 3.0 will initialize a scalar with the value v='()' #D0184
# local -a v=("a b") # Bash 3.0 will split it into the two elements "a" and "b" #D0525
```
Defining local readonly variables should be avoided
because they will hide global variables from the utilities `ble/variable#is-global`, `ble/util/print-global-definitions`, etc.
Global readonly variables should never be defined.
The background is described in the Limitation section of README.
### Conditional commands `[[ ... ]]`
Do not use `[ ... ]` or `test` unless it is intended to be a POSIX script. Always use `[[ ... ]]`.
Use `[[ word ]]` and `[[ ! word ]]` instead of `[[ -n word ]]` and `[[ -z word ]]`.
Use `==` instead of the operator `=` inside conditional commands.
**Quoting**--The right-hand sides of `==` and `!=` inside conditional commands `[[ ... ]]` should be properly quoted.
The right-hand sides of `=~` inside the conditional commands `[[ ... ]]` should be specified by a single parameter expansion
as `[[ word =~ $rex ]]`, or one can use `ble/string#match 'word' "$rex"` instead.
In other contexts, the arguments of the conditional command should not be quoted
unless raw special characters ``[[:space:]|&;<>\`"$]`` are contained in the argument.
**No `-eq` etc**--Basically use arithmetic commands `((expr))`
instead of the operators `-eq`, `-ne`, `-gt`, `-ge`, `-lt`, and `-le` of the conditional command.
They might be used when the test is used as a part of complicated conditions in the conditional commands.
For example, `[[ -f $file || $word && word -eq 0 ]]` can be used instead of `[[ -f $file ]] || { [[ $word ]] && ((word == 0)); }` because sticking with the arithmetic command would unnecessarily complicate the code in this case.
### Other styles
**Function definition**--There are two forms of function definitions, the POSIX style `func()` and the ksh style `function func`, as well as the mixed form.
We always use the ksh style of the function definition.
The reasons are that it is easier to search by the keyword `function ` and that it is protected by the aliases of the same name as the function (unless the user defines an alias with the same name as the keyword `function`).
The function body is always the compound command `{ ... }` (instead of any other compound commands such as `( ... )`, `for`, `if`, etc.), and the opening brace `{` is placed on the first line.
```bash
function function-name {
: do_something
}
```
**`ble/util/print`**--Use `ble/util/print` instead of `echo`. Use `ble/util/put` instead of `echo -n`.
The control characters should be directly specified by the escape string literal `$'...'` instead of relying on the conversion by `echo -e`.
This is because the builtin `echo` can change its behavior depending on the shell option `shopt -s xpg_echo`, where the backslashes in the arguments might have special meaning.
`ble.sh` is intended to work under any possible user options.
**Quote/unquote**--The arguments where the word splitting and pathname expansions can take place need to be always quoted.
When the subject word of the `case` statement and the right-hand sides of variable assignments
(including those specified to assignment builtins `declare`, `typeset`, `local`, `export`, and `readonly`)
contains `$*`, `${arr[*]}`, or raw special characters ``[[:space:]|&;<>\`"$]``, they need to be quoted.
In other contexts, the subject word of `case` and the right-hand sides of variable assignments should not be quoted.
In these contexts, the word splitting and pathname expansions will never happen, so the quoting is unnecessary.
Array subscripts are arithmetic context, so the arithmetic expansions `$((expr))` inside the array subscripts are redundant. One should simply write it as `arr[expr]` instead of `arr[$((expr))]`.
**`ble/util/assign`**--Use `ble/util/assign`, `ble/util/assign-array`, and `ble/util/assign-words` instead of `var=$(cmd)`, `mapfile -t var <<< "$(cmd)"`, and `var=($(cmd))`, respectively.
The command substitutions `$(...)` are slow because they involve the forks of subshells.
**External commands**--Implement it using built-in Bash features as much as possible.
If the same result can be obtained by built-in Bash features efficiently, do not use the external commands.
When the external command is used, first freeze the path by calling `ble/bin#freeze-utility-path '<cmd>'` and call the commands through `ble/bin/<cmd>`.
Or save the path of the external command in a variable, and call the command through the variable as `"$_saved_cmd" args...`.
The POSIX commands should be basically used. If non-POSIX commands are used, a POSIX fallback should be always prepared.
Please combine multiple calls of external commands into a single call of the command as much as possible.
Usually, a single call of `sed` and `awk` is preferred over the chain of simple commands.

3198
.local/share/blesh/doc/ChangeLog.md Normal file
View file

File diff suppressed because it is too large Load diff

12
.local/share/blesh/doc/LICENSE.md Normal file
View file

@ -0,0 +1,12 @@
Copyright (c) 2013, 2015-2023, K. Murase @akinomyoga <myoga.murase@gmail.com>,
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

768
.local/share/blesh/doc/README-ja_JP.md Normal file
View file

@ -0,0 +1,768 @@
[ Languages: [English](README.md) (英語) | **日本語** ]
<h1 align="center"><ruby>ble.sh<rp> (</rp><rt>/blɛʃ/</rt><rp>)</rp></ruby> ―Bash Line Editor―</h1>
<p align="center">
[ <b>README</b> | <a href="https://github.com/akinomyoga/ble.sh/wiki/%E8%AA%AC%E6%98%8E%E6%9B%B8-%C2%A71-%E5%9F%BA%E6%9C%AC">説明書</a> |
<a href="https://github.com/akinomyoga/ble.sh/wiki/%E8%B3%AA%E5%95%8F%E3%81%A8%E5%9B%9E%E7%AD%94">Q&A</a> |
<a href="https://github.com/akinomyoga/blesh-contrib"><code>contrib</code></a> |
<a href="https://github.com/akinomyoga/ble.sh/wiki/%E9%80%86%E5%BC%95%E3%81%8D%E3%83%AC%E3%82%B7%E3%83%94">逆引き</a> ]
</p>
`ble.sh` (*Bash Line Editor*) はピュア Bash スクリプトで書かれたコマンドラインエディタで、標準の GNU Readline を置き換える形で動作します。
現在の開発バージョンは 0.4 です。
このスクリプトは Bash 3.0 以降で利用できますが、速度・機能などの観点から 4.0 以降のリリース版 Bash でお使い頂くことがお薦めです。
現時点では、文字コードとして `UTF-8` のみの対応です。
このスクリプトは [**BSD License**](LICENSE.md) (3条項 BSD ライセンス) の下で提供されます。
免責: ラインエディタ本体は **ピュア Bash** で書かれていますが、
ユーザーコマンド実行時には TTY 設定の為に `stty` (POSIX) を呼び出します。
他にも処理の高速化の為に、初期化・終了処理、
巨大なデータの処理 (補完、貼り付けなど) の局面でPOSIX 標準コマンドを利用しています。
呼称: `ble.sh` はお好きな様に読んでいただいて問題ありませんが、一番短いのは標記の /blɛʃ/ になりましょう。
しかし個人的には脳裡で /biːɛliː/ または /biːɛliː dɑt ɛseɪtʃ/ と読んでいるものですから、標記の読み方は飽くまで参考と受け止めていただければ幸いです。
## 簡単設定
`ble.sh` をお使いいただくには Bash 3.0 以上 (及び POSIX の基本的なコマンド) が必要です。
<!-- 但し、macOS では附属の `/usr/bin/awk` (awk-32 以降) でマルチバイト文字セットの問題があるため、`gawk`, `nawk`, または `mawk` を別途インストールする必要があるかもしれません。 -->
`ble.sh` を取得するには主に2つの方法があります: `git` を用いてソースを取得しビルドする方法と `curl` または `wget` を用いて nightly ビルドをダウンロードする方法です。
詳細は、試用またはインストールに関しては [節1.1](#get-from-source) と [節1.2](#get-from-tarball) を、
`~/.bashrc` の設定に関しては [節1.3](#set-up-bashrc) を御覧ください。
> [!NOTE]
> `fzf` を `ble.sh` と組み合わせてお使いの場合は [節2.8](#set-up-bashrc) を必ず
> 御覧ください。
<details open><summary><b><code>git</code> を用いてソースを取得し <code>ble.sh</code> を生成</b></summary>
この方法では `git`, `make` (GNU make), 及び `gawk` が必要です。
以下、GNU make が `gmake` として提供されているシステム (BSD など) では、`make` を `gmake` に置き換えて実行してください。
```bash
# 簡単お試し (インストールせずにお試しいただけます)
git clone --recursive --depth 1 --shallow-submodules https://github.com/akinomyoga/ble.sh.git
make -C ble.sh
source ble.sh/out/ble.sh
# インストール & .bashrc 簡単設定 (動かない場合は節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
```
生成過程では、複数のBashスクリプトファイルを前処理・結合することで `ble.sh` を生成し、
他の関連ファイルを正しく配置し、またソースコード中のコードコメントを削除してロードを最適化します。
※生成過程は、C/C++ のコンパイルも伴わずバイナリも生成しませんので、コンパイラを準備していただく必要はありません。
</details>
<details><summary><b><code>curl</code> を用いて nightly ビルドをダウンロード</b></summary>
この方法では `curl`, `tar` (オプション `J` に対応), 及び `xz` (XZ Utils) が必要です。
```bash
# 簡単お試し (インストールせずにお試しいただけます)
curl -L https://github.com/akinomyoga/ble.sh/releases/download/nightly/ble-nightly.tar.xz | tar xJf -
source ble-nightly/ble.sh
# インストール & .bashrc 簡単設定 (動かない場合は節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
```
インストール後はディレクトリ `ble-nightly` は削除して問題ありません。
</details>
<details><summary><b><code>wget</code> を用いて nightly ビルドをダウンロード</b></summary>
この方法では `wget`, `tar` (オプション `J` に対応), 及び `xz` (XZ Utils) が必要です。
```bash
# 簡単お試し (インストールせずにお試しいただけます)
wget -O - https://github.com/akinomyoga/ble.sh/releases/download/nightly/ble-nightly.tar.xz | tar xJf -
source ble-nightly/ble.sh
# インストール & .bashrc 簡単設定 (動かない場合は節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
```
インストール後はディレクトリ `ble-nightly` は削除して問題ありません。
</details>
<details open><summary><b>パッケージ管理システムを通じてパッケージをインストール</b> (現在限られたパッケージのみ)</summary>
この方法では対応するパッケージ管理ツールのみが必要です。
- [AUR (Arch Linux)](https://github.com/akinomyoga/ble.sh/wiki/Manual-A1-Installation#user-content-AUR) `blesh-git` (devel), `blesh` (stable 0.3.4)
- [NixOS (nixpkgs)](https://github.com/akinomyoga/ble.sh/wiki/Manual-A1-Installation#user-content-nixpkgs) `blesh` (devel)
- [Guix](https://packages.guix.gnu.org/packages/blesh/0.4.0-devel2/) `blesh` (0.4.0-devel2)
</details>
<details open><summary><b>既存の <code>ble.sh</code> を更新</b></summary>
```bash
# 更新 (ble.sh をロードした状態で)
ble-update
# 更新 (ble.sh 外部から)
bash /path/to/ble.sh --update
```
</details>
<details><summary><b><code>ble.sh</code> のパッケージ作成</b></summary>
`ble.sh` は単にシェルスクリプトの集合ですので環境に依存せずにお使いいただけます (いわゆる "`noarch`") ので、
単にリリースページからビルド済みの tar ボールをダウンロードし中身を `/tmp/blesh-package/usr/local` など所定の位置に配置するだけで問題ありません。
それでも何らかの理由により自前でビルドする必要がある場合には以下のコマンドをお使いください。
ビルドの為には git リポジトリ (`.git`) が必要になることにご注意ください。
```bash
# ビルド & パッケージ作成用コマンド
git clone --recursive --depth 1 --shallow-submodules https://github.com/akinomyoga/ble.sh.git
make -C ble.sh install DESTDIR=/tmp/blesh-package PREFIX=/usr/local
```
パッケージ管理システムを用いたパッケージ更新方法を指定すると `ble-update` でそれが呼び出されます。
更新方法を指定するにはスクリプトファイルを `${prefix}/share/blesh/lib/_package.bash` に配置します。
スクリプトは次の様な変数と関数を定義します。但し `XXX` はパッケージ管理システムの名前に置き換えてください。
```bash
# ${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
}
```
シェル関数がステータス 0 で終了した場合、更新が成功した事を表し `ble.sh` のリロードが自動的に行われます。
シェル関数がステータス 6 で終了した場合、`ble.sh` のタイムスタンプが確認され、`ble.sh` が現セッションの開始時刻よりも新しい時に限りリロードが行われます。
シェル関数がステータス 125 で終了した場合、`ble.sh` に組み込みの更新処理が試みられます。
それ以外の場合には更新処理が中断されます。この場合、シェル関数が状況を説明するメッセージを出力するようにして下さい。
具体例として `AUR` パッケージの [`_package.bash`](https://aur.archlinux.org/cgit/aur.git/tree/blesh-update.sh?h=blesh-git) も参考にしていただければ幸いです。
</details>
## 機能概要
- **構文着色**: `fish` や `zsh-syntax-highlighting` のような文法構造に従った着色を行います。
`zsh-syntax-highlighting` のような単純な着色ではなく、構文の入れ子構造や複数のヒアドキュメントなども正しく解析して着色します。
着色は[全て設定可能](https://github.com/akinomyoga/ble.sh/wiki/%E8%AA%AC%E6%98%8E%E6%9B%B8-%C2%A72-%E6%8F%8F%E7%94%BB)です。
- **補完増強**: [補完](https://github.com/akinomyoga/ble.sh/wiki/%E8%AA%AC%E6%98%8E%E6%9B%B8-%C2%A77-%E8%A3%9C%E5%AE%8C)を大幅に増強します。
**文法構造に応じた補完**、クォートやパラメータ展開を展開した上でのプログラム補完、**曖昧補完**に対応しています。
また、候補をカーソルキーや <kbd>TAB</kbd>, <kbd>S-TAB</kbd> で選択できる
[**メニュー補完**](https://github.com/akinomyoga/ble.sh/wiki/%E8%AA%AC%E6%98%8E%E6%9B%B8-%C2%A77-%E8%A3%9C%E5%AE%8C#user-content-sec-menu-complete)、
`fish` や `zsh-autosuggestions` のような
[**自動補完**](https://github.com/akinomyoga/ble.sh/wiki/%E8%AA%AC%E6%98%8E%E6%9B%B8-%C2%A77-%E8%A3%9C%E5%AE%8C#user-content-sec-auto-complete)
(Bash 4.0 以上) の機能もあります。
更に、従来 `peco` や `fzf` を呼び出さなければならなかった補完候補の絞り込みも
[**メニュー絞り込み**](https://github.com/akinomyoga/ble.sh/wiki/%E8%AA%AC%E6%98%8E%E6%9B%B8-%C2%A77-%E8%A3%9C%E5%AE%8C#user-content-sec-menu-filter)
(Bash 4.0 以上) として自然な形で組み込んでいます。
他に、[**動的略語展開**](https://github.com/akinomyoga/ble.sh/wiki/%E8%AA%AC%E6%98%8E%E6%9B%B8-%C2%A77-%E8%A3%9C%E5%AE%8C#user-content-sec-dabbrev)
や、[*zsh abbreviations*](https://unix.stackexchange.com/questions/6152/zsh-alias-expansion)・[`zsh-abbr`](https://github.com/olets/zsh-abbr) のような
[**静的略語展開**](https://github.com/akinomyoga/ble.sh/wiki/%E8%AA%AC%E6%98%8E%E6%9B%B8-%C2%A77-%E8%A3%9C%E5%AE%8C#user-content-sec-sabbrev)
にも対応しています。
- **Vim編集モード**: `set -o vi` による編集モードを増強します。
挿入・ノーマルモードの他に(行・矩形)ビジュアルモード、置換モードなどの各種モードに対応しています。
テキストオブジェクト・各種レジスタ・オペレータ・キーボードマクロなどにも対応しています。
拡張として `vim-surround` も提供しています。
- 他にも
[**ステータス行**](https://github.com/akinomyoga/ble.sh/wiki/%E8%AA%AC%E6%98%8E%E6%9B%B8-%C2%A74-%E7%B7%A8%E9%9B%86#user-content-bleopt-prompt_status_line),
[**コマンド履歴共有**](https://github.com/akinomyoga/ble.sh/wiki/%E8%AA%AC%E6%98%8E%E6%9B%B8-%C2%A74-%E7%B7%A8%E9%9B%86#user-content-bleopt-history_share),
[**右プロンプト**](https://github.com/akinomyoga/ble.sh/wiki/%E8%AA%AC%E6%98%8E%E6%9B%B8-%C2%A74-%E7%B7%A8%E9%9B%86#user-content-bleopt-prompt_rps1),
[**過渡的プロンプト**](https://github.com/akinomyoga/ble.sh/wiki/%E8%AA%AC%E6%98%8E%E6%9B%B8-%C2%A74-%E7%B7%A8%E9%9B%86#user-content-bleopt-prompt_ps1_transient),
[**xterm タイトル**](https://github.com/akinomyoga/ble.sh/wiki/%E8%AA%AC%E6%98%8E%E6%9B%B8-%C2%A74-%E7%B7%A8%E9%9B%86#user-content-bleopt-prompt_xterm_title),
など様々な機能に対応しています。
注意: `ble.sh` は、(プロンプト (`PS1`)、エイリアス、関数などを提供する) 典型的な Bash 設定集と異なります。
`ble.sh` はより低層の基盤を提供するもので、ユーザは自分でプロンプトやエイリアスを設定する必要があります。
勿論 [`bash-it`](https://github.com/Bash-it/bash-it) や [`oh-my-bash`](https://github.com/ohmybash/oh-my-bash) の様な他の Bash 設定と一緒に使っていただくことも可能です。
> デモ
>
> ![ble.sh demo gif](https://github.com/akinomyoga/ble.sh/wiki/images/trial1.gif)
## 来し方行く末
このプロジェクトは初めは `.bashrc` の片隅で行われた小さな実験からスタートしました。
2013年5月に `zsh-syntax-highlighting` のとある記事に触発されたのがきっかけでした。
初めは数百行のコードを書けば構文着色が簡単に実現できるのではないかと思って始めた実験ですが、
すぐに行エディタを根本から書き直さなければ実現できないのではないかということが分かり、
独立したファイルにコードを移動した後に `ble.sh` という名前を与えました。
この名前は Zsh の行エディタ (*ZLE* (*Zsh Line Editor*)) を真似て、
但しシェルで書かれているという事を意識して `.sh` という拡張子にしたように記憶しています。
`ble.sh` の読み方について屡々訊かれるのですが、最初に書いたように特に定まった読み方はありません。
最初の実験は2週間程コードを弄って原理的に行エディタを作れるという事を結論づけて終わりました。
本格的な実装が始まったのは2015年2月の事で12月には公開しました。
その時点で行エディタとしては普段遣いに堪える程度に完成していました。
Vimモードの実装は2017年9月に始まり2018年3月に一先ず完成としました。
続いて補完の拡張は2018年8月に始まり2019年2月には一通り完成しました。
現在は漫然とメンテナンスしている所でいつになるかは分かりませんが、以下に挙げるような機能も加えたいと何となく考えています。
- 2013-06 v0.0 -- 実験
- 2015-12 v0.1 -- 構文着色 [[v0.1.15](https://github.com/akinomyoga/ble.sh/releases/tag/v0.1.15)]
- 2018-03 v0.2 -- Vim モード [[v0.2.7](https://github.com/akinomyoga/ble.sh/releases/tag/v0.2.7)]
- 2019-02 v0.3 -- 拡張補完 [[v0.3.4](https://github.com/akinomyoga/ble.sh/releases/tag/v0.3.4)]
- 20xx-xx v0.4 (plan) -- プログラム着色 [[nightly build](https://github.com/akinomyoga/ble.sh/releases/tag/nightly)]
- 20xx-xx v0.5 (plan) -- TUI設定画面
- 20xx-xx v0.6 (plan) -- エラー診断?
## 制限および前提
`ble.sh` の実装形態から来る制限があります。
ユーザー設定や他の Bash の枠組みとの干渉によって問題が起こる可能性があります。
- 既定では、実行コストの都合上、`ble.sh` は前回のコマンドライン実行後の `PIPESTATUS` を設定しません。代わりに `BLE_PIPESTATUS` を参照することができます。
もし本当に `PIPESTATUS` 経由でこれらの値を利用する必要がある場合には設定 `bleopt exec_restore_pipestatus=1` を使用して下さい。
- 既定では、よりなめらかな描画の為に、`ble.sh` は `PROMPT_COMMAND` および `PRECMD` フックが端末内のカーソル位置およびレイアウトを変更しないことを想定します。
`PROMPT_COMMAND` および `PRECMD` で出力を行うまたはカーソル位置を変更する設定をお持ちの場合は、設定 `bleopt prompt_command_changes_layout=1` を使用してください。
- `ble.sh` は一般的な変数名のシェル変数や環境変数 (`LC_*` など) がグローバルで読み込み専用変数になっていないことを想定します。
Bash ではグローバル変数の読み込み専用属性は関数のローカルスコープに於いても制限を与えます。
つまり、同名の異なるローカル変数さえ定義することができません。
この問題は `ble.sh` 固有の制限ではなく、あらゆる Bash の枠組みがグローバルの読み込み専用変数に影響を受けます。
一般的にグローバルスコープに読み込み変数を設定することはセキュリティ的な理由がない限りは非推奨と考えられています (参照 [[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))。
また、`ble.sh` はビルトインコマンド `readonly` をシェル関数で置き換え、グローバル変数を読み込み専用にするのをブロックします。
例外として、全て大文字の変数 (`ble.sh` が内部使用するものを除く) および `_*` の形の変数 (`_ble_*` および `__ble_*` を除く) を読み込み専用にすることは可能です。
- `ble.sh` は Bash のビルトインコマンド (`trap`, `readonly`, `bind`, `history`, `read`, `exit`) をシェル関数で上書きし、`ble.sh` と干渉しないようにその振る舞いを調整します。
ユーザーまたは他の枠組みが元のビルトインを直接呼び出した場合、または `ble.sh` の定義したシェル関数を別のシェル関数で上書きした場合、正しい動作を保証できません。
- シェル及び端末の設定はラインエディタ用とコマンド実行用で異なります。`ble.sh`
はラインエディタ向けに必要な調整を行い、ユーザが指定したコマンド実行用の設定
をできるだけ復元します。但し、様々な理由により、一部の設定については意図的に
復元しない場合や復元することができない場合があります。詳細については
[wiki](https://github.com/akinomyoga/ble.sh/wiki/Internals#internal-and-external)
(英語) に情報があります。
# 1 使い方
## 1.1 最新の git repository のソースから生成して試す (バージョン ble-0.4)<sup><a id="get-from-source" href="#get-from-source">†</a></sup>
### ble.sh 生成
`ble.sh` を生成する為には `gawk` (GNU awk) と `gmake` (GNU make) が必要です。
以下のコマンドで生成できます。
GNU make が `gmake` という名前でインストールされている場合は、`make` の代わりに `gmake` として下さい。
```console
$ git clone --recursive https://github.com/akinomyoga/ble.sh.git
$ cd ble.sh
$ make
```
スクリプトファイル `ble.sh` がサブディレクトリ `ble.sh/out` 内に生成されます。
### 試用
生成された `ble.sh` は `source` コマンドを用いてお試しいただけます。
```console
$ source out/ble.sh
```
### インストール
指定したディレクトリにインストールするには `make install` コマンドを使用します。
```bash
# ~/.local/share/blesh にインストール
make install
# 指定したディレクトリにインストール
make install INSDIR=/path/to/blesh
# パッケージ作成用 (パッケージ管理者用)
make install DESTDIR=/tmp/blesh-package PREFIX=/usr/local
```
Make 変数 `DESTDIR` または `PREFIX` が指定されている時、`ble.sh` は `$DESTDIR/$PREFIX/share/blesh` にコピーされます。
それ以外で Make 変数 `INSDIR` が指定されている時、直接 `$INSDIR` にインストールされます。
更にそれ以外で環境変数 `$XDG_DATA_HOME` が指定されている時、`$XDG_DATA_HOME/blesh` にインストールされます。
以上の変数が何れも指定されていない時の既定のインストール先は `~/.local/share/blesh` です。
インストール時にコード中のコメントは自動で削除されますが、コメントを保持したい場合は `strip_comment=no` を `make` の引数に指定して下さい。
`.bashrc` の設定に関しては[節1.3](#set-up-bashrc)を御覧ください。
## 1.2 GitHub Releases から tar をダウンロードして使う<sup><a id="get-from-tarball" href="#get-from-tarball">†</a></sup>
ダウンロード・試用・インストールの方法については各リリースページの説明を御覧ください。
現在、安定版は開発版に比べてかなり古いので様々な機能が欠けている事にご注意下さい。
- 開発版 [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)
- 安定版 [v0.3.4](https://github.com/akinomyoga/ble.sh/releases/tag/v0.3.4) (2019-02 fork) 拡張補完
- 安定版 [v0.2.7](https://github.com/akinomyoga/ble.sh/releases/tag/v0.2.7) (2018-03 fork) Vim モード
- 安定版 [v0.1.15](https://github.com/akinomyoga/ble.sh/releases/tag/v0.1.15) (2015-12 fork) 構文着色
## 1.3 `.bashrc` に設定する<sup><a id="set-up-bashrc" href="#set-up-bashrc">†</a></sup>
対話シェルで常用する場合には `.bashrc` に設定を行います。
単に `ble.sh` を `source` して頂くだけでも大抵の場合動作しますが、
より確実に動作させる為には以下の様にコードを記述します。
```bash
# bashrc
# .bashrc の先頭近くに以下を追加して下さい。
[[ $- == *i* ]] && source /path/to/blesh/ble.sh --noattach
# 間に通常の bashrc の内容を既述します。
# .bashrc の末端近くに以下を追加して下さい。
[[ ${BLE_VERSION-} ]] && ble-attach
```
`source /path/to/ble.sh` 及び `ble-attach` を呼び出す時は、
標準ストリーム (`stdin`, `stdout`, `stderr`) が現在のセッションの制御端末とは別の物にリダイレクトされていない様にして下さい。
`source /path/to/ble.sh` をシェル関数の中から実行するのは避けて下さい。
この「より確実な設定」が必要になる詳細な条件については [Discussion #254 への回答 (英語)](https://github.com/akinomyoga/ble.sh/discussions/254#discussioncomment-4284757) で説明されています。
## 1.4 初期化スクリプト `~/.blerc` について
ユーザー設定は初期化スクリプト `~/.blerc` (またはもし `~/.blerc` が見つからなければ `${XDG_CONFIG_HOME:-$HOME/.config}/blesh/init.sh`) に記述します。
テンプレートとしてリポジトリの [`blerc.template`](https://github.com/akinomyoga/ble.sh/blob/master/blerc.template) というファイルを利用できます。
初期化スクリプトは `ble.sh` ロード時に自動で読み込まれる Bash スクリプトなので、Bash で使えるコマンドを初期化スクリプトの中で利用できます。
初期化スクリプトの位置を変更する場合には、`source ble.sh` 時に `--rcfile INITFILE` を指定します。以下に例を挙げます。
```bash
# 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
```
## 1.5 アップデート
Git (`git'), GNU awk (`gawk`), 及び GNU make (`make`) が必要になります。
`ble-0.3` 以上をお使いの場合は `ble.sh` をロードした状態で `ble-update` を実行して下さい。
```bash
$ ble-update
```
`ble-0.4` 以上をお使いの場合は `ble.sh` をロードしなくても以下のコマンドで更新可能です。
```bash
$ bash /path/to/ble.sh --update
```
それ以外の場合には、以下のように `git pull` で最新版を入手・インストールできます。
```bash
cd ble.sh # ※既に持っている git リポジトリに入る
git pull
git submodule update --recursive --remote
make
make INSDIR="$HOME/.local/share/blesh" install
```
## 1.6 アンインストール
基本的に `ble.sh` ディレクトリとユーザの追加した設定を単に削除していただければ問題ありません。
- 全ての `ble.sh` セッション (`ble.sh` をロードしている Bash 対話セッション) を終了します。
- 関連するユーザーデータを削除します。これらのデータを保持しておきたい場合は必要に応じてスキップしてください。
- `.bashrc` に追加した行があれば削除します。
- `blerc` 設定ファイル (`~/.blerc` または `~/.config/blesh/init.sh`) があれば削除します。
- 状態ディレクトリ `~/.cache/blesh` が生成されていればそれを削除します。
- `ble.sh` をインストールしたディレクトリを削除します。git リポジトリ内の
`out/ble.sh` を直接ご使用の場合はインストールしたディレクトリは、git リポジト
リ自体です。`make intall` を用いてインストールした場合は、インストールしたディ
レクトリは `<PREFIX>/share/blesh` です。但し、`<PREFIX>` (既定値: `~/.local`)
は `make install` に指定した `PREFIX` の値です。生成済み tarball をご利用の際
には、インストールしたディレクトリは tarball を展開して得られたディレクトリを
配置した場所です。
- キャッシュディレクトリ `~/.cache/blesh` が生成されていればそれを削除します。
- 一時ディレクトリ `/tmp/blesh` が生成されていればそれを削除します。これは `/tmp` の内容が自動的にクリアされないシステムで必要です。
# 2 基本設定
ここでは `~/.blerc` に記述する基本的な設定を幾つか紹介します。
[質問と回答](https://github.com/akinomyoga/ble.sh/wiki/%E8%B3%AA%E5%95%8F%E3%81%A8%E5%9B%9E%E7%AD%94)、
[逆引きレシピ](https://github.com/akinomyoga/ble.sh/wiki/%E9%80%86%E5%BC%95%E3%81%8D%E3%83%AC%E3%82%B7%E3%83%94)、
[`contrib` リポジトリ](https://github.com/akinomyoga/blesh-contrib/blob/master/README-ja.md) にも便利な設定があります。
その他の全ての設定項目はテンプレート [`blerc.template`](https://github.com/akinomyoga/ble.sh/blob/master/blerc.template) に含まれています。
詳細な説明に関しては[説明書](https://github.com/akinomyoga/ble.sh/wiki/%E7%9B%AE%E6%AC%A1)を参照して下さい。
## 2.1 Vim モード
Vim モードについては [Wiki の説明ページ](https://github.com/akinomyoga/ble.sh/wiki/Vi-(Vim)-editing-mode) を御覧ください。
## 2.2 各機能の無効化
よくお尋ね頂くご質問の一つにそれぞれの機能をどのように無効化すれば良いのかというものが御座います。
各機能の無効化方法を以下にまとめます。
```bash
# 構文着色を無効化
bleopt highlight_syntax=
# ファイル名に基づく構文着色を無効化
bleopt highlight_filename=
# 変数の種類に基づく構文着色の無効化
bleopt highlight_variable=
# 自動補完の無効化 (自動補完は Bash 4.0 以降にて既定で有効です)
bleopt complete_auto_complete=
# Tip: 代わりに自動補完の起動遅延をミリ秒単位でご指定いただくこともできます。
bleopt complete_auto_delay=300
# コマンド履歴に基づく自動補完の無効化
bleopt complete_auto_history=
# 曖昧補完の無効化
bleopt complete_ambiguous=
# TAB によるメニュー補完の無効化
bleopt complete_menu_complete=
# メニュー自動絞り込みの無効化 (Bash 4.0 以降にて既定で有効化されます)
bleopt complete_menu_filter=
# 行末マーカー "[ble: EOF]" の無効化
bleopt prompt_eol_mark=''
# Tip: 代わりに他の文字列をご指定頂くこともできます。
bleopt prompt_eol_mark='⏎'
# 終了ステータスマーカー "[ble: exit %d]" の無効化
bleopt exec_errexit_mark=
# Tip: 代わりに他の文字列をご指定頂くこともできます。
bleopt exec_errexit_mark=$'\e[91m[error %d]\e[m'
# コマンド実行時間マーカー "[ble: elapsed 1.203s (CPU 0.4%)]" の無効化
bleopt exec_elapsed_mark=
# Tip: 代わりに別の文字列をご指定いただくこともできます。
bleopt exec_elapsed_mark=$'\e[94m[%ss (%s %%)]\e[m'
# Tip: マーカーを表示する条件を変更することも可能です。
bleopt exec_elapsed_enabled='sys+usr>=10*60*1000' # 例: 合計CPU時間が 10 分以上の時に表示
# 終了マーカー "[ble: exit]" の無効化
bleopt exec_exit_mark=
# その他のマーカー "[ble: ...]" の無効化
bleopt edit_marker=
bleopt edit_marker_error=
```
## 2.3 曖昧文字幅
設定 `char_width_mode` を用いて、曖昧文字幅を持つ文字 (Unicode 参考特性 `East_Asian_Width` が `A` (Ambiguous) の文字) の幅を制御できます。
現在は 4 つの選択肢 `emacs`, `west`, `east`, `auto` が用意されています。
設定値 `emacs` を指定した場合、GNU Emacs における既定の文字幅と同じ物を使います。
設定値 `west` を指定した場合、全ての曖昧文字幅を 1 (半角) と解釈します。
設定値 `east` を指定した場合、全ての曖昧文字幅を 2 (全角) と解釈します。
設定値 `auto` を指定した場合、`west` か `east` かを端末とのやり取りに基づいて自動判定します。
既定値は `auto` です。この設定項目は、利用している端末の振る舞いに応じて適切に設定する必要があります。
例えば `west` に設定する場合は以下の様にします:
```bash
bleopt char_width_mode='west'
```
## 2.4 文字コード
設定 `input_encoding` は入力の文字コードを制御するのに使います。現在 `UTF-8` と `C` のみに対応しています。
設定値 `C` を指定した場合は、受信したバイト値が直接文字コードであると解釈されます。
既定値は `UTF-8` です。`C` に設定を変更する場合には以下の様にします:
```bash
bleopt input_encoding='C'
```
## 2.5 ベル
設定 `edit_bell` は編集関数 `bell` の振る舞いを制御するコロン区切りのリストです。
値 `abell`, `vbell`, `visual` はそれぞれ対応するベルの提示方法を有効化します。
値 `abell` は音による通知に対応し、制御文字の <kbd>BEL</kbd> (0x07) を `stderr` に出力します。
値 `vbell` は画面での通知に対応し、端末画面上にメッセージを表示します。
値 `visual` は画面の反転に対応し、<kbd>DECSCNM</kbd> を用いて端末画面を瞬間的に反転します。
既定では音による通知のみが有効になっています。
設定 `vbell_default_message` は画面での通知で使用するメッセージ文字列を指定します。既定値は `' Wuff, -- Wuff!! '` です。
設定 `vbell_duration` は画面での通知を表示する時間の長さを指定します。単位はミリ秒です。既定値は `2000` です。
設定 `vbell_align` は画面での通知の表示位置を指定します。`left`, `center`, `right` が指定できます。
例えば、以下の設定によって、音による通知を無効化して画面での通知を設定・有効化できます。
```bash
bleopt edit_bell=vbell vbell_{default_message=' BEL ',duration=3000,align=right}
```
## 2.6 着色の設定
構文に従った着色で使用される、各文法要素の色と属性は `ble-face` シェル関数で設定します。
既定の設定は以下のコードに対応します:
```bash
# 編集に関連する着色の設定
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
# 構文着色の設定
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
# 補完の着色
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
```
現在の描画設定の一覧は以下のコマンドでも確認できます (`ble-face` を無引数で呼び出す)。
```console
$ ble-face
```
色コードはシェル関数 `ble-color-show` (`ble.sh` 内で定義) で確認できます。
```console
$ ble-color-show
```
## 2.7 キーバインディング
キーバインディングはシェル関数 `ble-bind` を使って変更できます。
例えば <kbd>C-x h</kbd> を入力した時に "Hello, world!" と挿入させたければ以下のようにします。
```bash
ble-bind -f 'C-x h' 'insert-string "Hello, world!"'
```
上記の <kbd>C-x h</kbd> の様なキー表記については
[マニュアル §3.1](https://github.com/akinomyoga/ble.sh/wiki/%E8%AA%AC%E6%98%8E%E6%9B%B8-%C2%A73-%E3%82%AD%E3%83%BC%E3%83%90%E3%82%A4%E3%83%B3%E3%83%87%E3%82%A3%E3%83%B3%E3%82%B0#user-content-sec-kspecs) で詳細に説明されています。
スペース・タブ・エンター・バックスペース・エスケープなどの特殊キーの表記については
[マニュアル §3.1.1](https://github.com/akinomyoga/ble.sh/wiki/%E8%AA%AC%E6%98%8E%E6%9B%B8-%C2%A73-%E3%82%AD%E3%83%BC%E3%83%90%E3%82%A4%E3%83%B3%E3%83%87%E3%82%A3%E3%83%B3%E3%82%B0#user-content-sec-kspecs-ret) で説明されています:
スペースは <kbd>SP</kbd> と表現します。
タブキーは端末によって <kbd>C-i</kbd> または <kbd>TAB</kbd> と表現します。
エンター・リターンキーは端末によって <kbd>C-m</kbd> または <kbd>RET</kbd> と表現します。
バックスペースは端末によって <kbd>C-?</kbd>, <kbd>DEL</kbd>, <kbd>C-h</kbd>, または <kbd>BS</kbd> 等様々な表現があります。
<kbd>Ctrl+Return</kbd> や <kbd>Shift+Return</kbd> などの修飾された特殊キーの取り扱いについては
[マニュアル §3.6.4](https://github.com/akinomyoga/ble.sh/wiki/%E8%AA%AC%E6%98%8E%E6%9B%B8-%C2%A73-%E3%82%AD%E3%83%BC%E3%83%90%E3%82%A4%E3%83%B3%E3%83%87%E3%82%A3%E3%83%B3%E3%82%B0#user-content-sec-modifyOtherKeys-manual) で説明されています。
お使いの端末が `modifyOtherKeys` に対応していない場合、手動で各キーの組み合わせに対応するエスケープシーケンスを設定する必要があります。
<kbd>M-c</kbd> を入力した時にコマンドを実行するには以下のようにします。
```bash
ble-bind -c 'M-c' 'my-command'
```
<kbd>C-r</kbd> を入力した時に、ユーザー定義編集関数 (Bash の `bind -x` で指定するのと同様の物) を実行するには以下のようにします。
```bash
ble-bind -x 'C-r' 'my-edit-function'
```
既存のキーバインディングは以下のコマンドで確認できます。
```console
$ ble-bind -P
```
以下のコマンドでキーバインディングに使える編集関数一覧を確認できます。
```console
$ ble-bind -L
```
一つのキーで複数の編集関数を呼び出したい場合は、以下の例の様に、
`ble/widget/編集関数の名前` という名前のシェル関数を通して新しい編集関数を定義できます。
既存の標準の編集関数と名前が重複しない様に、
編集関数の名前は `ユーザー名/`, `my/`, `blerc/`, `dotfiles/` などで始める事が強く推奨されます。
```bash
# 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 との統合<sup><a id="fzf-integration" href="#fzf-integration">†</a></sup>
`fzf` を `ble.sh` と一緒にお使いいただく場合には、[`contrib/fzf` 統合機能](https://github.com/akinomyoga/blesh-contrib#pencil-fzf-integration) を用いて `fzf` を設定していただく必要があります。
詳細についてはリンク先の説明を御覧ください。
```bash
# blerc
# 注意: fzf を bash_completion と組み合わせて使用する場合は、fzf-completion よ
# りも先に bash_completion をロードしておく必要があります。これは ble.sh と関係
# なく必要です。
source /etc/profile.d/bash_completion.sh
ble-import -d integration/fzf-completion
ble-import -d integration/fzf-key-bindings
```
上記 `ble-import` に指定されているオプション `-d` は指定したファイルの読み込み
を遅延させます。このように設定した場合、指定したファイルはプロンプトが表示され
た後にバックグランドで読み込まれます。詳細に関しては [`ble-import` - 説明書
§8](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A78-Miscellaneous#user-content-fn-ble-import)
を御覧ください。もし fzf の設定を読み込んだ後で更に設定を行うには、四つの方法が
ございます。最も単純な方法はオプション `-d` を指定しない方法 [1] です。或いは、
`ble-import -d` [2] または `ble/util/idle.push` [3] を用いて追加設定も同様に遅
延させることができます。または、fzf 設定ファイルの読み込み完了に対して
`ble-import -C` [4] を用いてフックを設定することもできます。
```bash
# [1] オプション -d を使用しない
ble-import integration/fzf-completion
ble-import integration/fzf-key-bindings
<settings>
# [2] 追加設定も ble-import -d を使う
ble-import -d integration/fzf-completion
ble-import -d integration/fzf-key-bindings
ble-import -d '<filename containing the settings>'
# [3] 追加設定を ble/util/idle.push で登録
ble-import -d integration/fzf-completion
ble-import -d integration/fzf-key-bindings
ble/util/idle.push '<settings>'
# [4] 追加設定を ble-import -C で登録
ble-import -d integration/fzf-completion
ble-import -d integration/fzf-key-bindings
ble-import -C '<settings>' integration/fzf-key-bindings
```
# 3 ヒント
## 3.1 複数行モード
コマンドラインに改行が含まれている場合、複数行モード (MULTILINE モード) になります。
<kbd>C-v C-j</kbd> または <kbd>C-q C-j</kbd> とすると改行をコマンドラインの一部として入力できます。
複数行モードでは、<kbd>RET</kbd> (<kbd>C-m</kbd>) はコマンドの実行ではなく新しい改行の挿入になります。
複数行モードでは、<kbd>C-j</kbd> を用いてコマンドを実行して下さい。
`shopt -s cmdhist` が設定されているとき (既定)、もし <kbd>RET</kbd> (<kbd>C-m</kbd>) を押した時にコマンドラインが構文的に閉じていなければ、コマンドの実行ではなく改行の挿入を行います。
## 3.2 Vim モード
`.bashrc` に `set -o vi` が設定されているとき、または `.inputrc` に `set editing-mode vi` が設定されているとき、vim モードが有効になります。
Vim モードの詳細な設定については [Wiki のページ (英語)](https://github.com/akinomyoga/ble.sh/wiki/Vi-(Vim)-editing-mode) を御覧ください。
## 3.3 自動補完
Bash 4.0 以降では自動補完が有効になり、予測候補が表示されます。
候補を確定するには <kbd>S-RET</kbd> を入力します (編集文字列の末尾にいる時は <kbd>right</kbd>, <kbd>C-f</kbd> または <kbd>end</kbd> でも確定できます)。
表示されている候補の初めの単語だけ部分的に確定する時は <kbd>M-f</kbd> または <kbd>M-right</kbd> を入力します。
現在の候補で確定しそのままコマンドを実行する場合には <kbd>C-RET</kbd> (※お使いの端末が対応している時) を入力します。
お使いの端末が対応していない時は [マニュアル §3.6.4](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A73-Key-Binding#user-content-sec-modifyOtherKeys-manual) を参照して下さい。
## 3.4 静的略語展開
特定の単語を静的略語展開に登録することで好きな文字列に展開することができます。
登録済み単語に一致する単語の直後で <kbd>SP</kbd> を入力した時に静的略語展開が起きます。
例えば、以下の設定をしておくと `command L` まで入力した状態で <kbd>SP</kbd> を押した時に、コマンドラインが `command | less` に展開されます。
```bash
# blerc
ble-sabbrev L='| less'
```
実際に実行したいコマンドに含まれる可能性の低い単語として、`\` で始まる単語を静的略語展開に登録することもお薦めです。
```bash
# blerc
ble-sabbrev '\L'='| less'
```
`~` で始まる静的略語展開は <kbd>/</kbd> でも展開されます。これは Zsh の名前付きディレクトリ (named directories) に模した使い方ができます。
例えば、以下の設定の下で `~mybin/` と入力すると、`/home/user/bin/` など (`HOME=/home/user` の場合) に展開されます。
```bash
# blerc
ble-sabbrev "~mybin=$HOME/bin"
```
# 4 謝辞
GitHub の Issue/PR を通して多くの方からフィードバックを頂き、皆様に本当に感謝しております。
特に以下の方には大きな寄与を受けたので言及させていただきます。
- [`@cmplstofB`](https://github.com/cmplstofB) 様には vim モードの実装において初期よりテスト及び様々な提案をしていただきました。
- [`@dylankb`](https://github.com/dylankb) 様には `fzf` との互換性や `ble.sh` 初期化に関連して様々な問題報告をいただきました。
- [`@rux616`](https://github.com/rux616) 様には幾つかの問題報告および `.blerc` の既定パス解決のバグ修正をいただきました。
- [`@timjrd`](https://github.com/timjrd) 様には補完の枠組みの高速化に関する PR をいただきました。
- [`@3ximus`](https://github.com/3ximus) 様には広範囲に渡る様々な問題について報告いただきました。
- [`@SuperSandro2000`](https://github.com/SuperSandro2000) 様には NixOS 関係を始め様々なご報告をいただきました。

792
.local/share/blesh/doc/README.md Normal file
View file

@ -0,0 +1,792 @@
[ Languages: **English** | [日本語](README-ja_JP.md) (Japanese) ]
<h1 align="center"><ruby>ble.sh<rp> (</rp><rt>/blɛʃ/</rt><rp>)</rp></ruby> ―Bash Line Editor―</h1>
<p align="center">
[ <b>README</b> | <a href="https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A71-Introduction">Manual</a> |
<a href="https://github.com/akinomyoga/ble.sh/wiki/Q&A">Q&A</a> |
<a href="https://github.com/akinomyoga/blesh-contrib"><code>contrib</code></a> |
<a href="https://github.com/akinomyoga/ble.sh/wiki/Recipes">Recipes</a> ]
</p>
*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**](LICENSE.md) (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.
## Quick instructions
To use `ble.sh`, Bash 3.0+ and POSIX standard utilities are required.
<!-- 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. -->
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](#get-from-source) and [Sec 1.2](#get-from-tarball) for trial/installation,
and [Sec 1.3](#set-up-bashrc) for the setup of your `~/.bashrc`.
> [!NOTE]
> If you want to **use fzf with `ble.sh`**, you need to check [Sec
> 2.8](#fzf-integration).
<details open><summary><b>Download and generate <code>ble.sh</code> using <code>git</code></b></summary>
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).
```bash
# 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`](https://github.com/akinomyoga/ble.sh/blob/master/src/canvas.GraphemeClusterBreak.sh),
[`canvas.c2w.musl.sh`](https://github.com/akinomyoga/ble.sh/blob/master/src/canvas.c2w.musl.sh),
[`canvas.c2w.sh`](https://github.com/akinomyoga/ble.sh/blob/master/src/canvas.c2w.sh),
and [`canvas.emoji.sh`](https://github.com/akinomyoga/ble.sh/blob/master/src/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`](make/README.md).
</details>
<details><summary><b>Download the nightly build with <code>curl</code></b></summary>
This requires the commands `curl`, `tar` (with the support for the `J` flag), and `xz` (XZ Utils).
```bash
# 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.
</details>
<details><summary><b>Download the nightly build with <code>wget</code></b></summary>
This requires the commands `wget`, `tar` (with the support for the `J` flag), and `xz` (XZ Utils).
```bash
# 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.
</details>
<details open><summary><b>Install a package using a package manager</b> (currently only a few packages)</summary>
This only requires the corresponding package manager.
- [AUR (Arch Linux)](https://github.com/akinomyoga/ble.sh/wiki/Manual-A1-Installation#user-content-AUR) `blesh-git` (devel), `blesh` (stable 0.3.4)
- [NixOS (nixpkgs)](https://github.com/akinomyoga/ble.sh/wiki/Manual-A1-Installation#user-content-nixpkgs) `blesh` (devel)
- [Guix](https://packages.guix.gnu.org/packages/blesh) `blesh` (devel)
</details>
<details open><summary><b>Update an existing copy of <code>ble.sh</code></b></summary>
```bash
# UPDATE (in a ble.sh session)
ble-update
# UPDATE (outside ble.sh sessions)
bash /path/to/ble.sh --update
```
</details>
<details><summary><b>Create a package of <code>ble.sh</code></b></summary>
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.
```bash
# 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):
```bash
# ${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](https://aur.archlinux.org/cgit/aur.git/tree/blesh-update.sh?h=blesh-git).
</details>
## 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.
Highlighting colors and styles are [fully configurable](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A72-Graphics).
- **Enhanced completion**:
Extend [completion](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A77-Completion)
by **syntax-aware completion**, completion with quotes and parameter expansions in prefix texts, **ambiguous candidate generation**, etc.
Also, [**menu-complete**](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A77-Completion#user-content-sec-menu-complete)
supports the selection of candidates in the menu (candidate list) by cursor keys, <kbd>TAB</kbd>, and <kbd>S-TAB</kbd>.
The feature [**auto-complete**](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A77-Completion#user-content-sec-auto-complete)
supports the automatic suggestion of completed texts as in `fish` and `zsh-autosuggestions` (with Bash 4.0+).
The feature [**menu-filter**](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A77-Completion#user-content-sec-menu-filter)
integrates automatic filtering of candidates into menu completion (with Bash 4.0+).
There are other functionalities such as
[**dabbrev**](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A77-Completion#user-content-sec-dabbrev) and
[**sabbrev**](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A77-Completion#user-content-sec-sabbrev) like
[*zsh abbreviations*](https://unix.stackexchange.com/questions/6152/zsh-alias-expansion) or [`zsh-abbr`](https://github.com/olets/zsh-abbr).
- **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.
- Other interesting features include
[**status line**](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A74-Editing#user-content-bleopt-prompt_status_line),
[**history share**](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A74-Editing#user-content-bleopt-history_share),
[**right prompt**](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A74-Editing#user-content-bleopt-prompt_rps1),
[**transient prompt**](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A74-Editing#user-content-bleopt-prompt_ps1_transient),
[**xterm title**](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A74-Editing#user-content-bleopt-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`](https://github.com/Bash-it/bash-it) and [`oh-my-bash`](https://github.com/ohmybash/oh-my-bash).
> Demo (version 0.2)
>
> ![ble.sh demo gif](https://github.com/akinomyoga/ble.sh/wiki/images/trial1.gif)
## History and roadmap
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](https://github.com/akinomyoga/ble.sh/releases/tag/v0.1.15)]
- 2018-03 v0.2 -- Vim mode [[v0.2.7](https://github.com/akinomyoga/ble.sh/releases/tag/v0.2.7)]
- 2019-02 v0.3 -- Enhanced completion [[v0.3.4](https://github.com/akinomyoga/ble.sh/releases/tag/v0.3.4)]
- 20xx-xx v0.4 (plan) -- programmable highlighting [[nightly build](https://github.com/akinomyoga/ble.sh/releases/tag/nightly)]
- 20xx-xx v0.5 (plan) -- TUI configuration
- 20xx-xx v0.6 (plan) -- error diagnostics?
## Limitations and assumptions
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 set `PIPESTATUS` for the previous command line
because it adds extra execution costs. Instead, the array `BLE_PIPESTATUS`
contains the values of `PIPESTATUS` of the previous command line. If you
need to access the values directly through the variable `PIPESTATUS`, please
set the option `bleopt exec_restore_pipestatus=1`.
- By default, `ble.sh` assumes that `PROMPT_COMMAND` and `PRECMD` 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 in `PROMPT_COMMAND` and `PRECMD`, please set the option
`bleopt prompt_command_changes_layout=1`.
- `ble.sh` assumes that common variable names and environment variables (such as `LC_*`) 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 to `ble.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]](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)).
Also, `ble.sh` overrides the builtin `readonly` 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`, and `exit`) with shell functions to adjust the behavior of each built-in command and prevent them from interfering with `ble.sh`.
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.
- 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](https://github.com/akinomyoga/ble.sh/wiki/Internals#internal-and-external).
# 1 Usage
## 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>
### Generate
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`.
```bash
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`.
### Try
Then, you can load `ble.sh` in the Bash session using the `source` command:
```bash
source out/ble.sh
```
### Install
To install `ble.sh` in a specified directory, use `make install`.
```bash
# 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](#set-up-bashrc).
## 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>
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](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)
- Stable [v0.3.4](https://github.com/akinomyoga/ble.sh/releases/tag/v0.3.4) (2019-02 fork) Enhanced completions
- Stable [v0.2.7](https://github.com/akinomyoga/ble.sh/releases/tag/v0.2.7) (2018-03 fork) Vim mode
- Stable [v0.1.15](https://github.com/akinomyoga/ble.sh/releases/tag/v0.1.15) (2015-12 fork) Syntax highlighting
## 1.3 Set up `.bashrc`<sup><a id="set-up-bashrc" href="#set-up-bashrc">†</a></sup>
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:
```bash
# 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](https://github.com/akinomyoga/ble.sh/discussions/254#discussioncomment-4284757).
## 1.4 User settings `~/.blerc`
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`](https://github.com/akinomyoga/ble.sh/blob/master/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:
```bash
# 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
```
## 1.5 Update
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:
```bash
$ ble-update
```
For `ble.0.4+`, you can also update it outside the `ble.sh` session using
```bash
$ bash /path/to/ble.sh --update
```
You can instead download the latest version by `git pull` and install it:
```bash
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
```
## 1.6 Uninstall
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 with `ble.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 directory where `ble.sh` is installed. When you use `out/ble.sh`
inside the working tree of the git repository, the installed directory is the
directory of the repository. When you use `ble.sh` installed by `make
install`, the installed directory is `<PREFIX>/share/blesh` where `<PREFIX>`
(default: `~/.local`) is the prefix specified to `make 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` ].
# 2 Basic settings
Here, some of the settings for `~/.blerc` are picked up.
You can find useful settings also in [Q\&A](https://github.com/akinomyoga/ble.sh/wiki/Q&A),
[Recipes](https://github.com/akinomyoga/ble.sh/wiki/Recipes),
and [`contrib` repository](https://github.com/akinomyoga/blesh-contrib).
The complete list of setting items can be found in the file [`blerc.template`](https://github.com/akinomyoga/ble.sh/blob/master/blerc.template).
For detailed explanations please refer to [Manual](https://github.com/akinomyoga/ble.sh/wiki).
## 2.1 Vim mode
For the vi/vim mode, check [the wiki page](https://github.com/akinomyoga/ble.sh/wiki/Vi-(Vim)-editing-mode).
## 2.2 Disable features
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.
```bash
# 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=
```
## 2.3 CJK Width
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:
```bash
bleopt char_width_mode='west'
```
## 2.4 Input 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:
```bash
bleopt input_encoding='C'
```
## 2.5 Bell
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 <kbd>BEL</kbd> (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 <kbd>DECSCNM</kbd> 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:
```bash
bleopt edit_bell=vbell vbell_{default_message=' BEL ',duration=3000,align=right}
```
## 2.6 Highlight Colors
The colors and attributes used in the syntax highlighting are controlled by the function `ble-face`. The following code reproduces the default configuration:
```bash
# 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):
```console
$ ble-face
```
The color codes can be checked in output of the function `ble-color-show` (defined in `ble.sh`):
```console
$ ble-color-show
```
## 2.7 Key Bindings
Key bindings can be controlled with the shell function, `ble-bind`.
For example, with the following setting, "Hello, world!" will be inserted on typing <kbd>C-x h</kbd>
```bash
ble-bind -f 'C-x h' 'insert-string "Hello, world!"'
```
The details on the key representation, such as <kbd>C-x h</kbd> in the above example,
are described in [Manual §3.1](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A73-Key-Binding#user-content-sec-kspecs).
The representations of <kbd>Space</kbd>, <kbd>Tab</kbd>, <kbd>Enter</kbd>, <kbd>Backspace</kbd>, <kbd>Escape</kbd>, etc. are described
in [Manual §3.1.1](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A73-Key-Binding#user-content-sec-kspecs-ret):
The space is represented as <kbd>SP</kbd>,
the tab key is represented as <kbd>C-i</kbd> or <kbd>TAB</kbd> depending on the terminal,
the enter/return key is represented as <kbd>C-m</kbd> or <kbd>RET</kbd> depending on the terminal,
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.
The representations of modified special keys such as <kbd>Ctrl+Return</kbd> and <kbd>Shift+Return</kbd> are described
in [Manual §3.6.4](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A73-Key-Binding#user-content-sec-modifyOtherKeys-manual):
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 <kbd>M-c</kbd>, you can write it as follows:
```bash
ble-bind -c 'M-c' 'my-command'
```
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:
```bash
ble-bind -x 'C-r' 'my-edit-function'
```
The existing key bindings are shown by the following command:
```console
$ ble-bind -P
```
The list of widgets is shown by the following command:
```console
$ 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.
```bash
# 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<sup><a id="fzf-integration" href="#fzf-integration">†</a></sup>
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).
Please follow the instructions in the link for the detailed description.
```bash
# 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](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A78-Miscellaneous#user-content-fn-ble-import)
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].
```bash
# [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
```
# 3 Tips
## 3.1 Use multiline mode
When the command line string contains a newline character, `ble.sh` enters the MULTILINE mode.
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.
In the MULTILINE mode, <kbd>RET</kbd> (<kbd>C-m</kbd>) causes the insertion of a new newline character.
In the MULTILINE mode, the command can be executed by typing <kbd>C-j</kbd>.
When the shell option `shopt -s cmdhist` is set (which is the default),
<kbd>RET</kbd> (<kbd>C-m</kbd>) inserts a newline if the current command line string is syntactically incomplete.
## 3.2 Use vim editing mode
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](https://github.com/akinomyoga/ble.sh/wiki/Vi-(Vim)-editing-mode).
## 3.3 Use `auto-complete`
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 <kbd>S-RET</kbd>
(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).
If you want to insert only the first word of the suggested contents, you can use <kbd>M-right</kbd> or <kbd>M-f</kbd>.
If you want to accept the suggestion and immediately run the command, you can use <kbd>C-RET</kbd>
(if your terminal does not support special key combinations like <kbd>C-RET</kbd>, please check
[Manual §3.6.4](https://github.com/akinomyoga/ble.sh/wiki/Manual-%C2%A73-Key-Binding#user-content-sec-modifyOtherKeys-manual)).
## 3.4 Use `sabbrev` (static abbrev expansions)
By registering words to `sabbrev`, the words can be expanded to predefined strings.
When the cursor is just after a registered word, typing <kbd>SP</kbd> causes the `sabbrev` expansion.
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`.
```bash
# 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.
```bash
# blerc
ble-sabbrev '\L'='| less'
```
The sabbrevs starting with `~` can be expanded also by <kbd>/</kbd>. 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`).
```bash
# blerc
ble-sabbrev "~mybin=$HOME/bin"
```
# 4 Contributors
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`](https://github.com/cmplstofB) helped me implement vim-mode by testing it and giving me a lot of suggestions.
- [`@dylankb`](https://github.com/dylankb) reported many issues with the fzf integration, initialization, etc.
- [`@rux616`](https://github.com/rux616) reported several issues and created a PR for fixing the default path of `.blerc`
- [`@timjrd`](https://github.com/timjrd) suggested and contributed to performance improvements in completion.
- [`@3ximus`](https://github.com/3ximus) reported many issues for a wide variety of problems.
- [`@SuperSandro2000`](https://github.com/SuperSandro2000) reported many issues related to NixOS and others

797
.local/share/blesh/doc/Release.md Normal file
View file

@ -0,0 +1,797 @@
# ble-0.4.0-devel3
## Usage
**Prerequisites**
Bash 3.0+ and basic POSIX utilities are required.
**Download ble-0.4.0-devel3.tar.xz**
https://github.com/akinomyoga/ble.sh/releases/download/v0.4.0-devel3/ble-0.4.0-devel3.tar.xz
```bash
# DOWNLOAD with wget
wget https://github.com/akinomyoga/ble.sh/releases/download/v0.4.0-devel3/ble-0.4.0-devel3.tar.xz
# DOWNLOAD with curl
curl -LO https://github.com/akinomyoga/ble.sh/releases/download/v0.4.0-devel3/ble-0.4.0-devel3.tar.xz
```
**Trial & Install**
```bash
# TRIAL
tar xJf ble-0.4.0-devel3.tar.xz
source ble-0.4.0-devel3/ble.sh
# INSTALL (quick)
tar xJf ble-0.4.0-devel3.tar.xz -C ~/.local/share/blesh
echo 'source ~/.local/share/blesh' >> ~/.bashrc
# INSTALL (more robust)
tar xJf ble-0.4.0-devel3.tar.xz -C ~/.local/share/blesh
# Add the following line near the top of ~/.bashrc
[[ $- == *i* ]] && source ~/.local/share/blesh/ble.sh --attach=none
# Add the following line at the end of ~/.bashrc
[[ ${BLE_VERSION-} ]] && ble-attach
```
--------------------------------------------------------------------------------
# ble-0.3.4
## Usage
**Prerequisites**
Bash 3.0+ and basic POSIX utilities are required.
**Download ble-0.3.4.tar.xz**
https://github.com/akinomyoga/ble.sh/releases/download/v0.3.4/ble-0.3.4.tar.xz
```bash
# DOWNLOAD with wget
wget https://github.com/akinomyoga/ble.sh/releases/download/v0.3.4/ble-0.3.4.tar.xz
# DOWNLOAD with curl
curl -LO https://github.com/akinomyoga/ble.sh/releases/download/v0.3.4/ble-0.3.4.tar.xz
```
**Trial & Install**
```bash
# TRIAL
tar xJf ble-0.3.4.tar.xz
source ble-0.3.4/ble.sh
# INSTALL
tar xJf ble-0.3.4.tar.xz -C ~/.local/share/blesh
# Add the following line near the top of ~/.bashrc
[[ $- == *i* ]] && source ~/.local/share/blesh/ble.sh --attach=none
# Add the following line at the end of ~/.bashrc
[[ ${BLE_VERSION-} ]] && ble-attach
```
## blesh-0.3 Fixes
- decode: fix `bind` emulation in .bashrc (v0.3) 742777e
- global: pick fixes and changes from ble-0.1..0.2 backports 78bbc5e
- bump 0.3.4 9da6774
## Fixes
- complete: fix a problem that candidates are not updated after menu-filter (reported by 3ximus) `#D1428` 1c7786e (master: 98fbc1c)
- edit: work around the wrong job information of Bash in trap handlers (reported by 3ximus) `#D1435` `#D1436` d40847f (master: bc4735e)
- edit (command-help): work around the Bash bug that tempenv vanishes with `builtin eval` `#D1438` cc8ca96 (master: 8379d4a)
- global: suppress missing locale errors (reported by 3ximus) `#D1440` b52a798 (master: 4d3c595)
- edit (sword): fix definition of `sword` (shell words) `#D1441` 2370bce (master: f923388)
- edit (`kill-forward-logical-line`): fix a bug not deleting newline at the end of the line `#D1443` 2a8a7f6 (master: 09cf7f1)
- global: work around bash-4.2 bug of `declare -gA` (reported by 0xC0ncord) `#D1470` 2f85ed3 (master: 8856a04)
- global: fix declaration of associative arrays for `ble-reload` (reported by 0xC0ncord) `#D1471` 422de69 (master: 3cae6e4)
- util (`ble/util/msleep`): fix hang in Cygwin by swithing from `/dev/udp/0.0.0.0/80` to `/dev/zero` `#D1452` 5ace564 (master: d4d718a)
- syntax: fix broken AST with `[[` keyword `#D1454` 1d48e79 (master: 69658ef)
- benchmark (`ble-measure`): work around a locale-dependent decimal point of `EPOCHREALTIME` (reported by 3ximus) `#D1460` f3833ad (master: 1aa471b)
- util (`ble/util/msleep`): work around the bash-4.3 bug of `read -t` (reported by 3ximus) `#D1468` `#D1469` 70797cf (master: 4ca9b2e)
- bind: work around broken `cmd_xmap` after switching the editing mode `#D1478` 909f461 (master: 8d354c1)
- edit: clear graphic rendition on newlines and external commands `#D1479` 59ede5c (master: 18bb2d5)
- decode (rlfunc): work around incomplete bytes in keyseq (reported by onelittlehope) `#D1483` 948a38d (master: 3559658) beb0383 37363be
- canvas: fix a glitch that SGR at the end of command line is applied to new lines `#D1498` 6871634 (master: 4bdfdbf)
- syntax: fix a bug that `eval() { :; }`, `declare() { :; }` are not treated as function definition `#D1529` 6c1d295 (master: b429095)
- decode: fix a hang on attach failure by cache corruption `#D1531` d4b0700 (master: 24ea379)
- progcomp: fix non-working `complete -C prog` (reported by Archehandoro) `#D1535` 47b3ade (master: 026432d)
- bind: fix a problem that `bind '"seq":"key"'` causes a loop macro `bind -s key key` (reported by thanosz) `#D1536` e2a502d (master: ea05fc5)
- main: work around `. ble.sh --{test,update,clear-cache}` in intereactive sessions `#D1555` 500915f (master: bbc2a90)
- main: fix reloading after ble-update (fixup 500915f (master: bbc2a90)) (fixed by oc1024) `#D1558` 9372670
- main: fix exit status for `bash ble.sh --test` (fixup 500915f (master: bbc2a90)) `#D1558` 641238a
- main: work around sourcing `ble.sh` inside subshells `#D1554` 500915f (master: bbc2a90)
- global: use a better workaround of bash-4.2 `declare -gA` by separating assignment `#D1567` 40827ef (master: 2408a20)
- util: work around bash-3.0 bug `"${scal[@]/xxx}"` `#D1570` 7e10cf4 (master: 24f79da)
- syntax: fix a bug that argument completion is attempted in nested commands (reported by huresche) `#D1579` 6987ae8 (master: 301d40f)
- edit (brackated-paste): fix incomplete `CR => LF` conversion (reported by alborotogarcia) `#D1587` 2651c8e (master: 8d6da16)
- main (adjust-bash-options): adjust `LC_COLLATE=C` `#D1588` 94cc9d2 (master: e87ac21)
- highlight (`layer:region`): fix blocked lower-layer changes without selection changes `#D1596` d40d42a (master: 5ede3c6)
- complete (`auto-menu`): fix sleep loops by clock/sclock difference `#D1597` 0abc15b (master: 53dd018)
- util: work around the Bash 3 bug of array assignments with `^A` and `^?` in Bash 3.2 `#D1614` 0eac4df (master: b9f7611)
- benchmark (`ble-measure`): fix a bug that the result is always 0 in Bash 3 and 4 (fixup bbc2a904) `#D1615` bc3cdab (master: a034c91)
- decode, canvas, etc.: explicitly treat CSI arguments as decimal numbers (reported by GorrillaRibs) `#D1625` 97bce68 (master: c6473b7) 2ea48d7
- edit: fix a bug that `command-help` doesn't work `#D1635` c375fbb (master: 0f6a083)
- complete: fix a task scheduling bug of referencing two different clocks (reported by rashil2000) `#D1636` df9f932 (master: fea5f5b)
- canvas: update prompt trace on `char_width_mode` change (reported by Barbarossa93) `#D1642` 00f9ce8 (master: 68ee111)
- decode: fix a bug that the characters input while initialization are delayed `#D1670` 734bd50 (master: 430f449)
- util (`ble/util/readfile`): fix a bug of always exiting with 1 in `bash <= 3.2` (reported by laoshaw) `#D1678` 51d244a (master: 61705bf)
- trace: fix wrong positioning of the ellipses on overflow `#D1684` dea87c7 (master: b90ac78)
- mandb: generate completions of options also for the empty word `#D1689` dea87c7 (master: b90ac78)
- complete: do not generate keywords for quoted command names `#D1691` 5b1e5be (master: 60d244f)
- menu (menu-style:align): fix the failure of delaying `ble/canvas/trace` on items (motivated by banoris) `#D1710` 3d56593 (master: acc9661)
- complete: fix empty completions with `FIGNORE` (reported by seanfarley) `#D1711` 49e75ee (master: 144ea5d)
- main: fix the message of owner errors of cache directories (reported by zim0369) `#D1712` 02aeb4a (master: b547a41)
- util (`ble/string#escape-for-bash-specialchars`): fix escaping of TAB `#D1713` accf8f3 (master: 7db3d2b)
- util (visible-bell): erase visible-bell before running external commands `#D1723` 72a11ae (master: 0da0c1c)
- util (`ble/function`): work around `shopt -u extglob` `#D1725` 3819e83 (master: 952c388)
- syntax: fix uninitialized syntax-highlighting in bash-3.2 `#D1731` 7bd03a5 (master: e3f5bf7)
- main: fix the workaround for `set -eu` and refactor `#D1743` a949af0 (master: 6a946f0)
- progcomp: retry completions on `$? == 124` also for non-default completions (reported by SuperSandro2000) `#D1759` e217932 (master: 82b9c01)
- util (`ble/util/import`): work around filenames with bash special characters `#D1763` 4179e3d (master: b27f758)
- edit: fix the restore failure of `PS1` and `PROMPT_COMMAND` on `ble-detach` `#D1784` 4f4c924 (master: b9fdaab)
- complete: do not attempt an independent rhs completion for arguments (reported by rsteube) `#D1787` 7bf32ca (master: f8bbe2c)
- history: work around possible dirty prefix `*` in the history output `#D1808` 84184ce (master: 64a740d)
- util(`ble/util/eval-pathname-expansion`): fix restoring shopt options in bash-4.0 `#D1825` d3b3f7b (master: 736f4da)
- decode: fix the workaround for `set -e` with `--prompt=attach` `#D1832` 51cb735 (master: 5111323)
- decode (`encoding:C`): fix initialization for isolated ESC `#D1839` aaa74b5 (master: c3bba5b)
- main. util: fix problems of readlink etc. found by test in macOS (reported by aiotter) `#D1849` a1adc7f (master: fa955c1) `#D1855` a22e145
- progcomp: fix a bug that `COMP_WORDBREAKS` is ignored `#D1872` b338066 (master: 4d2dd35)
- global: quote `return $?` `#D1884` 4f14f7a (master: 801d14a)
- main: fix adjustments of bash options (reported by rashil2000) `#D1895` 7bd25c9 (master: 138c476)
- decode: fix a bug that the tab completion do not work with bash-4.4 and lower `#D1928` 6351e7f (master: 7da9bce)
- bind: fix <kbd>M-C-@</kbd>, <kbd>C-x C-@</kbd>, and <kbd>M-C-x</kbd> (`bash-4.2 -o emacs`) `#D1920` 02f45f3 (master: a410b03)
- complete: fix non-working ambiguous path completion with `..` and `.` in the path `#D1930` fdb76e9 (master: 632e90a)
- main (ble-reload): fix failure by non-existent rcfile `#D1931` 58de996 (master: b7ae2fa)
- util: fix ble/util/clock in bash-4.2 [main: fix the timestamp in the session ID in bash-4.2] `#D1954` 9a24b1e (master: 651c70c1)
- edit (`ble/textarea#render`): fix interleaving outputs to `_ble_util_buffer` and `DRAW_BUFF` `#D1987` 62519a7 (master: 6d61388)
- keymap/vi (`operator:filter`): do not append newline at the end of line `#D1994` 8207d4f (master: bce2033)
- keymap/vi (`expand-range-for-linewise-operator`): fix the end point being not extended `#D1994` 8207d4f (master: bce2033)
- syntax: fix unrecognized asignment `echo arr[i]+=rhs` [sabbrev: apply sabbrev to right-hand sides of variable assignments] `#D2007` 948f50f (master: 41faa494)
## Changes
- syntax: exclude <code>\\ + LF</code> at the word beginning from words (motivated by cmplstofB) `#D1431` 1b00fd2 (master: 67e62d6)
- edit: preserve the state of `READLINE_{LINE,POINT,MARK}` `#D1437` cc8ca96 (master: 8379d4a)
- edit: change default behavior of <kbd>C-w</kbd> and <kbd>M-w</kbd> to operate on backward words `#D1448` b1fd84a (master: 47a3301)
- edit (`ble/builtin/read`): cancel by <kbd>C-d</kbd> on an empty line `#D1473` 4fae77a (master: ecb8888)
- syntax: change syntax context after `time ;` and `! ;` for Bash 4.4 `#D1477` e55e3df (master: 4628370)
- decode (rlfunc): update mapping `vi-replace` in `imap` and `vi-editing-mode` in `nmap` (reported by onelittlehope) `#D1484` 3a2d0fe (master: f2ca811)
- prompt: invalidate prompt and textarea on prompt setting changes `#D1492` e28f330 (master: 1f55913)
- main: accept non-regular files as `blerc` and add option `--norc` `#D1530` 4b0eb87 (master: 7244e2f)
- prompt: adjust behavior of `LINENO` and prompt sequence `\#` (reported by tycho-kirchner) `#D1542` f3668ba (master: 8b0257e)
- main: show notifications against debug versions of Bash `#D1612` 0ee8415 (master: 8f974aa)
- edit: suppress only `stderr` with `internal_suppress_bash_output` (motivated by rashil2000) `#D1646` b0a9021 (master: a30887f)
- prompt: do not evaluate `PROMPT_COMMAND` for subprompts `#D1654` 9c0e515 (master: 08e903e)
- main: suppress non-interactive warnings from manually sourced startup files (reported by andreclerigo) `#D1676` a602876 (master: 0525528) 88e2df5
- main: suppress non-interactive warnings from manually sourced startup files (reported by andreclerigo) `#D1676` 0525528 79efd42 (master: 88e2df5)
- syntax: revert 99f2234 (master: 371a5a4) and generate empty completion source on syntax error `#D1609` e09fcab
- syntax: do not start argument completions immediately after previous word (reported by EmilySeville7cfg) `#D1690` 99f2234 (master: 371a5a4)
- syntax: revert 371a5a4 and generate empty completion source on syntax error `#D1609` a1d1286 (master: e09fcab)
- canvas: do not insert explicit newlines on line folding if possible (reported by banoris) `#D1745` d878fce (master: 02b9da6) dc3827b
- edit (`ble-bind -x`): preserve multiline prompts on execution of `bind -x` commands (requested by SuperSandro2000) `#D1755` 240bfaa (master: 7d05a28)
- util (`ble/util/buffer`): hide cursor in rendering `#D1758` 5907567 (master: e332dc5)
- complete (`action:file`): always suffix `/` to complete symlinked directory names (reported by SuperSandro2000) `#D1759` ebdc58b (master: 397ac1f)
- edit: fix layout with `prompt_rps1` caused by missing `opts=relative` for `ble/textmap#update` `#D1769` e799191 (master: f6af802)
- edit (`ble-detach`): prepend a space to `stty sane` for `HISTIGNORE=' *'` `#D1796` 31bc2b7 (master: 26b532e)
- edit: the widgets `{kill,copy,delete}-region-or` now receives widgets as arguments `#D1021` e222c48 (master: bbbd155)
- decode (`bind`): do not treat non-beginning `#` as comments `#D1820` f9db7d8 (master: 65c4138)
- history: disable the history file when `HISTFILE` is empty `#D1836` 7153250 (master: 9549e83)
- main (`ble-reload`): preserve the original initialization options `#D1852` 8912d81 (master: d8c92cc)
- progcomp: reproduce arguments of completion functions passed by Bash `#D1872` b338066 (master: 4d2dd35)
- color: let `bleopt term_index_colors` override the default if specified `#D1878` e7c657c (master: 7d238c0)
- decode (`vi_imap-rlfunc.txt`): update the widget for `backward-kill-word` as `kill-backward-{u => c}word` `#D1896` 3c4e3a4 (master: e19b796)
- term (`_ble_term_TERM`): detect wezterm-20220408 `#D1909` f3a8382 (master: 486564a)
- keymap/vi (`decompose-meta`): translate <kbd>S-a</kbd> to <kbd>A</kbd> `#D1988` 9e0c187 (master: 600e845)
- term (`_ble_term_TERM`): detect konsole `#D1988` 9e0c187 (master: 600e845) ed53858
## Compatibility
- term: work around leaked <kbd>DA2R</kbd> in screen from outside terminal `#D1485` 4d77fab (master: e130619)
- util (`modifyOtherKeys`): work around a quirk of kitty (reported by NoahGorny) `#D1549` 823eb83 (master: f599525)
- global: work around empty `vi_imap` cache by `tmux-resurrect` `#D1562` d7d2a23 (master: 560160b)
- decode: identify `kitty` and treat `\e[27u` as isolated ESC (reported by lyiriyah) `#D1585` 2f7404e (master: c2a84a2)
- complete: suppress known error messages of `bash-completion` (reported by oc1024, Lun4m) `#D1622` 558322c (master: d117973)
- util (`modifyOtherKeys`): update the workaround for a new quiark of kitty `#D1627` 90d9284 (master: 3e4ecf5)
- main: work around `set -B` and `set -k` `#D1628` 55494eb (master: a860769)
- term: disable `modifyOtherKeys` and do not send `DA2` for `st` (requested by Shahabaz-Bagwan) `#D1632` 7e08766 (master: 92c7b26)
- cmap: add `st`-specific escape sequences for cursor keys `#D1633` 1391c90 (master: acfb879)
- cmap: distinguish <kbd>find</kbd>/<kbd>select</kbd> from <kbd>home</kbd>/<kbd>end</kbd> for openSUSE `inputrc.keys` (reported by cornfeedhobo) `#D1648` 886cc07 (master: c4d28f4)
- cmap: freeze the internal codes of <kbd>find</kbd>/<kbd>select</kbd> and kitty special keys `#D1674` 7d02058 (master: fdfe62a)
- decode: work around the overwritten builtin `set` (reported by eadmaster) `#D1680` 5acb117 (master: a6b4e2c)
- util (`modifyOtherKeys`): use the kitty protocol for kitty 0.23+ which removes the support of `modifyOtherKeys` (reported by kovidgoyal) `#D1681` 696264b (master: ec91574)
- complete: work around the variable leaks by `virsh` completion from `libvirt` (reported by telometto) `#D1682` 7a65fc3 (master: f985b9a)
- stty: do not remove keydefs for <kbd>C-u</kbd>, <kbd>C-v</kbd>, <kbd>C-w</kbd>, and <kbd>C-?</kbd> (reported by laoshaw) `#D1683` ff8fb83 (master: 82f74f0)
- decode (`ble/builtin/bind`): improve compatibility of the deprecated form `bind key:rlfunc` (motivated by cmplstofB) `#D1698` c3904ff (master: b6fc4f0)
- main: work around `XDG_RUNTIME_DIR` of a different user by `su` (reported by zim0369) `#D1712` dbf58e4 (master: 8d37048)
- main (`ble/util/readlink`): work around non-standard or missing `readlink` (motivated by peterzky) `#D1720` 60595bd (master: a41279e)
- decode (`ble/builtin/bind`): fix a bug that only lowercase is accepted for deprecated form `bind key:rlfunc` (reported by returntrip) `#D1726` 43cf9b9 (master: a67458e) e363f1b
- decode (`ble/builtin/bind`): fix a bug that only lowercase is accepted for deprecated form `bind key:rlfunc` (reported by returntrip) `#D1726` a67458e dd358d7 (master: e363f1b)
- global: work around the arithmetic syntax error of `10#` in Bash-5.1 `#D1734` b321b57 (master: 7545ea3)
- global: adjust implementations for Bash 5.2 `patsub_replacement` `#D1738` 66ae615 (master: 4590997)
- main: check `/dev/tty` on startup (reported by andychu) `#D1749` e6c2855 (master: 711c69f)
- global: work around `shopt -s compat42` `#D1754` 1f254b5 (master: a75bb25)
- global: identify bash-4.2 bug that internal quoting of `${v/%$empty/"$rep"}` remains `#D1753` 1f254b5 (master: a75bb25)
- prompt: fix a bug of `ble/prompt/print` redundantly quoting `$` `#D1752` 1f254b5 (master: a75bb25)
- global: work around `compat42` quoting of `"${v/pat/"$rep"}"` `#D1751` 1f254b5 (master: a75bb25)
- util: add identification of Windows Terminal `wt` `#D1758` 5907567 (master: e332dc5)
- global: work around bash-3.0 bug that single quotes remains for `"${v-$''}"` `#D1774` 30440b2 (master: 9b96578)
- util (`modifyOtherKeys`): fix a bug that kitty protocol is never activated `#D1842` f8aeb51 (master: 14f3c81)
- util (`modifyOtherKeys`): work around delayed terminal identification `#D1842` f8aeb51 (master: 14f3c81)
- main: resolve empty `HOSTNAME` [originally: contrib: add `histdb`] `#D1925` e82230e (master: 44d9e104)
- main: warn empty `LANG` [originally: main: support an option `--inputrc={diff,all,user,none}`] `#D1926` ede4ee7 (master: 92f2006)
- term (`terminology`): work around terminal glitches `#D1946` ccb93a5 (master: 9a1b4f9)
- edit: always adjust the terminal states with `bind -x` (reported by linwaytin) `#D1983` 992131c (master: 5d14cf1)
- syntax: suppress brace expansions in designated array initialization in Bash 5.3 `#D1989` 1f0d8e1 (master: 1e7b884)
- util (function#evaldef): work around `set -e` [progcomp: work around slow `nix` completion] `#D1997` 2ab4e4b (master: 2c1aacfc)
- util (`string#quote-word`): work around `set -ue` [util, edit: add `ble/util/message` and `ble append-line`] `#D2001` 2317562 (master: 2a524f34)
- complete: suppress error messages from `_adb` `#D2005` 2f77171 (master: f2aa32b)
- edit: restore `PS1` while processing `bind -x` `#D2024` 604c092 (master: 2eadcd5)
## Optimization
- complete (`ble/complete/source:file`): remove slow old codes (reported by timjrd) `#D1512` 60a33e2 (master: e5be0c1)
- util (`ble/util/assign`): work around subshell conflicts `#D1578` 4117d1b (master: 6e4bb12)
- prompt: fix not properly set `$?` in `${PS1@P}` evaluation (reported by nihilismus) `#D1644` a3cfd0d (master: 521aff9)
- util (`ble/string#split`): optimize `#D1826` 9dcbbd4 (master: 7bb10a7)
- debug: add `ble/debug/profiler` (motivated by SuperSandro2000) `#D1824` f629698 11aa4ab 9dcbbd4 (master: 7bb10a7)
- global: avoid passing arbitrary strings through `awk -v var=value` `#D1827` 9edb1aa (master: 82232de)
## Internal changes and fixes
- main: include hostname in local runtime directory `#D1444` 3e648a9 (master: 6494836)
- benchmark (`ble-measure`): support `-T TIME` and `-B TIME` option `#D1460` f3833ad (master: 1aa471b)
- global: fix status check for read timeout `#D1467` f190f9a (master: e886883)
- util, etc: ensure each function to work with arbitrary `IFS` `#D1490` `#D1491` c33fad0 (master: 5f9adfe)
- global: work around `localvar_inherit` for varname-list init `#D1566` 8c67b79 (master: 5c2edfc)
- util: fix `ble/util/dense-array#fill-range` e397120 (master: a46fdaf)
- util: fix leak variables `buff`, `trap`, `{x,y}{1,2}` `#D1572` 82113e9 (master: 5967d6c)
- util: fix leak variables `#D1643` 0817df6 (master: fcf634b)
- edit (`command-help`): use `ble/util/assign/.mktmp` to determine the temporary filename `#D1663` 2ff6078 (master: 1af0800)
- Makefile: add fallback Makefile for BSD make `#D1805` ea8b966 (master: e5d8d00)
- util, decode, vi: fix leak variables `#D1933` 9e2e823 (master: 8d5cab8)
- syntax: fix code formatting [originally: complete: support auto-complete sources] `#D1938` 450f70b (master: 00cae745)
- main: use builtin for ":" [histdb: support timeout of background processes] `#D1971` 482ddb5 (master: e0566bdc)
- global: normalize to `_a-zA-Z` [sabbrev: apply sabbrev to right-hand sides of variable assignments] `#D2006` a101fe6 (master: 41faa494)
- util (restore-vars): work around `set -u` [lib: add `util.bgproc` for `ble/util/bgproc`] `#D2017` 8787ca5 (master: 7803305f)
- util: update `ble/util/conditional-sync` [util.bgproc: increase frequency of bgproc termination check] `#D2027` 79fd13c (master: 8d623c1)
## Test
- util (ble/util/s2bytes): clear locale cache `#D1881` 45f3df3 (master: 2e1a7c1)
- util (ble/util/s2c): work around intermediate mbstate of bash <= 5.2 `#D1881` 45f3df3 (master: 2e1a7c1)
- util (ble/encoding:UTF-8/b2c): fix interpretation of leading byte `#D1881` 45f3df3 (master: 2e1a7c1)
- complete: fix syntax error for bash-3.0 `#D1881` b534799 (master: 0b3e611)
## Documentation
- blerc: rename from `blerc` to `blerc.template` `#D1899` 3c4e3a4 (master: e19b796)
- wiki/Q&A: add item for defining a widget calling multiple widgets (motivated by micimize) `#D1898` 3c4e3a4 (master: e19b796)
- blerc: add frequently used keybindings (motivated by KiaraGrouwstra, micimize) `#D1896` `#D1897` 3c4e3a4 (master: e19b796)
## Contrib
- fzf-key-bindings: fix a problem that `modifyOtherKeys` is not reflected (reported by SuperSandro2000) `#D1908` f3a8382 (master: 486564a)
## New features
- canvas: update emoji database and support `bleopt emoji_version` (motivated by endorfina) `#D1454` 3f6c9b9 (master: d1f8c27)
- syntax: support tilde expansions in parameter expansions `#D1513` e32914f (master: 0506df2)
- prompt (`contrib/prompt-git`): support dirty checking `#D1601` 50a0094 (master: b2713d9)
- util (`bleopt`, `bind`): fix error message and exit status, respectively `#D1640` 29728b1 (master: b663cee)
- edit: support bash-5.2 binding of `prior/next` to `history-search-{for,back}ward` `#D1661` a3a353e (master: d26a6e1)
- util: suppress false warnings of `bind` inside non-interactive shells (reported by wukuan405) `#D1823` 82c9934 (master: 1e19a67)
- auto-complete: cancel auto-complete for `magic-space` `#D1913` 05c0888 (master: 01b4f67)
- complete: support ambiguous completion for command paths `#D1922` 6d1e1ba (master: 8a716ad)
- syntax: support context after `((...))` and `[[ ... ]]` in bash-5.2 `#D1962` 57d7674 (master: 67cb967)
--------------------------------------------------------------------------------
# ble-0.2.7
## Usage
**Prerequisites**
Bash 3.0+ and basic POSIX utilities are required.
**Download ble-0.2.7.tar.xz**
https://github.com/akinomyoga/ble.sh/releases/download/v0.2.7/ble-0.2.7.tar.xz
```bash
# DOWNLOAD with wget
wget https://github.com/akinomyoga/ble.sh/releases/download/v0.2.7/ble-0.2.7.tar.xz
# DOWNLOAD with curl
curl -LO https://github.com/akinomyoga/ble.sh/releases/download/v0.2.7/ble-0.2.7.tar.xz
```
**Trial & Install**
```bash
# TRIAL
tar xJf ble-0.2.7.tar.xz
source ble-0.2.7/ble.sh
# INSTALL
tar xJf ble-0.2.7.tar.xz -C ~/.local/share/blesh
# Add the following line near the top of ~/.bashrc
[[ $- == *i* ]] && source ~/.local/share/blesh/ble.sh --noattach
# Add the following line at the end of ~/.bashrc
((_ble_bash)) && ble-attach
```
## blesh-0.2 fixes
- global: fix `ble/{is- => util/is}function` 5e82ca7a
- global: pick fixes and changes from ble-0.1 backports 013eb1cd
- complete: fix up 4df15e1e f02bd2a5
- bump 0.2.7 1118c803
## Fixes
- edit: work around the wrong job information of Bash in trap handlers (reported by 3ximus) `#D1435` `#D1436` 795a647c (master: bc4735e0)
- edit (sword): fix definition of `sword` (shell words) `#D1441` 5e73cf6b (master: f9233889)
- edit (`kill-forward-logical-line`): fix a bug not deleting newline at the end of the line `#D1443` 03787a2d (master: 09cf7f14)
- global: work around bash-4.2 bug of `declare -gA` (reported by 0xC0ncord) `#D1470` a2ace444 (master: 8856a04f)
- global: fix declaration of associative arrays for `ble-reload` (reported by 0xC0ncord) `#D1471` 533eba77 (master: 3cae6e4d)
- util (`ble/util/msleep`): fix hang in Cygwin by swithing from `/dev/udp/0.0.0.0/80` to `/dev/zero` `#D1452` 46992e79 (master: d4d718ab)
- syntax: fix broken AST with `[[` keyword `#D1454` 0482bf64 (master: 69658efc)
- util (`ble/util/msleep`): work around the bash-4.3 bug of `read -t` (reported by 3ximus) `#D1468` `#D1469` fad78ea5 (master: 4ca9b2e2)
- bind: work around broken `cmd_xmap` after switching the editing mode `#D1478` 97ca1171 (master: 8d354c1b)
- edit: clear graphic rendition on newlines and external commands `#D1479` 759b96dd (master: 18bb2d5c)
- canvas: fix a glitch that SGR at the end of command line is applied to new lines `#D1498` a6ac1216 (master: 4bdfdbf8)
- syntax: fix a bug that `eval() { :; }`, `declare() { :; }` are not treated as function definition `#D1529` a4cda9c3 (master: b4290958)
- decode: fix a hang on attach failure by cache corruption `#D1531` a4c13ab8 (master: 24ea3792)
- benchmark (`ble-measure`): fix a bug that the result is always 0 in Bash 3 and 4 (fixup 8eb493a9 (master: bbc2a904)) `#D1615` a034c91
- main: work around `. ble.sh --{test,update,clear-cache}` in intereactive sessions `#D1555` 8eb493a9 (master: bbc2a904)
- main: fix reloading after ble-update (fixup 8eb493a9 (master: bbc2a904)) (fixed by oc1024) `#D1558` 9372670
- main: fix exit status for `bash ble.sh --test` (fixup 8eb493a9 (master: bbc2a904)) `#D1558` 641238a
- main: work around sourcing `ble.sh` inside subshells `#D1554` 8eb493a9 (master: bbc2a904)
- global: use a better workaround of bash-4.2 `declare -gA` by separating assignment `#D1567` 0b7de999 (master: 2408a207)
- edit (brackated-paste): fix incomplete `CR => LF` conversion (reported by alborotogarcia) `#D1587` ac738bb4 (master: 8d6da161)
- highlight (`layer:region`): fix blocked lower-layer changes without selection changes `#D1596` 650140ff (master: 5ede3c69)
- util: work around the Bash 3 bug of array assignments with `^A` and `^?` in Bash 3.2 `#D1614` 0ed7f6dc (master: b9f76118)
- benchmark (`ble-measure`): fix a bug that the result is always 0 in Bash 3 and 4 (fixup bbc2a904) `#D1615` 28e8dfed (master: a034c91a)
- decode, canvas, etc.: explicitly treat CSI arguments as decimal numbers (reported by GorrillaRibs) `#D1625` c9e4198b (master: c6473b78) 2ea48d7
- edit: fix a bug that `command-help` doesn't work `#D1635` b992bb5d (master: 0f6a0834)
- canvas: update prompt trace on `char_width_mode` change (reported by Barbarossa93) `#D1642` 56b77a83 (master: 68ee1112)
- util (`ble/util/readfile`): fix a bug of always exiting with 1 in `bash <= 3.2` (reported by laoshaw) `#D1678` 5b843bb6 (master: 61705bf6)
- complete: do not generate keywords for quoted command names `#D1691` 7211b1ec (master: 60d244fe)
- complete: fix empty completions with `FIGNORE` (reported by seanfarley) `#D1711` 90f388aa (master: 144ea5db)
- main: fix the message of owner errors of cache directories (reported by zim0369) `#D1712` d2bf86c1 (master: b547a41a)
- syntax: fix uninitialized syntax-highlighting in bash-3.2 `#D1731` 6aa12c82 (master: e3f5bf74)
- progcomp: retry completions on `$? == 124` also for non-default completions (reported by SuperSandro2000) `#D1759` c641fb1b (master: 82b9c011)
- util (`ble/util/import`): work around filenames with bash special characters `#D1763` 7da5f048 (master: b27f7585)
- edit: fix the restore failure of `PS1` and `PROMPT_COMMAND` on `ble-detach` `#D1784` 47dfdd94 (master: b9fdaabd)
- history: work around possible dirty prefix `*` in the history output `#D1808` cc14f59c (master: 64a740d7)
- decode: fix the workaround for `set -e` with `--prompt=attach` `#D1832` 958aae6b (master: 51113237)
- main. util: fix problems of readlink etc. found by test in macOS (reported by aiotter) `#D1849` 8f0acf3d (master: fa955c1a) `#D1855` a22e145
- global: quote `return $?` `#D1884` 9e10b54b (master: 801d14af)
- bind: fix <kbd>M-C-@</kbd>, <kbd>C-x C-@</kbd>, and <kbd>M-C-x</kbd> (`bash-4.2 -o emacs`) `#D1920` 342826f3 (master: a410b038)
- keymap/vi (`operator:filter`): do not append newline at the end of line `#D1994` 2a8e746f (master: bce20339)
- keymap/vi (`expand-range-for-linewise-operator`): fix the end point being not extended `#D1994` 2a8e746f (master: bce20339)
- syntax: fix unrecognized asignment `echo arr[i]+=rhs` [sabbrev: apply sabbrev to right-hand sides of variable assignments] `#D2006` 4ed4fd4f (master: 41faa494)
- syntax: fix unrecognized variable assignment of the form `echo arr[i]+=rhs` `#D2007` 4ed4fd4f (master: 41faa494)
## Changes
- syntax: exclude <code>\\ + LF</code> at the word beginning from words (motivated by cmplstofB) `#D1431` 6044a485 (master: 67e62d64)
- edit: change default behavior of <kbd>C-w</kbd> and <kbd>M-w</kbd> to operate on backward words `#D1448` 787ff57f (master: 47a3301a)
- edit: the widgets `{kill,copy,delete}-region-or` now receives widgets as arguments `#D1021` 8f48aff1 (master: bbbd155f)
- edit (`ble/builtin/read`): cancel by <kbd>C-d</kbd> on an empty line `#D1473` 551bde3a (master: ecb8888d)
- syntax: change syntax context after `time ;` and `! ;` for Bash 4.4 `#D1477` 0b66cf4a (master: 46283706)
- prompt: invalidate prompt and textarea on prompt setting changes `#D1492` 54d310df (master: 1f559135)
- prompt: adjust behavior of `LINENO` and prompt sequence `\#` (reported by tycho-kirchner) `#D1542` 4b63b164 (master: 8b0257e2)
- main: show notifications against debug versions of Bash `#D1612` 608ac2ad (master: 8f974aa1)
- prompt: do not evaluate `PROMPT_COMMAND` for subprompts `#D1654` 5c0cfdef (master: 08e903e0)
- main: suppress non-interactive warnings from manually sourced startup files (reported by andreclerigo) `#D1676` 2587bb01 (master: 05255282) 88e2df5
- main: suppress non-interactive warnings from manually sourced startup files (reported by andreclerigo) `#D1676` 0525528 5f638563 (master: 88e2df51)
- util (`ble/util/buffer`): hide cursor in rendering `#D1758` 4ecbbdc2 (master: e332dc5f)
- edit (`ble-detach`): prepend a space to `stty sane` for `HISTIGNORE=' *'` `#D1796` bd903716 (master: 26b532e7)
- history: disable the history file when `HISTFILE` is empty `#D1836` d97ca100 (master: 9549e831)
- keymap/vi (`decompose-meta`): translate <kbd>S-a</kbd> to <kbd>A</kbd> `#D1988` eaf66c7c (master: 600e845e)
- term (`_ble_term_TERM`): detect konsole `#D1988` eaf66c7c (master: 600e845e) ed53858
- complete (`source:argument`): fallback to rhs completion also for `name+=rhs` `#D2006` 4ed4fd4f (master: 41faa494)
## Compatibility
- highlight: fix a problem that the attribute of the last character is applied till EOL `#D1393` 36f9d809 (master: 2ddb1ba2) `#D1395` ef09932
- highlight: fix a problem that the attribute of the last character is applied till EOL `#D1393` 2ddb1ba `#D1395` 6bcb4053 (master: ef099326)
- global: work around empty `vi_imap` cache by `tmux-resurrect` `#D1562` d7130d55 (master: 560160b0)
- main: work around `set -B` and `set -k` `#D1628` 3c97ae84 (master: a8607692)
- cmap: add `st`-specific escape sequences for cursor keys `#D1633` bf46e344 (master: acfb8790)
- cmap: distinguish <kbd>find</kbd>/<kbd>select</kbd> from <kbd>home</kbd>/<kbd>end</kbd> for openSUSE `inputrc.keys` (reported by cornfeedhobo) `#D1648` ad675556 (master: c4d28f40)
- cmap: freeze the internal codes of <kbd>find</kbd>/<kbd>select</kbd> and kitty special keys `#D1674` f41b8004 (master: fdfe62a4)
- decode: work around the overwritten builtin `set` (reported by eadmaster) `#D1680` 93ae08d0 (master: a6b4e2ca)
- complete: work around the variable leaks by `virsh` completion from `libvirt` (reported by telometto) `#D1682` ee2ac075 (master: f985b9a4)
- stty: do not remove keydefs for <kbd>C-u</kbd>, <kbd>C-v</kbd>, <kbd>C-w</kbd>, and <kbd>C-?</kbd> (reported by laoshaw) `#D1683` c01487bf (master: 82f74f0a)
- main: work around `XDG_RUNTIME_DIR` of a different user by `su` (reported by zim0369) `#D1712` e5501a31 (master: 8d370486)
- main (`ble/util/readlink`): work around non-standard or missing `readlink` (motivated by peterzky) `#D1720` d785f5db (master: a41279ed)
- global: work around the arithmetic syntax error of `10#` in Bash-5.1 `#D1734` 2b55aa16 (master: 7545ea31)
- global: adjust implementations for Bash 5.2 `patsub_replacement` `#D1738` 359a3891 (master: 4590997a)
- main: check `/dev/tty` on startup (reported by andychu) `#D1749` 19fa0924 (master: 711c69f1)
- global: work around `shopt -s compat42` `#D1754` e7adfb34 (master: a75bb25a)
- global: identify bash-4.2 bug that internal quoting of `${v/%$empty/"$rep"}` remains `#D1753` e7adfb34 (master: a75bb25a)
- prompt: fix a bug of `ble/prompt/print` redundantly quoting `$` `#D1752` e7adfb34 (master: a75bb25a)
- global: work around `compat42` quoting of `"${v/pat/"$rep"}"` `#D1751` e7adfb34 (master: a75bb25a)
- util: add identification of Windows Terminal `wt` `#D1758` 4ecbbdc2 (master: e332dc5f)
- global: work around bash-3.0 bug that single quotes remains for `"${v-$''}"` `#D1774` fb607ad6 (master: 9b96578c)
- main: resolve empty `HOSTNAME` [add `histdb`] `#D1925` 5812f2ef (master: 44d9e104)
- main: warn empty `LANG` [main: support an option `--inputrc={diff,all,user,none}`] `#D1926` 3f29bee3 (master: 92f20063)
- main: never load `/etc/inputrc` in openSUSE (motivated by Ultra980) `#D1926` 3f29bee3 (master: 92f20063) 0ceb0cb
- main: show warning for empty locale (movivated by Ultra980) `#D1927` 3f29bee3 (master: 92f20063)
- term (`terminology`): work around terminal glitches `#D1946` 2d4caa67 (master: 9a1b4f9f)
- edit: always adjust the terminal states with `bind -x` (reported by linwaytin) `#D1983` cdda7c44 (master: 5d14cf17)
- syntax: suppress brace expansions in designated array initialization in Bash 5.3 `#D1989` 78dd47ee (master: 1e7b884d)
- edit: restore `PS1` while processing `bind -x` (reported by adoyle-h) `#D2024` c46f4230 (master: 2eadcd5b)
## Optimization
- util (`ble/util/assign`): work around subshell conflicts `#D1578` 59d6355c (master: 6e4bb126)
- prompt: fix not properly set `$?` in `${PS1@P}` evaluation (reported by nihilismus) `#D1644` 66fd10b7 (master: 521aff9b)
- util (`ble/string#split`): optimize `#D1826` 5b3fc89c (master: 7bb10a79)
- debug: add `ble/debug/profiler` (motivated by SuperSandro2000) `#D1824` f629698 11aa4ab 5b3fc89c (master: 7bb10a79)
- global: avoid passing arbitrary strings through `awk -v var=value` `#D1827` 4571695a (master: 82232de5)
## Internal changes and fixes
- main: include hostname in local runtime directory `#D1444` d19ab298 (master: 64948361)
- global: fix status check for read timeout `#D1467` 0bcc12c9 (master: e886883b)
- util, etc: ensure each function to work with arbitrary `IFS` `#D1490` `#D1491` 2fe60b64 (master: 5f9adfe8)
- util: fix `ble/util/dense-array#fill-range` b708ee29 (master: a46fdaf4)
- util: fix leak variables `buff`, `trap`, `{x,y}{1,2}` `#D1572` 36d151e2 (master: 5967d6ce)
- make: add fallback Makefile for BSD make `#D1805` 6498a5d3 (master: e5d8d00c)
- util, decode, vi: fix leak variables `#D1933` 002dda7f (master: 8d5cab85)
- syntax: fix code formatting [histdb: support auto-complete source `histdb-word`] `#D1938` edd48d1c (master: 00cae745)
- main: use builtin for `:` [histdb: support timeout of background processes] `#D1971` 8640dc41 (master: e0566bdc)
- global: normalize bracket expressions to `_a-zA-Z` / `_a-zA-Z0-9` `#D2006` 4ed4fd4f (master: 41faa494)
- util (restore-vars): work around `set -u` [util.bgproc: separate `ble/util/bgproc` from `histdb`] `#D2017` d60758ae (master: 7803305f)
## Test
- util (ble/util/s2bytes): clear locale cache `#D1881` 99e217d3 (master: 2e1a7c17)
- util (ble/util/s2c): work around intermediate mbstate of bash <= 5.2 `#D1881` 99e217d3 (master: 2e1a7c17)
- util (ble/encoding:UTF-8/b2c): fix interpretation of leading byte `#D1881` 99e217d3 (master: 2e1a7c17)
## New features
- syntax: support context after `((...))` and `[[ ... ]]` in bash-5.2 `#D1962` 74af9e60 (master: 67cb967a)
--------------------------------------------------------------------------------
# ble-0.1.15
## Usage
**Prerequisites**
Bash 3.0+ and basic POSIX utilities are required.
**Download ble-0.1.15.tar.xz**
https://github.com/akinomyoga/ble.sh/releases/download/v0.1.15/ble-0.1.15.tar.xz
```bash
# DOWNLOAD with wget
wget https://github.com/akinomyoga/ble.sh/releases/download/v0.1.15/ble-0.1.15.tar.xz
# DOWNLOAD with curl
curl -LO https://github.com/akinomyoga/ble.sh/releases/download/v0.1.15/ble-0.1.15.tar.xz
```
**Trial & Install**
```bash
# TRIAL
tar xJf ble-0.1.15.tar.xz
source ble-0.1.15/ble.sh
# INSTALL
tar xJf ble-0.1.15.tar.xz -C ~/.local/share/blesh
# Add the following line near the top of ~/.bashrc
[[ $- == *i* ]] && source ~/.local/share/blesh/ble.sh --noattach
# Add the following line at the end of ~/.bashrc
((_ble_bash)) && ble-attach
```
## blesh-0.1 fixes
- edit,highlight: backport changes in rebased commits dfac242
- bump 0.1.15 3f4d866
## Fixes
- edit (sword): fix definition of `sword` (shell words) `#D1441` 03980f1 (master: f923388)
- bind: work around broken `cmd_xmap` after switching the editing mode `#D1478` 847e602 (master: 8d354c1)
- benchmark (`ble-measure`): fix a bug that the result is always 0 in Bash 3 and 4 (fixup 4759768 (master: bbc2a90)) `#D1615` a034c91
- main: work around `. ble.sh --{test,update,clear-cache}` in intereactive sessions `#D1555` 4759768 (master: bbc2a90)
- main: fix reloading after ble-update (fixup 4759768 (master: bbc2a90)) (fixed by oc1024) `#D1558` 9372670
- main: fix exit status for `bash ble.sh --test` (fixup 4759768 (master: bbc2a90)) `#D1558` 641238a
- main: work around sourcing `ble.sh` inside subshells `#D1554` 4759768 (master: bbc2a90)
- util: work around the Bash 3 bug of array assignments with `^A` and `^?` in Bash 3.2 `#D1614` 9648bd4 (master: b9f7611)
- decode, canvas, etc.: explicitly treat CSI arguments as decimal numbers (reported by GorrillaRibs) `#D1625` 40a0ec9 (master: c6473b7) 2ea48d7
- edit: fix a bug that `command-help` doesn't work `#D1635` c99e2f1 (master: 0f6a083)
- canvas: update prompt trace on `char_width_mode` change (reported by Barbarossa93) `#D1642` 5b22cd6 (master: 68ee111)
- complete: do not generate keywords for quoted command names `#D1691` cd75f39 (master: 60d244f)
- progcomp: retry completions on `$? == 124` also for non-default completions (reported by SuperSandro2000) `#D1759` a66b547 (master: 82b9c01)
- edit: fix the restore failure of `PS1` and `PROMPT_COMMAND` on `ble-detach` `#D1784` a0f6594 (master: b9fdaab)
- history: work around possible dirty prefix `*` in the history output `#D1808` 0ed2ffb (master: 64a740d)
- main. util: fix problems of readlink etc. found by test in macOS (reported by aiotter) `#D1849` 1dc5938 (master: fa955c1) `#D1855` a22e145
- global: quote `return $?` `#D1884` c2ba90b (master: 801d14a)
- bind: fix <kbd>M-C-@</kbd>, <kbd>C-x C-@</kbd>, and <kbd>M-C-x</kbd> (`bash-4.2 -o emacs`) `#D1920` de577dc (master: a410b03)
## Changes
- syntax: exclude <code>\\ + LF</code> at the word beginning from words (motivated by cmplstofB) `#D1431` 69156f1 (master: 67e62d6)
- edit: change default behavior of <kbd>C-w</kbd> and <kbd>M-w</kbd> to operate on backward words `#D1448` 0a07c13 (master: 47a3301)
- edit: the widgets `{kill,copy,delete}-region-or` now receives widgets as arguments `#D1021` ec16708 (master: bbbd155)
- main: show notifications against debug versions of Bash `#D1612` 8f989e4 (master: 8f974aa)
- main: suppress non-interactive warnings from manually sourced startup files (reported by andreclerigo) `#D1676` 2a045d8 (master: 0525528) 88e2df5
- main: suppress non-interactive warnings from manually sourced startup files (reported by andreclerigo) `#D1676` 0525528 4ef844e (master: 88e2df5)
- util (`ble/util/buffer`): hide cursor in rendering `#D1758` 444abff (master: e332dc5)
- edit (`ble-detach`): prepend a space to `stty sane` for `HISTIGNORE=' *'` `#D1796` acb7c08 (master: 26b532e)
- history: disable the history file when `HISTFILE` is empty `#D1836` a79095a (master: 9549e83)
## Compatibility
- global: work around empty `vi_imap` cache by `tmux-resurrect` `#D1562` b0cc0a3 (master: 560160b)
- cmap: add `st`-specific escape sequences for cursor keys `#D1633` ae298f1 (master: acfb879)
- cmap: distinguish <kbd>find</kbd>/<kbd>select</kbd> from <kbd>home</kbd>/<kbd>end</kbd> for openSUSE `inputrc.keys` (reported by cornfeedhobo) `#D1648` 603cf41 (master: c4d28f4)
- cmap: freeze the internal codes of <kbd>find</kbd>/<kbd>select</kbd> and kitty special keys `#D1674` 66263c4 (master: fdfe62a)
- decode: work around the overwritten builtin `set` (reported by eadmaster) `#D1680` 43dcb66 (master: a6b4e2c)
- complete: work around the variable leaks by `virsh` completion from `libvirt` (reported by telometto) `#D1682` d13ce5b (master: f985b9a)
- stty: do not remove keydefs for <kbd>C-u</kbd>, <kbd>C-v</kbd>, <kbd>C-w</kbd>, and <kbd>C-?</kbd> (reported by laoshaw) `#D1683` 6335dc2 (master: 82f74f0)
- main (`ble/util/readlink`): work around non-standard or missing `readlink` (motivated by peterzky) `#D1720` 94137b7 (master: a41279e)
- global: work around the arithmetic syntax error of `10#` in Bash-5.1 `#D1734` 7c2463e (master: 7545ea3)
- global: adjust implementations for Bash 5.2 `patsub_replacement` `#D1738` f1599ee (master: 4590997)
- main: check `/dev/tty` on startup (reported by andychu) `#D1749` 28e9c44 (master: 711c69f)
- global: work around `shopt -s compat42` `#D1754` 59075cc (master: a75bb25)
- global: identify bash-4.2 bug that internal quoting of `${v/%$empty/"$rep"}` remains `#D1753` 59075cc (master: a75bb25)
- prompt: fix a bug of `ble/prompt/print` redundantly quoting `$` `#D1752` 59075cc (master: a75bb25)
- global: work around `compat42` quoting of `"${v/pat/"$rep"}"` `#D1751` 59075cc (master: a75bb25)
- util: add identification of Windows Terminal `wt` `#D1758` 444abff (master: e332dc5)
- global: work around bash-3.0 bug that single quotes remains for `"${v-$''}"` `#D1774` d0dc13e (master: 9b96578)
- highlight: fix a problem that the attribute of the last character is applied till EOL `#D1393` 2ddb1ba `#D1395` 8c33557 (master: ef09932)
- main: resolve empty `HOSTNAME` [add `histdb`] `#D1925` e6cc6c3 (master: 44d9e10)
- main: warn empty `LANG` [main: support an option `--inputrc={diff,all,user,none}`] `#D1926` 2bd1544 (master: 92f2006)
- term (`terminology`): work around terminal glitches `#D1946` c5c3bc9 (master: 9a1b4f9)
- edit: restore `PS1` while processing `bind -x` (reported by adoyle-h) `#D2024` 94db09b (master: 2eadcd5)
## Optimization
- prompt: fix not properly set `$?` in `${PS1@P}` evaluation (reported by nihilismus) `#D1644` a7b5c4b (master: 521aff9)
## Internal changes and fixes
- main: include hostname in local runtime directory `#D1444` 1a5e90a (master: 6494836)
- global: fix status check for read timeout `#D1467` b56d638 (master: e886883)
- util, etc: ensure each function to work with arbitrary `IFS` `#D1490` `#D1491` 7228fd0 (master: 5f9adfe)
- util: fix leak variables `buff`, `trap`, `{x,y}{1,2}` `#D1572` de71ada (master: 5967d6c)
- make: add fallback Makefile for BSD make `#D1805` 2cb758f (master: e5d8d00)
- util, decode, vi: fix leak variables `#D1933` a2197a6 (master: 8d5cab8)
- syntax: fix code formatting [histdb: support auto-complete source `histdb-word`] `#D1938` 492349f (master: 00cae74)
## Test
- util (ble/util/s2bytes): clear locale cache `#D1881` a8d7fd7 (master: 2e1a7c1)
- util (ble/util/s2c): work around intermediate mbstate of bash <= 5.2 `#D1881` a8d7fd7 (master: 2e1a7c1)
- util (ble/encoding:UTF-8/b2c): fix interpretation of leading byte `#D1881` a8d7fd7 (master: 2e1a7c1)
--------------------------------------------------------------------------------
# ble-0.4.0-devel2
## Usage
**Prerequisites**
Bash 3.0+ and basic POSIX utilities are required.
**Download ble-0.4.0-devel2.tar.xz**
https://github.com/akinomyoga/ble.sh/releases/download/v0.4.0-devel2/ble-0.4.0-devel2.tar.xz
```bash
# DOWNLOAD with wget
wget https://github.com/akinomyoga/ble.sh/releases/download/v0.4.0-devel2/ble-0.4.0-devel2.tar.xz
# DOWNLOAD with curl
curl -LO https://github.com/akinomyoga/ble.sh/releases/download/v0.4.0-devel2/ble-0.4.0-devel2.tar.xz
```
**Trial & Install**
```bash
# TRIAL
tar xJf ble-0.4.0-devel2.tar.xz
source ble-0.4.0-devel2/ble.sh
# INSTALL (quick)
tar xJf ble-0.4.0-devel2.tar.xz -C ~/.local/share/blesh
echo 'source ~/.local/share/blesh' >> ~/.bashrc
# INSTALL (more robust)
tar xJf ble-0.4.0-devel2.tar.xz -C ~/.local/share/blesh
# Add the following line near the top of ~/.bashrc
[[ $- == *i* ]] && source ~/.local/share/blesh/ble.sh --attach=none
# Add the following line at the end of ~/.bashrc
[[ ${BLE_VERSION-} ]] && ble-attach
```
--------------------------------------------------------------------------------
# ble-0.3.3
## Usage
**Prerequisites**
Bash 3.0+ and basic POSIX utilities are required.
**Download ble-0.3.3.tar.xz**
https://github.com/akinomyoga/ble.sh/releases/download/v0.3.3/ble-0.3.3.tar.xz
```bash
# DOWNLOAD with wget
wget https://github.com/akinomyoga/ble.sh/releases/download/v0.3.3/ble-0.3.3.tar.xz
# DOWNLOAD with curl
curl -LO https://github.com/akinomyoga/ble.sh/releases/download/v0.3.3/ble-0.3.3.tar.xz
```
**Trial & Install**
```bash
# TRIAL
tar xJf ble-0.3.3.tar.xz
source ble-0.3.3/ble.sh
# INSTALL
tar xJf ble-0.3.3.tar.xz -C ~/.local/share/blesh
# Add the following line near the top of ~/.bashrc
[[ $- == *i* ]] && source ~/.local/share/blesh/ble.sh --attach=none
# Add the following line at the end of ~/.bashrc
[[ ${BLE_VERSION-} ]] && ble-attach
```
## New features
- syntax: allow unquoted `[!` and `[^` in `simple-word` (reported by cmplstofB) `#D1303` 4bf8b86 (master: 1efe833)
## Changes
- auto-complete: bind `insert-on-end` to `C-e` `#D1250` 1070aba (master: 90b45eb)
- util (`bleopt`): fail when a specified bleopt variable does not exist (test-util) 0a51044 (master: 5966f22)
- edit: preserve `PS1` when `internal_suppress_bash_output` is set `#D1344` 537acf2 (master: 6ede0c7)
- complete: change to generate filenames starting from `.` by default `#D1425` e26867d (master: 987436d)
## Fix
- [ble-0.3] reload: fix a bug that the state is broken by `ble-reload` `#D1266` f2f30d1 (master: N/A)
- decode (`ble/builtin/bind`): remove comment from bind argument `#D1267` 82f4aaa (master: 880bb2c)
- complete: clear menu on history move `#D1248` 04fddd6 (master: 06cc7de)
- syntax: fix a bug that arguments of `eval` are not highlighted `#D1254` 38a7fc7 (master: 5046d14)
- decode: use `BRE` instead of `ERE` for `POSIX sed` (reported by dylankb) `#D1283` a577ec4 (master: 2184739)
- vi (vi-command/nth-column): fix a bug in arithmetic expansion (reported by andychu) `#D1292` ea2fa8e (master: da6cc47)
- complete: fix a bug that menu-filter is only partially turned off by `complete_menu_filter` `#D1298` 7278e27 (master: b3654e2)
- syntax: fix failglob errors of heredocs of the form `<<$(echo A)` `#D1308` 5ba9400 (master: 3212fd2)
- util (`bleopt`): fix a bug that a new setting is not defined with `name:=` (test-util) `#D1312` f2dbad0 (master: c757b92)
- util (`ble/util/{save,restore}-vars`): fix a bug that `name` and `prefix` cannot be saved/restored (test-util) f91f7ed (master: 5f2480c)
- util (`ble/path#remove{,-glob}`): fix corner cases (test-util) 2ba1d42 (master: ccbc9f8)
- util (`ble/variable#get-attr`): fix an error message with special variable names such as `?` and `*` `#D1321` b58f006 (master: 557b774)
- edit: fix a bug that `set +H` is cancelled on command execution `#D1332` bc454a2 (master: 02bdf4e)
- syntax (`ble/syntax/parse/shift`): fix a bug of shift skip in nested words `#D1333` 78e2170 (master: 65fbba0)
- util (`ble-stackdump`): fix a shift of line numbers `#D1337` 1505a5b (master: a14b72f)
- edit (`ble-bind -x`): check range of `READLINE_{POINT,MARK}` `#D1339` 1bc1ff6 (master: efe1e81)
- main: fix a bug that `~/.config/blesh/init.sh` is not detected (GitHub #53 by rux616) 9f74da6 (master: 61f9e10)
- util (`ble/string#to{upper,lower}`): work around `LC_COLLATE=en_US.utf8` (test-util) `#D1341` 5d9aa64 (master: 1f6b44e) `#D1355` 4e67719 (master: 4da6103)
- fixup 5d9aa64 fef40eb (master: N/A)
- util (encoding, keyseq): fix miscelleneous encoding bugs (test-util) 6d72d2a (master: 435bd16)
- edit: work around `WINCH` not updating `COLUMNS`/`LINES` after `ble-reload` `#D1345` e2d54a2 (master: a190455)
- complete: initialize `bleopt complete_menu_style` options before `complete_load` hook (reported by rux616) `#D1352` 15ba24f (master: 8a9a386)
- main: fix problems caused by multiple `source ble.sh` in bashrc `#D1354` 983e8a9 (master: 5476933)
- syntax: allow single-character variable name in named redirections `{a}<>` `#D1360` 52de342 (master: 4760409)
- decode (`bind`): work around `shopt -s nocasematch` (reported by tigger04) `#D1372` b34ad58 (master: 855cacf)
- prompt: fix a bug that rprompt is not cleared when `bleopt prompt_rps1` is reset `#D1377` c736bd5 (master: 1904b1d)
- complete: fix a bug of duplicated completions of filenames with spaces `#D1390` 048f17e (master: 98576c7)
- complete: fix bugs that quotation disappears on ambiguous completion `#D1387` 048f17e (master: 98576c7)
- complete: fix a bug that progcomp retry by 124 caused the default completion again `#D1386` 048f17e (master: 98576c7)
- syntax (tree-enumerate): fix unmodified `wtype` of reconstructed words at the end `#D1385` 048f17e (master: 98576c7)
- complete: fix superlinear performace of ambiguous matching globpat `#D1389` bd4657a (master: 71afaba)
- prompt: fix a bug that lonig rps1 is not correctly turned off `#D1401` 9266961 (master: d84bcd8)
- prompt: fix extra spaces on line folding before double width character `#D1400` 9266961 (master: d84bcd8)
- syntax (glob bracket expression): fix a bug of unsupported POSIX brackets `#D1402` e1eca65 (master: 6fd9e22)
- syntax (`ble/syntax:bash/simple-word/evaluate-path-spec`): fix a bug of unrecognized `[!...]` and `[^...]` `#D1403` 50fcd03 (master: 0b842f5)
- highlight: fix remaininig highlighting of vanishing words `#D1421` `#D1422` 0f85719 (master: 1066653)
- highlight: fix unhighlighted tilde expansions `~+` (reported by cmplstofB) `#D1424` 1f9abf6 (master: a32962e)
- complete: fix a problem that the user setting `dotglob` is changed `#D1425` e26867d (master: 987436d)
- complete: fix a problem of redundant unmatched ambiguous part with tilde expansions in the common prefix `#D1417` 20cb6af (master: 5777d7f)
- complete (`source:file`): fix a bug that tilde expansion candidates are always filtered out `#D1416` 20cb6af (master: 5777d7f)
- complete (`cd`): fix duplicate candidates by `CDPATH` (reported by Lennart00 at `oh-my-bash`) `#D1415` 20cb6af (master: 5777d7f)
## Compatibility
- msys2: support2 MSYS (motivated by SUCHMOKUO) `#D1264` 500e051 (master: 47e2863)
- edit: support `\$` in `PS1` for MSYS2 `#D1265` b8c2ca6 (master: f6f8956)
- edit: fixup b8c2ca6 fe78bd6 (master: N/A)
- msys2: work around MSYS2 Bash bug of missing <kbd>CR</kbd> `#D1270` 8c09190 (master: 71f3498)
- edit (`ble/widget/bracketed-paste`): fix error messages on `paste_end` in older version of Bash (test-util) 1631069 (master: b2c7d1c)
- decode: work around Bash-3.1 bug of `declare -f` rejecting special characters in function names (test-util) 1631069 (master: b2c7d1c)
- util (`ble/variable#get-attr`): fix a bug that attributes are not obtained in Bash <= 4.3 (test-util) 1631069 (master: b2c7d1c)
- decode: work around Bash-4.1 bug that locale not applied with `LC_CTYPE=C eval command` (test-util) 1631069 (master: b2c7d1c)
- complete: follow Bash-5.1 change of arithmetic literal `10#` `#D1322` b58f006 (master: 557b774)
- decode: work around Bash-4.1 arithmetic bug of array subscripts evaluated in discarded branches `#D1320` b58f006 (master: 557b774)
- decode: fix a bug of broken cmap cache found in ble-0.3 `#D1327` 4b15993 (master: 16b56bf)
- util (strftime): fix a bug not working with `-v var` option in Bash <= 4.1 (test-util) 360211c (master: f1a2818)
- complete: work around slow `compgen -c` in Cygwin `#D1329` 185a443 (master: 5327f5d)
- edit: work around problems with `mc` (reported by onelittlehope) `#D1392` 4d534b4 (master: e97aa07)
- highlight: fix a problem that the attribute of the last character is applied till EOL `#D1393` f47a5b8 (master: 2ddb1ba) `#D1395` 8c1e17c (master: ef09932)
## Internal
- global: check isolated identifiers and leak variables `#D1246` f92ba5c (master: 19cc99d) 9461953 (master: 2e74b6d)
- main: unset `BLE_VERSION`, `_ble_bash`, etc. on `ble-unload` `#D1382` 2bbd0fb (master: 6b615b6)
- complete: fix unfiltered tilde expansions `#D1414` 20cb6af (master: 5777d7f)
-------------------------------------------------------------------------------
# ble-0.2.6
## New features
- syntax: allow unquoted `[!` and `[^` in `simple-word` (reported by cmplstofB) `#D1303` 5cff40f (master: 1efe833)
## Changes
- edit: preserve `PS1` when `internal_suppress_bash_output` is set `#D1344` 72ae9c6 (master: 6ede0c7)
## Fix
- decode: use `BRE` instead of `ERE` for `POSIX sed` (reported by dylankb) `#D1283` bca4598 (master: 2184739)
- vi (vi-command/nth-column): fix a bug in arithmetic expansion (reported by andychu) `#D1292` 4260bc2 (master: da6cc47)
- syntax: fix failglob errors of heredocs of the form `<<$(echo A)` `#D1308` 1f874ba (master: 3212fd2)
- util (`bleopt`): fix a bug that a new setting is not defined with `name:=` (test-util) `#D1312` a9eb0e9 (master: c757b92)
- util (`ble/util/{save,restore}-vars`): fix a bug that `name` and `prefix` cannot be saved/restored (test-util) 49841db (master: 5f2480c)
- edit: fix a bug that `set +H` is cancelled on command execution `#D1332` 2ff6d06 (master: 02bdf4e)
- syntax (`ble/syntax/parse/shift`): fix a bug of shift skip in nested words `#D1333` bc935bd (master: 65fbba0)
- util (`ble-stackdump`): fix a shift of line numbers `#D1337` b597e90 (master: a14b72f)
- edit (`ble-bind -x`): check range of `READLINE_{POINT,MARK}` `#D1339` 47a93e8 (master: efe1e81)
- util (`ble/string#to{upper,lower}`): work around `LC_COLLATE=en_US.utf8` (test-util) `#D1341` 5b32621 (master: 1f6b44e) `#D1355` b38ef10 (master: 4da6103)
- util (encoding, keyseq): fix miscelleneous encoding bugs (test-util) 03c0b44 (master: 435bd16)
- edit: work around `WINCH` not updating `COLUMNS`/`LINES` after `ble-reload` `#D1345` 50af6a5 (master: a190455)
- syntax: allow single-character variable name in named redirections `{a}<>` `#D1360` f81734f (master: 4760409)
- syntax (glob bracket expression): fix a bug of unsupported POSIX brackets `#D1402` b7ea892 (master: 6fd9e22)
- highlight: fix remaininig highlighting of vanishing words `#D1421` `#D1422` cc5e4d1 (master: 1066653)
- highlight: fix unhighlighted tilde expansions `~+` (reported by cmplstofB) `#D1424` 3f7f044 (master: a32962e)
## Compatibility
- msys2: support2 MSYS (motivated by SUCHMOKUO) `#D1264` 7cf81c0 (master: 47e2863)
- edit: support `\$` in `PS1` for MSYS2 `#D1265` 8f44624 (master: f6f8956)
- msys2: work around MSYS2 Bash bug of missing <kbd>CR</kbd> `#D1270` bbe1b61 (master: 71f3498)
- edit (`ble/widget/bracketed-paste`): fix error messages on `paste_end` in older version of Bash (test-util) a80f1d1 (master: b2c7d1c)
- decode: work around Bash-3.1 bug of `declare -f` rejecting special characters in function names (test-util) a80f1d1 (master: b2c7d1c)
- util (`ble/variable#get-attr`): fix a bug that attributes are not obtained in Bash <= 4.3 (test-util) a80f1d1 (master: b2c7d1c)
- decode: work around Bash-4.1 bug that locale not applied with `LC_CTYPE=C eval command` (test-util) a80f1d1 (master: b2c7d1c)
- decode: fix a bug of broken cmap cache found in ble-0.3 `#D1327` 366e8c1 (master: 16b56bf)
- util (strftime): fix a bug not working with `-v var` option in Bash <= 4.1 (test-util) 4f11463 (master: f1a2818)
- complete: work around slow `compgen -c` in Cygwin `#D1329` 887be6e (master: 5327f5d)
- edit: work around problems with `mc` (reported by onelittlehope) `#D1392` a2d6099 (master: e97aa07)
## Internal
- global: check isolated identifiers and leak variables `#D1246` 146c98b (master: 19cc99d)
-------------------------------------------------------------------------------
# ble-0.1.14
## Change
- edit: preserve `PS1` when `internal_suppress_bash_output` is set `#D1344` 549f8f5 (master: 6ede0c7)
## Fix
- fixup ab01ceb 8129816 (v0.2: 51bde60)
- decode: use `BRE` instead of `ERE` for `POSIX sed` (reported by dylankb) `#D1283` 1244d86 (master: 2184739)
- edit: fix a bug that `set +H` is cancelled on command execution `#D1332` ba3687a (master: 02bdf4e)
- syntax (`ble/syntax/parse/shift`): fix a bug of shift skip in nested words `#D1333` 16fb351 (master: 65fbba0)
- util (`ble-stackdump`): fix a shift of line numbers `#D1337` 5d5b86b (master: a14b72f)
- edit (`ble-bind -x`): check range of `READLINE_{POINT,MARK}` `#D1339` 6909cc0 (master: efe1e81)
- util (`ble/string#to{upper,lower}`): work around `LC_COLLATE=en_US.utf8` (test-util) `#D1341` 31476cc (master: 1f6b44e) `#D1355` 65cab5c (master: 4da6103)
- util (encoding, keyseq): fix miscelleneous encoding bugs (test-util) 11d8db7 (master: 435bd16)
- edit: work around `WINCH` not updating `COLUMNS`/`LINES` after `ble-reload` `#D1345` e15c5a6 (master: a190455)
- syntax: allow single-character variable name in named redirections `{a}<>` `#D1360` 6bbed24 (master: 4760409)
- highlight: fix remaininig highlighting of vanishing words `#D1421` `#D1422` bf8fdc8 (master: 1066653)
## Compatibility
- global: work around Bash 3.2 bug of array initialization with <kbd>SOH</kbd>/<kbd>DEL</kbd> `#D1238` 566f53e (master: defdbd4) `#D1241`
- msys2: support2 MSYS (motivated by SUCHMOKUO) `#D1264` 19a36ea (master: 47e2863)
- edit: support `\$` in `PS1` for MSYS2 `#D1265` 8658738 (master: f6f8956)
- msys2: work around MSYS2 Bash bug of missing <kbd>CR</kbd> `#D1270` b72c063 (master: 71f3498)
- decode: fix a bug of broken cmap cache found in ble-0.3 `#D1327` fc6ded3 (master: 16b56bf)
- util (strftime): fix a bug not working with `-v var` option in Bash <= 4.1 (test-util) cb2389c (master: f1a2818)
- complete: work around slow `compgen -c` in Cygwin `#D1329` d6d49cc (master: 5327f5d)
- edit: work around problems with `mc` (reported by onelittlehope) `#D1392` 15111cf (master: e97aa07)
## Internal
- global: check isolated identifiers and leak variables `#D1246` 03b3204 (master: 19cc99d) 2e74b6d

28
.local/share/blesh/doc/contrib/LICENSE Normal file
View file

@ -0,0 +1,28 @@
Copyright (c) 2020-2021, K. Murase @akinomyoga <myoga.murase@gmail.com>,
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
3. Neither the name of the copyright holder nor the names of its
contributors may be used to endorse or promote products derived from this
software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

97
.local/share/blesh/doc/contrib/README-ja.md Normal file
View file

@ -0,0 +1,97 @@
\[ Language: [English](README.md) | **日本語** ]
# blesh-contrib
[akinomyoga/ble.sh](https://github.com/akinomyoga/ble.sh)向けの設定
特に指定のない限りこのリポジトリのファイルは [3条項 BSD ライセンス](LICENSE) で提供されます。
サブディレクトリ `airline` 以下のファイルは MIT ライセンスで提供されます。
<sup>〔訳註: これは[2020年5月20日（日本標準時）時点のREADME.md](https://github.com/akinomyoga/blesh-contrib/blob/8d89d469bd46d9d1158ab5295cd48a3df6942074/README.md) (8d89d46)の，技術的内容を変更しない日本語訳です〕</sup>
## :pencil: fzfとの統合
### 選択肢その1: `~/.fzf.bash`内で設定する
fzfを`ble.sh`と共に用いたい場合，`.fzf.bash`を次のように書き直します（`/path/to/fzf`は fzf ディレクトリへのパスに置き換えてください。※fzf バイナリではなくて **fzf ディレクトリ**へのパスです）。
```bash
# fzf.bash
# fzfの設定
# ---------
_ble_contrib_fzf_base=/path/to/fzf
if [[ ! "$PATH" == *"$_ble_contrib_fzf_base/bin"* ]]; then
export PATH="${PATH:+${PATH}:}/path/to/fzf/bin"
fi
# 自動補完
# ---------------
if [[ ${BLE_VERSION-} ]]; then
ble-import -d integration/fzf-completion
else
[[ $- == *i* ]] && source "$_ble_contrib_fzf_base/shell/completion.bash" 2> /dev/null
fi
# キー束縛
# ------------
if [[ ${BLE_VERSION-} ]]; then
ble-import -d integration/fzf-key-bindings
else
source "$_ble_contrib_fzf_base/shell/key-bindings.bash"
fi
```
### 選択肢その2: `~/.blerc`内で設定する
別の方法として，`blerc`において次のように直接設定を書くこともできます（`/path/to/fzf`は各人のfzfへのパスに置き換えてください）。
この場合，`.fzf.bash`を`.bashrc`の中で呼び出さ（`source`コマンドを用い）ないでください。
```bash
# blerc
# fzfの設定
_ble_contrib_fzf_base=/path/to/fzf
ble-import -d integration/fzf-completion
ble-import -d integration/fzf-key-bindings
```
## :pencil: fzf-git
[fzf-git](https://gist.github.com/junegunn/8b572b8d4b5eddd8b85e5f4d40f17236)での設定を`ble.sh`と共に用いるには，次のように設定してください。
```bash
# bashrc / fzf.bash
if [[ ${BLE_VERSION-} ]]; then
_ble_contrib_fzf_base=/path/to/fzf
_ble_contrib_fzf_git_config=key-binding:sabbrev:arpeggio
ble-import -d integration/fzf-git
fi
```
または，`~/.blerc`内でも構成できます:
```bash
# blerc
_ble_contrib_fzf_base=/path/to/fzf
_ble_contrib_fzf_git_config=key-binding:sabbrev:arpeggio
ble-import -d integration/fzf-git
```
シェル変数`$_ble_contrib_fzf_git_config`には，有効にする束縛の種別をコロン区切りで列挙します。
`key-binding`という値で，次の形式のキー束縛を有効にします: <kbd>C-g C-f</kbd>, <kbd>C-g C-b</kbd>, <kbd>C-g C-t</kbd>, <kbd>C-g C-h</kbd>及び<kbd>C-g C-r</kbd>。
`sabbrev`という値で，次の語に対する静的略語展開を有効にします: `gf`, `gb`, `gt`, `gh`及び`gr`。
`arpeggio`という値で，次のキーの組み合わせを同時に押下できるようにします: <kbd>g f</kbd>, <kbd>g b</kbd>, <kbd>g t</kbd>, <kbd>g h</kbd>及び<kbd>g r</kbd>。
## :pencil: プロンプトシーケンス
### プロンプトシーケンス `\q{contrib/vim-mode}`
この指定はVimのモード名に展開されます。
```bash
# blerc（例）
ble-import contrib/prompt-vim-mode
PS1='[\u@\h \W]\q{contrib/vim-mode}\$ ' # PS1にモード名を表示
bleopt keymap_vi_mode_show:= # モード行を表示しない
```

305
.local/share/blesh/doc/contrib/README.md Normal file
View file

@ -0,0 +1,305 @@
[ Languages: **English** | [日本語](README-ja.md) (Japanese) ]
# blesh-contrib
Settings for [akinomyoga/ble.sh](https://github.com/akinomyoga/ble.sh)
Unless otherwise specified, files in this repository are licensed by [BSD 3-clause license](LICENSE).
The files in `airline` are licensed by the MIT License.
## :pencil: fzf integration
Source: [`fzf-completion.bash`](https://github.com/akinomyoga/blesh-contrib/blob/master/integration/fzf-completion.bash),
[`fzf-key-bindings.bash`](https://github.com/akinomyoga/blesh-contrib/blob/master/integration/fzf-key-bindings.bash)
Note: If you would like to integrate `fzf-completion` with `bash-completion`, `bash-completion` needs to be loaded before `fzf-completion` is loaded.
### Option 1: Setup in `~/.fzf.bash`
If you would like to use fzf with `ble.sh`, for example, you can rewrite your `.fzf.bash` in the following way.
In this case, `.fzf.bash` needs to be sourced after `ble.sh`.
Please replace `/path/to/fzf-directory`, `/path/to/fzf/...`, and `/path/to/bash_completion.sh` if necessary.
```bash
# fzf.bash
# If ble/contrib/integration/fzf cannot find the fzf directory, please set the
# following variable "_ble_contrib_fzf_base" manually. The value
# "/path/to/fzf-directory" should be replaced by a path to the fzf directory
# such as "$HOME/.fzf" or "/usr/share/fzf" that contain
# "shell/{completion,key-bindings}.bash" or "{completion,key-bindings}.bash".
#_ble_contrib_fzf_base=/path/to/fzf-directory
# Setup fzf
# ---------
if [[ ! "$PATH" == *"/path/to/fzf/bin"* ]]; then
export PATH="${PATH:+${PATH}:}/path/to/fzf/bin"
fi
# Auto-completion
# ---------------
if [[ $- == *i* ]]; then
# Note: If you would like to combine fzf-completion with bash_completion, you
# need to load bash_completion earlier than fzf-completion.
#source /path/to/bash_completion.sh
if [[ ${BLE_VERSION-} ]]; then
ble-import -d integration/fzf-completion
else
source /path/to/fzf/shell/completion.bash 2> /dev/null
fi
fi
# Key bindings
# ------------
if [[ ${BLE_VERSION-} ]]; then
ble-import -d integration/fzf-key-bindings
else
source /path/to/fzf/shell/key-bindings.bash
fi
```
### Option 2: Setup in `~/.blerc`
Or, you can directly write settings in your `blerc` as follows.
In this case, do not source `.fzf.bash` in your `.bashrc`.
```bash
# blerc
# If ble/contrib/integration/fzf cannot find the fzf directory, please set the
# following variable "_ble_contrib_fzf_base" manually. The value
# "/path/to/fzf-directory" should be replaced by a path to the fzf directory
# such as "$HOME/.fzf" or "/usr/share/fzf" that contain
# "shell/{completion,key-bindings}.bash" or "{completion,key-bindings}.bash".
#_ble_contrib_fzf_base=/path/to/fzf-directory
# Note: If you would like to combine fzf-completion with bash_completion, you
# need to load bash_completion earlier than fzf-completion.
#source /path/to/bash_completion.sh
# Setup fzf
ble-import -d integration/fzf-completion
ble-import -d integration/fzf-key-bindings
```
Note: the option `-d` for `ble-import` means the asynchronous loading of the
modules. If you need to immediately load the module, please drop the option
`-d`. For example, if the user needs to call a function defined in a module,
the module can be loaded immediately, so that the user can use the function.
```bash
ble-import integration/fzf-completion
_fzf_setup_completion foo bar
```
However, in most cases, the user would probably want to reserve the execution
of the commands relying on the module by using the `-C callback` option. In
this way, the reserved command is evaluated when the module is successfully
loaded.
```bash
ble-import -d integration/fzf-completion \
-C '_fzf_setup_completion foo bar'
```
## :pencil: `integration/fzf-git`
Source: [`fzf-git.bash`](https://github.com/akinomyoga/blesh-contrib/blob/master/integration/fzf-git.bash)
You can use the [`junegunn/fzf-git.sh`](https://gist.github.com/junegunn/8b572b8d4b5eddd8b85e5f4d40f17236) settings for `ble.sh` with the following setup.
```bash
# bashrc / fzf.bash
if [[ ${BLE_VERSION-} ]]; then
# If needed. See above for details:
#_ble_contrib_fzf_base=/path/to/fzf-directory
_ble_contrib_fzf_git_config=key-binding:sabbrev:arpeggio
ble-import -d integration/fzf-git
fi
```
Or you can configure it in `~/.blerc`:
```bash
# blerc
# If needed. See above for details:
#_ble_contrib_fzf_base=/path/to/fzf-directory
_ble_contrib_fzf_git_config=key-binding:sabbrev:arpeggio
ble-import -d integration/fzf-git
```
The shell variable `_ble_contrib_fzf_git_config` is a colon-separated list of the enabled types of bindings.
The value `key-binding` enables the key bindings of the form <kbd>C-g C-f</kbd>, <kbd>C-g C-b</kbd>, <kbd>C-g C-t</kbd>, <kbd>C-g C-h</kbd>, <kbd>C-g C-r</kbd>, and <kbd>C-g C-s</kbd>.
The value `sabbrev` enables the sabbrev expansion for the words `gf`, `gb`, `gt`, `gh`, `gr`, and `gs`.
The value `arpeggio` enables the simultaneous key combinations of <kbd>g f</kbd>, <kbd>g b</kbd>, <kbd>g t</kbd>, <kbd>g h</kbd>, <kbd>g r</kbd>, and <kbd>g s</kbd>.
The value `old-functions` enables old function names: `is_in_git_repo`, `fzf-down`, `gh`, `gb`, `gt`, `gh`, `gr`, and `gs`.
# &#x2699; Prompt sequences
## :pencil: `contrib/prompt-vim-mode`
Source: [`prompt-vim-mode.bash`](https://github.com/akinomyoga/blesh-contrib/blob/master/prompt-vim-mode.bash)
### Prompt sequence `\q{contrib/vim-mode}`
This prompt sequence expands to the vim mode name.
```bash
# blerc (example)
ble-import contrib/prompt-vim-mode
PS1='[\u@\h \W]\q{contrib/vim-mode}\$ ' # show mode name in PS1
bleopt keymap_vi_mode_show:= # hide mode line
```
## :pencil: `contrib/prompt-git`
Source: [`prompt-git.bash`](https://github.com/akinomyoga/blesh-contrib/blob/master/prompt-git.bash)
```bash
# blerc (example)
ble-import contrib/prompt-git
bleopt prompt_rps1='\q{contrib/git-info}'
```
### Prompt sequence `\q{contrib/git-info}`
This expands to a string that explains the current git status.
### Prompt sequence `\q{contrib/git-name}`
This expands to the directory name of the repository.
### Prompt sequence `\q{contrib/git-hash N}`
This expands to the commit hash.
The hash is truncated to the length `N`.
The default value for `N` is `7`.
### Prompt sequence `\q{contrib/git-branch}`
This expands to the branch name (or tag name or hash) of `HEAD`.
### Prompt sequence `\q{contrib/git-path}`
This expands to the current path relative to the root directory of the repository.
## :pencil: `contrib/prompt-elapsed`
Source: [`prompt-elapsed.bash`](https://github.com/akinomyoga/blesh-contrib/blob/master/prompt-elapsed.bash)
Measures the time of the previous command execution.
```bash
# blerc (example)
ble-import contrib/prompt-elapsed
bleopt prompt_rps1='\g{fg=69,italic}\q{contrib/elapsed}'
```
### Prompt sequence `\q{contrib/elapsed}`
This expands to the high-resolution elapsed time for the command execution.
### Prompt sequence `\q{contrib/elapsed-real}`
This expands to the `real` time of `time`.
### Prompt sequence `\q{contrib/elapsed-user}`
This expands to the `user` time of `time`.
### Prompt sequence `\q{contrib/elapsed-sys}`
This expands to the `sys` time of `time`.
### Prompt sequence `\q{contrib/elapsed-cpu}`
This expands to the average cpu usage.
## :pencil: colorglass
If your terminal supports 24-bit color, you can adjust the theme colors by specifying gamma, contrast, hue rotation, etc.
This also works for the terminals without the 24-bit color support if `bleopt term_index_colors` is properly set up, but the resulting colors would be reduced to a smaller number of colors.
```bash
ble-import contrib/colorglass
# If your terminal does not support the 24-bit colors, please explicitly
# configure it by putting the following line:
#bleopt term_true_colors=
```
### Blopet colorglass_gamma
This option specifies the change of gamma by percentage.
For example, `bleopt colorglass_gamma=5` performs the gamma correction with $\gamma=1.05$, and `bleopt colorglass_gamma=-5` performs the gamma correction with $\gamma=0.95$
```bash
# default
bleopt colorglass_gamma=0
```
### Blopet colorglass_contrast
This option specifies the contrast modification in the range -100..100.
```bash
# default
bleopt colorglass_contrast=0
```
### Blopet colorglass_rotate
This option specifies the angle of hue rotation in degrees.
```bash
# default
bleopt colorglass_rotate=0
```
### Blopet colorglass_saturation
This option specifies the change of saturation in the range -100..100.
```bash
# default
bleopt colorglass_saturation=0
```
### Blopet colorglass_brightness
This option specifies the change of brightness in the range -100..100.
```bash
# default
bleopt colorglass_brightness=0
```
### Blopet colorglass_alpha
This option specifies the opacity in the range 0..255 when the color is synthesized with the background color specified by `bleopt colorglass_color`.
```bash
# defualt
bleopt colorglass_alpha=255
```
### Blopet colorglass_color
This option specifies the background color used by the color synthesis by `bleopt colorglass_alpha`.
```bash
# defualt
bleopt colorglass_color=0x8888FF
```