Function: pcomplete-arg

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

Signature

(pcomplete-arg &optional INDEX OFFSET)

Documentation

Return the textual content of the INDEXth argument.

INDEX is based from the current processing position. If INDEX is positive, values returned are closer to the command argument; if negative, they are closer to the last argument. If the INDEX is outside of the argument list, nil is returned. The default value for INDEX is 0, meaning the current argument being examined.

The special indices first and last may be used to access those parts of the list.

The OFFSET argument is added to/taken away from the index that will be used. This is really only useful with first and last, for accessing absolute argument positions.

When the argument has been transformed into something that is not a string by pcomplete-parse-arguments-function, the text representation of the argument, namely what the user actually typed in, is returned, and the value of the argument is stored in the pcomplete-arg-value text property of that string.

Source Code

;; Defined in /usr/src/emacs/lisp/pcomplete.el.gz
(defun pcomplete-arg (&optional index offset)
  "Return the textual content of the INDEXth argument.
INDEX is based from the current processing position.  If INDEX is
positive, values returned are closer to the command argument; if
negative, they are closer to the last argument.  If the INDEX is
outside of the argument list, nil is returned.  The default value for
INDEX is 0, meaning the current argument being examined.

The special indices `first' and `last' may be used to access those
parts of the list.

The OFFSET argument is added to/taken away from the index that will be
used.  This is really only useful with `first' and `last', for
accessing absolute argument positions.

When the argument has been transformed into something that is not
a string by `pcomplete-parse-arguments-function', the text
representation of the argument, namely what the user actually
typed in, is returned, and the value of the argument is stored in
the pcomplete-arg-value text property of that string."
  (let ((arg
         (nth (+ (pcase index
                   ('first 0)
                   ('last  pcomplete-last)
                   (_      (- pcomplete-index (or index 0))))
                 (or offset 0))
              pcomplete-args)))
    (if (or (stringp arg)
            ;; FIXME: 'last' is handled specially in Emacs 29, because
            ;; 'pcomplete-parse-arguments' accepts a list of strings
            ;; (which are completion candidates) as return value for
            ;; (pcomplete-arg 'last).  See below: "it means it's a
            ;; list of completions computed during parsing,
            ;; e.g. Eshell uses that to turn globs into lists of
            ;; completions".  This special case will be dealt with
            ;; differently in Emacs 30: the pcomplete-arg-value
            ;; property will be used by 'pcomplete-parse-arguments'.
            (eq index 'last))
        arg
      (propertize
       (car (split-string (pcomplete-actual-arg index offset)))
       'pcomplete-arg-value arg))))