.bashrc

# ~/.bashrc
# ============================================================================
# Bash shell configuration
# Copyright (c) Corey Goldberg (https://github.com/cgoldberg)
# ============================================================================
#
#    bbbbbbbb
#    b::::::b                                             hhhhhhh
#    b::::::b                                             h:::::h
#    b::::::b                                             h:::::h
#     b:::::b                                             h:::::h
#     b:::::bbbbbbbbb      aaaaaaaaaaaaa      ssssssssss   h::::h hhhhh
#     b::::::::::::::bb    a::::::::::::a   ss::::::::::s  h::::hh:::::hhh
#     b::::::::::::::::b   aaaaaaaaa:::::ass:::::::::::::s h::::::::::::::hh
#     b:::::bbbbb:::::::b           a::::as::::::ssss:::::sh:::::::hhh::::::h
#     b:::::b    b::::::b    aaaaaaa:::::a s:::::s  ssssss h::::::h   h::::::h
#     b:::::b     b:::::b  aa::::::::::::a   s::::::s      h:::::h     h:::::h
#     b:::::b     b:::::b a::::aaaa::::::a      s::::::s   h:::::h     h:::::h
#     b:::::b     b:::::ba::::a    a:::::assssss   s:::::s h:::::h     h:::::h
#     b:::::bbbbbb::::::ba::::a    a:::::as:::::ssss::::::sh:::::h     h:::::h
#     b::::::::::::::::b a:::::aaaa::::::as::::::::::::::s h:::::h     h:::::h
#     b:::::::::::::::b   a::::::::::aa:::as:::::::::::ss  h:::::h     h:::::h
#     bbbbbbbbbbbbbbbb     aaaaaaaaaa  aaaa sssssssssss    hhhhhhh     hhhhhhh
#
# ============================================================================


# if not running interactively, don't do anything
case $- in
    *i* )
        ;;
    * )
        return
        ;;
esac


# ANSI color codes
BOLD="\e[1m"
BLUE="\e[34m"
GREEN="\e[32m"
RED="\e[31m"
RESET="\e[0m"


# export environment variables
export LANGUAGE="en_US"
export PAGER="/usr/bin/less"
export LESS="--LONG-PROMPT --RAW-CONTROL-CHARS --no-init --quit-at-eof --quit-if-one-screen --quit-on-intr"
export GITHUB_USERNAME="cgoldberg"
export PIP_DISABLE_PIP_VERSION_CHECK=true
export PIP_REQUIRE_VIRTUALENV=true
export DO_NOT_TRACK=true
export LESSHISTFILE=- # don't leave .lesshst files
if type subl >/dev/null 2>&1; then
    export EDITOR="subl --new-window --wait"
elif type nano >/dev/null 2>&1; then
    export EDITOR="nano"
else
    export EDITOR="vi"
fi
export VISUAL="${EDITOR}"


# set termcap colors for less pager
export LESS_TERMCAP_mb=$(printf '\e[01;31m')
export LESS_TERMCAP_md=$(printf '\e[01;38;5;75m')
export LESS_TERMCAP_me=$(printf '\e[0m')
export LESS_TERMCAP_se=$(printf '\e[0m')
export LESS_TERMCAP_so=$(printf '\e[01;33m')
export LESS_TERMCAP_ue=$(printf '\e[0m')
export LESS_TERMCAP_us=$(printf '\e[04;38;5;200m')


# disable suspend/resume feature in terminal
stty -ixon


# set shell behavior
# ------------------
# change to directory by name without cd command
shopt -s autocd
# check window size after each command and update the values
# of LINES and COLUMNS
shopt -s checkwinsize
# include filenames beginning with a "." in the results of
# filename expansion
shopt -s dotglob
# the pattern "**" used in a pathname expansion context will match
# all files and zero or more directories and subdirectories
shopt -s globstar
# automatically close file descriptors assigned using the
# "{varname}" redirection syntax instead of leaving them
# open when a command completes
shopt -s varredir_close


# better command history handling
# -------------------------------
# append to history file, rather than overwrite it
shopt -s histappend
# edit recalled history line before executing
shopt -s histverify
# save each line of a multi-line command in the same history entry
shopt -s cmdhist
# save multi-line commands with embedded newlines rather than
# semicolon separators where possible
shopt -s lithist
# remove duplicate commands from history
HISTCONTROL=ignoredups:erasedups
# don't add entries to history (sometimes get duplicates of 'x'
# and 'exit' because shell is closed immediately
HISTIGNORE="x:exit"
# number of previous commands stored in memory for current session
HISTSIZE=9999
# number of previous commands stored in history file
HISTFILESIZE=9999
# immediately add commands to history instead of waiting for end of session
PROMPT_COMMAND="history -n; history -w; history -c; history -r"


# add local bin directories to the end of PATH
for d in "${HOME}/bin" "${HOME}/.local/bin"; do
    if [[ ":${PATH}:" != *":${d}:"* ]]; then
        export PATH="${PATH}:${d}"
    fi
done


# ruby gems
if type ruby >/dev/null 2>&1; then
    export GEM_HOME="${HOME}/.gems"
    export PATH="${PATH}:${HOME}/.gems/bin"
fi


# rust/cargo
if [ -d "${HOME}/.cargo" ]; then
    source "${HOME}/.cargo/env"
fi


# deno/js
if [ -d "${HOME}/.deno" ]; then
    source "${HOME}/.deno/env"
fi


# golang
if [ -d "/usr/local/go" ]; then
    export PATH="${PATH}:/usr/local/go/bin"
fi


# pipx
if type pipx >/dev/null 2>&1; then
    eval "$(register-python-argcomplete pipx)"
fi


# ======================================================
#
#            888 d8b
#            888 Y8P
#            888
#    8888b.  888 888  8888b.  .d8888b   .d88b.  .d8888b
#       "88b 888 888     "88b 88K      d8P  Y8b 88K
#    d888888 888 888 .d888888 "Y8888b. 88888888 "Y8888b.
#    88  888 888 888 888  888      X88 Y8b.          X88
#    Y888888 888 888 "Y888888  88888P'  "Y8888   88888P'
#
# ======================================================


# navigate up the directory tree
alias ..="cd .."
alias ...="cd ../.."
alias ....="cd ../../.."
alias .....="cd ../../../.."
alias ......="cd ../../../../.."
alias .......="cd ../../../../../.."
alias ........="cd ../../../../../../.."
alias .........="cd ../../../../../../../.."
alias cd..="cd .."
alias cd...="cd ../.."
alias cd....="cd ../../.."
alias cd.....="cd ../../../.."
alias cd......="cd ../../../../.."
alias cd.......="cd ../../../../../.."
alias cd........="cd ../../../../../../.."
alias cd.........="cd ../../../../../../../.."


# enable color support for grep
alias grep="grep --color=always"


# version control
alias g="git"


# disk usage (directory sizes)
alias du="du --human-readable --max-depth=1 | sort --human-numeric-sort --reverse"
alias gdu="gdu --no-delete --show-item-count"


# shell script static analysis
alias shellcheck="shellcheck --color=always --shell=bash --exclude=SC1090,SC1091,SC2155"


# extract a tarball
alias untar="tar zxvf"


# clear screen and scrollback buffer
alias cls="clear"
alias c="clear"


# list directory contents
alias ls="LC_ALL=C \ls --almost-all --classify --group-directories-first --color=always"
alias ll="LC_ALL=C \ls -l --almost-all --classify --group-directories-first \
    --human-readable --no-group --color=always"
if type eza >/dev/null 2>&1; then
    alias l="eza --long --all --git --git-repos-no-status \
        --group-directories-first --header --modified --no-quotes \
        --classify=always --sort=Name --time-style=long-iso"
    alias tree="eza --tree --all --group-directories-first --no-git \
        --no-quotes --classify=always --color=always --sort=Name \
        --ignore-glob='venv|.git|.tox|*_cache|__pycache__' \
        | less"
else
    alias l="ll"
fi


# editors (sublime/nano/vim)
if type subl >/dev/null 2>&1; then
    alias edit="subl"
    alias ed="subl"
    alias e="subl --new-window ."
elif type nano >/dev/null 2>&1; then
    alias edit="nano"
    alias ed="nano"
    alias e="nano"
else
    alias edit="vi"
    alias ed="vi"
    alias e="vi"
fi


# open ~/.bashrc for editing
alias ebrc="edit ${HOME}/.bashrc"


# open github website in default browser
alias github="web https://github.com/${GITHUB_USERNAME}"
alias gist="web https://gist.github.com/${GITHUB_USERNAME}"


# python
alias py="python"


# uninstall all python packages in current environment
alias pip-uninstall-all="\
    python -m pip freeze |
        sed 's/^-e //g' |
        PIP_REQUIRE_VIRTUALENV=false \
        xargs --no-run-if-empty python -m pip uninstall -y"


# show the zen of python
alias zen="python3 -c 'import this'"


# serve current directory over HTTP on port 8000 (bind all interfaces)
alias webserver="python3 -m http.server"


# =========================================================================================
#
#     .o88o.                                       .    o8o
#     888 `"                                     .o8    `"'
#    o888oo  oooo  oooo  ooo. .oo.    .ooooo.  .o888oo oooo   .ooooo.  ooo. .oo.    .oooo.o
#     888    `888  `888  `888P"Y88b  d88' `"Y8   888   `888  d88' `88b `888P"Y88b  d88(  "8
#     888     888   888   888   888  888         888    888  888   888  888   888  `"Y88b.
#     888     888   888   888   888  888   .o8   888 .  888  888   888  888   888  o.  )88b
#    o888o    `V88V"V8P' o888o o888o `Y8bod8P'   "888" o888o `Y8bod8P' o888o o888o 8""888P'
#
# =========================================================================================


# print bold message to stderr preceded with red ballot x
err() {
    printf '%b%b✗%b %b%s%b\n' \
        "${BOLD}" "${RED}" "${RESET}" "${BOLD}" "$*" "${RESET}" >&2
}


# print bold message to stderr preceded with green check mark
ok() {
    printf '%b%b✓%b %b%s%b\n' \
        "${BOLD}" "${GREEN}" "${RESET}" "${BOLD}" "$*" "${RESET}" >&2
}


# list bash functions and aliases
funcs() {
    ( alias | cut -d= -f1 | sed 's/^alias //' && \
        declare -F | sed 's/^.* //g' | grep -v '^_' ) |
    sort | less
}


# chop lines at screen width
# - usage: echo $really_long_line | nowrap
nowrap() {
    cut -c-"$(tput cols)"
}


# show spinner for indicating progress
spinner() {
    local shs=( - \\ \| / ) pnt=0
    printf '\e7'
    while ! read -rsn1 -t .2 _; do
        printf '%b\e8' "${shs[pnt++%${#shs[@]}]}"
    done
}


# start spinner background task
start_spinner() {
    tput civis
    exec {doSpinner}> >(spinner "$@")
}


# stop spinner background task
stop_spinner() {
    echo >&"${doSpinner}" && exec {doSpinner}>&-
    tput cnorm
    echo
}


# extract audio from a YouTube video and save as .mp3
# - usage: yt-mp3 <video url> [quality]
# - examples:
#   - encode at highest CBR (320k)
#     - yt-mp3 <video url>
#   - encode at 256k CBR
#     - yt-mp3 <video url> 256k
#   - encode at highest quality VBR
#     - yt-mp3 <video url> vbr
yt-mp3() {
    if [ -z "$1" ]; then
        err "please specify a YouTube URL"
        return 1
    fi
    local bitrate="${2:-320k}"
    if [ "${bitrate}" = "vbr" ]; then
        bitrate="0"
    fi
    yt-dlp \
        --format "bestaudio" \
        --extract-audio \
        --audio-format mp3 \
        --audio-quality "${bitrate}" \
        "$1"
}


# download a YouTube video and save as .mp4
yt-video() {
    if [ -z "$1" ]; then
        err "please specify a YouTube URL"
        return 1
    fi
    yt-dlp \
        --format "bestvideo+bestaudio/best" \
        --merge-output-format mp4 \
        "$1"
}


# colored diffs
dff() {
    if [ -z "$1" ] || [ -z "$2" ]; then
        err "please enter 2 files to diff"
        return 1
    fi
    \diff --report-identical-files --strip-trailing-cr \
        --color=always "$1" "$2" | less
}
alias diff="dff"


# install python packages globally
gpip-install() {
    PIP_REQUIRE_VIRTUALENV=false \
        python -m pip install --user --upgrade --upgrade-strategy=eager "$@"
}


# uninstall python packages globally
gpip-uninstall() {
    PIP_REQUIRE_VIRTUALENV=false \
        python -m pip uninstall "$@"
}


# rename all files under the current directory (recursive),
# replacing spaces with underscores. If inside a git repo,
# renames will be tracked by git
replace-whitespace-in-filenames() {
    if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
        find . -path ./.git -prune -o -type f -name "* *" \
            -exec bash -c 'git mv "$0" "${0// /_}"' {} \;
    else
        find . -type f -name "* *" \
            -exec bash -c 'mv "$0" "${0// /_}"' {} \;
    fi
}


# remove trailing whitespace from lines in given file
# - usage: trim-trailing-whitespace <file>
trim-trailing-whitespace() {
    if [ -z "$1" ]; then
        err "please specify a file name"
        return 1
    fi
    echo "trimming whitespace..."
    perl -pi -e 's/[ \t]+(?=\r?$)//' "$1"
}


# remove trailing whitespace from lines in all files under
# current directory (recursive)
trim-trailing-whitespace-from-files() {
    echo "trimming whitespace..."
    find . -type f -print0 |
        xargs --null --no-run-if-empty sed -i -e 's/[[:blank:]]*$//'
}


# give file(s) a new filesystem identity (inode/file ID) and discard most
# filesystem metadata, while preserving its contents.
# - usage: renew-inode <file_or_glob>
renew-inode() {
    if [ -z "$1" ]; then
        err "please specify a file or glob pattern with matches"
        return 1
    fi
    for f in "$@"; do
        [ -f "${f}" ] || continue
        tmp="${f}.tmp.$$"
        if cat -- "${f}" >"$tmp"; then
            rm -- "${f}" &&
            mv -- "${tmp}" "${f}" &&
            echo "renewed: ${f}"
        else
            echo "failed: ${f}"
            rm -f -- "${tmp}"
        fi
    done
}


# remove metadata from an image
# - usage: clean-img-metadata <image_file_or_glob>
clean-img-metadata() {
    if [ -z "$1" ]; then
        err "please specify an image file or glob pattern with matches"
        return 1
    fi
    if ! type exiftool >/dev/null 2>&1; then
        err "exiftool not found"
        return 1
    fi
    echo "removing metadata..."
    # keep orientation tag
    exiftool -all= -tagsfromfile @ -Orientation -overwrite_original "$@" 2>/dev/null
}


# generate a self-contained html from markdown using pandoc
# - uses modified bootstrap css
# - usage: md2html <markdown_file> [output_html_file]
md2html() {
    if [ -z "$1" ]; then
        err "please specify a markdown file"
        return 1
    fi
    if ! type pandoc >/dev/null 2>&1; then
        err "pandoc not found"
        return 1
    fi
    local input="$1"
    local base="${input%.*}"
    local output="${2:-${base}.html}"
    local title="${base##*/}"
    pandoc "${input}" \
        --output "${output}" \
        --template "${HOME}/.pandoc/template.html" \
        --css "${HOME}/.pandoc/template.css" \
        --from gfm \
        --eol native \
        --metadata title="${title}" \
        --embed-resources \
        --standalone
    echo "generated: ${output}"
}


# preview rendered html from a markdown file in web browser
# - generates a temporary self-contained html file
# - launches default browser to view it
# - usage: preview-md2html <markdown_file>
preview-md2html() {
    if [ -z "$1" ]; then
        err "please specify a markdown file"
        return 1
    fi
    local input="$1"
    local filename="${input##*/}"
    local basename="${filename%.md}"
    local tmpdir="$(mktemp -d)" || return 1
    local output="${tmpdir}/${basename}.html"
    md2html "${input}" "${output}" || return 1
    web "${output}"
}


# print system PATH
path() {
    IFS=":"
    for d in ${PATH}; do
        echo "${d}"
    done
    unset IFS
}


# use bat for colored help if available
help() {
    if type bat >/dev/null 2>&1; then
        "$@" --help 2>&1 | bat --plain --language=help
    else
        builtin help "$@"
    fi
}


# search recursively for files or directories matching pattern
# - case-insensitive unless pattern contains an uppercase
# - uses fd if available
# - usage: ff <regex>
ff() {
    if type fd >/dev/null 2>&1; then
        local command_name="\fd --hidden --no-ignore --color=always "
        local exclude_patterns=(
            ".git/"
            ".tox/"
            ".venv/"
            "__pycache__/"
            "venv/"
        )
        for pattern in "${exclude_patterns[@]}"; do
            command_name+=" --exclude=${pattern}"
        done
        if [ -n "$1" ]; then
            command_name+=" $1"
        fi
        eval "${command_name}" | less
    else
        if [ -z "$1" ]; then
            err "please enter a search pattern"
            return 1
        fi
        find . \
            -xdev \
            ! -readable \
            -prune \
            -o \
            -iname "*$1*" \
            ! -path "*/.git/*" \
            ! -path "*/.tox/*" \
            ! -path "*/.venv/*" \
            ! -path "*/__pycache__/*" \
            ! -path "*/venv/*" \
            -print |
            \grep --ignore-case --color=always "$1" | less
    fi
}


# search recursively in files for pattern (case-insensitive)
# - uses ripgrep if available
# - usage: rg <pattern>
rg() {
    if [ -z "$1" ]; then
        err "please specify a search pattern"
        return 1
    fi
    if [ -f "${HOME}/.cargo/bin/rg" ]; then
        local rg_bin="${HOME}/.cargo/bin/rg"
    elif [ -f "${HOME}/Scoop/shims/rg" ]; then # Windows/Scoop/MinGW
        local rg_bin="${HOME}/Scoop/shims/rg"
        rg_bin="${rg_bin} --path-separator='//'"
    fi
    if [ -n "${rg_bin+x}" ]; then # using ripgrep
        local escaped_pattern=$(sed 's/./\\&/g' <<<"$1")
        eval "${rg_bin}" \
            --crlf \
            --hidden \
            --ignore-case \
            --ignore-vcs \
            --line-number \
            --no-ignore \
            --no-messages \
            --one-file-system \
            --with-filename \
            --color=always \
            --glob='!.git/' \
            --glob='!.tox/' \
            --glob='!.venv/' \
            --glob=!'.*_cache/' \
            --glob='!__pycache__/' \
            --glob='!venv/' \
            "${escaped_pattern}" | less
    else
        \grep -r \
            --ignore-case \
            --line-number \
            --no-messages \
            --with-filename \
            --binary-files=without-match \
            --color=always \
            --devices=skip \
            --exclude-dir=.git \
            --exclude-dir=.tox \
            --exclude-dir=.venv \
            --exclude-dir=__pycache__ \
            --exclude-dir="venv" \
            "$1" | less
    fi
}


# search command history by regex (case-insensitive) show last n matches
# - usage: h <pattern>
h() {
    local num="50"
    history | \grep -v "  h " |
        \grep --ignore-case --color=always "$1" |
        tail -n "${num}"
}


# create directory (make parent directories as needed)
makedir() {
    mkdir --parents --verbose "$1"
    cd "$1"
}
alias md="makedir"


# reload shell configuration
re-source() {
    echo 'sourcing ~/.bashrc...'
    unalias -a # remove all aliases
    source "${HOME}/.bashrc"
    # if a virtual env is active, reactivate it, since the prompt
    # prefix gets clobbered
    if [ -n "${VIRTUAL_ENV}" ]; then
        activate
    fi
}


# display weather in boston
weather() {
    date
    echo
    echo -ne "fetching weather...\r"
    curl --max-time 10 https://wttr.in/Boston?2F
    echo
}
alias w="weather"


# stock watchlist
stocks() {
    local tickers="^DJI,^IXIC,^GSPC,^RUI,^RLV,^RLG,^RUT,^RUJ,^RUO,AMZN,COPP,FBTC,FETH,XRPZ"
    tickrs \
        --show-x-labels \
        --summary \
        --trunc-pre \
        --update-interval 30 \
        --symbols "${tickers}"
}


# count all files and symlinks in current directory
# - recursive
# - also shows tracked file if in a git repo
# - ignores .git directories
# - uses fd if available
countfiles() {
    if [ -n "$1" ]; then
        local path=". $1"
    else
        local path="."
    fi
    if type fd >/dev/null 2>&1; then
        local num_files=$(\fd --hidden --no-ignore --type=f --type=l --exclude=.git/ "${path}" | wc -l)
    else
        local num_files="$(find . -type f,l ! -path './.git/*' | wc -l)"
    fi
    echo "files: ${num_files}"
    if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
        local num_files="$(git ls-files | wc -l)"
        echo "tracked files: ${num_files}"
    fi
}


# search active processes for pattern (case-insensitive)
# - usage: psgrep <pattern>
psgrep() {
    if [ -n "$1" ]; then
        ps -ef |
            \grep --color=always --extended-regexp --ignore-case "$1" |
            \grep --invert-match --word-regexp "grep" | nowrap
    else
        ps -ef
    fi
}


# run pyupgrade against all python files in current directory (recursive)
# and fix recommendations in-place
py-upgrade() {
    if ! type pyupgrade >/dev/null 2>&1; then
        err "pyupgrade not found"
        return 1
    fi
    local count=0
    while IFS= read -r -d '' file; do
        pyupgrade --py310-plus "${file}"
        count=$((count + 1))
    done < <(
        find . \
            -name "*.py" \
            ! -path "*/.git/*" \
            ! -path "*/.tox/*" \
            ! -path "*/venv/*" \
            ! -path "*/"*"_cache/*" \
            -print0
    )
    # on Windows, pyupgrade rewrites files with LF line endings,
    # so we convert them back
    if [[ "${OSTYPE}" == "msys" || "${OSTYPE}" == "cygwin" ]]; then
        find . \
            -name "*.py" \
            ! -path "*/.git/*" \
            ! -path "*/.tox/*" \
            ! -path "*/venv/*" \
            ! -path "*/"*"_cache/*" \
            -print0 |
            xargs --null --no-run-if-empty unix2dos 2>/dev/null
        fi
    echo
    ok "Processed ${count} files"
}


# run refurb against all python files in current directory (recursive)
# and display recommendations
py-refurb() {
    if ! type refurb >/dev/null 2>&1; then
        err "refurb not found"
        return 1
    fi
    local count=0
    while IFS= read -r -d '' file; do
        refurb \
            --enable-all \
            --python-version 3.10 \
            --disable FURB107 \
            --disable FURB173 \
            --disable FURB183 \
            --disable FURB184 \
            "${file}"
        count=$((count + 1))
    done < <(
        find . \
            -name "*.py" \
            ! -path "*/.git/*" \
            ! -path "*/.tox/*" \
            ! -path "*/venv/*" \
            ! -path "*/"*"_cache/*" \
            -print0
    )
    echo
    ok "Processed ${count} files"
}


# clean pip/pipx cache
clean-pip() {
    echo "cleaning pip/pipx cache..."
    pip cache purge
    local dirs=(
        "${HOME}/.cache/pip/"
        "${HOME}/.cache/pip-tools/"
        "${HOME}/.cache/pipx/"
        "${HOME}/.local/pipx/.cache/"
        "${HOME}/.local/pipx/logs/"
        "${HOME}/pipx/.cache/"
        "${HOME}/pipx/logs/"
        "${HOME}/AppData/Local/pip/cache/"
    )
    for d in ${dirs[@]}; do
        if [ -d ${d} ]; then
            echo "deleting ${d}"
            rm -rf ${d}
        fi
    done
}


# clean python dev/temp files from current directory and subdirectories
clean-py() {
    if [[ "${PWD}" == "${HOME}" || "${PWD}" != "${HOME}"/* ]]; then
        err "can't run from this directory"
        return 1
    fi
    if ! type fd >/dev/null 2>&1; then
        err "fd not found"
        return 1
    fi
    local dirs=(
        build
        dist
    )
    local recurse_dirs=(
        __pycache__
        .tox
        .venv
        .*_cache
        *.egg-info
        htmlcov
        venv
    )
    local recurse_files=(
        *.coverage
        *.spec
        *.pyc
    )
    if [ -n "${VIRTUAL_ENV}" ]; then
        echo "deactivating venv"
        deactivate
    fi
    echo "cleaning python dev/temp files..."
    echo
    for d in "${dirs[@]}"; do
        if [ -d ${d} ]; then
            echo "deleting ${d}/"
            rm -rf "${d}/"
        fi
    done
    for rd in "${recurse_dirs[@]}"; do
        echo "recursively deleting ${rd}/"
        \fd --hidden --no-ignore --glob --exclude=".git/" --type=d "${rd}" \
            --exec rm -r
    done
    for rf in "${recurse_files[@]}"; do
        echo "recursively deleting ${rf}"
        \fd --hidden --no-ignore --glob --exclude=".git/" --type=f "${rf}" \
            --exec rm -r
    done
    echo
    ok "done"
}


# run pytest with coverage and open html report in browser
pytest-with-cov() {
    if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
        err "not a git repository"
        return 1
    fi
    cd "$(git rev-parse --show-toplevel)"
    if [ ! -f "pyproject.toml" ]; then
        err "not a python project"
        return 1
    fi
    local tmp_dir="$(mktemp -d)"
    local html_dir="${tmp_dir}/html"
    local cov_cfg="${tmp_dir}/coveragerc"
    cat > "${cov_cfg}" <<'EOF'
[run]
branch = True
omit =
    */tests/*
    */test_*
    */venv/*
    */.venv/*
    */site-packages/*
    */dist-packages/*
    */build/*
    */dist/*
EOF
    trap 'rm -f "${cov_cfg}"' EXIT
    echo "installing packages..."
    venv
    pip install --group test --upgrade --editable . || pip install --upgrade --editable .
    pip install --upgrade pytest-cov
    COVERAGE_FILE="${tmp_dir}/.coverage" pytest \
        --cov=. \
        --cov-context=test \
        --cov-config="${cov_cfg}" \
        --cov-report=html:"${html_dir}"
    web "${html_dir}/index.html"
}


# install a python application in an isoloated environment with the
# current global interpreter
# - usage: pipx-install <package>
pipx-install() {
    if [ -z "$1" ]; then
        err "please specify a package"
        return 1
    fi
    if ! type pipx >/dev/null 2>&1; then
        err "pipx not found"
        return 1
    fi
    if [ -n "${VIRTUAL_ENV}" ]; then
        echo "deactivating venv"
        deactivate
    fi
    if [ -d "${HOME}/.pyenv" ]; then
        pipx install "$1" --backend=pip --python "$(pyenv which python)"
    else
        pipx install "$1" --backend=pip
    fi
}


# upgrade all pipx applications
# - reinstalls apps if they don't match the current python interpreter version
pipx-upgrade-all() {
    if ! type pipx >/dev/null 2>&1; then
        err "pipx not found"
        return 1
    fi
    if [ -n "${VIRTUAL_ENV}" ]; then
        echo "deactivating venv"
        deactivate
    fi
    echo "upgrading pip..."
    PIP_REQUIRE_VIRTUALENV=false python -m pip install --upgrade \
        --upgrade-strategy=eager pip
    echo "upgrading pipx..."
    PIP_REQUIRE_VIRTUALENV=false pip install --user --upgrade \
        --upgrade-strategy=eager pipx
    local py_version=$(python3 --version)
    local pipx_list_output=$(pipx list)
    echo "upgrading pipx apps..."
    if [[ "${pipx_list_output}" == *"${py_version}"* ]]; then
        pipx upgrade-all --backend=pip --pip-args=--upgrade-strategy=eager
    else
        echo "app versions don't match interpreter. reinstalling packages..."
        echo
        if [ -d "${HOME}/.pyenv" ]; then
            pipx reinstall-all --backend=pip --python "$(pyenv which python)"
        else
            pipx reinstall-all --backend=pip
        fi
    fi
    echo
    local pipx_list_output=$(pipx list)
    echo "${pipx_list_output}"
    echo
    ok "$(grep -c '\- ' <<< ${pipx_list_output}) apps from"\
        "$(grep -c 'package ' <<< ${pipx_list_output}) packages installed"
}


# preview markdown file in browser
# - requires GitHub CLI (gh) and gh-markdown-preview extension
# - install extension with: `gh extension install yusukebe/gh-markdown-preview`
preview-md() {
    gh markdown-preview --light-mode --markdown-mode "$1"
}


# resize all .jpg and .png images in the current directory to
# specified pixel width
# - won't resize images that are already the same or smaller width
# - files are overwritten in-place
# - usage: shrink-images <width>
shrink-images() {
    if [ -z "$1" ]; then
        err "please specify a width in pixels"
        return 1
    fi
    local width="$1"
    for f in *.[jJ][pP][gG] *.[pP][nN][gG]; do
        [ -f "${f}" ] || continue
        local actual_width=$(magick identify -format '%w' "${f}")
        local dim_before=$(magick identify -format '%wx%h' "${f}")
        if [ "${actual_width}" -le "${width}" ]; then
            err "${f} is too small to resize: ${dim_before}"
            break
        fi
        local size_before=$(stat -c%s "${f}" | numfmt --to=iec)
        magick "${f}" -resize "${width}" "${f}"
        local dim_after=$(magick identify -format '%wx%h' "${f}")
        local size_after=$(stat -c%s "${f}" | numfmt --to=iec)
        ok "resized ${f} from ${dim_before} (${size_before}) to ${dim_after} (${size_after})"
    done
}


# -----------------------------------------------------------------------------


# load additional bash configurations if they exist
load-bash-configs() {
    local config_files=(
        "${HOME}/.bashrc_linux"
        "${HOME}/.bashrc_linux_selenium"
        "${HOME}/.bashrc_squeezebox"
        "${HOME}/.bashrc_windows"
    )
    for config_file in "${config_files[@]}"; do
        if [ -f "${config_file}" ]; then
            source "${config_file}"
        fi
    done
}
load-bash-configs


# - if not available, download it and put it in ~/etc
# - https://salsa.debian.org/debian/bash-completion/-/raw/master/bash_completion
load-bash-completions() {
    local found_completions="false"
    local completion_paths=(
        "/usr/share/bash-completion/bash_completion"
        "/etc/bash_completion"
        "${HOME}/etc/bash_completion"
    )
    local completion_loader_funcs=(
        "_completion_loader"
        "_comp_complete_load"
    )
    for completion_path in "${completion_paths[@]}"; do
        if [ -f "${completion_path}" ]; then
            source "${completion_path}"
            found_completions="true"
        fi
    done
    if [ "${found_completions}" == "false" ]; then
        err "no bash completions found"
    fi
    for completion_loader_func in "${completion_loader_funcs[@]}"; do
        if declare -f "${completion_loader_func}" >/dev/null; then
            # git completions
            if type git >/dev/null 2>&1; then
                "${completion_loader_func}" git
                complete -o bashdefault -o default -o nospace -F __git_wrap__git_main git
                complete -o bashdefault -o default -o nospace -F __git_wrap__git_main g
            fi
        fi
    done
}
load-bash-completions