[BK-2020-03.git] / unitproc / bklu

#!/bin/bash

# Date: 2020-05-04T18:50Z
# Author: Steven Baltakatei Sandoval
# Description: Script to lookup file hash from existing hash list.
# Note: Use hide-show-block function to aid readability. (ex: https://www.emacswiki.org/emacs/HideShow ).

#== Variable Initialization ==

#== Global constants ==
SCRIPT_TTL=10                   # Limit script life to this in seconds.
PATH="/usr/local/bin/:$PATH"    # Add user binary executable directory to PATH.
PATH="/opt/bktei:$PATH"         # Add 'optional' executable directory to PATH.
SCRIPT_HOSTNAME=$(hostname)     # Save hostname of system running this script.
SCRIPT_VERSION="bktemplate.sh 0.0.0" # Define version of script. Used by function 'showVersion'.
SCRIPT_TIME_SHORT="$(date +%Y%m%dT%H%M%S%z)" # Save current date & time in ISO-8601 format (YYYYmmddTHHMMSS+zzzz).
SCRIPT_DATE_SHORT="$(date +%Y%m%d)"          # Save current date in ISO-8601 format.

#== Function Definitions ==
echoerr() {
    # Usage: echo [ arguments ]
    # Description: Prints provided arguments to stderr.
    # Input: unspecified
    # Output: stderr
    # Script function dependencies: none
    # External function dependencies: echo
    # Last modified: 2020-04-11T21:16Z
    # Last modified by: Steven Baltakatei Sandoval
    # License: GPLv3+
    # Ref./Attrib:
    #  [1]: # Roth, James (2010-06-07). ["How to print text to stderr instead of stdout"](https://stackoverflow.com/a/2990533). Licensed CC BY-SA 4.0.
    
    echo "$@" 1>&2; # Define stderr echo function. See [1].
    return 0; # Function finished.
} # Define stderr message function.
vbm() {
    # Usage: vbm "DEBUG:verbose message here"
    # Description: Prints verbose message ("vbm") to stderr if OPTION_VERBOSE is set to "true".
    # Input:
    #   - OPTION_VERBOSE  variable set by processArguments function. (ex: "true", "false")
    #   - "$@"            positional arguments fed to this function.
    # Output: stderr
    # Script function dependencies: echoerr
    # External function dependencies: echo
    # Last modified: 2020-04-11T23:57Z
    # Last modified by: Steven Baltakatei Sandoval
    # License: GPLv3+
    # Ref./Attrib:

    if [ "$OPTION_VERBOSE" == "true" ]; then
	FUNCTION_TIME=$(date --iso-8601=ns); # Save current time in nano seconds.
	echoerr "[$FUNCTION_TIME] ""$@"; # Display argument text.
    fi

    # End function
    return 0; # Function finished.
} # Verbose message display function.
showUsage() {
    # Usage: showUsage
    # Description: Displays script usage information.
    # Input: none
    # Output: stderr
    # Script function dependencies: echoerr
    # External dependencies: bash (5.0.3), echo
    # Last modified: 2020-05-04T16:58Z
    # Last modified by: Steven Baltakatei Sandoval
    # License: GPLv3+
    # Ref./Attrib.:

    echoerr "USAGE:"
    echoerr "    bklu [OPTIONS] [FILE]"
    echoerr
    echoerr "    [FILE] hash is compared against file contents of directory"
    echoerr "      specified by --input-dir option or environment variable"
    echoerr "      BK_FILEHASHLIST_DIR ."
    echoerr
    echoerr "OPTIONS:"
    echoerr "    --digest-algo [ digest name ]"
    echoerr "            Specify digest command name. Value should be GNU"
    echoerr "            coreutils commands such as: sha256sum, md5sum, b2sum."
    echoerr "            Default value is: b2sum"
    echoerr
    echoerr "    -h, --help"
    echoerr "            Display help information."
    echoerr
    echoerr "    --version"
    echoerr "            Display script version."
    echoerr
    echoerr "    -v, --verbose"
    echoerr "            Display debugging info."
    echoerr
    echoerr "    -o, --output-file [ file ]"
    echoerr "            Specify output file."
    echoerr
    echoerr "    -i, --input-file [ file ]"
    echoerr "            Specify input file."
    echoerr
    echoerr "    -o, --output-dir [ directory ]"
    echoerr "            Specify output directory."
    echoerr
    echoerr "    -i, --input-dir [ directory ]"
    echoerr "            Specify input directory."
    echoerr


    # End function
    return 0; # Function finished.
} # Display information on how to use this script.
showVersion() {
    # Usage: showVersion
    # Descriptoin: Displays script version and license information.
    # Input: unspecified
    # Output: stderr
    # Script function dependencies: echoerr
    # External function dependencies: echo
    # Last modified: 2020-04-11T23:57Z
    # Last modified by: Steven Baltakatei Sandoval
    # License: GPLv3+
    # Ref./Attrib:

    # Initialize function
    vbm "DEBUG:showVersion function called."

    # Perform work
    OUTPUT="$SCRIPT_VERSION"

    # Display results
    echoerr "$OUTPUT";

    # End function
    vbm "DEBUG:showVersion function ended."
    return 0; # Function finished.
} # Display script version.
processArguments() {
    # Usage: processArguments "$@"
    # Description: Processes provided arguments in order to set script option variables useful for
    #   changing how other functions behave. For example, it may:
    #   1. Activate verbose mode
    # Input: "$@"          (list of arguments provided to the function)
    # Output: Sets following variables used by other functions:
    #   OPTION_VERBOSE     Indicates verbose mode enable status.  (ex: "true", "false")
    #   DIROUT1            Path to output directory.
    #   FILEOUT1           Path to output file.
    #   DIRIN1             Path to input directory.
    #   FILEIN1            Path to input file.
    #   OPTION_FILEOUT1_OVERWRITE Indicates whether file FILEOUT1 should be overwritten (ex: "true", "false')
    #   DIGEST_ALGO        Name of digest command (unverified).
    # Script function dependencies:
    #   - echoerr          Displays messages to stderr.
    #   - vbm              Displays messsages to stderr if OPTION_VERBOSE set to "true".
    # External dependencies: bash (5.0.3), echo
    # Last modified: 2020-05-04T18:13Z
    # Last modified by: Steven Baltakatei Sandoval
    # License: GPLv3+
    # Ref./Attrib.:
    #  [1]: Marco Aurelio (2014-05-08). "echo that outputs to stderr". https://stackoverflow.com/a/23550347

    # Initialize function
    #vbm "DEBUG:processArguments function called."

    # Perform work
    while [ ! $# -eq 0 ]; do   # While number of arguments ($#) is not (!) equal to (-eq) zero (0).
	#1>&2 echo "DEBUG:Starting processArguments while loop." # Debug stderr message. See [1].
        #1>&2 echo "DEBUG:Provided arguments are:""$@" # Debug stderr message. See [1].
	case "$1" in
	    -h | --help) showUsage; exit 1;; # Display usage.
	    --version) showVersion; exit 1;; # Show version
	    -v | --verbose) OPTION_VERBOSE="true"; vbm "DEBUG:Verbose mode enabled.";; # Enable verbose mode. See [1].
	    -i | --input-file) # Define input file path
		if [ -f "$2" ]; then # If $2 is file that exists, set FILEIN1 to $2, pop $2.
		    FILEIN1="$2";
		    shift;
		    vbm "DEBUG:Input file FILEIN1 set to:""$2";
		else
		    echoerr "ERROR: Specified input file does not exist:""$2";
		    echoerr "Exiting.";
		    exit 1;
		fi ;; 
	    -I | --input-dir) # Define input directory path.
		if [ -d "$2" ]; then # If $2 is dir that exists, set DIRIN1 to $2, pop $2.
		    DIRIN1="$2";
		    shift;
		    vbm "DEBUG:Input directory DIRIN1 set to:""$2";
		else # Display error if $2 is not a valid dir.
		    echoerr "ERROR:Specified input directory does not exist:""$2";
		    echoerr "Exiting.";
		    exit 1;
		fi ;; 
	    -o | --output-file) # Define output file path
		if [ -f "$2" ]; then # If $2 is file that exists, prompt user to continue to overwrite, set FILEOUT1 to $2, pop $2.
		    echoerr "Specified output file $2 already exists. Overwrite? (y/n):"
		    read m; case $m in
				y | Y | yes) OPTION_FILEOUT1_OVERWRITE="true";;
				n | N | no) OPTION_FILEOUT1_OVERWRITE="false";;
				*) echoerr "Invalid selection. Exiting."; exit 1;;
			    esac
		    if [ "$OPTION_FILEOUT1_OVERWRITE" == "true" ]; then
			FILEOUT1="$2";
			shift;
			vbm "DEBUG:Output file FILEOUT1 set to:""$2";
		    else
			echoerr "ERORR:Exiting in order to not overwrite output file:""$FILEOUT1";
			exit 1;
		    fi
		else
		    FILEOUT1="$2";
		    shift;
		    vbm "DEBUG:Output file FILEOUT1 set to:""$2";
		fi ;;
	    -O | --output-dir) # Define output directory path
		if [ -d "$2" ]; then # If $2 is dir that exists, set DIROUT1 to $2, pop $2
		    DIROUT1="$2";
		    shift;
		    vbm "DEBUG:Output directory DIROUT1 set to:""$2";
		else
		    echoerr "ERROR:Specified output directory is not valid:""$2";
		    echoerr "Exiting.";
		    exit 1;
		fi ;;
	    --digest-algo) # Define file digest algorithm command name.
		if ! [ -z "$2" ]; then # If $2 is non-zero, set DIGEST_ALGO to $2, pop $2
		    DIGEST_ALGO="$2";
		    shift;
		    vbm "DEBUG:DIGEST_ALGO set to:""$DIGEST_ALGO";
		else
		    echoerr "ERROR:Cannot set DIGEST_ALGO because no string specified."; echoerr "Exiting."; exit 1;
		fi ;;
	    *) if [ -f "$1" ] && ! [ -v FILEIN1 ]; then # If $1 is file and FILEIN1 not set, then set FILEIN1 to $1, pop $1.
		   FILEIN1="$1";
		   shift;
		   vbm "DEBUG:FILEIN1 set to:""$FILEIN1";
	       else # Handle non-option (ex: [FILE] )
		   echoerr "ERROR: Unrecognized non-option argument."; echoerr "Exiting."; exit 1;
	       fi ;;
	esac
	shift;
    done

    # End function
    vbm "DEBUG:processArguments function ended."
    return  0; # Function finished.
} # Evaluate script options from positional arguments (ex: $1, $2, $3, etc.).
checkExecutables() {
    # Usage: checkExecutables [ command1 ] [ command2 ] [...] [ commandN ]
    # Description: Checks that provided commands exist. If one or more do not exist, then display missing commands and exit with error.
    # Input:
    #   - command names (arguments)
    # Output: commands that don't exist (stderr)
    # Script function dependencies:
    #   - echoerr          for displaying errors via stderr
    #   - processArguments for setting OPTION_VERBOSE
    #   - vbm              for displaying verbose messages if OPTION_VERBOSE is "true"
    # External dependencies: bash (5.0.3), command
    # Last modified: 2020-05-04T17:12Z
    # Last modified by: Steven Baltakatei Sandoval
    # License: GPLv3+
    # Ref./Attrib.:
    #  [1]: SiegeX (2010-12-12). ["Difference between return and exit in Bash functions."](https://stackoverflow.com/a/4419971). Licensed CC BY-SA 4.0.
    #  [2]: Darryl Hein (2009-12-23). ["Add a new element to an array without specifying the index in Bash"](https://stackoverflow.com/a/1951523). Licensed CC BY-SA 4.0.
    #  [3]: kojiro (2012-10-03). ["Convert command line arguments into an array in Bash"](https://stackoverflow.com/a/12711853)
    #  [4]: niieani (2016-01-12). ["How to copy an array in Bash?"](https://stackoverflow.com/a/34733375/10850071). Licensed CC BY-SA 4.0.

    # Initialize function
    vbm "DEBUG:checkExecutables function called."
    declare -a candidateCommandsNames # Initialize array for storing positional arguments provided to this function.
    candidateCommandsNames=("$@") # Save positional arguments to variable as string. See [3].
    vbm "DEBUG:candidateCommandsNames:""$@"
    vbm "DEBUG:candidateCommandsNames[0]:""${candidateCommandsNames[0]}"
    vbm "DEBUG:candidateCommandsNames[1]:""${candidateCommandsNames[1]}"
    vbm "DEBUG:candidateCommandsNames[2]:""${candidateCommandsNames[2]}"
    declare -a outputInvalidCommandsArray # Initialize arary for storing names of invalid commands.
    declare -a outputValidCommandsArray # Initialize array for storing names of valid commands.

    # Perform work
    for candidateCommandName in "${candidateCommandsNames[@]}"; do  # Search through all space-delimited text for valid commands.
	if command -v "$candidateCommandName" 1>/dev/null 2>/dev/null; then # Check if a command is valid or not.
	    outputValidCommandsArray+=("$candidateCommandName") ; # See [2].
	    vbm "DEBUG:Adding $candidateCommandName to outputValidCommandsArray."
	else
	    outputInvalidCommandsArray+=("$candidateCommandName") ; # See [2].
	    vbm "DEBUG:Adding $candidateCommandName to outputInvalidCommandsArray."
	fi
    done

    # Output results
    if [ ${#outputInvalidCommandsArray[@]} -gt 0 ]; then # if number of elements in outputInvalidCommandsArray greater than 0, then display offending commands and exit 1.
	echoerr "ERROR: Invalid commands found:""${outputInvalidCommandsArray[@]}"; # display invalid commands as error
	exit 1; # See [1].
    elif [ ${#outputInvalidCommandsArray[@]} -eq 0 ]; then # if number of elements in outputInvalidCommandsArray equals zero, then return 0.
	vbm "DEBUG: Valid commands are:""${outputValidCommandsArray[@]}"; # display valid commands if verbose mode enabled
	return 0; # See [1].
    else
	echoerr "ERROR: Check outputInvalidCommandsArray.";
    fi

    # End function
    vbm "DEBUG:checkExecutables function ended."
    return 0; # Function finished.
} # Check that certain executables exist.
updateTimeConstants() {
    # Usage: updateTimeConstants
    # Description: Updates time-related variables for use by other scripts.
    # Input: (none)
    # Output: Sets following variables:
    #   TIME_CURRENT       Current time in long ISO-8601 format.  (ex: YYYY-mm-ddTHH:MM:SS+ZZZZ)
    #   TIME_CURRENT_SHORT Current time in short ISO-8601 format. (ex: YYYYmmddTHHMMSS+ZZZZ)
    #   DATE_CURRENT       Current date in ISO-8601 format.       (ex: YYYY-mm-dd)
    #   DATE_CURRENT_SHORT Current date in short ISO-8601 format. (ex: YYYYmmdd)
    #   DATE_TOMORROW      Tomorrow's date in ISO-8601 format.    (ex: YYYY-mm-dd)
    #   TIME_NEXT_MIDNIGHT Time of tomorrow's midnight in long    (ex: YYYY-mm-ddTHH:MM:SS+ZZZZ)
    #                       ISO-861 format.
    #   SEC_TIL_MIDNIGHT   Seconds until next midnight.
    # Script function dependencies:
    #   - echoerr          for displaying errors via stderr
    #   - processArguments for setting OPTION_VERBOSE
    #   - vbm              for displaying verbose messages if OPTION_VERBOSE is "true"
    # External dependencies: bash (5.0.3), date, echo
    # Last modified: 2020-04-11T23:59Z
    # Last modified by: Steven Baltakatei Sandoval
    # License: GPLv3+
    # Ref./Attrib.:

    # Initialize function
    vbm "DEBUG:updateTimeConstants function called."

    # Perform work
    TIME_CURRENT="$(date --iso-8601=seconds)" ;
    TIME_CURRENT_SHORT="$(date -d "$TIME_CURRENT" +%Y%m%dT%H%M%S%z)"
    DATE_CURRENT="$(date -d "$TIME_CURRENT" --iso-8601=date)" ;
    DATE_CURRENT_SHORT="$(date -d "$TIME_CURRENT" +%Y%m%d)" ;
    DATE_TOMORROW="$(date -d "$TIME_CURRENT next day" --iso-8601=date)" ;
    TIME_NEXT_MIDNIGHT="$(date -d "$DATE_TOMORROW" --iso-8601=seconds)" ;
    SECONDS_UNTIL_NEXT_MIDNIGHT="$((  $(date +%s -d "$TIME_NEXT_MIDNIGHT") - $(date +%s -d "$TIME_CURRENT")  ))" ;

    # End function
    vbm "DEBUG:updateTimeConstants function ended."
    return 0; # Function finished.
} # Update time constants
getGnucuDigest() {
    # Usage: getGnucuDigest [algo] [file]
    # Description: Calculates cryptographic digest using specified GnuCoreutils command.
    # Input:
    #   $1: [algo]     (ex: sha256sum, sha512sum, b2sum, md5sum)
    #   $2: [file]
    # Output: stdout 
    # Script function dependencies:
    #   - echoerr          for displaying errors via stderr
    #   - processArguments for setting OPTION_VERBOSE
    #   - vbm              for displaying verbose messages if OPTION_VERBOSE is "true"
    #   - checkExecutables for checking that digest algo commands exist
    # External dependencies: bash (5.0.3), echo, awk
    # Last modified: 2020-05-04T18:51Z
    # Last modified by: Steven Baltakatei Sandoval
    # License: GPLv3+
    # Ref./Attrib.:
    #  [1]: gnu.org (2000-11). [GNU Coreutils](https://www.gnu.org/software/coreutils/manual/coreutils.html). Licensed FDL v1.3+.
    #  [2]: linuxize.com (2019-07-19). [How to Check if a String Contains a Substring in Bash](https://linuxize.com/post/how-to-check-if-string-contains-substring-in-bash/).

    # Initialize function
    vbm "DEBUG:getGnucuDigest function called."
    DIGEST_ALGO=$1 # Define candidate digest algorithm
    TARGET_FILE=$2 # Define target file to be digested
    GNUCU_DIGESTS="b2sum md5sum sha1sum sha224sum sha256sum sha384sum sha512sum" # Define space-delimited string with GNU Coreutils digest algorithms. See [1].
    vbm "DEBUG:DIGEST_ALGO set to:""$DIGEST_ALGO"
    vbm "TARGET_FILE set to:""$TARGET_FILE"
    vbm "GNUCU_DIGESTS set to:""$GNUCU_DIGESTS"
    checkExecutables "$DIGEST_ALGO"; # Check that specified alogirthm command available.
    if [[ "$GNUCU_DIGESTS" =~ .*"$DIGEST_ALGO".* ]]; then
	vbm "DEBUG:Confirmed to be a valid GNU Coreutils command:""$DIGEST_ALGO";
    else
	vbm "ERROR:Not a valid GNU coreutils command:""$DIGEST_ALGO";
	exit 1;
    fi # Check specified algo against GNUCU_DIGESTS. See [2].
    
    # Perform work
    OUTPUT="$("$DIGEST_ALGO" "$TARGET_FILE" | awk '{print $1}')"
    vbm "DEBUG:Calculated digest using $DIGEST_ALGO is:""$OUTPUT"

    # Output results
    echo "$OUTPUT"
    
    # End function
    vbm "DEBUG:getGnucuDigest function ended."
    return 0; # Function finished.
} # Calculate GNUCoreutils digest


#== Main Program Definition ==
main() {
    # Usage: main "$@"    # See [1].
    # Input: unspecified (note: all Global Constants declared at beginning of script assumed to be available)
    #   OPTION_VERBOSE   (used by vbm, set by processArguments)  (ex: "true", "false")
    #   DIGEST_ALGO      (used by getGnucuDigest, set by processArguments) (ex: "md5sum")
    # Output: unspecified
    # Script function dependencies:
    #   - echoerr          for displaying errors via stderr
    #   - vbm              for displaying verbose messages if OPTION_VERBOSE is "true"
    #   - processArguments for setting OPTION_VERBOSE
    #   - checkExecutables for checking that specified commands are available
    # External dependencies: bash (5.0.3), echo
    # Last modified: 2020-05-04T18:44Z
    # Last modified by: Steven Baltakatei Sandoval
    # License: GPLv3+
    # Ref./Attrib.:
    #  [1]: ErichBSchulz (2011-11-20). [How to correctly pass bash script arguments to functions](https://stackoverflow.com/a/8198970). Licensed CC BY-SA 4.0.

    # Initialize function
    processArguments "$@" # Process arguments.
    vbm "DEBUG:main function called."
    vbm "DEBUG:main function arguments are:""$@"
    checkExecutables "echo" "date" "cut" "awk" "grep" # Confirm that executables necessary to run are available. Exit if any fail.

    # Process inputs
    # If DIRIN1 unset and global variable BK_FILEHASHLIST_DIR set and is dir, then set DIRIN1 to BK_FILEHASHLIST_DIR.
    if ! [ -v DIRN1 ] && [ -v BK_FILEHASHLIST_DIR ] && [ -d "$BK_FILEHASHLIST_DIR" ]; then
	DIRIN1="$BK_FILEHASHLIST_DIR";
	vbm "DEBUG:DIRN1 not set, BK_FILEHASHLIST_DIR is dir, so setting DIRIN1 to BK_FILEHASHLIST_DIR:""$BK_FILEHASHLIST_DIR";
    fi

    # Set defaults
    if ! [ -v DIGEST_ALGO ]; then # If DIGEST_ALGO is not set then set it to default value of "b2sum"
	DIGEST_ALGO="b2sum";
	vbm "DEBUG:DIGEST_ALGO not set. Setting to default value:""$DIGEST_ALGO"
    fi

    
    # if [ -v FILEIN1 ]; then # VERBOSE: Display contents of FILEIN1 if FILEIN1 has been set.
    # 	vbm "DEBUG:main function detects input file:""$FILEIN1" ;
    # 	vbm "DEBUG:contents of following file is displayed below:""$FILEIN1" ;
    # 	if [ "$OPTION_VERBOSE" == "true" ]; then # display FILEIN1 contents via cat if verbose mode specified
    # 	    echoerr "========""$FILEIN1"" START""========" ;
    # 	    cat "$FILEIN1" 1>&2 ;
    # 	    echoerr "========""$FILEIN1"" END""========" ;
    # 	fi
    # fi

    
    # Perform work
    DIGEST="$(getGnucuDigest "$DIGEST_ALGO" "$FILEIN1")" # Calculate digest of FILEIN1
    vbm "DEBUG:Hash of $FILEIN1 is:""$DIGEST"
    vbm "DEBUG:Value of DIGEST is:""$DIGEST"
    vbm "DEBUG:Value of DIRIN1 is:""$DIRIN1"
    OUTPUT="$(grep -ri "$DIGEST" "$DIRIN1")" # Search contents of DIRIN1 for pattern DIGEST, save results to OUTPUT.

    # Output results
    echo -e "$OUTPUT"

    if [ -v FILEOUT1 ]; then  # if FILEOUT1 set, write to this file.
	vbm "DEBUG:main function detects FILEOUT1 set to:""$FILEOUT1" ;
	echo -e "$OUTPUT" > "$FILEOUT1" ;
	vbm "DEBUG:main funtion wrote OUTPUT to:""$FILEOUT1" ;
    elif [ -v DIROUT1 ]; then  # else if DIROUT1 set, set FILEOUT1 to timestamped filename, combine into PATHOUT1, write output to PATHOUT1.
	vbm "DEBUG:main function detects DIROUT1 set to:""$DIROUT1" ;
	FILEOUT1="$SCRIPT_TIME_SHORT".."$(basename "$0")".txt
	PATHOUT1="$DIROUT1"/"$FILEOUT1"
	echo -e "$OUTPUT" > $PATHOUT1 ;
	vbm "DEBUG:main function wrote output file to:""$PATHOUT1" ;
    fi

    # End function
    vbm "DEBUG:main function ended."
    return 0; # Function finished.
}

#== Perform work and exit ==
main "$@" # Run main function.
exit 0;
Commit	Line	Data
0d22dfcd SBS	1	#!/bin/bash
	2
	3	# Date: 2020-05-04T18:50Z
	4	# Author: Steven Baltakatei Sandoval
	5	# Description: Script to lookup file hash from existing hash list.
	6	# Note: Use hide-show-block function to aid readability. (ex: https://www.emacswiki.org/emacs/HideShow ).
	7
	8	#== Variable Initialization ==
	9
	10	#== Global constants ==
	11	SCRIPT_TTL=10 # Limit script life to this in seconds.
	12	PATH="/usr/local/bin/:$PATH" # Add user binary executable directory to PATH.
	13	PATH="/opt/bktei:$PATH" # Add 'optional' executable directory to PATH.
	14	SCRIPT_HOSTNAME=$(hostname) # Save hostname of system running this script.
	15	SCRIPT_VERSION="bktemplate.sh 0.0.0" # Define version of script. Used by function 'showVersion'.
	16	SCRIPT_TIME_SHORT="$(date +%Y%m%dT%H%M%S%z)" # Save current date & time in ISO-8601 format (YYYYmmddTHHMMSS+zzzz).
	17	SCRIPT_DATE_SHORT="$(date +%Y%m%d)" # Save current date in ISO-8601 format.
	18
	19	#== Function Definitions ==
	20	echoerr() {
	21	# Usage: echo [ arguments ]
	22	# Description: Prints provided arguments to stderr.
	23	# Input: unspecified
	24	# Output: stderr
	25	# Script function dependencies: none
	26	# External function dependencies: echo
	27	# Last modified: 2020-04-11T21:16Z
	28	# Last modified by: Steven Baltakatei Sandoval
	29	# License: GPLv3+
	30	# Ref./Attrib:
	31	# [1]: # Roth, James (2010-06-07). ["How to print text to stderr instead of stdout"](https://stackoverflow.com/a/2990533). Licensed CC BY-SA 4.0.
	32
	33	echo "$@" 1>&2; # Define stderr echo function. See [1].
	34	return 0; # Function finished.
	35	} # Define stderr message function.
	36	vbm() {
	37	# Usage: vbm "DEBUG:verbose message here"
	38	# Description: Prints verbose message ("vbm") to stderr if OPTION_VERBOSE is set to "true".
	39	# Input:
	40	# - OPTION_VERBOSE variable set by processArguments function. (ex: "true", "false")
	41	# - "$@" positional arguments fed to this function.
	42	# Output: stderr
	43	# Script function dependencies: echoerr
	44	# External function dependencies: echo
	45	# Last modified: 2020-04-11T23:57Z
	46	# Last modified by: Steven Baltakatei Sandoval
	47	# License: GPLv3+
	48	# Ref./Attrib:
	49
	50	if [ "$OPTION_VERBOSE" == "true" ]; then
	51	FUNCTION_TIME=$(date --iso-8601=ns); # Save current time in nano seconds.
	52	echoerr "[$FUNCTION_TIME] ""$@"; # Display argument text.
	53	fi
	54
	55	# End function
	56	return 0; # Function finished.
	57	} # Verbose message display function.
	58	showUsage() {
	59	# Usage: showUsage
	60	# Description: Displays script usage information.
	61	# Input: none
	62	# Output: stderr
	63	# Script function dependencies: echoerr
	64	# External dependencies: bash (5.0.3), echo
65	# Last modified: 2020-05-04T16:58Z
66	# Last modified by: Steven Baltakatei Sandoval
67	# License: GPLv3+
68	# Ref./Attrib.:
69
70	echoerr "USAGE:"
71	echoerr " bklu [OPTIONS] [FILE]"
72	echoerr
73	echoerr " [FILE] hash is compared against file contents of directory"
74	echoerr " specified by --input-dir option or environment variable"
75	echoerr " BK_FILEHASHLIST_DIR ."
76	echoerr
77	echoerr "OPTIONS:"
78	echoerr " --digest-algo [ digest name ]"
79	echoerr " Specify digest command name. Value should be GNU"
80	echoerr " coreutils commands such as: sha256sum, md5sum, b2sum."
81	echoerr " Default value is: b2sum"
82	echoerr
83	echoerr " -h, --help"
84	echoerr " Display help information."
85	echoerr
86	echoerr " --version"
87	echoerr " Display script version."
88	echoerr
89	echoerr " -v, --verbose"
90	echoerr " Display debugging info."
91	echoerr
92	echoerr " -o, --output-file [ file ]"
93	echoerr " Specify output file."
94	echoerr
95	echoerr " -i, --input-file [ file ]"
96	echoerr " Specify input file."
97	echoerr
98	echoerr " -o, --output-dir [ directory ]"
99	echoerr " Specify output directory."
100	echoerr
101	echoerr " -i, --input-dir [ directory ]"
102	echoerr " Specify input directory."
103	echoerr
104
105
106	# End function
107	return 0; # Function finished.
108	} # Display information on how to use this script.
109	showVersion() {
110	# Usage: showVersion
111	# Descriptoin: Displays script version and license information.
112	# Input: unspecified
113	# Output: stderr
114	# Script function dependencies: echoerr
115	# External function dependencies: echo
116	# Last modified: 2020-04-11T23:57Z
117	# Last modified by: Steven Baltakatei Sandoval
118	# License: GPLv3+
119	# Ref./Attrib:
120
121	# Initialize function
122	vbm "DEBUG:showVersion function called."
123
124	# Perform work
125	OUTPUT="$SCRIPT_VERSION"
126
127	# Display results
128	echoerr "$OUTPUT";
129
130	# End function
131	vbm "DEBUG:showVersion function ended."
132	return 0; # Function finished.
133	} # Display script version.
134	processArguments() {
135	# Usage: processArguments "$@"
136	# Description: Processes provided arguments in order to set script option variables useful for
137	# changing how other functions behave. For example, it may:
138	# 1. Activate verbose mode
139	# Input: "$@" (list of arguments provided to the function)
140	# Output: Sets following variables used by other functions:
141	# OPTION_VERBOSE Indicates verbose mode enable status. (ex: "true", "false")
142	# DIROUT1 Path to output directory.
143	# FILEOUT1 Path to output file.
144	# DIRIN1 Path to input directory.
145	# FILEIN1 Path to input file.
146	# OPTION_FILEOUT1_OVERWRITE Indicates whether file FILEOUT1 should be overwritten (ex: "true", "false')
147	# DIGEST_ALGO Name of digest command (unverified).
148	# Script function dependencies:
149	# - echoerr Displays messages to stderr.
150	# - vbm Displays messsages to stderr if OPTION_VERBOSE set to "true".
151	# External dependencies: bash (5.0.3), echo
152	# Last modified: 2020-05-04T18:13Z
153	# Last modified by: Steven Baltakatei Sandoval
154	# License: GPLv3+
155	# Ref./Attrib.:
156	# [1]: Marco Aurelio (2014-05-08). "echo that outputs to stderr". https://stackoverflow.com/a/23550347
157
158	# Initialize function
159	#vbm "DEBUG:processArguments function called."
160
161	# Perform work
162	while [ ! $# -eq 0 ]; do # While number of arguments ($#) is not (!) equal to (-eq) zero (0).
163	#1>&2 echo "DEBUG:Starting processArguments while loop." # Debug stderr message. See [1].
164	#1>&2 echo "DEBUG:Provided arguments are:""$@" # Debug stderr message. See [1].
165	case "$1" in
166	-h \| --help) showUsage; exit 1;; # Display usage.
167	--version) showVersion; exit 1;; # Show version
168	-v \| --verbose) OPTION_VERBOSE="true"; vbm "DEBUG:Verbose mode enabled.";; # Enable verbose mode. See [1].
169	-i \| --input-file) # Define input file path
170	if [ -f "$2" ]; then # If $2 is file that exists, set FILEIN1 to $2, pop $2.
171	FILEIN1="$2";
172	shift;
173	vbm "DEBUG:Input file FILEIN1 set to:""$2";
174	else
175	echoerr "ERROR: Specified input file does not exist:""$2";
176	echoerr "Exiting.";
177	exit 1;
178	fi ;;
179	-I \| --input-dir) # Define input directory path.
180	if [ -d "$2" ]; then # If $2 is dir that exists, set DIRIN1 to $2, pop $2.
181	DIRIN1="$2";
182	shift;
183	vbm "DEBUG:Input directory DIRIN1 set to:""$2";
184	else # Display error if $2 is not a valid dir.
185	echoerr "ERROR:Specified input directory does not exist:""$2";
186	echoerr "Exiting.";
187	exit 1;
188	fi ;;
189	-o \| --output-file) # Define output file path
190	if [ -f "$2" ]; then # If $2 is file that exists, prompt user to continue to overwrite, set FILEOUT1 to $2, pop $2.
191	echoerr "Specified output file $2 already exists. Overwrite? (y/n):"
192	read m; case $m in
193	y \| Y \| yes) OPTION_FILEOUT1_OVERWRITE="true";;
194	n \| N \| no) OPTION_FILEOUT1_OVERWRITE="false";;
195	*) echoerr "Invalid selection. Exiting."; exit 1;;
196	esac
197	if [ "$OPTION_FILEOUT1_OVERWRITE" == "true" ]; then
198	FILEOUT1="$2";
199	shift;
200	vbm "DEBUG:Output file FILEOUT1 set to:""$2";
201	else
202	echoerr "ERORR:Exiting in order to not overwrite output file:""$FILEOUT1";
203	exit 1;
204	fi
205	else
206	FILEOUT1="$2";
207	shift;
208	vbm "DEBUG:Output file FILEOUT1 set to:""$2";
209	fi ;;
210	-O \| --output-dir) # Define output directory path
211	if [ -d "$2" ]; then # If $2 is dir that exists, set DIROUT1 to $2, pop $2
212	DIROUT1="$2";
213	shift;
214	vbm "DEBUG:Output directory DIROUT1 set to:""$2";
215	else
216	echoerr "ERROR:Specified output directory is not valid:""$2";
217	echoerr "Exiting.";
218	exit 1;
219	fi ;;
220	--digest-algo) # Define file digest algorithm command name.
221	if ! [ -z "$2" ]; then # If $2 is non-zero, set DIGEST_ALGO to $2, pop $2
222	DIGEST_ALGO="$2";
223	shift;
224	vbm "DEBUG:DIGEST_ALGO set to:""$DIGEST_ALGO";
225	else
226	echoerr "ERROR:Cannot set DIGEST_ALGO because no string specified."; echoerr "Exiting."; exit 1;
227	fi ;;
228	*) if [ -f "$1" ] && ! [ -v FILEIN1 ]; then # If $1 is file and FILEIN1 not set, then set FILEIN1 to $1, pop $1.
229	FILEIN1="$1";
230	shift;
231	vbm "DEBUG:FILEIN1 set to:""$FILEIN1";
232	else # Handle non-option (ex: [FILE] )
233	echoerr "ERROR: Unrecognized non-option argument."; echoerr "Exiting."; exit 1;
234	fi ;;
235	esac
236	shift;
237	done
238
239	# End function
240	vbm "DEBUG:processArguments function ended."
241	return 0; # Function finished.
242	} # Evaluate script options from positional arguments (ex: $1, $2, $3, etc.).
243	checkExecutables() {
244	# Usage: checkExecutables [ command1 ] [ command2 ] [...] [ commandN ]
245	# Description: Checks that provided commands exist. If one or more do not exist, then display missing commands and exit with error.
246	# Input:
247	# - command names (arguments)
248	# Output: commands that don't exist (stderr)
249	# Script function dependencies:
250	# - echoerr for displaying errors via stderr
251	# - processArguments for setting OPTION_VERBOSE
252	# - vbm for displaying verbose messages if OPTION_VERBOSE is "true"
253	# External dependencies: bash (5.0.3), command
254	# Last modified: 2020-05-04T17:12Z
255	# Last modified by: Steven Baltakatei Sandoval
256	# License: GPLv3+
257	# Ref./Attrib.:
258	# [1]: SiegeX (2010-12-12). ["Difference between return and exit in Bash functions."](https://stackoverflow.com/a/4419971). Licensed CC BY-SA 4.0.
259	# [2]: Darryl Hein (2009-12-23). ["Add a new element to an array without specifying the index in Bash"](https://stackoverflow.com/a/1951523). Licensed CC BY-SA 4.0.
260	# [3]: kojiro (2012-10-03). ["Convert command line arguments into an array in Bash"](https://stackoverflow.com/a/12711853)
261	# [4]: niieani (2016-01-12). ["How to copy an array in Bash?"](https://stackoverflow.com/a/34733375/10850071). Licensed CC BY-SA 4.0.
262
263	# Initialize function
264	vbm "DEBUG:checkExecutables function called."
265	declare -a candidateCommandsNames # Initialize array for storing positional arguments provided to this function.
266	candidateCommandsNames=("$@") # Save positional arguments to variable as string. See [3].
267	vbm "DEBUG:candidateCommandsNames:""$@"
268	vbm "DEBUG:candidateCommandsNames[0]:""${candidateCommandsNames[0]}"
269	vbm "DEBUG:candidateCommandsNames[1]:""${candidateCommandsNames[1]}"
270	vbm "DEBUG:candidateCommandsNames[2]:""${candidateCommandsNames[2]}"
271	declare -a outputInvalidCommandsArray # Initialize arary for storing names of invalid commands.
272	declare -a outputValidCommandsArray # Initialize array for storing names of valid commands.
273
274	# Perform work
275	for candidateCommandName in "${candidateCommandsNames[@]}"; do # Search through all space-delimited text for valid commands.
276	if command -v "$candidateCommandName" 1>/dev/null 2>/dev/null; then # Check if a command is valid or not.
277	outputValidCommandsArray+=("$candidateCommandName") ; # See [2].
278	vbm "DEBUG:Adding $candidateCommandName to outputValidCommandsArray."
279	else
280	outputInvalidCommandsArray+=("$candidateCommandName") ; # See [2].
281	vbm "DEBUG:Adding $candidateCommandName to outputInvalidCommandsArray."
282	fi
283	done
284
285	# Output results
286	if [ ${#outputInvalidCommandsArray[@]} -gt 0 ]; then # if number of elements in outputInvalidCommandsArray greater than 0, then display offending commands and exit 1.
287	echoerr "ERROR: Invalid commands found:""${outputInvalidCommandsArray[@]}"; # display invalid commands as error
288	exit 1; # See [1].
289	elif [ ${#outputInvalidCommandsArray[@]} -eq 0 ]; then # if number of elements in outputInvalidCommandsArray equals zero, then return 0.
290	vbm "DEBUG: Valid commands are:""${outputValidCommandsArray[@]}"; # display valid commands if verbose mode enabled
291	return 0; # See [1].
292	else
293	echoerr "ERROR: Check outputInvalidCommandsArray.";
294	fi
295
296	# End function
297	vbm "DEBUG:checkExecutables function ended."
298	return 0; # Function finished.
299	} # Check that certain executables exist.
300	updateTimeConstants() {
301	# Usage: updateTimeConstants
302	# Description: Updates time-related variables for use by other scripts.
303	# Input: (none)
304	# Output: Sets following variables:
305	# TIME_CURRENT Current time in long ISO-8601 format. (ex: YYYY-mm-ddTHH:MM:SS+ZZZZ)
306	# TIME_CURRENT_SHORT Current time in short ISO-8601 format. (ex: YYYYmmddTHHMMSS+ZZZZ)
307	# DATE_CURRENT Current date in ISO-8601 format. (ex: YYYY-mm-dd)
308	# DATE_CURRENT_SHORT Current date in short ISO-8601 format. (ex: YYYYmmdd)
309	# DATE_TOMORROW Tomorrow's date in ISO-8601 format. (ex: YYYY-mm-dd)
310	# TIME_NEXT_MIDNIGHT Time of tomorrow's midnight in long (ex: YYYY-mm-ddTHH:MM:SS+ZZZZ)
311	# ISO-861 format.
312	# SEC_TIL_MIDNIGHT Seconds until next midnight.
313	# Script function dependencies:
314	# - echoerr for displaying errors via stderr
315	# - processArguments for setting OPTION_VERBOSE
316	# - vbm for displaying verbose messages if OPTION_VERBOSE is "true"
317	# External dependencies: bash (5.0.3), date, echo
318	# Last modified: 2020-04-11T23:59Z
319	# Last modified by: Steven Baltakatei Sandoval
320	# License: GPLv3+
321	# Ref./Attrib.:
322
323	# Initialize function
324	vbm "DEBUG:updateTimeConstants function called."
325
326	# Perform work
327	TIME_CURRENT="$(date --iso-8601=seconds)" ;
328	TIME_CURRENT_SHORT="$(date -d "$TIME_CURRENT" +%Y%m%dT%H%M%S%z)"
329	DATE_CURRENT="$(date -d "$TIME_CURRENT" --iso-8601=date)" ;
330	DATE_CURRENT_SHORT="$(date -d "$TIME_CURRENT" +%Y%m%d)" ;
331	DATE_TOMORROW="$(date -d "$TIME_CURRENT next day" --iso-8601=date)" ;
332	TIME_NEXT_MIDNIGHT="$(date -d "$DATE_TOMORROW" --iso-8601=seconds)" ;
333	SECONDS_UNTIL_NEXT_MIDNIGHT="$(( $(date +%s -d "$TIME_NEXT_MIDNIGHT") - $(date +%s -d "$TIME_CURRENT") ))" ;
334
335	# End function
336	vbm "DEBUG:updateTimeConstants function ended."
337	return 0; # Function finished.
338	} # Update time constants
339	getGnucuDigest() {
340	# Usage: getGnucuDigest [algo] [file]
341	# Description: Calculates cryptographic digest using specified GnuCoreutils command.
342	# Input:
343	# $1: [algo] (ex: sha256sum, sha512sum, b2sum, md5sum)
344	# $2: [file]
345	# Output: stdout
346	# Script function dependencies:
347	# - echoerr for displaying errors via stderr
348	# - processArguments for setting OPTION_VERBOSE
349	# - vbm for displaying verbose messages if OPTION_VERBOSE is "true"
350	# - checkExecutables for checking that digest algo commands exist
351	# External dependencies: bash (5.0.3), echo, awk
352	# Last modified: 2020-05-04T18:51Z
353	# Last modified by: Steven Baltakatei Sandoval
354	# License: GPLv3+
355	# Ref./Attrib.:
356	# [1]: gnu.org (2000-11). [GNU Coreutils](https://www.gnu.org/software/coreutils/manual/coreutils.html). Licensed FDL v1.3+.
357	# [2]: linuxize.com (2019-07-19). [How to Check if a String Contains a Substring in Bash](https://linuxize.com/post/how-to-check-if-string-contains-substring-in-bash/).
358
359	# Initialize function
360	vbm "DEBUG:getGnucuDigest function called."
361	DIGEST_ALGO=$1 # Define candidate digest algorithm
362	TARGET_FILE=$2 # Define target file to be digested
363	GNUCU_DIGESTS="b2sum md5sum sha1sum sha224sum sha256sum sha384sum sha512sum" # Define space-delimited string with GNU Coreutils digest algorithms. See [1].
364	vbm "DEBUG:DIGEST_ALGO set to:""$DIGEST_ALGO"
365	vbm "TARGET_FILE set to:""$TARGET_FILE"
366	vbm "GNUCU_DIGESTS set to:""$GNUCU_DIGESTS"
367	checkExecutables "$DIGEST_ALGO"; # Check that specified alogirthm command available.
368	if [[ "$GNUCU_DIGESTS" =~ ."$DIGEST_ALGO". ]]; then
369	vbm "DEBUG:Confirmed to be a valid GNU Coreutils command:""$DIGEST_ALGO";
370	else
371	vbm "ERROR:Not a valid GNU coreutils command:""$DIGEST_ALGO";
372	exit 1;
373	fi # Check specified algo against GNUCU_DIGESTS. See [2].
374
375	# Perform work
376	OUTPUT="$("$DIGEST_ALGO" "$TARGET_FILE" \| awk '{print $1}')"
377	vbm "DEBUG:Calculated digest using $DIGEST_ALGO is:""$OUTPUT"
378
379	# Output results
380	echo "$OUTPUT"
381
382	# End function
383	vbm "DEBUG:getGnucuDigest function ended."
384	return 0; # Function finished.
385	} # Calculate GNUCoreutils digest
386
387
388	#== Main Program Definition ==
389	main() {
390	# Usage: main "$@" # See [1].
391	# Input: unspecified (note: all Global Constants declared at beginning of script assumed to be available)
392	# OPTION_VERBOSE (used by vbm, set by processArguments) (ex: "true", "false")
393	# DIGEST_ALGO (used by getGnucuDigest, set by processArguments) (ex: "md5sum")
394	# Output: unspecified
395	# Script function dependencies:
396	# - echoerr for displaying errors via stderr
397	# - vbm for displaying verbose messages if OPTION_VERBOSE is "true"
398	# - processArguments for setting OPTION_VERBOSE
399	# - checkExecutables for checking that specified commands are available
400	# External dependencies: bash (5.0.3), echo
401	# Last modified: 2020-05-04T18:44Z
402	# Last modified by: Steven Baltakatei Sandoval
403	# License: GPLv3+
404	# Ref./Attrib.:
405	# [1]: ErichBSchulz (2011-11-20). [How to correctly pass bash script arguments to functions](https://stackoverflow.com/a/8198970). Licensed CC BY-SA 4.0.
406
407	# Initialize function
408	processArguments "$@" # Process arguments.
409	vbm "DEBUG:main function called."
410	vbm "DEBUG:main function arguments are:""$@"
411	checkExecutables "echo" "date" "cut" "awk" "grep" # Confirm that executables necessary to run are available. Exit if any fail.
412
413	# Process inputs
414	# If DIRIN1 unset and global variable BK_FILEHASHLIST_DIR set and is dir, then set DIRIN1 to BK_FILEHASHLIST_DIR.
415	if ! [ -v DIRN1 ] && [ -v BK_FILEHASHLIST_DIR ] && [ -d "$BK_FILEHASHLIST_DIR" ]; then
416	DIRIN1="$BK_FILEHASHLIST_DIR";
417	vbm "DEBUG:DIRN1 not set, BK_FILEHASHLIST_DIR is dir, so setting DIRIN1 to BK_FILEHASHLIST_DIR:""$BK_FILEHASHLIST_DIR";
418	fi
419
420	# Set defaults
421	if ! [ -v DIGEST_ALGO ]; then # If DIGEST_ALGO is not set then set it to default value of "b2sum"
422	DIGEST_ALGO="b2sum";
423	vbm "DEBUG:DIGEST_ALGO not set. Setting to default value:""$DIGEST_ALGO"
424	fi
425
426
427	# if [ -v FILEIN1 ]; then # VERBOSE: Display contents of FILEIN1 if FILEIN1 has been set.
428	# vbm "DEBUG:main function detects input file:""$FILEIN1" ;
429	# vbm "DEBUG:contents of following file is displayed below:""$FILEIN1" ;
430	# if [ "$OPTION_VERBOSE" == "true" ]; then # display FILEIN1 contents via cat if verbose mode specified
431	# echoerr "========""$FILEIN1"" START""========" ;
432	# cat "$FILEIN1" 1>&2 ;
433	# echoerr "========""$FILEIN1"" END""========" ;
434	# fi
435	# fi
436
437
438	# Perform work
439	DIGEST="$(getGnucuDigest "$DIGEST_ALGO" "$FILEIN1")" # Calculate digest of FILEIN1
440	vbm "DEBUG:Hash of $FILEIN1 is:""$DIGEST"
441	vbm "DEBUG:Value of DIGEST is:""$DIGEST"
442	vbm "DEBUG:Value of DIRIN1 is:""$DIRIN1"
443	OUTPUT="$(grep -ri "$DIGEST" "$DIRIN1")" # Search contents of DIRIN1 for pattern DIGEST, save results to OUTPUT.
444
445	# Output results
446	echo -e "$OUTPUT"
447
448	if [ -v FILEOUT1 ]; then # if FILEOUT1 set, write to this file.
449	vbm "DEBUG:main function detects FILEOUT1 set to:""$FILEOUT1" ;
450	echo -e "$OUTPUT" > "$FILEOUT1" ;
451	vbm "DEBUG:main funtion wrote OUTPUT to:""$FILEOUT1" ;
452	elif [ -v DIROUT1 ]; then # else if DIROUT1 set, set FILEOUT1 to timestamped filename, combine into PATHOUT1, write output to PATHOUT1.
453	vbm "DEBUG:main function detects DIROUT1 set to:""$DIROUT1" ;
454	FILEOUT1="$SCRIPT_TIME_SHORT".."$(basename "$0")".txt
455	PATHOUT1="$DIROUT1"/"$FILEOUT1"
456	echo -e "$OUTPUT" > $PATHOUT1 ;
457	vbm "DEBUG:main function wrote output file to:""$PATHOUT1" ;
458	fi
459
460	# End function
461	vbm "DEBUG:main function ended."
462	return 0; # Function finished.
463	}
464
465	#== Perform work and exit ==
466	main "$@" # Run main function.
467	exit 0;