devscript: add list_url_attributes_on_file

Uses OS X extended attributes (via `xattr`) to find the source
of a downloaded file.

developer/bin/list_url_attributes_on_file

@@ -0,0 +1,84 @@
+#!/bin/bash
+#
+# list_url_attributes_on_file
+#
+
+###
+### settings
+###
+
+set -e                # exit on any uncaught error
+set +o histexpand     # don't expand history expressions
+shopt -s nocasematch  # case-insensitive regular expressions
+
+###
+### global variables
+###
+
+file_arg=''
+attribute_1='com.apple.metadata:kMDItemWhereFroms'
+
+###
+### functions
+###
+
+warn () {
+    local message="$@"
+    message="${message//\\t/$'\011'}"
+    message="${message//\\n/$'\012'}"
+    message="${message%"${message##*[![:space:]]}"}"
+    printf "%s\n" "$message" 1>&2
+}
+
+die () {
+    warn "$@"
+    exit 1
+}
+
+xml_source_1 () {
+    if /usr/bin/xattr -p "$attribute_1" "$file_arg" > /dev/null 2>&1; then
+        /usr/bin/xattr -p "$attribute_1" "$file_arg" | /usr/bin/xxd -r -p | /usr/bin/plutil -convert xml1 -o - -
+    fi
+}
+
+extract_string_elements () {
+    /usr/bin/perl -ne 'print "$1\n" if m{\A\s*<\s*string\s*>(.+?)<\s*/\s*string\s*>\Z}'
+}
+
+###
+### main
+###
+
+_list_url_attributes_on_file () {
+    file_arg="$1"
+    {
+      xml_source_1;
+    } |                \
+    extract_string_elements
+}
+
+# process_args
+if [[ $1 =~ ^-+h(elp)?$ || -z "$1" ]]; then
+    printf "list_url_attributes_on_file <file>
+
+Given a downloaded file, extract possible sources from OS X extended
+attributes, which may be useful in a Cask url stanza.
+
+Currently the only attribute examined is
+
+    com.apple.metadata:kMDItemWhereFroms
+
+This attribute will typically be set if the file was downloaded via a
+browser, but not if the file was downloaded by a CLI utility such as
+curl.
+
+See CONTRIBUTING.md for more information.
+
+"
+    exit
+fi
+
+# dispatch main
+_list_url_attributes_on_file "${@}"
+
+#

doc/CASK_LANGUAGE_REFERENCE.md

@@ -194,6 +194,19 @@ Example of using `:cookies`: [java.rb](../Casks/java.rb)
 
 Example of using `:referer`: [freefilesync.rb](../Casks/freefilesync.rb)
 
+### Difficulty Finding a URL
+
+Web browsers may obscure the direct `url` download location for a variety of
+reasons.  Homebrew-cask supplies a script which can read extended file
+attributes to extract the actual source URL for most files downloaded by a
+browser on OS X.  The script usually emits multiple candidate URLs; you may
+have to test each of them:
+
+```bash
+$ ./developer/bin/list_url_attributes_on_file <file>
+```
+
+
 
 ### Subversion URLs