# /path/to/fileIndex.src
function index {
    local startSeconds="$(date +'%s')"
    local startNanos="$(date +'%N')"
    local fileName='.index'
    if [ -z "${@}" ]; then
        # @TODO: Add error handling for cases where the index file cannot be created or written (e.g., due to insufficient permissions).
        echo
        echo "indexing:"
        # @TODO: handling of passed-in filepaths + multiples
        echo -e ">\t$(pwd)"
        if [ ! -f "${fileName}" ]; then
			lt
				touch "${fileName}" #&& \
#					lt "Location not currently indexed, created an empty index at '${fileName}' in '$(pwd)'" || \
#					lt "Error: Could not create file index, please debug!"
	        if [ ! -w "${fileName}" ]; then
	            echo "Error: Permission denied. Cannot write to the index file." >&2
	            return 1
	        fi
			fi
			
        if [ -f "${fileName}" ]; then
            # using the first character of the filename to delimit the `cut` for determining number of lines
				local fileDelimiter=${fileName:0:1}
            local fileLines=$(wc -l "${fileName}" | cut -d"${fileDelimiter}" -f1 | sed 's/ //g')
#            lt "file delimited: '${fileDelimiter}'"
#            lt "file lines: '${fileLines}'"
        fi
        local secondsPassed="$(($(date +'%s') - ${startSeconds}))"
        local nanosPassed="$(($(date +'%N') - ${startNanos}))"
        if [ "${nanosPassed}" -lt 0 ]; then
            nanosPassed="$((1 - ${nanosPassed}))"
        fi
        # @TODO there's probably a way to use pure 'find' without invoking 'grep', and today is too short for delving that :-/
        find . | egrep -v "/.git/|/.atom/|/.cargo/|/.*~" >"${fileName}" && \
			# @TODO - set up an array for the exclusions and build the full command string programmatically.
			echo "Indexing completed in '${secondsPassed}.${nanosPassed}' seconds. "
            echo "The index previously contained '${fileLines}' lines.)"
            unset fileLines
			local fileLines=$(wc -l "${fileName}" | cut -d"${fileDelimiter}" -f1 | sed 's/ //g')
			lt
			lt "The index now contains '${fileLines}' total lines."
			lt
    else
        echo "input was '${@}'"
    fi
}