#!/bin/bash -e

_util_sh_include_guard_utils=1

	# lowercase: on case-insensitive filesystems, paths sometimes canonicalize

	# to a different capitalization than the original

## fi # load new aliases

## if self_being_included; then

# this is needed because aliases defined inside an if statement are not

# available inside that if statement

#### options

# stderr_matches(). (it also isn't supported on Mac.) use @PIPESTATUS instead.

{ return "$?"; } # can't use `:` because that resets $?

alias log--='"log--" ' # last space alias-expands next word

alias log!='"log!" ' # last space alias-expands next word

alias caller_indent="$__caller_indent"

alias indent="declare $__caller_indent"

alias echo_run='"echo_run" ' # last space alias-expands next word

not() { ! "$@"; } # usage: wrapper_cmd not wrapped_cmd... # inverts exit status

{ if test ! "$1"; then echo -n 1; fi } # empty<->non-empty

	# `local` does not support arrays in older versions of bash/on Mac

# usage: local var=...; local_inv

'declare "no_$var=$(test "${!var}" || echo 1)"; echo_vars no_$var'

	# `declare +x` won't work because it defines the var if it isn't set

	# `export` does not support arrays in older versions of bash/on Mac

# within cmd: var="$var" cmd...

# usage: local prefix=..._; import_vars

# when used inside another alias 2+ levels deep, *must* be run inside a function

: "${prefix:?}"

declare src_var dest_var

for src_var in $(get_prefix_vars); do

	dest_var="${src_var#$prefix}"

EOF

)"

let!() { let "$@" || true; } # always returns true; safe to use for setting

	# "If the last ARG evaluates to 0, let returns 1" (`help let`)

bool2int() { try test ! "$1"; echo "$e"; } # empty->0; non-empty->1

int2exit() { (( "$1" != 0 )); }

exit2bool() { if (( $? == 0 )); then echo 1; fi } # 0->non-empty; !=0->empty

#### floats

int_part() { echo "${1%%.*}"; }

dec_suffix() { echo "${1#$(int_part "$1")}"; }

round_down() { int_part "$1"; }

float+int() { echo "$(($(int_part "$1")+$2))$(dec_suffix "$1")"; }

float_set_min() { if (($(int_part $1) >= $2)); then echo $1; else echo $2; fi; }

#### strings

starts_with() { test "${2#$1}" != "$2"; } # usage: starts_with pattern str

ends_with() { test "${2%$1}" != "$2"; } # usage: ends_with pattern str

{ if starts_with "$1" "$2"; then echo "${2%${2#$1}}"; fi }

rm_prefix() { echo "${2#$1}"; } # usage: rm_prefix pattern str

contains_match() { starts_with "*$1" "$2"; } # usage: contains_match pattern str

repeat() # usage: str=... n=... repeat

{

	: "${str?}" "${n:?}"; local result= n="$n" # n will be modified in function

	for (( ; n > 0; n-- )); do result="$result$str"; done

	echo "$result"

}

# usage: outer_cmd $sed_cmd ...

sed_cmd="env LANG= sed -`case "$(uname)" in Darwin) echo El;; *) echo ru;;esac`"

	# LANG: avoid invalid UTF-8 "illegal byte sequence" errors when LANG=*.UTF-8

	# -l: line buffered / -u: unbuffered

alias sed="$sed_cmd"

	# can't be function because this causes segfault in redir() subshell when

	# used with make.sh make() filter

fi # load new aliases

if self_being_included; then

rtrim() { log_local; log+ 3; sed 's/[[:space:]]+$//' <<<"$1"; }

#### arrays

echo1() { echo "$1"; } # usage: echo1 values...

esc() # usage: array=($(log++; prep_env... (eg. cd); esc args...))

{ local arg; for arg in "$@"; do printf '%q ' "$arg"; done; }

# usage: split delim str; use ${parts[@]}

join() { local IFS="$delim"; echo "$*"; } # usage: delim=char join elems...

reverse() # usage: array=($(reverse args...))

{

	local i

	for (( i=$#; i > 0; i-- )); do printf '%q ' "${!i}"; done

}

contains() # usage: contains value in_array...

{

	local value="$1"; shift

	local elem

	for elem in "$@"; do if test "$elem" = "$value"; then return 0; fi; done

	return 1

}

is_array() # handles unset vars (=false)

{

	isset "$1" || return 1

	local decl; decl="$(declare -p "$1")" || return; echo_vars decl

	starts_with 'declare -a' "$decl" # also matches -ax

}

### formatting

has_bg()

{

	# inverse (black background)/set background (normal colors)/set background

	# (bright colors) (xfree86.org/current/ctlseqs.html#Character_Attributes)

	starts_with 7 "$1" || starts_with 4 "$1" || starts_with 10 "$1"

}

format() # usage: format format_expr msg

# format_expr: the #s in xfree86.org/current/ctlseqs.html#Character_Attributes

{

	local format="$1" msg="$2"

	if starts_with '[' "$msg"; then format=; fi #don't add padding if formatted

	if has_bg "$format"; then msg=" $msg "; fi # auto-add padding if has bg

	echo "${format:+[0;${format}m}$msg${format:+}"

}

plain() { echo "$1"; }

fade() { format 90 "$@"; } # medium gray fades on white *&* black backgrounds

err_fd=2 # stderr

# usage: local func=...; set_func_loc; use $file, $line

alias set_func_loc="$(cat <<'EOF'

: "${func:?}"

local func_info="$(shopt -s extdebug; declare -F "$func")" # 'func line file'

func_info="${func_info#$func }"

local line="${func_info%% *}"

local file="${func_info#$line }"

EOF

)"

fi # load new aliases

if self_being_included; then

func_loc() # gets where function declared in the format file:line

{

	local func="$1"; set_func_loc

	file="$(canon_rel_path "$file")" || return

	echo "$file:$line"

}

# makes stack_trace() skip the entry for the caller

alias skip_stack_frame='init_i; next_stack_frame'

alias unskip_stack_frame_in_caller='prev_stack_frame'

fi # load new aliases

if self_being_included; then

# usage: [i=#] get_stack_frame # i: 0-based index from top of stack

# to get all stack frames:

# init_i; while get_stack_frame; do use $func $file $line; next_stack_frame;done

# better than `caller` builtin because returns info in separate vars

get_stack_frame()

{

	skip_stack_frame; init_i

	# the extra FUNCNAME/BASH_LINENO entries have dummy values (main/0)

	func="${FUNCNAME[$i]}" # the called function, which = the current function

	file="${BASH_SOURCE[$i+1]}" # not the *current* file, but the call's file

	line="${BASH_LINENO[$i]}" # the line the function was called at

	test "$file" # exit false if invalid index

}

alias get_stack_frame='declare func file line && "get_stack_frame"'

	# && instead of ; so it can be used as a while cond

# lookahead: look at entry *after* current to deterine whether to skip current.

#  useful for skipping wrappers, by looking at the *calling* function's name.

	skip_stack_frame_in_caller # current function's frame

		next_stack_frame # skip matching frame

	done

	local caller="$file:$line"

	local func_loc; func_loc="$(func_loc "$func")" || return

	func_loc="${func_loc#$file:}" # include just line # if file same

{

	skip_stack_frame; init_i

	while get_stack_frame; do

		format_stack_frame

		next_stack_frame

	done

}

# *note*: don't call from logging functions b/c will cause infinite recursion

debug_fd="$err_fd"

ps() { echo "$@" >&"$debug_fd"; } # usage: ps str...

pv() { declare -p "$@" >&"$debug_fd"; } # usage: pv var... # debug-prints vars

pf() { declare -f "$@" >&"$debug_fd"; } # usage: pf func... # prints func decls

# *note*: don't call from logging functions b/c will cause infinite recursion

## shell-variable-based caching

alias cached='isset "$cache_var"'

alias save_cache='set_var "$cache_var"'

alias echo_cached_value='echo "${!cache_var}"'

clear_cache() # usage: func=... clear_cache

{ : "${func:?}"; unset $(prefix="${func}___" get_prefix_vars); }

fi # load new aliases

if self_being_included; then

func_exists() { declare -f "$1" >/dev/null; }

kw_params() # usage: func() { kw_params param_var...; }; ...; param_var=... cmd

# removes keyword-param-only vars from the environment

{ unexport "$@"; }

function foreach_arg()

{

	echo_func; kw_params cmd; : "${cmd:?}"

	local a; for a in "$@"; do

		a="$(log++ echo_run "$cmd" "$a")" || return; args+=("$a")

	done

	echo_vars args

}

alias foreach_arg='"foreach_arg" "$@"; set -- "${args[@]}"; unset args'

alias self_name='echo "${FUNCNAME%%__*}"' # usage: "$(self_name)"

alias self='command "$(self_name)"' # usage: wrapper() { self ...; }

alias self_sys='sys_cmd "$(self_name)"' # wrapper() { self_sys ...; }

alias self_builtin='builtin "${FUNCNAME%%__*}"' #wrapper() { self_builtin ...; }

all_funcs() # usage: for func in $(all_funcs); do ...; done # all declared funcs

{ declare -F|while read -r line; do echo -n "${line#declare -f } "; done; }

copy_func() # usage: from=... to=... copy_func

# $to must not exist. to get around the no-clobber restriction, use `unset -f`.

{

	func_exists "$from" || die "function does not exist: $from"

	! func_exists "$to" || die "function already exists: $to"

	local from_def="$(declare -f "$from")"

	eval "$to${from_def#$from}"

}

func_override() # usage: func_override old_name__suffix

ensure_nested_func() # usage: func__nested_func() { ensure_nested_func; ... }

{

	local nested_func="${FUNCNAME[1]}"

	local func="${nested_func%%__*}"

	contains "$func" "${FUNCNAME[@]}" || \

		die "$nested_func() must be used by $func()"

}

if self_being_included; then

function run_cmd() { "$@"; }

alias run_cmd='"run_cmd" ' # last space alias-expands next word

{ (unalias "$(1st_non_opt "$@")"; self_builtin "$@") || return; }

{ log_local;log++; echo_func; test "${BASH_LINENO[${#BASH_LINENO[@]}-1]}" != 0;}

{

	echo_func

	if ! is_dot_script; then # was run without initial "."

		echo "usage: . $top_script (note initial \".\")"|fold -s >&2

		return 2

	fi

}

# allows running a system command of the same name as the script

alias cmd2sys="$(cat <<'EOF'

declare _1="$1"; shift

EOF

)"

fi # load new aliases

if self_being_included; then

sys_cmd() { cmd2sys; command "$@"; } # usage: sys_cmd cmd... # runs system cmd

	# allows running a system command of the same name as the script

{

	echo_func

	if is_callable "$1"; then set -- env PATH="$PATH" "$@"; fi # preserve PATH

	self -E "$@"

}

alias self_sudo='sudo "${FUNCNAME%%__*}" "$@"'

alias become_sudo='if ! test "$is_root"; then self_sudo; fi'

if self_being_included; then

exit() { self_builtin "${1:-$?}"; } # exit sometimes inxeplicably ignores $?

{ return "$1"; }

	# can't use `(exit "$1")` because a bug in bash prevents subshells from

	# triggering errexit (would need to append `|| return` for it to work)

# **WARNING**: if using this after a command that might succeed (rather than

alias save_e='# idempotent: use $e if the caller already called save_e

declare e_=$?;

declare e="$(if test "$e_" = 0; then echo "${e:-0}"; else echo "$e_"; fi)"'

if self_being_included; then

# finally...; end_try

# usage: ...; try cmd... # *MUST* be at beginning of statement

sig_e() { echo $(( 128+$(kill -l "$1") )); } # usage: sig_e SIGINT, etc.

catch() # supports SIG* as exception type

{

	catch__exceptions "$@"

}

if self_being_included; then

nl='

'

#        with wrapper: declare lines; wrapper "split_lines" str; use ${lines[@]}

	# no echo_func because used by log++

strip/() { echo "${1%/}"; } # strips trailing /s

	set -- $(wildcard/ "$@") # first strip trailing /s

	local to_rm=(. ..)

	local item

	if contains "$1" "${to_rm[@]}"; then

		shift

		if contains "$1" "${to_rm[@]}"; then shift; fi

	fi

{ sleep 0.1; } # s; display after leading output of cmd1

: "${log_level=$(( ${#PS4}-1 ))}" # defaults to # non-space symbols in PS4

export log_level # propagate to invoked commands

# for messages that use can_log(), the log_level starts with *1*, not 0

# for unfiltered messages, the log_level is 0 (i.e. still output at verbosity=0)

if self_being_included; then

#        outside func: log_local; log++; ...; log--

function log--() { log- 1 "$@"; }

function log!() { log: 0 "$@"; } # force-displays next log message

#  so that it doesn't mess up the logging mechanism

export log_indent_step log_indent # propagate to invoked commands

if self_being_included; then

	local format="${format-1}" # bold