[elpa] externals/urgrep c879c02558 040/115: Add some docs and clean up spacing

[ELPA Syncer]

branch: externals/urgrep
commit c879c02558e18fa63cebb45eec8c57390983975b
Author: Jim Porter <jporterbugs@gmail.com>
Commit: Jim Porter <jporterbugs@gmail.com>

    Add some docs and clean up spacing
---
 urgrep-tests.el |  4 ++--
 urgrep.el       | 73 +++++++++++++++++++++++++++++++++++++++------------------
 2 files changed, 52 insertions(+), 25 deletions(-)

diff --git a/urgrep-tests.el b/urgrep-tests.el
index c9f11edb05..b58391a0a1 100644
--- a/urgrep-tests.el
+++ b/urgrep-tests.el
@@ -12,11 +12,11 @@
 
 ;; This program is distributed in the hope that it will be useful, but WITHOUT
 ;; ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-;; FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+;; FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
 ;; more details.
 
 ;; You should have received a copy of the GNU General Public License along with
-;; this program. If not, see <http://www.gnu.org/licenses/>.
+;; this program.  If not, see <http://www.gnu.org/licenses/>.
 
 ;;; Commentary:
 
diff --git a/urgrep.el b/urgrep.el
index cd3dcef03b..56008bed3c 100644
--- a/urgrep.el
+++ b/urgrep.el
@@ -15,16 +15,16 @@
 
 ;; This program is distributed in the hope that it will be useful, but WITHOUT
 ;; ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-;; FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+;; FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
 ;; more details.
 
 ;; You should have received a copy of the GNU General Public License along with
-;; this program. If not, see <http://www.gnu.org/licenses/>.
+;; this program.  If not, see <http://www.gnu.org/licenses/>.
 
 ;;; Commentary:
 
-;; A universal frontend to various grep-like tools. Currently, ripgrep, ag, 
ack,
-;; git-grep, and grep are supported.
+;; A universal frontend to various grep-like tools.  Currently, ripgrep, ag,
+;; ack, git-grep, and grep are supported.
 
 ;;; Code:
 
@@ -69,8 +69,9 @@ Valid values are nil (case-sensitive), t (case-insensitive), 
`smart'
 
 (defcustom urgrep-context-lines 0
   "Number of lines of context to show.
-If this is an integer, show that many lines of context on either side.
-If a cons, show CAR and CDR lines before and after, respectively."
+If this is an integer, show that many lines of context on either
+side.  If a cons, show CAR and CDR lines before and after,
+respectively."
   :type '(choice integer (cons integer integer))
   :group 'urgrep)
 
@@ -103,8 +104,9 @@ If a cons, show CAR and CDR lines before and after, 
respectively."
   (cond ((and (not (eq from-syntax to-syntax))
               (or (eq from-syntax 'bre) (eq to-syntax 'bre)))
          ;; XXX: This is a bit of a hack, but xref.el contains an internal
-         ;; function for converting between basic and extended regexps. It 
might
-         ;; be wise to use our own implementation, but this should work for 
now.
+         ;; function for converting between basic and extended regexps.  It
+         ;; might be wise to use our own implementation, but this should work
+         ;; for now.
          (require 'xref)
          (xref--regexp-to-extended expr))
         (t expr)))
@@ -117,7 +119,7 @@ If a cons, show CAR and CDR lines before and after, 
respectively."
       (substring string1 0 (1- (abs cmp))))))
 
 (defun urgrep--wildcard-to-regexp-hunk (wildcard syntax)
-  "Convert WILDCARD to a SYNTAX-style regexp.
+  "Convert WILDCARD to a SYNTAX style regexp.
 Unlike `wildcard-to-regexp', this excludes the begin/end specifiers,
 and escapes null characters."
   (if wildcard
@@ -127,7 +129,7 @@ and escapes null characters."
     ""))
 
 (defun urgrep--wildcards-to-regexp (wildcards syntax)
-  "Convert a list of WILDCARDS to a SYNTAX-style regexp."
+  "Convert a list of WILDCARDS to a SYNTAX style regexp."
   (let ((to-re (lambda (i) (urgrep--wildcard-to-regexp-hunk i syntax)))
         (wildcards (cl-remove-duplicates wildcards :test #'string=)))
     (if (<= (length wildcards) 1)
@@ -257,7 +259,7 @@ See also `grep-process-setup'."
      (process-setup ,#'urgrep--rgrep-process-setup)
      (context-arguments ,urgrep--context-arguments)
      ;; XXX: On MS Windows, -P and -F seem to cause issues due to the default
-     ;; locale. Setting LC_ALL=en_US.utf8 fixes this, but I'm not sure if this
+     ;; locale.  Setting LC_ALL=en_US.utf8 fixes this, but I'm not sure if this
      ;; is the right thing to do in general...
      (regexp-arguments (('bre  '("-G"))
                         ('ere  '("-E"))
@@ -315,7 +317,7 @@ This caches the default tool per-host in 
`urgrep--host-defaults'."
                          (string= vc-backend-name tool-vc-backend)))
             ;; So long as we didn't examine a VC-specific tool, we can cache
             ;; this result for future calls, since the result will always be 
the
-            ;; same. If we *did* see a VC-specific tool, this host will use
+            ;; same.  If we *did* see a VC-specific tool, this host will use
             ;; different tools for different directories, so we can't cache
             ;; anything.
             (unless saw-vc-tool-p
@@ -324,8 +326,8 @@ This caches the default tool per-host in 
`urgrep--host-defaults'."
 
 (defun urgrep-get-tool (&optional tool)
   "Get the urgrep tool for TOOL.
-If TOOL is nil, get the default tool. If TOOL is a string, look it
-up in `urgrep-tools'. Otherwise, return TOOL as-is."
+If TOOL is nil, get the default tool.  If TOOL is a string, look it up
+in `urgrep-tools'.  Otherwise, return TOOL as-is."
   (pcase tool
     ('nil (urgrep--get-default-tool))
     ((and (pred stringp) tool) (assoc tool urgrep-tools))
@@ -350,8 +352,32 @@ for MS shells."
           ((and (eq syntax 'pcre) (memq 'extended tool-syntaxes)) 'ere)
           (t (car tool-syntaxes)))))
 
+;;;###autoload
 (cl-defun urgrep-command (query &rest rest &key tool (group t) regexp
                                 (case-fold 'inherit) (context 0) files)
+  "Return a command to use to search for QUERY.
+Several keyword arguments can be supplied to adjust the resulting
+command:
+
+TOOL: a tool from `urgrep-tools': a key-value pair from the list, just
+the key, or nil to use the default tool.
+
+GROUP: show results grouped by filename (t, the default), or if nil,
+prefix the filename on each result line.
+
+REGEXP: the style of regexp to use for results; one of nil (fixed
+strings), `bre' (basic regexp), `ere' (extend regexp), `pcre'
+\(Perl-compatible regexp), or t (the default regexp style stored in
+`urgrep-regexp-syntax').
+
+CASE-FOLD: determine whether QUERY is case-sensitive or not; possible
+values are as `urgrep-case-fold', defaulting to `inherit'.
+
+CONTEXT: the number of lines of context to show around results; either
+an integer (to show the same number of lines before and after) or a
+cons (to show CAR and CDR lines before and after, respectively).
+
+FILES: a wildcard (or list of wildcards) to limit the files searched."
   (let* ((regexp-syntax (if (eq regexp t) urgrep-regexp-syntax regexp))
          (files (if (listp files) files (list files)))
          (tool (urgrep-get-tool tool))
@@ -389,7 +415,7 @@ for MS shells."
 ;; urgrep-mode
 
 (defvar urgrep-num-matches-found 0
-  "Running total of matches found. This will be set buffer-locally.")
+  "Running total of matches found.  This will be set buffer-locally.")
 
 ;; Set the first column to 0 because that's how we currently count.
 ;; XXX: It might be worth changing this to 1 if we allow reading the column
@@ -637,8 +663,8 @@ This function is called from `compilation-filter-hook'."
 (defun urgrep--start (command query tool)
   "Start a urgrep process for COMMAND.
 QUERY is the original argument list that generated COMMAND (or it may
-be the same value as COMMAND). TOOL is the tool that was used to
-generate the command. This sets `urgrep-current-query' and
+be the same value as COMMAND).  TOOL is the tool that was used to
+generate the command.  This sets `urgrep-current-query' and
 `urgrep-current-tool' buffer-locally so that they can be used when
 rerunning the search."
   (with-current-buffer
@@ -661,7 +687,8 @@ rerunning the search."
 
 (defun urgrep--search-default ()
   "Return the default thing to search for.
-If the region is active, return that. Otherwise, return the symbol at point."
+If the region is active, return that.  Otherwise, return the symbol at
+point."
   (if (use-region-p)
       (buffer-substring-no-properties (region-beginning) (region-end))
     (when-let ((symbol (symbol-at-point)))
@@ -669,8 +696,8 @@ If the region is active, return that. Otherwise, return the 
symbol at point."
 
 (defun urgrep--search-prompt (default)
   "Return the prompt to use when asking for the search query.
-This depends on the current values of various urgrep options. DEFAULT indicates
-the default query, if any."
+This depends on the current values of various urgrep options.  DEFAULT
+indicates the default query, if any."
   (concat "Search "
           (if urgrep-search-regexp "regexp" "string")
           (let ((block (append `(,#'pcase ',urgrep-context-lines)
@@ -789,7 +816,7 @@ future searches."
                                       (files urgrep-file-wildcards))
   "Prompt the user for a search query starting with an INITIAL value.
 Return a list that can be passed to `urgrep-command' to turn into a shell
-command. TOOL, GROUP, REGEXP, CASE-FOLD, and CONTEXT are as in
+command.  TOOL, GROUP, REGEXP, CASE-FOLD, CONTEXT, and FILES are as in
 `urgrep-command'."
   (let* ((urgrep-search-regexp regexp)
          (urgrep-case-fold case-fold)
@@ -818,8 +845,8 @@ command. TOOL, GROUP, REGEXP, CASE-FOLD, and CONTEXT are as 
in
 
 (defun urgrep--read-directory (arg)
   "Get the directory to search in.
-If ARG is nil, return the project's root directory. If ARG's numeric
-value is 4, return the current directory. Otherwise, prompt for the
+If ARG is nil, return the project's root directory.  If ARG's numeric
+value is 4, return the current directory.  Otherwise, prompt for the
 directory."
   (cond
    ((not arg) (let ((proj (project-current)))