.bash_useful_functions

# This file is part of eRCaGuy_dotfiles: https://github.com/ElectricRCAircraftGuy/eRCaGuy_dotfiles

# Utilities and useful Bash functions:
#
# Put anything in here that you don't think needs to be in its own stand-alone file/program
# inside "eRCaGuy_dotfiles/useful_scripts", and which might fit better here than inside:
#
# 1. eRCaGuy_dotfiles/home/.profile
# 1. eRCaGuy_dotfiles/home/.bashrc
# 1. eRCaGuy_dotfiles/home/.bash_aliases
# 1. eRCaGuy_dotfiles/home/.bash_aliases_private
# 1. eRCaGuy_dotfiles/home/.git_aliases
#
# In other words, I'm thinking that small, general-purpose **utilities** and functions and things
# can go here. If the complexity becomes too much, consider moving them to their own file
# inside "eRCaGuy_dotfiles/useful_scripts" instead.


# ==================================================================================================
# Hex file utilities
# ==================================================================================================

# Function to convert .hex firmware files to .bin
# - Could be very useful for binary and hex file comparisons, too. See my answer here:
#   https://superuser.com/a/1790518/425838
#
# Example usage:
#
#       # this produces "path/to/myfile.bin" from "path/to/myfile.hex"
#       hex2bin path/to/myfile.hex
#
#       # you can pass multiple paths at once too
#       hex2bin path/to/myfile1.hex path/to/myfile2.hex path/to/myfile3.hex
#
hex2bin() {
    # treat all input args as file paths
    for filepath_hex in "$@"; do
        # See: https://stackoverflow.com/a/965072/4561887
        filepath_hex_no_extension="${filepath_hex%.*}"
        filepath_bin="${filepath_hex_no_extension}.bin"
        # debugging
        # echo "filepath_hex_no_extension = $filepath_hex_no_extension"
        # echo "filepath_bin = $filepath_bin"
        echo "Converting \"$filepath_hex\" to \"$filepath_bin\"."

        xc32-objcopy --input-target=ihex --output-target=binary \
            "$filepath_hex" "$filepath_bin"
    done
}

# (Optional) add an alias prefixed with your initials so you can find all your
# custom aliases and functions easily by typing your initials followed by an
# underscore and hitting Tab Tab.
alias gs_hex2bin="hex2bin"

# Function to convert .hex firmware files to .bin and then to a
# human-compare-friendly .xxd.hex, so you can easily compare two files with
# `diff` or `meld`.
# - See my answer here: https://superuser.com/a/1790518/425838
#
# Example usage:
#
#       # this produces both "path/to/myfile.bin" and "path/to/myfile.xxd.hex"
#       # from "path/to/myfile.hex"
#       hex2xxdhex path/to/myfile.hex
#
#       # you can pass multiple paths at once too
#       hex2xxdhex path/to/myfile1.hex path/to/myfile2.hex
#       # then compare the two output ".xxd.hex" or ".xxd_short.hex" files with `meld`
#       meld path/to/myfile1.xxd_short.hex path/to/myfile2.xxd_short.hex
#
hex2xxdhex() {
    # treat all input args as file paths
    for filepath_hex in "$@"; do
        # See: https://stackoverflow.com/a/965072/4561887
        filepath_hex_no_extension="${filepath_hex%.*}"
        filepath_bin="${filepath_hex_no_extension}.bin"
        filepath_xxdhex="${filepath_hex_no_extension}.xxd.hex"
        filepath_xxdhex_short="${filepath_hex_no_extension}.xxd_short.hex"
        echo "Converting \"$filepath_hex\" to:"
        echo "  \"$filepath_bin\"           - the binary firmware image"
        echo "  \"$filepath_xxdhex\"       - the hex image with a binary/ASCII text panel to"\
             "the right"
        echo "  \"$filepath_xxdhex_short\" - same as just above, except removing all rows"\
             "containing only zeros."
        echo ""
        echo "Note that the '.xxd_short.hex' files are usually the best files to compare with"
        echo "'meld', since the '.xxd.hex' file might be too large (as large as 200 MB, for"
        echo "example), when the '.hex' file is only 3.5 MB, and the '.xxd_short.hex' file"
        echo "is 5 MB. Meld can compare 5 MB ok, but not 200 MB!"

        xc32-objcopy --input-target=ihex --output-target=binary "$filepath_hex" "$filepath_bin"

        xxd "$filepath_bin" "$filepath_xxdhex"

        grep -v '0000 0000 0000 0000 0000 0000 0000 0000' "$filepath_xxdhex" \
            > "$filepath_xxdhex_short"
    done
}
alias gs_hex2xxdhex="hex2xxdhex"

find_illegal_windows_chars() {
    # Find all files and folders with any of these Windows-illegal characters in
    # their name:  \ : * ? " < > |
    # - See my answer here: https://stackoverflow.com/a/76794738/4561887
    find . -name '*[\\:\*?\"<\>|]*'
}
alias gs_find_illegal_windows_chars='find_illegal_windows_chars'