What is this?

This is a bash library primarily intented for a project Orange Rigol at https://github.com/norbertkiszka/rigol-orangerigol-build

But... should be usable for many other projects with bash scripts.

Also it can be used directly straight from the terminal to help with administration tasks.

Features in short

• Colors.
• Version checker.
• Whiptail menu helper.
• Error handling by calling functions with colorized output.
• Script and function call trace.
• Exit and int signal traps.
• System functions.
• Chroot with mounts and unmounting (also after error).
• Adding own traps for different situations (see public function list below).
• Possibility to use it directly from a terminal ($ source /path/to/lib-bash.sh) instead of from script.
• After being called directly, it can be recalled by a some script (it shouldnt trigger any problems).

Usage - include in script

Add lib-bash.sh to your script:

source "/path/to/lib-bash.sh"

Usage - inside terminal with interactive bash (not in script)

You can call it directly (from interactive bash instead from a script) and after that, You can call functions in this lib just by typing them like a in a script.

First and simpliest method to do this:

source "/path/to/lib-bash.sh" # it will detect direct call and it will not call exit when error function is executed (kinda ugly behaviour)

Instead of calling it everytime, Yoy can add this line into ~/.bashrc or into ~/.profile file.

Other method possible from v0.1.2 which will behave more like in a real script. At first copy paste this code into terminal (not into script):

while true
do
  bash # nested bash
done

From now any bash exit will cause to go back to loop in previous bash which will execute another bash.

After that You can type this:

source "/path/to/lib-bash.sh" libignoredirect # it will ignore direct call and it will behave same as included from script

In that way, call to exit from this lib will cause to kill nested bash and return to previous bash which will execute another bash in a loop, instead of closing terminal emulator or using return when no arg ignoredirect is given.

After each error You have to execute last line (source...) again because we are in another bash.

Ugly workaround of this is to add this line into ~/.bashrc - but still You have to copy this loop into terminal (and press enter ofc).

This currently cannot be scripted due to another bash behaviour in interactive mode - at least as far I know.

Public functions list, description and usage

List below describes functions in order as its defined by this lib.

Side note: Not all functions arguments are documented. See source code if not sure.

General:

• version_is_eqal_or_greater_than

    Will return 1 when true, 0 otherwise.
    
    Example:

   REQUIRED_BASH_VERSION="5.1"
   if ! version_is_eqal_or_greater_than "${BASH_VERSION}" "${REQUIRED_BASH_VERSION}" ; then
   	error "Bash is older than ${REQUIRED_BASH_VERSION}. We will do cleanup and exit now, since we called error() function."
   fi
   info "Continuing..."
   do_something
   MESSAGE="Script successfully finished doing something."
   success $MESSAGE # Print success on stdout.
   success_whiptail $MESSAGE # Print success in green whiptail window (msgbox).

Colors:

• echo_green, echo_red, echo_yellow, echo_white

    Colorized echo.

• echo_green_e, echo_red_e, echo_yellow_e, echo_white_e

    Colorized echo with interpretation of backslash escapes (same as echo -e).

Error handling and debugging:

• sctrace

    Trace of process execution tree.

• show_stacktrace_for_warnings

    Will force to display (execute) stacktrace as normally only in error and error_e.

• always_show_stacktrace_at_exit

    Display (execute) stacktrace always when exit is trapped.

• forbidden_warning

    Warning will trigger error (like in a gcc with -Werror).

• forbidden_warning_disable

    Warning will not trigger error.

• check_require_args_with_real_data

    Function helper to require arg(s).

• is_executable

    Check if given command is executable by bash.
    
    It will check only first arg, since only first arg is a command and remaining args are args...

• require_executable

    Helper for functions that require (first) arg to be executable by bash (uses is_executable())
    
    It will check only first arg, since first arg is a command and remaining args are args...

• info, notice, warning, error_without_exit, error, success, success_whiptail

    Self explanatory.
    
    error function will trigger exit 1 unless lib was called directly from a terminal (bash interactive mode) and without libignoredirect passed as first arg.
    
    Any call to exit is catched by this lib and any exit code different than 0 will trigger debug output.

• info_e, notice_e, warning_e, error_without_exit_e, error_e, success_e, success_whiptail_e

    _e -  interpretation of backslash escapes (same as echo -e).

• errorhandling_use_whiptail_for_warning, errorhandling_use_whiptail_for_error

    Will force warning, warning_e, error and error_e to additionally show same message by whiptail
  

• whiptail_display_warning

    Display warning only by whiptail... And nothing more than just that.
    
    It will return after displaying whiptail msgbox.
    
    Used internally, but it can be used outside of this lib.

• whiptail_display_error

    Display error only by whiptail... And nothing more than just that.
    
    It will return after displaying whiptail msgbox.
    
    Used internally, but it can be used outside of this lib.

Traps:

• trap_exit_at_first

    Add function to trap exit at first (both on exit success and on exit error).

• trap_exit_at_end

    Add trap function at exit and at very end.

• trap_exit_at_ok

    Add trap function at exit and when exit code is 0 (exit success).

• trap_exit_at_error

    Add trap function at exit and when exit code is not 0.

Debugging:

• scriptstacktrace

    Display (via echo) script and function call stack.

System:

• random_hex

    Generate random hex chars.
    
    Arg1: optional chars count. When omitted, it will generate 32 chars.

• sys_mktempdir

    Create and test temp directory. It will return path via echo.
    
    This directory will be automatically deleted at script exit - also in case of a error.

• sys_require_dev_null, sys_require_dev_zero, sys_require_dev_urandom, sys_require_tmp

    If given device or tmp doesnt exist it will generate error. It will also check if those files are "real" null/zero/etc.

• sys_chroot_add_bind

    Add directory to bind at every sys_chroot call.
    
    This directories will be unmounted at chroot command exit and at error.
    
    If destination path doesnt exists, it will be created.
    
    Arg1: source path.
    Arg2: optional destination path - relative to chroot directory. If omitted, source path will be also used as a destination path.

• sys_chroot

    Chroot with mounted /proc, /sys, /dev, /dev/pts and optional binds added via sys_chroot_add_bind.
    
    Everything will be unmounted at exit and at error.
    
    Arg1: destination path.
    Arg2: command.
    Argn: optional args for a given command.

• scriptstacktrace

    Display (via echo) script and function call stack.

Whiptail menu helper:

• whiptail_menu_reset

    Reset all options and settings.
    
    Normally is no need to call it, since its being called everytime in function whiptail_menu_execute.

• whiptail_menu_set_height

    Set different menubox height than default. Only for next whiptail_menu_execute.
    
    This option is one time - its reset to default after each whiptail_menu_execute() call.
    
    See: whiptail_menu_set_default_height, whiptail_menu_set_default_dimensions

• whiptail_menu_set_width

    Set different menubox width than default. Only for next whiptail_menu_execute.
    
    This option is one time - its reset to default after each whiptail_menu_execute() call.
    
    See: whiptail_menu_set_default_width, whiptail_menu_set_default_dimensions

• whiptail_menu_set_list_height

    Set different menubox list height than default. Only for next whiptail_menu_execute.
    
    This option is one time - its reset to default after each whiptail_menu_execute() call.
    
    See: whiptail_menu_set_default_list_height, whiptail_menu_set_default_dimensions

• whiptail_menu_set_dimensions

    Arg1: height (optional, give a empty string to pass).
    Arg2: width (optional, give a empty string to pass).
    Arg3: list height (optional, give a empty string to pass).
    
    See: whiptail_menu_set_default_dimensions

• whiptail_menu_set_default_height, whiptail_menu_set_default_width, whiptail_menu_set_default_list_height

    Self explanatory.

• whiptail_menu_set_default_dimensions

    Set default dimensions.
    Arg1: height (optional, give a empty string to pass).
    Arg2: width (optional, give a empty string to pass).
    Arg3: list height (optional, give a empty string to pass).
    
    See: whiptail_menu_set_default_dimension, whiptail_menu_set_default_height, whiptail_menu_set_default_width, whiptail_menu_set_default_list_height

• whiptail_menu_dont_add_dot_in_key

    Force to not add dot in option ids.
    
    Those dots are only for displaying - it will be removed from WHIPTAIL_MENU_OPTION_ID by whiptail_menu_execute.
    
    This option is one time - its reset to default (display dot) after each whiptail_menu_execute() call.

• whiptail_menu_title_set_prefix

    Set prefix for titles in every whiptail_menu_execute calls (it will not be reset by whiptail_menu_reset).

• whiptail_menu_set_backtitle

    Set backtitle for next whiptail_menu_execute call.

• whiptail_menu_set_default_backtitle, whiptail_menu_is_option_id_exist

    Self explanatory.

• whiptail_menu_set_default_item

    User will see selected this option id.
    
    Option should be previously added by using whiptail_menu_option_add(), otherwise it will generate warning.
    
    See: warning, forbidden_warning

• whiptail_menu_option_add

    Add option to display.
    
    Arg1: numeric id. It can be any integer without any order and is not required to start with any special number.
    Arg2: text with displayed option

• whiptail_menu_add_option, whiptail_menu_options_add

    Alias for a whiptail_menu_option_add.

• whiptail_menu_execute

    Display whiptail (execute whiptail) to user.
    
    Selected option id is saved to a var WHIPTAIL_MENU_OPTION_ID without dot (see whiptail_menu_dont_add_dot_in_key).
    
    Selected option name is saved into a var WHIPTAIL_MENU_OPTION_NAME.
    
    If not sure how to use it, see tests/test-whiptail-menu.sh

Git:

• git_last_commit_hash_short

    Get last commit short hash.
    
    Arg1: optional directory. If not given, current directory will be used.

• git_list_modified_files

    Get list of modified files since last commit.
    
    Arg1: optional directory. If not given, current directory will be used.