add support for using existing Dash.app docsets

README.md

@@ -23,6 +23,8 @@ which aptly characterizes the terminal environment where everything is text.
 
 * Keep [Dash] docsets anywhere you like.
 
+* Access existing docset library managed by Dash.app (MacOS only).
+
 ### Preview
 
 Watch the "[dasht in a terminal](https://vimeo.com/159462598)"
@@ -61,6 +63,10 @@ Optional:
 
 * [gawk] for dasht-server(1) search engine
 
+[Dash.app]: https://kapeli.com/dash
+
+* [Dash.app] to let the Dash MacOS app manage your docsets
+
 Development:
 
 [binman]: https://sunaku.github.io/binman/
@@ -91,6 +97,15 @@ Manually, on any system:
 
         export MANPATH=location_where_you_cloned_or_downloaded_dasht/man:$MANPATH
 
+### Dash.app integration
+
+Set `DASHT_USE_DASH_APP=true` to use the docsets stored by Dash.app on your
+machine. This makes `dasht` act like a read-only client for your Dash.app
+docset library-- all docset management commands (`install`, `update`, `remove`)
+are disabled. This also provides access to an expanded library of docsets, as
+at present `dasht` itself can only download and/or build a subset of the
+docsets available through Dash.app.
+
 ### Vim integration
 
 Use the [vim-dasht](https://github.com/sunaku/vim-dasht) plugin for (Neo)Vim.
@@ -142,6 +157,11 @@ which defines the filesystem location where download links are cached.
 If undefined, its value is assumed to be `$XDG_CACHE_HOME/dasht/`
 or, if `XDG_CACHE_HOME` is also undefined, `$HOME/.cache/dasht/`.
 
+Set `DASHT_USE_DASH_APP=true` to enable Dash.app integration (MacOS only). See
+[Dash.app integration](#dashapp-integration) for details. Note that this will
+also change the default setting of `DASHT_DOCSETS_DIR` to `~/Libary/Application
+Support/Dash` (where Dash.app docsets are stored by default).
+
 ## Development
 
 If you make changes to the embedded manual pages found in the comment headers

bin/dasht

@@ -48,6 +48,11 @@
 #   If undefined, its value is assumed to be `$XDG_DATA_HOME/dasht/docsets/`
 #   or, if `XDG_DATA_HOME` is undefined, `$HOME/.local/share/dasht/docsets/`.
 #
+# `DASHT_USE_DASH_APP`
+#   Set to "true" to use Dash.app's (MacOS only) docset library. Disables
+#   docset management commands (install, remove, update). Also changes the
+#   default `DASHT_DOCSETS_DIR` to "~/Library/Application Support/Dash".
+#
 # ## EXIT STATUS
 #
 # 44
@@ -67,11 +72,29 @@
 # Written in 2016 by Suraj N. Kurapati <https://github.com/sunaku/dasht>
 # Distributed under the terms of the ISC license (refer to README file).
 
+: ${DASHT_USE_DASH_APP:=false}
+if $DASHT_USE_DASH_APP; then
+  : ${DASHT_DOCSETS_DIR:="/Users/smackesey/Library/Application Support/Dash"}
+else
+  : ${DASHT_DOCSETS_DIR:=${XDG_DATA_HOME:-$HOME/.local/share}/dasht/docsets}
+fi
+
 if test $# -gt 0; then
   pattern=$1
   shift
 fi
 
+# Ensure any docsets we are accessing from the Dash.app library have had their
+# documents extracted. Dash.app leaves the documents in the tarball by default.
+if $DASHT_USE_DASH_APP; then
+  dasht-docsets "$@" | while read docset; do
+    root=("$DASHT_DOCSETS_DIR/"*/*"/${docset}.docset")
+    if ! test -d "${root}/Contents/Resources/Documents"; then
+      dasht-docsets-extract "$root/Contents/Resources/tarix.tgz"
+    fi
+  done
+fi
+
 count=$(dasht-docsets "$@" | wc -l)
 if test $count -eq 0; then
   # notify user when no docsets are installed so they can go install them
@@ -80,6 +103,7 @@ if test $count -eq 0; then
 fi
 
 trap 'exit 44' USR1 # exit with a nonzero status when no results are found
+
 if ! dasht-query-html "$pattern" "$@"; then
   # notify user when no results are found so they can refine their search
   echo "dasht: '$pattern' not found in $count docsets matching '${*:-.*}'" >&2

bin/dasht-docsets

@@ -34,6 +34,11 @@
 #   If undefined, its value is assumed to be `$XDG_DATA_HOME/dasht/docsets/`
 #   or, if `XDG_DATA_HOME` is undefined, `$HOME/.local/share/dasht/docsets/`.
 #
+# `DASHT_USE_DASH_APP`
+#   Set to "true" to use Dash.app's (MacOS only) docset library. Disables
+#   docset management commands (install, remove, update). Also changes the
+#   default `DASHT_DOCSETS_DIR` to "~/Library/Application Support/Dash".
+#
 # ## SEE ALSO
 #
 # dasht-docsets-install(1), dasht-docsets-update(1), dasht-docsets-remove(1),
@@ -46,9 +51,22 @@
 # Written in 2016 by Suraj N. Kurapati <https://github.com/sunaku/dasht>
 # Distributed under the terms of the ISC license (refer to README file).
 
-: ${DASHT_DOCSETS_DIR:=${XDG_DATA_HOME:-$HOME/.local/share}/dasht/docsets}
+: ${DASHT_USE_DASH_APP:=false}
+if $DASHT_USE_DASH_APP; then
+  : ${DASHT_DOCSETS_DIR:="/Users/smackesey/Library/Application Support/Dash"}
+else
+  : ${DASHT_DOCSETS_DIR:=${XDG_DATA_HOME:-$HOME/.local/share}/dasht/docsets}
+fi
 
-ls "$DASHT_DOCSETS_DIR" |
+{
+  if $DASHT_USE_DASH_APP; then
+    for x in "$DASHT_DOCSETS_DIR"/*/*/*.docset; do
+      basename "$x"
+    done
+  else
+    ls "$DASHT_DOCSETS_DIR"
+  fi
+} | 
 sed -n 's/\.docset$//p' |
 sort -u |
 grep -E -i "$(IFS='|'; echo "$*")"

bin/dasht-docsets-extract

@@ -39,6 +39,16 @@
 #   If undefined, its value is assumed to be `$XDG_DATA_HOME/dasht/docsets/`
 #   or, if `XDG_DATA_HOME` is undefined, `$HOME/.local/share/dasht/docsets/`.
 #
+# `DASHT_USE_DASH_APP`
+#   Set to "true" to use Dash.app's (MacOS only) docset library. Disables
+#   docset management commands (install, remove, update). Also changes the
+#   default `DASHT_DOCSETS_DIR` to "~/Library/Application Support/Dash".
+#
+# ## EXIT STATUS
+#
+# 46
+#   Command was not executed because `DASHT_USE_DASH_APP` is set.
+#
 # ## SEE ALSO
 #
 # dasht-docsets-install(1), dasht-docsets-update(1), [Dash]
@@ -50,32 +60,50 @@
 # Written in 2016 by Suraj N. Kurapati <https://github.com/sunaku/dasht>
 # Distributed under the terms of the ISC license (refer to README file).
 
-: ${DASHT_DOCSETS_DIR:=${XDG_DATA_HOME:-$HOME/.local/share}/dasht/docsets}
+: ${DASHT_USE_DASH_APP:=false}
+if $DASHT_USE_DASH_APP; then
+  : ${DASHT_DOCSETS_DIR:="/Users/smackesey/Library/Application Support/Dash"}
+else
+  : ${DASHT_DOCSETS_DIR:=${XDG_DATA_HOME:-$HOME/.local/share}/dasht/docsets}
+fi
 
 test $# -gt 0
 for tgz; do
-  want="$DASHT_DOCSETS_DIR/$(basename "$tgz" .tgz).docset"
-  have="$DASHT_DOCSETS_DIR/$(tar -t -f "$tgz" -z | head -1 | sed 's|/.*||')"
 
-  # for dasht-docsets-update(1), the extracted directory will already exist
-  # with the correct name, but we need to temporarily rename it back to the
-  # wrong name so that the archive extraction below can update its contents
-  # in place, rather than extracting out to a new (and different) directory
-  test "$have" = "$want" -o ! -e "$want" || mv "$want" "$have"
+  # Extract Documents dir inside existing Dash.app docset directory. Dash.app
+  # leaves the Documents inside the tarball tarix.tgz by default.
+  if $DASHT_USE_DASH_APP; then
+    pushd "$(dirname "$tgz")" >/dev/null
+    docset_name="$(basename "$(dirname "$(dirname "$(dirname "$tgz")")")")"
+    tar -x -f "$tgz" "$docset_name/Contents/Resources/Documents"
+    mv "$docset_name/Contents/Resources/Documents" .
+    rm -r "$docset_name"
+    popd >/dev/null
+  else
+
+    want="$DASHT_DOCSETS_DIR/$(basename "$tgz" .tgz).docset"
+    have="$DASHT_DOCSETS_DIR/$(tar -t -f "$tgz" -z | head -1 | sed 's|/.*||')"
+
+    # for dasht-docsets-update(1), the extracted directory will already exist
+    # with the correct name, but we need to temporarily rename it back to the
+    # wrong name so that the archive extraction below can update its contents
+    # in place, rather than extracting out to a new (and different) directory
+    test "$have" = "$want" -o ! -e "$want" || mv "$want" "$have"
 
-  # extract the archive; the extracted directory's path is defined by $have
-  tar -v -C "$DASHT_DOCSETS_DIR" -x -f "$tgz" -z
+    # extract the archive; the extracted directory's path is defined by $have
+    tar -v -C "$DASHT_DOCSETS_DIR" -x -f "$tgz" -z
 
-  # rename the extracted directory to have the same rootname as the archive
-  test "$have" = "$want" || mv "$have" "$want"
+    # rename the extracted directory to have the same rootname as the archive
+    test "$have" = "$want" || mv "$have" "$want"
 
-  # remove any stale files that were left behind by the previous extraction
-  { find "$want" -print
-    tar -t -f "$tgz" -z | sed -e "s|^[^/]*|$want|" -e 's|/$||'
-  } | sort -r | uniq -c | sed -n 's/^ *1 //p' | while read -r arg; do
-      if test -d "$arg"
-      then rmdir "$arg"
-      else rm -v "$arg"
-      fi
-  done
+    # remove any stale files that were left behind by the previous extraction
+    { find "$want" -print
+      tar -t -f "$tgz" -z | sed -e "s|^[^/]*|$want|" -e 's|/$||'
+    } | sort -r | uniq -c | sed -n 's/^ *1 //p' | while read -r arg; do
+        if test -d "$arg"
+        then rmdir "$arg"
+        else rm -v "$arg"
+        fi
+    done
+  fi
 done

bin/dasht-docsets-install

@@ -44,6 +44,16 @@
 #   If undefined, its value is assumed to be `$XDG_CACHE_HOME/dasht/`
 #   or, if `XDG_CACHE_HOME` is also undefined, `$HOME/.cache/dasht/`.
 #
+# `DASHT_USE_DASH_APP`
+#   Set to "true" to use Dash.app's (MacOS only) docset library. Disables
+#   docset management commands (install, remove, update). Also changes the
+#   default `DASHT_DOCSETS_DIR` to "~/Library/Application Support/Dash".
+#
+# ## EXIT STATUS
+#
+# 46
+#   Command was not executed because `DASHT_USE_DASH_APP` is set.
+#
 # ## SEE ALSO
 #
 # dasht-docsets-extract(1), dasht-docsets-update(1), dasht-docsets-remove(1),
@@ -58,6 +68,13 @@
 
 : ${DASHT_DOCSETS_DIR:=${XDG_DATA_HOME:-$HOME/.local/share}/dasht/docsets}
 : ${DASHT_CACHE_DIR:=${XDG_CACHE_HOME:-$HOME/.cache}/dasht}
+: ${DASHT_USE_DASH_APP:=false}
+
+if $DASHT_USE_DASH_APP; then
+  echo "extract, install, remove, and update operations are disabled when \
+    DASHT_USE_DASH_APP=true." >&2
+  exit 46
+fi
 
 test "$1" = '-f' -o "$1" = '--force' && force=1 && shift || unset force
 

bin/dasht-docsets-remove

@@ -39,6 +39,16 @@
 #   If undefined, its value is assumed to be `$XDG_DATA_HOME/dasht/docsets/`
 #   or, if `XDG_DATA_HOME` is undefined, `$HOME/.local/share/dasht/docsets/`.
 #
+# `DASHT_USE_DASH_APP`
+#   Set to "true" to use Dash.app's (MacOS only) docset library. Disables
+#   docset management commands (install, remove, update). Also changes the
+#   default `DASHT_DOCSETS_DIR` to "~/Library/Application Support/Dash".
+#
+# ## EXIT STATUS
+#
+# 46
+#   Command was not executed because `DASHT_USE_DASH_APP` is set.
+#
 # ## SEE ALSO
 #
 # dasht-docsets-install(1), dasht-docsets-update(1), dasht-docsets(1), [Dash]
@@ -50,6 +60,15 @@
 # Written in 2016 by Suraj N. Kurapati <https://github.com/sunaku/dasht>
 # Distributed under the terms of the ISC license (refer to README file).
 
+: ${DASHT_DOCSETS_DIR:=${XDG_DATA_HOME:-$HOME/.local/share}/dasht/docsets}
+: ${DASHT_USE_DASH_APP:=false}
+
+if $DASHT_USE_DASH_APP; then
+  echo "extract, install, remove, and update operations are disabled when \
+    DASHT_USE_DASH_APP=true." >&2
+  exit 46
+fi
+
 : ${DASHT_DOCSETS_DIR:=${XDG_DATA_HOME:-$HOME/.local/share}/dasht/docsets}
 
 test "$1" = '-f' -o "$1" = '--force' && force=1 && shift || unset force

bin/dasht-docsets-update

@@ -33,6 +33,16 @@
 #   If undefined, its value is assumed to be `$XDG_DATA_HOME/dasht/docsets/`
 #   or, if `XDG_DATA_HOME` is undefined, `$HOME/.local/share/dasht/docsets/`.
 #
+# `DASHT_USE_DASH_APP`
+#   Set to "true" to use Dash.app's (MacOS only) docset library. Disables
+#   docset management commands (install, remove, update). Also changes the
+#   default `DASHT_DOCSETS_DIR` to "~/Library/Application Support/Dash".
+#
+# ## EXIT STATUS
+#
+# 46
+#   Command was not executed because `DASHT_USE_DASH_APP` is set.
+#
 # ## SEE ALSO
 #
 # dasht-docsets-extract(1), dasht-docsets-install(1), dasht-docsets-remove(1),
@@ -46,6 +56,13 @@
 # Distributed under the terms of the ISC license (refer to README file).
 
 : ${DASHT_DOCSETS_DIR:=${XDG_DATA_HOME:-$HOME/.local/share}/dasht/docsets}
+: ${DASHT_USE_DASH_APP:=false}
+
+if $DASHT_USE_DASH_APP; then
+  echo "extract, install, remove, and update operations are disabled when \
+    DASHT_USE_DASH_APP=true." >&2
+  exit 46
+fi
 
 dasht-docsets "$@" | while read -r docset; do
   ls "$DASHT_DOCSETS_DIR/$docset"*.tgz

bin/dasht-query-html

@@ -47,6 +47,11 @@
 #   If undefined, its value is assumed to be `$XDG_DATA_HOME/dasht/docsets/`
 #   or, if `XDG_DATA_HOME` is undefined, `$HOME/.local/share/dasht/docsets/`.
 #
+# `DASHT_USE_DASH_APP`
+#   Set to "true" to use Dash.app's (MacOS only) docset library. Disables
+#   docset management commands (install, remove, update). Also changes the
+#   default `DASHT_DOCSETS_DIR` to "~/Library/Application Support/Dash".
+#
 # ## EXIT STATUS
 #
 # 44

bin/dasht-query-line

@@ -70,6 +70,11 @@
 #   If undefined, its value is assumed to be `$XDG_DATA_HOME/dasht/docsets/`
 #   or, if `XDG_DATA_HOME` is undefined, `$HOME/.local/share/dasht/docsets/`.
 #
+# `DASHT_USE_DASH_APP`
+#   Set to "true" to use Dash.app's (MacOS only) docset library. Disables
+#   docset management commands (install, remove, update). Also changes the
+#   default `DASHT_DOCSETS_DIR` to "~/Library/Application Support/Dash".
+#
 # ## EXIT STATUS
 #
 # 44
@@ -86,7 +91,12 @@
 # Written in 2016 by Suraj N. Kurapati <https://github.com/sunaku/dasht>
 # Distributed under the terms of the ISC license (refer to README file).
 
-: ${DASHT_DOCSETS_DIR:=${XDG_DATA_HOME:-$HOME/.local/share}/dasht/docsets}
+: ${DASHT_USE_DASH_APP:=false}
+if $DASHT_USE_DASH_APP; then
+  : ${DASHT_DOCSETS_DIR:="/Users/smackesey/Library/Application Support/Dash"}
+else
+  : ${DASHT_DOCSETS_DIR:=${XDG_DATA_HOME:-$HOME/.local/share}/dasht/docsets}
+fi
 
 pattern=$(echo " $1 " | sed -e 's/[%_]/\\&/g' -e 's/[[:space:]]\{1,\}/%/g')
 test $# -gt 0 && shift # shift off PATTERN so argv contains solely DOCSETs
@@ -95,7 +105,12 @@ status=44 # (default) exit with a nonzero status when no results are found
 trap 'status=0' USR1 # override default exit status when results are found
 
 dasht-docsets "$@" | while read -r docset; do
-  database="$DASHT_DOCSETS_DIR/$docset".docset/Contents/Resources/docSet.dsidx
+  if $DASHT_USE_DASH_APP; then
+    relpath=("$DASHT_DOCSETS_DIR"/*/*/"$docset".docset)
+    database="$relpath/Contents/Resources/docSet.dsidx"
+  else
+    database="$DASHT_DOCSETS_DIR/$docset".docset/Contents/Resources/docSet.dsidx
+  fi
   file_url="file://$(dirname "$database")/Documents/"
 
   dasht-query-exec "$pattern" "$database" -line |

bin/dasht-server

@@ -36,6 +36,11 @@
 #   If undefined, its value is assumed to be `$XDG_DATA_HOME/dasht/docsets/`
 #   or, if `XDG_DATA_HOME` is undefined, `$HOME/.local/share/dasht/docsets/`.
 #
+# `DASHT_USE_DASH_APP`
+#   Set to "true" to use Dash.app's (MacOS only) docset library. Disables
+#   docset management commands (install, remove, update). Also changes the
+#   default `DASHT_DOCSETS_DIR` to "~/Library/Application Support/Dash".
+#
 # ## SEE ALSO
 #
 # socat(1), dasht-server-http(1), dasht-docsets(1), dasht(1), [Dash]

bin/dasht-server-http

@@ -37,6 +37,11 @@
 #   If undefined, its value is assumed to be `$XDG_DATA_HOME/dasht/docsets/`
 #   or, if `XDG_DATA_HOME` is undefined, `$HOME/.local/share/dasht/docsets/`.
 #
+# `DASHT_USE_DASH_APP`
+#   Set to "true" to use Dash.app's (MacOS only) docset library. Disables
+#   docset management commands (install, remove, update). Also changes the
+#   default `DASHT_DOCSETS_DIR` to "~/Library/Application Support/Dash".
+#
 # ## SEE ALSO
 #
 # dasht-query-html(1), dasht-server(1), dasht-docsets(1), dasht(1), [Dash]