#!/bin/sh -e
#
# # DASHT 1                       2020-05-16                            2.4.0
#
# ## NAME
#
# dasht - API documentation in your terminal
#
# ## SYNOPSIS
#
# `dasht` [*PATTERN*] [*DOCSET*]...
#
# ### Examples
#
# `dasht`
#   Topics (A-Z) from each installed docset.
#
# `dasht` 'c - x'
#   Search for "c - x" in all installed docsets.
#
# `dasht` 'c - x' bash
#   Search for "c - x" only in the "bash" docset.
#
# `dasht` 'c - x' bash css
#   Search for "c - x" only in the "bash" and "css" docsets.
#
# ## DESCRIPTION
#
# Searches for *PATTERN* in all installed [Dash] docsets, optionally searching
# only in those whose names match *DOCSET*s, by calling dasht-query-html(1).
# The results, if any, are then displayed in the w3m(1) terminal web browser,
# which terminates when you press the `q` key, just as typical UNIX pagers do.
# If no results were found, says so on stderr and exits with a nonzero status.
#
# ### Searching
#
# Whitespace characters in *PATTERN* are treated as wildcards, whereas the
# SQL LIKE wildcard characters `%` and `_` are not: they are taken literally.
#
# Before searching, *PATTERN* is surrounded by whitespace wildcards so that it
# can match anywhere: beginning, middle, or end.  As a result, if *PATTERN* is
# undefined, it becomes a whitespace wildcard and thereby matches everything.
#
# ## ENVIRONMENT
#
# `DASHT_DOCSETS_DIR`
#   Defines the filesystem location where your [Dash] docsets are installed.
#   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/`.
#
# ## EXIT STATUS
#
# 44
#   No results were found.
#
# 45
#   No docsets were searched.
#
# ## SEE ALSO
#
# w3m(1), dasht-query-html(1), dasht-docsets(1), [Dash]
#
# [Dash]: https://kapeli.com/dash
#
# ## AUTHOR
#
# Written in 2016 by Suraj N. Kurapati <https://github.com/sunaku/dasht>
# Distributed under the terms of the ISC license (refer to README file).

if test $# -gt 0; then
  pattern=$1
  shift
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
  echo "dasht: '$*' docsets not installed so '$pattern' not searched" >&2
  exit 45
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

  # emulate pipefail (which POSIX lacks) by killing off the w3m(1) process
  # below (which starts up simultaneously alongside this pipeline segment)
  kill $(ps -e -o comm,ppid,pid | sed -n "s/^w3m *$$ //p")

  # and then proceed to tell this script to generate a nonzero exit status
  kill -s USR1 $$
fi |
w3m -T text/html \
    -o confirm_qq=false \
    -o color=true \
    -o active_style=true \
    -o visited_anchor=true \
    -o label_topline=true \
    -o meta_refresh=true \
    -o wrap_search=true \
    -o ignorecase_search=true