Manual §8 Miscellaneous

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

8. Miscellaneous

8.1 ble.sh shell variables

8.1.1 Shell variable BLE_VERSION^†

This variable contains the version string of the currently loaded ble.sh.

8.1.2 Shell variable BLE_VERSINFO (Array)^†

This array contains the version information of the currently loaded ble.sh The major version, minor version and patch level are contained from ${BLE_VERSINFO[0]} to ${BLE_VERSINFO[2]}. ${BLE_VERSINFO[3]} contains the commit ID of git. ${BLE_VERSINFO[4]} contains the release status such as devel, alpha, beta or release. ${BLE_VERSINFO[5]} always contains the value noarch, i.e., ble.sh does not depend on a specific system.

8.1.3 Shell variable BLE_VER (v0.4)^†

This variable represents the version of ble.shin a signle integer. The value is calculated by ((BLE_VERSINFO[0] * 10000 + BLE_VERSINFO[1] * 100 + BLE_VERSINFO[2])).

8.1.4 Shell variable BLE_ONLOAD (Array) (v0.4)^†

To this array, other Bash plugins can specify initialization codes to be executed on the loading of ble.sh. This is useful when the Bash plugin does not know whether ble.sh will be loaded later or not, and want to do additional initialization when ble.sh is loaded.

8.1.5 Shell variable BLE_ATTACHED (v0.4)^†

This variable indicates the attached state of ble.sh. When ble.sh is attched, this variable contains a non-empty string. When ble.sh is not attached, this variable contains an empty string.

8.1.6 Shell variable BLE_SESSION_ID (Export) (v0.4)^†

This variable contains the ID string of the current session, which has the form of the (Session Start Time in Unix Epoch)/(Bash Process ID).

8.1.7 Shell variable BLE_COMMAND_ID (v0.4)^†

This variable contains the command ID of the current user command, which is sequential number.

8.1.8 Shell variable BLE_PIPESTATUS (v0.4)^†

This variable contains the values of PIPESTATUS after the previous user command.

8.2 ble.sh functions

8.2.1 Function ble-import^†

ble-import [-dfq|--delay|--force|--query] [--] [SCRIPTFILE...]

Search file SCRIPTFILE from the specific paths, and sources the file if the file has not yet been sourced. When the option -d or --delay is specified, the loading is delayed if possible.

When any of the specified files are not found, the call of ble-import is cancled and no files will be sourced. When the option -f or --force is specified, non-existent files are ignored without errors, and only existing files are sourced.

When the option -q or --query is specified with no files, ble-import prints the list of files already sourced. When the option -q or --query is specified with one or more files, ble-import checks whether all of the specified files are already sourced and returns the result with the exit status: status 127 if any files are not found, status 1 if any files have not yet sourced, or otherwise status 0.

8.2.2 Bleopt import_path (colon-separated dirpaths) (v0.4)^†

# default
bleopt import_path="${XDG_DATA_HOME:-$HOME/.local/share}/blesh/local"

This option specifies a colon-separated list of custom search paths of ble-import.

8.2.3 Function ble-autoload^†

This sets the delayed load for the function FUNCTION. When the function FUNCTION is called for the first time, ble-import SCRIPTFILE is called. SCRIPTFILE should contain the definition of FUNCTION. When shopt -s extdebug is set, the arguments for each function call are also output.

ble-autoload SCRIPTFILE FUNCTION...

8.2.4 Function ble-stackdump^†

This is the function for debugging purpose. It prints the information of call stack of shell functions.

ble-stackdump MESSAGE

8.2.5 Function ble-assert^†

This is the function for debugging purpose. First, COMMAND is evaluated by the eval builtin. If the command fails, the call stack information together with the message MESSAGE is printed.

ble-assert COMMAND [MESSAGE]

8.2.6 Function ble-append-line^†

This function can be called from the command line to append strings to the next command line. This function can also be used from inside subshells.

ble-append-line STRING


# Examples 1

$ ble-append-line 'echo hello world'
$ echo hello world # <-- the string specified above fills the next command line


# Examples 2

$ echo echo hello | ble-append-line $(cat)
$ echo hello

8.3 Bleopt variables for internal use

8.3.1 Bleopt internal_exec_type^†

# default
bleopt internal_exec_type=gexec   # ble-0.3 and later
bleopt exec_type=gexec            # ble-0.2 and before

It specifies the context of the command execution. The value gexec specifies that the user command is evaluated in global contexts. The value exec (ble-0.3 and before) specified that the user command is evaluated in a function, but the support is removed in ble-0.4 because this is only remained for a debugging purpose and not tested well.

8.3.2 Bleopt internal_exec_int_trace (Empty/Non-empty) (v0.4)^†

# default
bleopt internal_exec_int_trace=

If this option has a non-empty value, when the execution of a shell function is interrupted by SIGINT, the processing of SIGINT by the DEBUG trap is printed to stderr.

8.3.3 Bleopt internal_ignoreeof_trap (Text)^†

# default
bleopt internal_ignoreeof_trap='Use "exit" to leave the shell.' # ble-0.3 and later
bleopt ignoreeof_message='Use "exit" to leave the shell.'       # ble-0.2 and before

This option sets the message that Bash outputs when C-d is input by user. This value is used to detect that the user inputs C-d in Bash 3.

8.3.4 Bleopt internal_suppress_bash_output (Empty/Non-empty)^†

# default
bleopt internal_suppress_bash_output=1  # ble-0.3 and later
bleopt suppress_bash_output=1           # ble-0.2 and before

# bashrc
source ble.sh -o internal_suppress_bash_output=1   # ble-0.4 and later
source ble.sh --debug-bash-output                  # ble-0.4 and later (disable)

When a non-empty value is specified to this option, the standard output and standard error from Bash is not output to the terminal. When the value is empty, ble.sh tries to realize the line editing allowing Bash to output its own standard output and error. This setting has a flickering problem and only left for debugging purpose, so it is not tested. Normally a non-empty value should be specified so as to suppress the standard output and error from Bash.

8.3.5 Bleopt internal_stackdump_enabled (Arithmetic) (v0.2)^†

# default
bleopt internal_stackdump_enabled=0   # ble-0.3 and later
bleopt stackdump_enabled=0            # ble-0.2

This option controls the output of stack dump when assertion is failed in ble.sh. When the value is evaluated to be non-zero, the stack dump is printed for assertion failures.

8.3.6 Bleopt history_lazyload (Empty/Non-empty)^†

# default
bleopt history_lazyload=1

When this option has a non-empty value, delayed loading of history is enabled. This is enabled by default. When the value is empty, the user input is processed after completing the history loading on ble-attach.

8.3.7 Bleopt idle_interval (Arithmetic) (v0.3)^†

# default
bleopt idle_interval='ble_util_idle_elapsed>600000?500:(ble_util_idle_elapsed>60000?200:(ble_util_idle_elapsed>5000?100:20))'

This option sets the interval of checking new user inputs. The value is evaluated as an arithmetic expression. On the evaluation, a shell variable ble_util_idle_elapsed is provided for the time since the last user input in millisecond. This option is used for the polling for the background execution when there is no user inputs.

8.3.8 Bleopt openat_base (Integer)^†

# default
bleopt_openat_base=30

# bashrc
source ble.sh -o openat_base=50   # ble-0.4 and later

This setting needs to be set before ble.sh is loaded or specified in the source options. Therefore the value should be assigned directly to the shell variable bleopt_openat_base instead of using bleopt command. This setting specifies the starting number of the file descriptors which ble.sh internally uses in Bash 4.0 or lower. The value of this setting is used as the number for the first file descriptor of internal use, and the next value is used for the second file descriptor, and so on. When you want to use the default value 30 and succeeding number 31, 32, etc. for other purposes, please set to this settings another value which does not conflict with file descriptors of other purposes.

8.3.9 Bleopt connect_tty (Empty/Non-Empty/Enumerate) (v0.4)^†

# default
bleopt connect_tty=1

When a non-empty value is specified, ble.sh in the child interactive Bash processes tries to connect to /dev/tty for its user interface when the initial standard streams of Bash are redirected to non-TTY streams. The standard streams for the user-command executions are kept to be the original ones. If this is set to the value inherit, ble.sh tries to export the TTY for the child ble.sh sessions in case the child fails to find the TTY. This might cause an issue in non-closing terminal window when a background process starts in the session. This does not affect the behavior of the current session.

8.3.10 Bleopt syntax_debug (Empty/Non-empty)^†

# default
bleopt_syntax_debug=

When a non-empty value is specified to this option, displays the internal syntax analysis information and the syntax tree. This is only effective in devel versions.

8.3.11 Bleopt debug_xtrace (Empty/Filename) (v0.4)^†

# default
bleopt_debug_xtrace=

When a filename is specified, the xtrace log (internally enabled by set -x) for ble.sh's internal processing is written to the file.

8.3.12 Bleopt debug_xtrace_ps4 (Prompt string) (v0.4)^†

# default
bleopt_debug_xtrace_ps4='+ '

This option specifies the value of PS4 for xtrace enabled by bleopt debug_xtrace.

8.3.13 Bleopt debug_idle (Empty/Non-Empty) (v0.4)^†

# default
bleopt_debug_idle=

When a non-empty value is specified, the background tasks currently running are shown in the info panel.

8.3.14 Bleopt debug_profiler_opts (Colon-separated list) (v0.4)^†

# default
bleopt debug_profiler_opts=line:func

This controls the behavior of ble/debug/profiler#start and ble/debug/profiler#end. When the field line and func are specified, statistics for lines and function calls, respectively, are enabled. When the field tree is specified, function-call trees are saved. Optional parameter html can be specified to line and func separated by the equal sign, i.e., line=html and func=html. In such a case, the results are also saved in the .html format.

8.3.15 Bleopt debug_profiler_tree_threshold (Number) (v0.4)^†

# default
bleopt debug_profiler_tree_threshold=5.0

This option specifies the threshold time in milliseconds to determine whether to include a command in the tree generated by bleopt debug_profiler_opts=tree. The commands that took less than this time in execution will be skipped.

8.4 Limitations of ble.sh^†

ble.sh overwrites the user settings by .inputrc or by builtin command bind. ble.sh tries to read .inputrc on load, and also translate the call of bind for ble.sh by overwriting the builtin bind by a shell function bind. However, currently the call of bind before the source of ble.sh is not reflected in ble.sh. When you rite .inputrc, the settings only applied to ble.sh can be written in the following way.

# inputrc

$if Blesh

# Settings for ble.sh

$endif

ble.sh internally uses the following traps. In ble-0.4 and later, ble.sh overwrites trap by a shell function so that users do not have to care about the existing traps by ble.sh on setting the user traps. Note that users needs to use trap but not builtin trap.

# ble-0.4
builtin trap -- 'ble/builtin/trap/.handler 0 "$BASH_COMMAND" "$@"; builtin eval -- "${_ble_builtin_trap_postproc[0]}" \# "${_ble_builtin_trap_lastarg[0]}"' EXIT
builtin trap -- 'ble/builtin/trap/.handler 2 "$BASH_COMMAND" "$@"; builtin eval -- "${_ble_builtin_trap_postproc[2]}" \# "${_ble_builtin_trap_lastarg[2]}"' INT
builtin trap -- 'ble/builtin/trap/.handler 28 "$BASH_COMMAND" "$@"; builtin eval -- "${_ble_builtin_trap_postproc[28]}" \# "${_ble_builtin_trap_lastarg[28]}"' WINCH
builtin trap -- 'ble/builtin/trap/.handler 1000 "$BASH_COMMAND" "$@"; builtin eval -- "${_ble_builtin_trap_postproc[1000]}" \# "${_ble_builtin_trap_lastarg[1000]}"' DEBUG
# Bash 3.2 and before
builtin trap -- 'ble/builtin/trap/.handler 10 "$BASH_COMMAND" "$@"; builtin eval -- "${_ble_builtin_trap_postproc[10]}" \# "${_ble_builtin_trap_lastarg[10]}"' USR1

# ble-0.3
builtin trap -- 'ble-edit/exec:gexec/.eval-TRAPINT' INT
builtin trap -- 'ble/base/unload' EXIT
builtin trap -- 'ble-edit/attach/TRAPWINCH' WINCH
# Bash 3.2 and before
builtin trap -- 'ble-edit/bind/stdout/TRAPUSR1' USR1

# Currently not used
# builtin trap -- 'ble-edit/bind/.exit-TRAPRTMAX' RTMAX

ble.sh internally uses several file descriptors starting from ${bleopt_openat_base:-30}. Users should not change these file descriptors using exec.

ble.sh prohibits overwriting the following commands and keywords using shell functions or aliases. Even if users overwrites these commands and keywords, ble.sh tries to unset the functions or aliases.

• Builtins: builtin enable unalias return break continue declare typeset local eval :
• Keywords: if then elif else case esac while until for select do done { } [[ function

ble.sh overwrites the builtin unset by a readonly function that explicitly performs builtin unset so that other function cannot overwrite unset.

---

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