Function: pcomplete-from-help

pcomplete-from-help is a byte-compiled function defined in pcomplete.el.gz.

Signature

(pcomplete-from-help COMMAND &rest ARGS &key (MARGIN (rx bol (+ " "))) (ARGUMENT (rx "-" (+ (any "-" alnum)) (32 "="))) (METAVAR (rx (32 " ") (or (+ (any alnum "_-")) (seq "[" (+? nonl) "]") (seq "<" (+? nonl) ">") (seq "{" (+? nonl) "}")))) (SEPARATOR (rx ", " symbol-start)) (DESCRIPTION (rx (* nonl) (* "\n" (>= 9 " ") (* nonl)))) NARROW-START NARROW-END)

Documentation

Parse output of COMMAND into a list of completion candidates.

COMMAND can be a string to be executed in a shell or a list of strings (program name and arguments). It should print a help message.

A list of arguments is collected after each match of MARGIN. Each argument should match ARGUMENT, possibly followed by a match of METAVAR. If a match of SEPARATOR follows, then more argument-metavar pairs are collected. Finally, a match of DESCRIPTION is collected.

Keyword ARGS:

MARGIN: regular expression after which argument descriptions are
  to be found. Parsing continues at the end of the first match
  group or, failing that, the entire match.

ARGUMENT: regular expression matching an argument name. The
  first match group (failing that, the entire match) is collected
  as the argument name. Parsing continues at the end of the
  second matching group (failing that, the first group or entire
  match).

METAVAR: regular expression matching an argument parameter name.
  The first match group (failing that, the entire match) is
  collected as the parameter name and used as completion
  annotation. Parsing continues at the end of the second
  matching group (failing that, the first group or entire match).

SEPARATOR: regular expression matching the separator between
  arguments. Parsing continues at the end of the first match
  group (failing that, the entire match).

DESCRIPTION: regular expression matching the description of an
  argument. The first match group (failing that, the entire
  match) is collected as the parameter name and used as
  completion help. Parsing continues at the end of the first
  matching group (failing that, the entire match).

NARROW-START, NARROW-END: if non-nil, parsing of the help message
  is narrowed to the region between the end of the first match
  group (failing that, the entire match) of these regular
  expressions.

Source Code

;; Defined in /usr/src/emacs/lisp/pcomplete.el.gz
(cl-defun pcomplete-from-help (command
                               &rest args
                               &key
                               (margin (rx bol (+ " ")))
                               (argument (rx "-" (+ (any "-" alnum)) (? "=")))
                               (metavar (rx (? " ")
                                            (or (+ (any alnum "_-"))
                                                (seq "[" (+? nonl) "]")
                                                (seq "<" (+? nonl) ">")
                                                (seq "{" (+? nonl) "}"))))
                               (separator (rx ", " symbol-start))
                               (description (rx (* nonl)
                                                (* "\n" (>= 9 " ") (* nonl))))
                               narrow-start
                               narrow-end)
  "Parse output of COMMAND into a list of completion candidates.

COMMAND can be a string to be executed in a shell or a list of
strings (program name and arguments).  It should print a help
message.

A list of arguments is collected after each match of MARGIN.
Each argument should match ARGUMENT, possibly followed by a match
of METAVAR.  If a match of SEPARATOR follows, then more
argument-metavar pairs are collected.  Finally, a match of
DESCRIPTION is collected.

Keyword ARGS:

MARGIN: regular expression after which argument descriptions are
  to be found.  Parsing continues at the end of the first match
  group or, failing that, the entire match.

ARGUMENT: regular expression matching an argument name.  The
  first match group (failing that, the entire match) is collected
  as the argument name.  Parsing continues at the end of the
  second matching group (failing that, the first group or entire
  match).

METAVAR: regular expression matching an argument parameter name.
  The first match group (failing that, the entire match) is
  collected as the parameter name and used as completion
  annotation.  Parsing continues at the end of the second
  matching group (failing that, the first group or entire match).

SEPARATOR: regular expression matching the separator between
  arguments.  Parsing continues at the end of the first match
  group (failing that, the entire match).

DESCRIPTION: regular expression matching the description of an
  argument.  The first match group (failing that, the entire
  match) is collected as the parameter name and used as
  completion help.  Parsing continues at the end of the first
  matching group (failing that, the entire match).

NARROW-START, NARROW-END: if non-nil, parsing of the help message
  is narrowed to the region between the end of the first match
  group (failing that, the entire match) of these regular
  expressions."
  (with-memoization (gethash (cons command args) pcomplete-from-help)
    (with-temp-buffer
      (let ((case-fold-search nil)
            (default-directory (expand-file-name "~/"))
            (command (if (stringp command)
                         (list shell-file-name
                               shell-command-switch
                               command)
                       command))
            i result)
        (apply #'call-process (car command) nil t nil (cdr command))
        (goto-char (point-min))
        (narrow-to-region (or (and narrow-start
                                   (re-search-forward narrow-start nil t)
                                   (or (match-beginning 1) (match-beginning 0)))
                              (point-min))
                          (or (and narrow-end
                                   (re-search-forward narrow-end nil t)
                                   (or (match-beginning 1) (match-beginning 0)))
                              (point-max)))
        (goto-char (point-min))
        (while (re-search-forward margin nil t)
          (goto-char (or (match-end 1) (match-end 0)))
          (setq i 0)
          (while (and (or (zerop i)
                          (and (looking-at separator)
                               (goto-char (or (match-end 1)
                                              (match-end 0)))))
                      (looking-at argument))
            (setq i (1+ i))
            (goto-char (seq-some #'match-end '(2 1 0)))
            (push (or (match-string 1) (match-string 0)) result)
            (when (looking-at metavar)
              (goto-char (seq-some #'match-end '(2 1 0)))
              (put-text-property 0 1
                                 'pcomplete-annotation
                                 (or (match-string 1) (match-string 0))
                                 (car result))))
          (when (looking-at description)
            (goto-char (seq-some #'match-end '(2 1 0)))
            (let ((help (string-clean-whitespace
                         (or (match-string 1) (match-string 0))))
                  (items (take i result)))
              (while items
                (put-text-property 0 1 'pcomplete-help help
                                   (pop items))))))
        (nreverse result)))))