#!/usr/bin/env bash

###
# Home page: https://github.com/mklement0/fileicon
# Author:   Michael Klement <mklement0@gmail.com> (http://same2u.net)
# Invoke with:
#   --version for version information
#   --help for usage information
###

# --- STANDARD SCRIPT-GLOBAL CONSTANTS

kTHIS_NAME=${BASH_SOURCE##*/}
kTHIS_HOMEPAGE='https://github.com/mklement0/fileicon'
kTHIS_VERSION='v0.3.4' # NOTE: This assignment is automatically updated by `make version VER=<newVer>` - DO keep the 'v' prefix.

unset CDPATH  # To prevent unpredictable `cd` behavior.

# --- Begin: STANDARD HELPER FUNCTIONS

die() { echo "$kTHIS_NAME: ERROR: ${1:-"ABORTING due to unexpected error."}" 1>&2; exit ${2:-1}; }
dieSyntax() { echo "$kTHIS_NAME: ARGUMENT ERROR: ${1:-"Invalid argument(s) specified."} Use -h for help." 1>&2; exit 2; }

# SYNOPSIS
#   openUrl <url>
# DESCRIPTION
#   Opens the specified URL in the system's default browser.
openUrl() {
  local url=$1 platform=$(uname) cmd=()
  case $platform in
    'Darwin') # OSX
      cmd=( open "$url" )
      ;;
    'CYGWIN_'*) # Cygwin on Windows; must call cmd.exe with its `start` builtin
      cmd=( cmd.exe /c start '' "$url " )  # !! Note the required trailing space.
      ;;
    'MINGW32_'*) # MSYS or Git Bash on Windows; they come with a Unix `start` binary
      cmd=( start '' "$url" )
      ;;
    *) # Otherwise, assume a Freedesktop-compliant OS, which includes many Linux distros, PC-BSD, OpenSolaris, ...
      cmd=( xdg-open "$url" )
      ;;
  esac
  "${cmd[@]}" || { echo "Cannot locate or failed to open default browser; please go to '$url' manually." >&2; return 1; }
}

# Prints the embedded Markdown-formatted man-page source to stdout.
printManPageSource() {
  /usr/bin/sed -n -e $'/^: <<\'EOF_MAN_PAGE\'/,/^EOF_MAN_PAGE/ { s///; t\np;}' "$BASH_SOURCE"
}

# Opens the man page, if installed; otherwise, tries to display the embedded Markdown-formatted man-page source; if all else fails: tries to display the man page online.
openManPage() {
  local pager embeddedText
  if ! man 1 "$kTHIS_NAME" 2>/dev/null; then
    # 2nd attempt: if present, display the embedded Markdown-formatted man-page source
    embeddedText=$(printManPageSource)
    if [[ -n $embeddedText ]]; then
      pager='more'
      command -v less &>/dev/null && pager='less' # see if the non-standard `less` is available, because it's preferable to the POSIX utility `more`
      printf '%s\n' "$embeddedText" | "$pager"
    else # 3rd attempt: open the the man page on the utility's website
      openUrl "${kTHIS_HOMEPAGE}/doc/${kTHIS_NAME}.md"
    fi
  fi
}

# Prints the contents of the synopsis chapter of the embedded Markdown-formatted man-page source for quick reference.
printUsage() {
  local embeddedText
  # Extract usage information from the SYNOPSIS chapter of the embedded Markdown-formatted man-page source.
  embeddedText=$(/usr/bin/sed -n -e $'/^: <<\'EOF_MAN_PAGE\'/,/^EOF_MAN_PAGE/!d; /^## SYNOPSIS$/,/^#/{ s///; t\np; }' "$BASH_SOURCE")
  if [[ -n $embeddedText ]]; then
    # Print extracted synopsis chapter - remove backticks for uncluttered display.
    printf '%s\n\n' "$embeddedText" | tr -d '`'
  else # No SYNOPIS chapter found; fall back to displaying the man page.
    echo "WARNING: usage information not found; opening man page instead." >&2
    openManPage
  fi
}

# --- End: STANDARD HELPER FUNCTIONS

# ---  PROCESS STANDARD, OUTPUT-INFO-THEN-EXIT OPTIONS.
case $1 in
  --version)
    # Output version number and exit, if requested.
    ver="v0.3.4"; echo "$kTHIS_NAME $kTHIS_VERSION"$'\nFor license information and more, visit '"$kTHIS_HOMEPAGE"; exit 0
    ;;
  -h|--help)
    # Print usage information and exit.
    printUsage; exit
    ;;
  --man)
    # Display the manual page and exit.
    openManPage; exit
    ;;
  --man-source) # private option, used by `make update-doc`
    # Print raw, embedded Markdown-formatted man-page source and exit
    printManPageSource; exit
    ;;
  --home)
    # Open the home page and exit.
    openUrl "$kTHIS_HOMEPAGE"; exit
    ;;
esac

# --- Begin: SPECIFIC HELPER FUNCTIONS

# NOTE: The functions below operate on byte strings such as the one above:
#       A single single string of pairs of hex digits, without separators or line breaks.
#       Thus, a given byte position is easily calculated: to get byte $byteIndex, use
#         ${byteString:byteIndex*2:2}

# Outputs the specified EXTENDED ATTRIBUTE VALUE as a byte string (a hex dump that is a single-line string of pairs of hex digits, without separators or line breaks, such as "000A2C".
# IMPORTANT: Hex. digits > 9 use UPPPERCASE characters.
#   getAttribByteString <file> <attrib_name>
getAttribByteString() {
  /usr/bin/xattr -px "$2" "$1" | tr -d ' \n'
  return ${PIPESTATUS[0]}
}

# Outputs the specified file's RESOURCE FORK as a byte string (a hex dump that is a single-line string of pairs of hex digits, without separators or line breaks, such as "000a2c".
# IMPORTANT: Hex. digits > 9 use *lowercase* characters.
# Note: This function relies on `xxd -p <file>/..namedfork/rsrc | tr -d '\n'` rather than the conceptually equivalent call,
#       `getAttribByteString <file> com.apple.ResourceFork`, for PERFORMANCE reasons: 
#       getAttribByteString() (defined above) relies on `xattr`, which is a *Python* script [!! seemingly no longer, as of macOS 10.16] 
#       and therefore quite slow due to Python's startup cost.
#   getResourceByteString <file>
getResourceByteString() {
  xxd -p "$1"/..namedfork/rsrc | tr -d '\n'
}

# Patches a single byte in the byte string provided via stdin.
#  patchByteInByteString ndx byteSpec
#   ndx is the 0-based byte index
# - If <byteSpec> has NO prefix: <byteSpec> becomes the new byte
# - If <byteSpec> has prefix '|': "adds" the value: the result of a bitwise OR with the existing byte becomes the new byte
# - If <byteSpec> has prefix '~': "removes" the value: the result of a applying a bitwise AND with the bitwise complement of <byteSpec> to the existing byte becomes the new byte
patchByteInByteString() {
  local ndx=$1 byteSpec=$2 byteVal byteStr charPos op='' charsBefore='' charsAfter='' currByte
  byteStr=$(</dev/stdin)
  charPos=$(( 2 * ndx ))
  # Validat the byte spec.
  case ${byteSpec:0:1} in
    '|')
      op='|'
      byteVal=${byteSpec:1}
      ;;
    '~')
      op='& ~'
      byteVal=${byteSpec:1}
      ;;
    *)
      byteVal=$byteSpec
      ;;
  esac
  [[ $byteVal == [0-9A-Fa-f][0-9A-Fa-f] ]] || return 1
  # Validat the byte index.
  (( charPos > 0 && charPos < ${#byteStr} )) || return 1
  # Determine the target byte, and strings before and after the byte to patch.
  (( charPos >= 2 )) && charsBefore=${byteStr:0:charPos}
  charsAfter=${byteStr:charPos + 2}
  # Determine the new byte value
  if [[ -n $op ]]; then
      currByte=${byteStr:charPos:2}
      printf -v patchedByte '%02X' "$(( 0x${currByte} $op 0x${byteVal} ))"
  else
      patchedByte=$byteSpec
  fi
  printf '%s%s%s' "$charsBefore" "$patchedByte" "$charsAfter"
}

#  hasAttrib <fileOrFolder> <attrib_name>
hasAttrib() {
  /usr/bin/xattr "$1" | /usr/bin/grep -Fqx "$2"
}

#  hasIconData <file>
# Test if the file has a resource fork with icon data in it, or,
# in the case of a .VolumeIcon.icns file, has icon data *as the file contents*
hasIconData() {
  local file=$1
  if [[ $(basename "$file") == $kFILENAME_VOLUMECUSTOMICON ]]; then
    # special file for any folder that is a *volume mountpoint*: has the icon data as the file's *content*
    file "$file" | /usr/bin/grep -Fq ' Mac OS X icon'
  else
    # file itself or special helper file $'Icon\r' for a regular folder: has the icon data *in its resource fork*.
    getResourceByteString "$file" | /usr/bin/grep -Fq "$kMAGICBYTES_ICNS_RESOURCE"
  fi
}

#  isVolumeMountPoint <folder>
isVolumeMountPoint() {
  local folder=$1
  # Must resolve to the physical underlying path, as that is what `mount` shows
  folder=$(cd -P -- "$1"; pwd)
  mount | grep -qF "on $folder (" # !! Is there a more robust way to test for mountpoints?
}

#  getFileWithIconData <fileOrFolder>
# Returns the path of the file that contains the actual icon data, based on whether the target is
#  * a file ... the file path itself
#  * a folder:
#     * regular folder: file $'Icon\r' inside that folder, with the icon data in its resource fork
#     * volume mountpoint: file '.VolumeIcon.icns' inside that folder, with the icon data inside the file.
getFileWithIconData() {
  local fileOrFolder=$1
  if [[ -f $fileOrFolder ]]; then # file
    printf '%s' "$fileOrFolder"
  elif isVolumeMountPoint "$fileOrFolder"; then # volume mountpoint
    printf '%s' "$fileOrFolder/$kFILENAME_VOLUMECUSTOMICON"
  else # regular folder
    printf '%s' "$fileOrFolder/$kFILENAME_FOLDERCUSTOMICON"
  fi
}

#  getTargetType <fileOrFolder>
# Returns a descriptor for the specified target path:
#  * a file ... 'file'
#  * a folder:
#     * regular folder: 'folder'
#     * volume mountpoint: 'volume'
getTargetType() {
  local fileOrFolder=$1
  if [[ -f $fileOrFolder ]]; then # file
    printf 'file'
  elif isVolumeMountPoint "$fileOrFolder"; then # volume mountpoint
    printf 'volume'
  else # regular folder
    printf 'folder'
  fi
}


#  setCustomIcon <fileOrFolder> <imgFile>
# Tips for debugging:
#  * To exercise this function, from the repo dir.:
#      touch /tmp/tf; ./bin/fileicon set /tmp/tf ./test/.fixtures/img.png
# !!??? VOLUME SUPPORT, as of macOS 13.1:
# !!   * While targeting volume root folders is now supported *in principle*, 
# !!     assigning the 'com.apple.FinderInfo' extended attribute to the mountpoint folder 
# !!     typically (always??) fails, so the icon doesn't take effect.
# !!     SetFile -a C <file> also fails - with or without `sudo` - with "ERROR: Unexpected Error. (-5000)  on file: <file>"
# !!     (SetFile -a c <file> clears the custom-icon flag; note that SetFile isn't installed by default and is DEPRECATED: "Tools supporting Carbon development, including /usr/bin/SetFile, were deprecated with Xcode 6.")
# !!     ?? It feels like at *some point* on 13.1 our NFS mount from our NAS seemed to support it, but inexplicably no longer.
# !!   * SOME volumes, even if *network* volumes, support custom icons for their files and folders,
# !!     such as a SMB mount.
# !!     ?? Our NFS mount from our NAS seemed to support that *for a while* on 13.1, but inexplicably no longer.
setCustomIcon() {

  local fileOrFolder=$1 imgFile=$2 fileWithIconData

  [[ (-f $fileOrFolder || -d $fileOrFolder) && -r $fileOrFolder && -w $fileOrFolder ]] || return 3
  [[ -f $imgFile ]] || return 3

  # !! Sadly, Apple decided to remove the `-i` / `--addicon` option from the `sips` utility.
  # !! Therefore, use of *Cocoa* is required, which we do *via AppleScript* and its ObjC bridge,
  # !! which has the added advantage of creating a *set* of icons from the source image, scaling as necessary
  # !!  to create a 512 x 512 top resolution icon (whereas sips -i created a single, 128 x 128 icon).
  # !! Thanks:
  # !!  * https://apple.stackexchange.com/a/161984/28668 (Python original)
  # !!  * @scriptingosx (https://github.com/mklement0/fileicon/issues/32#issuecomment-1074124748) (AppleScript-ObjC version)
  # !! Note: We moved from Python to AppleScript when the system Python was removed in macOS 12.3

  # !! Note: The setIcon method seemingly always indicates True, even with invalid image files, so
  # !!       we attempt no error handling in the AppleScript code, and instead verify success explicitly later.
  osascript <<EOF >/dev/null || die
    use framework "Cocoa"

    set sourcePath to "$imgFile"
    set destPath to "$fileOrFolder"

    set imageData to (current application's NSImage's alloc()'s initWithContentsOfFile:sourcePath)
    (current application's NSWorkspace's sharedWorkspace()'s setIcon:imageData forFile:destPath options:2)
EOF

  # Fully verify that everything worked as intended.
  # Unfortunately, several things can go wrong.
  testForCustomIcon "$targetFileOrFolder" 2>/dev/null && return 0
  ec=$?

  if (( ec == 1 )); then
    cat >&2 <<EOF
Failed to assign a custom icon.
Typically, this means that the specified image file is not supported or corrupt: $imgFile
Supported image formats: jpeg | tiff | png | gif | jp2 | pict | bmp | qtif| psd | sgi | tga
EOF
  elif ((ec == 2 )); then
    cat >&2 <<EOF
Failed to set the custom-icon flag in the 'com.apple.FinderInfo' extended attribute of: $targetFileOrFolder
Typically, this means that you're targeting a volume itself or a file or folder on a volume that doesn't support custom icons.
Rerun with "rm" to clean up.
EOF
  elif ((ec == 3 )); then
    cat >&2 <<EOF
The custom-icon flag in the 'com.apple.FinderInfo' extended attribute of: $imgFile
was successfully set, but, unexpectedly, the associated icon data was not.
Rerun with "rm" to clean up.
EOF
  fi

  return $ec

}

#  getCustomIcon <fileOrFolder> <icnsOutFile>
getCustomIcon() {

  local fileOrFolder=$1 icnsOutFile=$2 byteStr fileWithIconData byteOffset byteCount

  [[ (-f $fileOrFolder || -d $fileOrFolder) && -r $fileOrFolder ]] || return 3

  # Determine what file to extract the resource fork from.
  if [[ -d $fileOrFolder ]]; then

    fileWithIconData=$(getFileWithIconData "$fileOrFolder")
    [[ -f $fileWithIconData ]] || { echo "Custom-icon file does not exist: '${fileWithIconData/$'\r'/\\r}'" >&2; return 1; }

    if [[ $(basename "$fileWithIconData") == $kFILENAME_VOLUMECUSTOMICON ]]; then
      # !! Volume mount points are an exception: their helper file contains the icon data as the file's *content*
      # !! rather than in a *resource fork*; therefore, simply *copying* the file's content is enough.
      # !! However, we use `cat` rather than `cp`, so as not to also copy the extended attributes.
      cat "$fileWithIconData" > "$icnsOutFile" || die
      return 0
    fi
    # Otherwise: proceed below to extract the data from the resource fork.

  else
    fileWithIconData=$fileOrFolder
  fi

  # Determine (based on format description at https://en.wikipedia.org/wiki/Apple_Icon_Image_format):
  # - the byte offset at which the icns resource begins, via the magic literal identifying an icns resource
  # - the length of the resource, which is encoded in the 4 bytes right after the magic literal.
  read -r byteOffset byteCount < <(getResourceByteString "$fileWithIconData" | /usr/bin/awk -F "$kMAGICBYTES_ICNS_RESOURCE" '{ printf "%s %d", (length($1) + 2) / 2, "0x" substr($2, 0, 8) }')
  (( byteOffset > 0 && byteCount > 0 )) || { echo "Custom-icon file contains no icons resource: '${fileWithIconData/$'\r'/\\r}'" >&2; return 1; }

  # Extract the actual bytes using tail and head and save them to the output file.
  tail -c "+${byteOffset}" "$fileWithIconData/..namedfork/rsrc" | head -c $byteCount > "$icnsOutFile" || return

  return 0
}

#  removeCustomIcon <fileOrFolder>
removeCustomIcon() {

  local fileOrFolder=$1 byteStr

  [[ (-f $fileOrFolder || -d $fileOrFolder) && -r $fileOrFolder && -w $fileOrFolder ]] || return 1

  # Step 1: Turn off the custom-icon flag in the com.apple.FinderInfo extended attribute.
  #         Note: Using SetFile -a c <file> is tempting, but SetFile doesn't come with macOS by default (part of XCode CLI package)
  if hasAttrib "$fileOrFolder" com.apple.FinderInfo; then
    byteStr=$(getAttribByteString "$fileOrFolder" com.apple.FinderInfo | patchByteInByteString $kFI_BYTEOFFSET_CUSTOMICON '~'$kFI_VAL_CUSTOMICON) || return
    if [[ $byteStr == "$kFI_BYTES_BLANK" ]]; then # All bytes cleared? Remove the entire attribute.
      /usr/bin/xattr -d com.apple.FinderInfo "$fileOrFolder"
    else # Update the attribute.
      /usr/bin/xattr -wx com.apple.FinderInfo "$byteStr" "$fileOrFolder" || return
    fi
  fi

  # Step 2: Remove the resource fork (if target is a file) / hidden file with custom icon (if target is a folder)
  if [[ -d $fileOrFolder ]]; then # folder or volume -> remove the special file inside it.
    rm -f "$(getFileWithIconData "$fileOrFolder")"
  else # file -> remove the resource fork
    if hasIconData "$fileOrFolder"; then
      /usr/bin/xattr -d com.apple.ResourceFork "$fileOrFolder"
    fi
  fi

  return 0
}

#  testForCustomIcon <fileOrFolder>
testForCustomIcon() {

  local fileOrFolder=$1 byteStr byteVal fileWithIconData hasCustomIconFlag hasIconData 

  [[ (-f $fileOrFolder || -d $fileOrFolder) && -r $fileOrFolder ]] || return 3

  # Step 1: Check if the com.apple.FinderInfo extended attribute has the custom-icon
  #         flag set. This applies to *all* target types.
  byteStr=$(getAttribByteString "$fileOrFolder" com.apple.FinderInfo 2>/dev/null) #  || return 1
  byteVal=${byteStr:2*kFI_BYTEOFFSET_CUSTOMICON:2}
  hasCustomIconFlag=$(( byteVal & kFI_VAL_CUSTOMICON ))

  fileWithIconData=$(getFileWithIconData "$fileOrFolder")
  # Step 2: Check if there's actual icon data present,
  #         via the resource fork of the file or the folder's helper file or the file content of a
  #         volume mountpoint's helper file (./.VolumeIcon.icns)
  hasIconData "$fileWithIconData" 2>/dev/null && hasIconData=1 || hasIconData=0

  # Provide a specific exit code reflecting the state.
  # !! This is used by setCustomIcon()
  if (( hasCustomIconFlag && hasIconData )); then
    return 0   # has custom icon
  elif (( ! hasCustomIconFlag && ! hasIconData  )); then
    return 1   # typical case of file/folder NOT having a custom icon
  elif (( ! hasCustomIconFlag )); then
    echo "WARNING: Custom-icon data is present, but the 'com.apple.FinderInfo' extended attribute isn't set for $(getTargetType "$fileOrFolder") '$fileOrFolder'"  >&2
    return 2   # broken state: has icons, but no custom flag
  else # (( ! hasIconData )) 
    echo "WARNING: While the 'com.apple.FinderInfo' extended attribute is set for $(getTargetType "$fileOrFolder") '$fileOrFolder', associated icon data is missing."  >&2
    return 3   # broken state: has custom flag, but no icons
  fi

}

# --- End: SPECIFIC HELPER FUNCTIONS

# --- Begin: SPECIFIC SCRIPT-GLOBAL CONSTANTS

kFILENAME_FOLDERCUSTOMICON=$'Icon\r' # the helper file for regular folders, with the actual icon image data in its *resource fork*
kFILENAME_VOLUMECUSTOMICON='.VolumeIcon.icns' # the helper file for volume mountpoints, with the actual icon image data in the file's *content*.

# The blank hex dump form (single string of pairs of hex digits) of the 32-byte data structure stored in extended attribute
# com.apple.FinderInfo
kFI_BYTES_BLANK='0000000000000000000000000000000000000000000000000000000000000000'

# [UPDATE]
#  * THIS CONSTANT ISN'T USED ANYMORE.
#  * Also, on macOS 13 (Ventura): seemingly, the Icon\r file's com.apple.FinderInfo extended attribute is now 
#    SIMPLER: where the folder itself has 0x4 in its 9th byte, Icon\r now has 0x40
# [ORIGINAL COMMENT]
# The hex dump form of the full 32 bytes that Finder assigns to the hidden $'Icon\r'
# file whose com.apple.ResourceFork extended attribute contains the icon image data for the enclosing folder.
# The first 8 bytes spell out the magic literal 'iconMACS'; they are followed by the invisibility flag, '40' in the 9th byte, and '10' (?? specifying what?)
# in the 10th byte.
# NOTE: Since file $'Icon\r' serves no other purpose than to store the icon, it is
#       safe to simply assign all 32 bytes blindly, without having to worry about
#       preserving existing values.
# kFI_BYTES_CUSTOMICONFILEFORFOLDER='69636F6E4D414353401000000000000000000000000000000000000000000000'

# The hex dump form of the magic literal inside a resource fork that marks the
# start of an icns (icons) resource.
# NOTE: This will be used with `xxd -p .. | tr -d '\n'`, which uses *lowercase*
#       hex digits, so we must use lowercase here.
kMAGICBYTES_ICNS_RESOURCE='69636e73'

# The byte values (as hex strings) of the flags at the relevant byte position
# of the com.apple.FinderInfo extended attribute.
kFI_VAL_CUSTOMICON='04'

# The custom-icon-flag byte offset in the com.apple.FinderInfo extended attribute.
kFI_BYTEOFFSET_CUSTOMICON=8

# --- End: SPECIFIC SCRIPT-GLOBAL CONSTANTS

# Option defaults.
force=0 quiet=0

# --- Begin: OPTIONS PARSING
allowOptsAfterOperands=1 operands=() i=0 optName= isLong=0 prefix= optArg= haveOptArgAttached=0 haveOptArgAsNextArg=0 acceptOptArg=0 needOptArg=0
while (( $# )); do
  if [[ $1 =~ ^(-)[a-zA-Z0-9]+.*$ || $1 =~ ^(--)[a-zA-Z0-9]+.*$ ]]; then # an option: either a short option / multiple short options in compressed form or a long option
    prefix=${BASH_REMATCH[1]}; [[ $prefix == '--' ]] && isLong=1 || isLong=0
    for (( i = 1; i < (isLong ? 2 : ${#1}); i++ )); do
        acceptOptArg=0 needOptArg=0 haveOptArgAttached=0 haveOptArgAsNextArg=0 optArgAttached= optArgOpt= optArgReq=
        if (( isLong )); then # long option: parse into name and, if present, argument
          optName=${1:2}
          [[ $optName =~ ^([^=]+)=(.*)$ ]] && { optName=${BASH_REMATCH[1]}; optArgAttached=${BASH_REMATCH[2]}; haveOptArgAttached=1; }
        else # short option: *if* it takes an argument, the rest of the string, if any, is by definition the argument.
          optName=${1:i:1}; optArgAttached=${1:i+1}; (( ${#optArgAttached} >= 1 )) && haveOptArgAttached=1
        fi
        (( haveOptArgAttached )) && optArgOpt=$optArgAttached optArgReq=$optArgAttached || { (( $# > 1 )) && { optArgReq=$2; haveOptArgAsNextArg=1; }; }
        # ---- BEGIN: CUSTOMIZE HERE
        case $optName in
          f|force)
            force=1
            ;;
          q|quiet)
            quiet=1
            ;;
          *)
            dieSyntax "Unknown option: ${prefix}${optName}."
            ;;
        esac
        # ---- END: CUSTOMIZE HERE
        (( needOptArg )) && { (( ! haveOptArgAttached && ! haveOptArgAsNextArg )) && dieSyntax "Option ${prefix}${optName} is missing its argument." || (( haveOptArgAsNextArg )) && shift; }
        (( acceptOptArg || needOptArg )) && break
    done
  else # an operand
    if [[ $1 == '--' ]]; then
      shift; operands+=( "$@" ); break
    elif (( allowOptsAfterOperands )); then
      operands+=( "$1" ) # continue
    else
      operands=( "$@" )
      break
    fi
  fi
  shift
done
(( "${#operands[@]}" > 0 )) && set -- "${operands[@]}"; unset allowOptsAfterOperands operands i optName isLong prefix optArgAttached haveOptArgAttached haveOptArgAsNextArg acceptOptArg needOptArg
# --- End: OPTIONS PARSING: "$@" now contains all operands (non-option arguments).

# Validate the command
cmd=$(printf %s "$1" | tr '[:upper:]' '[:lower:]') # translate to all-lowercase - we don't want the command name to be case-sensitive
[[ $cmd == 'remove' ]] && cmd='rm'  # support alias 'remove' for 'rm'
case $cmd in
  set|get|rm|remove|test)
    shift
    ;;
  *)
    dieSyntax "Unrecognized or missing command: '$cmd'."
    ;;
esac

# Validate file operands
(( $# > 0 )) || dieSyntax "Missing operand(s)."

# Target file or folder.
targetFileOrFolder=$1 imgFile= outFile=
[[ -f $targetFileOrFolder || -d $targetFileOrFolder ]] || die "Target not found or neither file nor folder: '$targetFileOrFolder'"
# Make sure the target file/folder is readable, and, unless only getting or testing for an icon are requested, writeable too.
[[ -r $targetFileOrFolder ]] || die "Cannot access '$targetFileOrFolder': you do not have read permissions."
[[ $cmd == 'test' || $cmd == 'get' || -w $targetFileOrFolder ]] || die "Cannot modify '$targetFileOrFolder': you do not have write permissions."

# Other operands, if any, and their number.
valid=0
case $cmd in
  'set')
    (( $# <= 2 )) && {
      valid=1
      # If no image file was specified, the target file is assumed to be an image file itself whose image should be self-assigned as an icon.
      (( $# == 2 )) && imgFile=$2 || imgFile=$1
      # !! Apparently, a regular file is required - a process subsitution such 
      # !! as `<(base64 -D <encoded-file.txt)` is NOT supported by NSImage.initWithContentsOfFile()
      [[ -f $imgFile && -r $imgFile ]] || die "Image file not found or not a (readable) regular file: $imgFile"
    }
    ;;
  'rm'|'test')
    (( $# == 1 )) && valid=1
    ;;
  'get')
    (( $# == 1 || $# == 2 )) && {
      valid=1
      outFile=$2
      if [[ $outFile == '-' ]]; then
        outFile=/dev/stdout
      else
        # By default, we extract to a file with the same filename root + '.icns'
        # in the current folder.
        [[ -z $outFile ]] && outFile=${targetFileOrFolder##*/}
        # Unless already specified, we append '.icns' to the output filename.
        mustReset=$(shopt -q nocasematch; echo $?); shopt -s nocasematch
        [[ $outFile =~ \.icns$ ]] || outFile+='.icns'
        (( mustReset )) && shopt -u nocasematch
        [[ -e $outFile && $force -eq 0 ]] && die "Output file '$outFile' already exists. To force its replacement, use -f."
      fi
    }
    ;;
esac
(( valid )) || dieSyntax "Unexpected number of operands."

case $cmd in
  'set')
    setCustomIcon "$targetFileOrFolder" "$imgFile" || die
    (( quiet )) || echo "Custom icon assigned to $(getTargetType "$targetFileOrFolder") '$targetFileOrFolder' based on '$imgFile'."
    ;;
  'rm')
    removeCustomIcon "$targetFileOrFolder" || die
    (( quiet )) || echo "Custom icon (if any) removed from $(getTargetType "$targetFileOrFolder") '$targetFileOrFolder'."
    ;;
  'get')
    getCustomIcon "$targetFileOrFolder" "$outFile" || die
    (( quiet )) || { [[ $outFile != '/dev/stdout' ]] && echo "Custom icon extracted to '$outFile'."; }
    exit 0
    ;;
  'test')
    if (( quiet )); then
      testForCustomIcon "$targetFileOrFolder" 2>/dev/null
    else
      testForCustomIcon "$targetFileOrFolder" # This may issue warnings.
    fi
    ec=$?
    if (( ! quiet )); then
      echo "$( (( ec == 0 )) && printf 'HAS' || printf 'Has NO' ) custom icon: $(getTargetType "$targetFileOrFolder") '$targetFileOrFolder'"
    fi
    exit $ec
    ;;
  *)
    die "DESIGN ERROR: unanticipated command: $cmd"
    ;;
esac

exit 0

####
# MAN PAGE MARKDOWN SOURCE
#  - Place a Markdown-formatted version of the man page for this script
#    inside the here-document below.
#    The document must be formatted to look good in all 3 viewing scenarios:
#     - as a man page, after conversion to ROFF with marked-man
#     - as plain text (raw Markdown source)
#     - as HTML (rendered Markdown)
#  Markdown formatting tips:
#   - GENERAL
#     To support plain-text rendering in the terminal, limit all lines to 80 chars.,
#     and, for similar rendering as HTML, *end every line with 2 trailing spaces*.
#   - HEADINGS
#     - For better plain-text rendering, leave an empty line after a heading
#       marked-man will remove it from the ROFF version.
#     - The first heading must be a level-1 heading containing the utility
#       name and very brief description; append the manual-section number
#       directly to the CLI name; e.g.:
#         # foo(1) - does bar
#     - The 2nd, level-2 heading must be '## SYNOPSIS' and the chapter's body
#       must render reasonably as plain text, because it is printed to stdout
#       when  `-h`, `--help` is specified:
#         Use 4-space indentation without markup for both the syntax line and the
#         block of brief option descriptions; represent option-arguments and operands
#         in angle brackets; e.g., '<foo>'
#     - All other headings should be level-2 headings in ALL-CAPS.
#   - TEXT
#      - Use NO indentation for regular chapter text; if you do, it will
#        be indented further than list items.
#      - Use 4-space indentation, as usual, for code blocks.
#      - Markup character-styling markup translates to ROFF rendering as follows:
#         `...` and **...** render as bolded (red) text
#         _..._ and *...* render as word-individually underlined text
#   - LISTS
#      - Indent list items by 2 spaces for better plain-text viewing, but note
#        that the ROFF generated by marked-man still renders them unindented.
#      - End every list item (bullet point) itself with 2 trailing spaces too so
#        that it renders on its own line.
#      - Avoid associating more than 1 paragraph with a list item, if possible,
#        because it requires the following trick, which hampers plain-text readability:
#        Use '&nbsp;<space><space>' in lieu of an empty line.
####
: <<'EOF_MAN_PAGE'
# fileicon(1) - manage file and folder custom icons

## SYNOPSIS

Manage custom icons for files and folders on macOS.  

SET a custom icon for a file or folder:

    fileicon set      <fileOrFolder> [<imageFile>]

REMOVE a custom icon from a file or folder:

    fileicon rm       <fileOrFolder>

GET a file or folder's custom icon:

    fileicon get [-f] <fileOrFolder> [<iconOutputFile>]

    -f ... force replacement of existing output file

TEST if a file or folder has a custom icon:

    fileicon test     <fileOrFolder>

All forms: option -q silences status output.

Standard options: `--help`, `--man`, `--version`, `--home`

## DESCRIPTION

`<fileOrFolder>` is the file or folder whose custom icon should be managed.  
Note that symlinks are followed to their (ultimate target); that is, you  
can only assign custom icons to regular files and folders, not to symlinks  
to them.

`<imageFile>` can be an image file of any format supported by the system.  
It is converted to an icon and assigned to `<fileOrFolder>`.  
If you omit `<imageFile>`, `<fileOrFolder>` must itself be an image file whose
image should become its own icon.

`<iconOutputFile>` specifies the file to extract the custom icon to:  
Defaults to the filename of `<fileOrFolder>` with extension `.icns` appended.  
If a value is specified, extension `.icns` is appended, unless already present.  
Either way, extraction fails if the target file already exists; use `-f` to  
override.  
Specify `-` to extract to stdout.  

Command `test` signals with its exit code whether a custom icon is set (0)  
or not (1); any other exit code signals an unexpected error.

**Options**:

  * `-f`, `--force`  
    When getting (extracting) a custom icon, forces replacement of the  
    output file, if it already exists.

  * `-q`, `--quiet`  
    Suppresses output of the status information that is by default output to  
    stdout.  
    Note that errors and warnings are still printed to stderr.

## NOTES

Custom icons are stored in extended attributes of the HFS+ filesystem.  
Thus, if you copy files or folders to a different filesystem that doesn't  
support such attributes, custom icons are lost; for instance, custom icons  
cannot be stored in a Git repository.

To determine if a give file or folder has extended attributes, use  
`ls -l@ <fileOrFolder>`.

When setting an image as a custom icon, a set of icons with several resolutions  
is created, with the highest resolution at 512 x 512 pixels.

All icons created are square, so images with a non-square aspect ratio will  
appear distorted; for best results, use square imges.

## STANDARD OPTIONS

All standard options provide information only.

* `-h, --help`  
  Prints the contents of the synopsis chapter to stdout for quick reference.

* `--man`  
  Displays this manual page, which is a helpful alternative to using `man`, 
  if the manual page isn't installed.

* `--version`  
  Prints version information.
  
* `--home`  
  Opens this utility's home page in the system's default web browser.

## LICENSE

For license information and more, visit the home page by running  
`fileicon --home`

EOF_MAN_PAGE