Merge pull request #56 from smackesey/tsv-output

Switch to Tab-Separated Values (TSV) format in dasht-query-line(1) and
dasht-query-html(1) for easier line-by-line parsing and user scripting.

Author: sunaku

bin/dasht-query-html

@@ -111,44 +111,50 @@ trap 'exit 44' USR1 # exit with a nonzero status when no results found
     gsub("[[:space:]]+", ".*", pattern)       # treat whitespace as wildcards
     pattern = ignorecase(pattern)             # emulate IGNORECASE=1 for POSIX
     if (pattern == "") pattern = "^."         # grouped by leading character
+    FS = "\t"                                 # fields are separated by tabs
   }
-  NR == 1      { print "<table>" }
-  $2 == "="    { result[$1] = substr($0, index($0, $2) + length($2) + 1) }
-  $1 == "from" { result["from"] = wordbreak_cached(result["from"], "<wbr>") }
-  $1 == "name" {
+  NR == 1 {
+    print "<table>"
+  }
+  {
+    name = $1
+    from = wordbreak_cached($2, "<wbr>")
+    type = $3
+    url = $4
+
     # mark search terms with STX and ETX bytes which are ignored by escape()
     if (pattern) {
-      gsub(pattern, "\002&\003", result["name"])
+      gsub(pattern, "\002&\003", name)
     }
 
     # mark word-wrappable points with VT bytes which are ignored by escape()
-    result["name"] = wordbreak(result["name"], "\v", "\002\003")
+    name = wordbreak(name, "\v", "\002\003")
 
     # escape XML entities in search result to make them visible in browsers
-    result["name"] = escape(result["name"])
+    name = escape(name)
 
     # insert word-break opportunity <wbr> tags at points marked by VT bytes
-    gsub("\v", "<wbr>", result["name"])
+    gsub("\v", "<wbr>", name)
 
     # highlight search terms in search result using the STX and ETX markers
     if (pattern) {
-      gsub("\002", "<b><i><u>", result["name"])
-      gsub("\003", "</u></i></b>", result["name"])
+      gsub("\002", "<b><i><u>", name)
+      gsub("\003", "</u></i></b>", name)
     }
-  }
-  $1 == "url"  { print \
-    "<tr>"\
-      "<td><a href=\"" result["url"] "\">" result["name"] "</a></td>"\
-      "<td valign=\"bottom\" align=\"right\">" result["from"] "</td>"\
-      "<td valign=\"bottom\">" tolower(result["type"]) "</td>"\
-    "</tr>"
+
+    print \
+      "<tr>"\
+        "<td><a href=\"" url "\">" name "</a></td>"\
+        "<td valign=\"bottom\" align=\"right\">" from "</td>"\
+        "<td valign=\"bottom\">" tolower(type) "</td>"\
+      "</tr>"
   }
   END {
     if (NR > 0) {
       print "</table>"
-      if (NR == 4) {
+      if (NR == 1) {
         # there was only one search result, so automatically visit its url
-        print "<meta http-equiv=\"refresh\" content=\"0;url=" result["url"] "\">"
+        print "<meta http-equiv=\"refresh\" content=\"0;url=" url "\">"
       }
     }
   }

bin/dasht-query-line

@@ -4,7 +4,7 @@
 #
 # ## NAME
 #
-# dasht-query-line - searches [Dash] docsets and emits groups of lines
+# dasht-query-line - searches [Dash] docsets and emits TSV table rows
 #
 # ## SYNOPSIS
 #
@@ -28,7 +28,7 @@
 #
 # Searches for *PATTERN* in all installed [Dash] docsets, optionally searching
 # only in those whose names match *DOCSET*s, by calling dasht-query-exec(1)
-# and emits the results in groups of lines, as described in "Results" below.
+# and emits the results, one per line, in Tab-Separated Values (TSV) format.
 # However, if no results were found, this program exits with a nonzero status.
 #
 # ### Searching
@@ -42,26 +42,24 @@
 #
 # ### Results
 #
-# Each search result is printed to stdout as a group of four lines of text:
+# Each search result is printed stdout as a line with 4 tab-separated fields:
 #
-# `name` `=` *VALUE*
+# `name`
 #   Name of the token that matched the *PATTERN*.
 #
-# `type` `=` *VALUE*
+# `type`
 #   Type of the token, as defined in the docset.
 #
-# `from` `=` *VALUE*
+# `from`
 #   Name of the docset this result was found in.
 #
-# `url` `=` *VALUE*
+# `url`
 #   URL of the API documentation for this result.
 #
-# For example, here is a search result for "c - x" from the "bash" docset:
+# For example, here is a search result for "c - x" from the "bash" docset,
+# with the tab separators represented by `<TAB>` for illustrative purposes:
 #
-#     name = undo (C-_ or C-x C-u)
-#     type = Function
-#     from = Bash
-#     url = file:///home/sunny/.local/share/dasht/docsets/Bash.docset/Contents/Resources/Documents/bash/Miscellaneous-Commands.html#//apple_ref/Function/undo%20%28C%2D%5F%20or%20C%2Dx%20C%2Du%29
+#     undo (C-_ or C-x C-u)<TAB>Function<TAB>Bash<TAB>file:///home/sunny/.local/share/dasht/docsets/Bash.docset/Contents/Resources/Documents/bash/Miscellaneous-Commands.html#//apple_ref/Function/undo%20%28C%2D%5F%20or%20C%2Dx%20C%2Du%29
 #
 # ## ENVIRONMENT
 #
@@ -245,9 +243,12 @@ dasht-docsets "$@" | while read -r docset; do
 
     { $1 = $1 } # strip whitespace from key
 
+    $2 == "=" {
+      # skip over the first 2 fields and grab the rest of the line
+      result[$1] = substr($0, 1 + length($1) + 1 + length($2) + 1)
+    }
+
     $1 == "url" { were_any_results_found=1
-      # indicate the source of this result
-      print "from = " docset
 
       # strip embedded XML from result URL
       gsub("<.*>", "", $3)
@@ -259,9 +260,10 @@ dasht-docsets "$@" | while read -r docset; do
 
       # resolve URL to filesystem location
       $3 = file_url $3
-    }
 
-    /./ # reject any empty lines from input
+      printf("%s\t%s\t%s\t%s\n", result["name"], docset, result["type"], $3)
+
+    }
 
     END { exit !were_any_results_found }
   ' && kill -s USR1 $$ || : # notify this script if any results were found

man/man1/dasht-query-line.1

@@ -1,7 +1,7 @@
 .TH DASHT\-QUERY\-LINE 1            2020\-05\-16                            2.4.0
 .SH NAME
 .PP
-dasht\-query\-line \- searches Dash \[la]https://kapeli.com/dash\[ra] docsets and emits groups of lines
+dasht\-query\-line \- searches Dash \[la]https://kapeli.com/dash\[ra] docsets and emits TSV table rows
 .SH SYNOPSIS
 .PP
 \fB\fCdasht\-query\-line\fR [\fIPATTERN\fP] [\fIDOCSET\fP]...
@@ -24,7 +24,7 @@ Searches for \fIPATTERN\fP in all installed Dash \[la]https://kapeli.com/dash\[r
 only in those whose names match \fIDOCSET\fPs, by calling 
 .BR dasht-query-exec (1)
 
-and emits the results in groups of lines, as described in "Results" below.
+and emits the results, one per line, in Tab\-Separated Values (TSV) format.
 However, if no results were found, this program exits with a nonzero status.
 .SS Searching
 .PP
@@ -36,28 +36,26 @@ can match anywhere: beginning, middle, or end.  As a result, if \fIPATTERN\fP is
 undefined, it becomes a whitespace wildcard and thereby matches everything.
 .SS Results
 .PP
-Each search result is printed to stdout as a group of four lines of text:
+Each search result is printed stdout as a line with 4 tab\-separated fields:
 .TP
-\fB\fCname\fR \fB\fC=\fR \fIVALUE\fP
+\fB\fCname\fR
 Name of the token that matched the \fIPATTERN\fP\&.
 .TP
-\fB\fCtype\fR \fB\fC=\fR \fIVALUE\fP
+\fB\fCtype\fR
 Type of the token, as defined in the docset.
 .TP
-\fB\fCfrom\fR \fB\fC=\fR \fIVALUE\fP
+\fB\fCfrom\fR
 Name of the docset this result was found in.
 .TP
-\fB\fCurl\fR \fB\fC=\fR \fIVALUE\fP
+\fB\fCurl\fR
 URL of the API documentation for this result.
 .PP
-For example, here is a search result for "c \- x" from the "bash" docset:
+For example, here is a search result for "c \- x" from the "bash" docset,
+with the tab separators represented by \fB\fC<TAB>\fR for illustrative purposes:
 .PP
 .RS
 .nf
-name = undo (C\-_ or C\-x C\-u)
-type = Function
-from = Bash
-url = file:///home/sunny/.local/share/dasht/docsets/Bash.docset/Contents/Resources/Documents/bash/Miscellaneous\-Commands.html#//apple_ref/Function/undo%20%28C%2D%5F%20or%20C%2Dx%20C%2Du%29
+undo (C\-_ or C\-x C\-u)<TAB>Function<TAB>Bash<TAB>file:///home/sunny/.local/share/dasht/docsets/Bash.docset/Contents/Resources/Documents/bash/Miscellaneous\-Commands.html#//apple_ref/Function/undo%20%28C%2D%5F%20or%20C%2Dx%20C%2Du%29
 .fi
 .RE
 .SH ENVIRONMENT