functions

#!/usr/bin/env bash
#
# Shell Utilities
# ===================================
#
# This file contains utility functions used to simplify repetitive
# tasks such as compilation, shell management, and dotfiles handling.
#
# Feel free to add new functions or modify the existing ones as needed.
# However, keep in mind that some dotfiles may depend on these utilities,
# so changing them could affect the shell configuration behaviour.
#
# SYNTAX (IMPORTANT!!) <<<<<<<<
#
# This file includes an internal parser which extracts information
# using a specific syntax format. The following rules must therefore
# be respected so the parser can work as expected:
#
#   - Function declarations must follow:
#       function <name> () {
#
#   - Private functions must be placed below the
#     "# PRIVATE FUNCTIONS" heading
#
#   - Private function names must start with "_"
#
#   - This comment block must end with:
#       END_DESCRIPTION
#
#   - Functions should include documentation whenever possible
#
#   - Only private functions may be declared below the
#     "# PRIVATE FUNCTIONS" heading
#
# END_DESCRIPTION

script_path="${BASH_SOURCE:-$0}"
abs_script_path="$(realpath "${script_path}")"
_shell_abs_script_directory="$(dirname "${abs_script_path}")"
unset script_path abs_script_path

source $_shell_abs_script_directory/aliases

# Display the error and usage message of a function.
# This function would not print anything if parameters are
# not all defined, but does not check its values.
#
# usage: showerr <FUNC_NAME> <ERR_MESSAGE> <USAGE_MESSAGE>
function showerr () {
	if (( $# == 3 )); then
		echo "error: $1: $2" 1>&2
		echo "use: $1: $3" 1>&2
	fi

	return 1
}

# Show information about the passed function.
# If no arguments were passed, this command would show help
# information for any single function defined here.
#
# usage: shellhelp <NAME> [NAMES ...]
function shellhelp () {
	local usage_mssg="shellhelp <NAME>"
	local error1_mssg="invalid number of arguments"
	local error2_mssg="cannot be an empty value"

	(( $# < 0 )) && showerr "shellhelp" $error1_mssg $usage_mssg && return 1

	if [[ ! -f $_shell_abs_script_directory/.shellhelp-cache ]]; then
		rm $_shell_abs_script_directory/.date-shellhelp-cache &>/dev/null

		touch $_shell_abs_script_directory/.shellhelp-cache
		touch -r $_shell_abs_script_directory/functions $_shell_abs_script_directory/.date-shellhelp-cache
		_parse_shellhelp > $_shell_abs_script_directory/.shellhelp-cache
	else
		local date_curr=$(stat -c %y "$_shell_abs_script_directory/functions")
		local date_last=$(stat -c %y "$_shell_abs_script_directory/.date-shellhelp-cache")

		if [ ! $date_curr = $date_last ]; then
			rm $_shell_abs_script_directory/.date-shellhelp-cache &>/dev/null
			touch -r $_shell_abs_script_directory/functions $_shell_abs_script_directory/.date-shellhelp-cache
			_parse_shellhelp > $_shell_abs_script_directory/.shellhelp-cache
		fi
	fi

	if (( $# == 0 )); then
		cat "$_shell_abs_script_directory/.shellhelp-cache" | egrep -v "^#"
	else
		while (( $# > 0 )); do
			[[ -z $1 ]] && showerr "shellhelp" "NAME $error2_mssg" $usage_mssg && return 1
			local temp_dir=$(mktemp)

			cat $_shell_abs_script_directory/.shellhelp-cache | egrep -n "#$1#" | cut -d ":" -f 1 > $temp_dir

			local min_value=$(sed -n 1p $temp_dir)
			min_value=$(($min_value + 1))

			local max_value=$(sed -n 2p $temp_dir)
			max_value=$(($max_value - 1))

			sed -n $min_value,${max_value}p $_shell_abs_script_directory/.shellhelp-cache
			rm $temp_dir &>/dev/null; shift
		done
	fi
}

# Reload all dotfiles and shell settings.
#
# Loading the full ZSH configuration may take some time,
# as some components are not fully optimised.
#
# Use reload-bash instead if you only need to reload
# aliases, functions, or environment variables.
#
# usage: reload-all-bash
function reload-all-bash () {
	case $SHELL_NAME in
		bash) exec bash ;;
		zsh) exec zsh ;;
		*) showerr "reload-bash" "invalid shell" "reload-bash"; return 1 ;;
    esac
}

# Reload all dotfiles configuration.
#
# usage: reload-bash
function reload-bash () {
	source ~/.config/shell/exports
	source ~/.config/shell/aliases
	source ~/.config/shell/functions
}

# Create or update a global variable.
# Changes will be applied after executing reload-bash.
#
# usage: setexport <NAME> <VALUE>
function setexport () {
	local usage_mssg="setexport <NAME> <VALUE>"
	local error1_mssg="invalid number of arguments"
	local error2_mssg="cannot be an empty value"

	(( $# != 2 )) && showerr "setexport" $error1_mssg $usage_mssg && return 1
	[[ -z $1 ]] && showerr "setexport" "$1 $error2_mssg" $usage_mssg && return 1
	[[ -z $2 ]] && showerr "setexport" "$2 $error2_mssg" $usage_mssg && return 1

	local n_line=$(egrep -n "^export $1=.*" ~/.config/shell/exports | cut -d ":" -f 1)
	local curr_n_line=1

	if [[ -z $n_line ]]; then
		echo "export $1=$2" >> ~/.config/shell/exports
		return 0
	fi

	local temp_file=$(mktemp)

	while IFS= read -r line; do
		if (( curr_n_line == n_line )); then
			echo "export $1=$2" >>$temp_file
		else
			echo "$line" >>$temp_file
		fi

		curr_n_line=$(($curr_n_line + 1))
	done < ~/.config/shell/exports

	rm  ~/.config/shell/exports
	mv $temp_file ~/.config/shell/exports
}

# Remove a global variable from the exports file if it exists.
# Changes will be applied after executing reload-bash.
#
# usage: rmexport <NAME>
function rmexport () {
	local usage_mssg="rmexport <NAME>"
	local error1_mssg="invalid number of arguments"
	local error2_mssg="cannot be an empty value"
	local error3_mssg="does not exist as a global variable"

	(( $# != 1 )) && showerr "rmexport" $error1_mssg $usage_mssg && return 1
	[[ -z $1 ]] && showerr "rmexport" "$1 $error2_mssg" $usage_mssg && return 1

	local n_line=$(egrep -n "^export $1=.*"  ~/.config/shell/exports | cut -d ":" -f 1)
	local curr_n_line=1

	[[ -z $n_line ]] && showerr "rmexport" "$1 $error3_mssg" $usage_mssg && return 1

	local temp_file=$(mktemp)

	while IFS=$'\t' read -r line; do
		if (( curr_n_line != n_line )); then
			echo "$line" >>$temp_file
		fi

		curr_n_line=$(($curr_n_line + 1))
	done < ~/.config/shell/exports

	rm  ~/.config/shell/exports
	mv $temp_file  ~/.config/shell/exports
}

# Change the current shell if the given value is valid
# and available on the system. Changes will be applied
# after executing reload-bash.
#
# usage: chshell <NAME>
function chshell () {
	local usage_mssg="chshell <NAME>"
	local error1_mssg="invalid number of arguments"
	local error2_mssg="cannot be an empty value"
	local error3_mssg="is not a valid shell"

	(( $# != 1 )) && showerr "chshell" $error1_mssg $usage_mssg && return 1
	[[ -z $1 ]] && showerr "chshell" "$1 $error2_mssg" $usage_mssg && return 1

	local curr_shell=$(ps --no-headers -p $$ -o cmd)

	case $1 in
		bash)
			setexport SHELL /bin/bash
			setexport SHELL_NAME bash
			setexport HISTFILE  ~/.config/shell/.bash_history
			reload-bash

			sudo chsh -s $(which bash)
			[ $curr_shell = "bash" ] || reload-all-bash
		;;

		zsh)
			setexport SHELL /bin/zsh
			setexport SHELL_NAME zsh
			setexport HISTFILE  ~/.config/shell/.zhistory
			reload-bash

			sudo chsh -s $(which zsh)
			[ $curr_shell = "zsh" ] || reload-all-bash
		;;

		*)
			showerr "chshell" "$1 $error3_mssg" $usage_mssg
			return 1
		;;
    esac
}

# Enable a minimal shell startup mode.
# Only essential files will be loaded in order
# to prioritise performance over appearance.
#
# usage: set-shell-simple
function set-shell-simple () {
	setexport SHELL_STARTUP_MODE simple
}

# Enable the full shell startup mode.
# All configuration files and visual components
# will be loaded in order to prioritise appearance
# over performance.
#
# usage: set-shell-pretty
function set-shell-pretty () {
	setexport SHELL_STARTUP_MODE pretty
}

# Return the percentage of available system memory.
#
# usage: porcmem
function porcmem () {
	local column=$(free -w | egrep "Mem:")
	local porc=$(( $(echo $column | awk '{print $3}') * 100 ))
	porc=$(( $porc / $(echo $column | awk '{print $2}') ))

	return $porc
}

# Display human-readable information about RAM usage,
# including used memory, total capacity, and usage percentage.
#
# usage: raminfo
function raminfo () {
	local porc=$(porcmem; echo $?)

	local column=$(free -hw | grep "Mem:")
	local used=$(echo $column | awk '{print $3}')
	local total=$(echo $column | awk '{print $2}')

	echo "${used} / ${total} (${porc}%)"
}

# Display human-readable information about a mounted
# filesystem, including usage, total size, usage percentage,
# filesystem type, and target path.
#
# usage: mountinfo <TARGET>
function mountinfo () {
	[[ -z $1 ]] && showerr "mountinfo" "target not specified" "mountinfo <TARGET>" && return 1

	local temp_file=$(mktemp)
	df -h --output=used,size,pcent,fstype,target | grep "$1" > $temp_file

	while IFS= read -r line; do
		if [[ $(echo $line | awk '{print $5}') = $1 ]]; then
			echo $line | awk '{print $1 " | " $2 " (" $3 ")" " (" $4 ")"}'
			return 0
		fi
	done < $temp_file

	showerr "mountinfo" "unkown target" "mountinfo <TARGET>"
	return 1
}

# Create one or more executable .sh files in the
# current directory.
#
# usage: mksh <FILE> [FILE ...]
function mksh () {
	local usage_mssg="mksh <FILE> [FILE, ...]"

	(( $# < 1 )) && showerr "mksh" "invalid number of parameters" $usage_mssg && return 1

	while (( $# != 0 )); do
		[[ ! $1 =~ .+\.sh ]] && showerr "mksh" "file needs to be a .sh file" $usage_mssg && return 1
		touch $1; chmod +x $1; shift
	done
}

# Create a new directory and change the current
# working directory to it.
#
# usage: mkd <DIR_PATH>
function mkd () {
	(( $# != 0 )) && showerr "mkd" "invalid number of parameters" "mkd <DIR_PATH>" && return 1
	mkdir -p "$@" && cd "$_"
}

# Display the size of a file or directory in a
# human-readable format.
#
# If no path is specified, the root directory "/"
# will be used by default.
#
# usage: fs <FILE_PATH>
function fs () {
	if [[ -n "$@" ]]; then
		du -sh -- "$@"
	else
		du -sh ./*
	fi
}

# Extract a compressed file based on its format.
#
# usage: ex <FILE>
function ex () {
	(( $# != 1 )) && showerr "ex" "invalid number of arguments" "ex <FILE>" && return 1
	[[ -z $1 ]] && showerr "ex" "$1 cannot be empty" "ex <FILE>" && return 1
	[[ ! -f $1 ]] && showerr "ex" "$1 is not a valid file" "ex <FILE>" && return 1

  	case $1 in
		*.tar.bz2)	tar xjf $1    ;;
      	*.tar.gz)   tar xzf $1    ;;
	  	*.tar.xz)	tar xf $1	  ;;
      	*.bz2)      bunzip2 $1    ;;
      	*.rar)      unrar x $1    ;;
      	*.gz)       gunzip $1     ;;
      	*.tar)      tar xf $1     ;;
      	*.tbz2)     tar xjf $1    ;;
      	*.tgz)      tar xzf $1    ;;
      	*.zip)      unzip $1      ;;
      	*.Z)        uncompress $1 ;;
      	*.7z)       7z x $1       ;;
      	*)
		  showerr "ex" "invalid format or not available" "ex <FILE>"
		  return 1
		;;
    esac
}

# Create an interactive menu controlled with arrow keys.
#
# An optional header can be displayed by passing a plain-text
# file containing the desired title.
#
# usage: interactive_menu [HEADER_FILE] SELECTED_OPTION OPTIONS
function interactive_menu () {
	local error1_mssg="invalid number of parameters"
	local usage_mssg="interactive_menu [HEADER_FILE] SELECTED_OPTION OPTIONS"

	(( $# < 2 )) && showerr "interactive_menu" $error1_mssg $usage_mssg

	local header_title=""
	[[ -f $1 ]] && header_title=$1 && shift

	local function_arguments=($@)

	local selected_item="$1"
	local menu_items=(${function_arguments[@]:1})
	local menu_size="${#menu_items[@]}"
	local menu_limit=$((menu_size - 1))

	clear; [[ ! -z $header_title ]] && echo -e $(cat $header_title)
	_print_menu "$selected_item" "${menu_items[@]}"

	while read -rsn1 input; do
		case "$input" in
			$'\x1B')
				read -rsn1 -t 0.1 input
				if [ "$input" = "[" ]; then
					read -rsn1 -t 0.1 input

					case "$input" in
						A)
							if [ "$selected_item" -ge 1 ]
							then
								selected_item=$((selected_item - 1))
								clear; [[ ! -z $header_title ]] && echo -e $(cat $header_title)
								_print_menu "$selected_item" "${menu_items[@]}"
							fi
						;;
						B)
							if [ "$selected_item" -lt "$menu_limit" ]
							then
								selected_item=$((selected_item + 1))
								clear; [[ ! -z $header_title ]] && echo -e $(cat $header_title)
								_print_menu "$selected_item" "${menu_items[@]}"
							fi
						;;
					esac
				fi

				read -rsn5 -t 0.1
			;;
			"") return "$selected_item" ;;
		esac
	done
}

# PRIVATE FUNCTIONS
# ===========================
#
# These functions are intended for internal use only
# and should not be called directly unless necessary.
#
# They are mainly used as helper utilities by other
# functions and may not be safe to use independently.
#
# Do not modify the private function heading, as some
# utilities depend on it to work correctly.

function _print_menu () {
	local function_arguments=($@)

	local selected_item="$1"
	local menu_items=(${function_arguments[@]:1})
	local menu_size="${#menu_items[@]}"

	for (( i = 0; i < $menu_size; ++i )); do
		if [ "$i" = "$selected_item" ]; then
			echo -e "  ${EXPAND_HI_BACKGROUND_WHITE}${BOLD_HI_BLACK}${menu_items[i]}${CLOSE_COLOR}"
		else
			echo -e "  ${menu_items[i]}"
		fi
	done
}

function _parse_shellhelp () {
	local func_name=""
	local func_usage=""
	local func_description=""
	local flag_descr=0

	while IFS= read -r line; do
		if (( flag_descr == 1 )); then
			[[ -n $(echo "$line" | egrep "^# PRIVATE FUNCTIONS") ]] && break

			if [[ -n $(echo "$line" | egrep "^function ") ]]; then
				func_name=$(echo "$line" | cut -d " " -f 2)

				echo "#$func_name#"
				[[ -n $func_usage ]] && echo "USAGE: $func_usage"
				echo
				echo "$func_description"
				echo "#$func_name#"

				unset func_name func_usage func_description
				continue
			fi

			if [[ $line =~ ^# ]]; then
				line=$(echo "$line" | sed 's/^# *//')

				if [[ $line =~ ^usage: ]]; then
					func_usage=$(echo "$line" | sed 's/^usage: *//')
				elif [[ -n $line ]]; then
					func_description="${func_description}$line"$'\n'
				fi
			fi
		else
			[[ -n $(echo "$line" | egrep "^# END_DESCRIPTION") ]] && flag_descr=1
		fi
	done < "$_shell_abs_script_directory/functions"
}