Function: goto-history-element

goto-history-element is an interactive and byte-compiled function defined in simple.el.gz.

Signature

(goto-history-element NABS)

Documentation

Insert into the minibuffer the element of minibuffer history specified by NABS.

Interactively, NABS is the prefix numeric argument, and defaults to 1. It specifies the absolute history position in descending order, where 0 means the current element and a positive number N means the Nth previous element. NABS that is a negative number -N means the Nth entry of "future history."

View in manual

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/simple.el.gz
(defun goto-history-element (nabs)
  "Insert into the minibuffer the element of minibuffer history specified by NABS.
Interactively, NABS is the prefix numeric argument, and defaults to 1.
It specifies the absolute history position in descending order,
where 0 means the current element and a positive number N means
the Nth previous element.  NABS that is a negative number -N means
the Nth entry of \"future history.\""
  (interactive "p")
  (when (and (not minibuffer-default-add-done)
	     (functionp minibuffer-default-add-function)
	     (< nabs (- (if (listp minibuffer-default)
			    (length minibuffer-default)
			  1))))
    (setq minibuffer-default-add-done t
	  minibuffer-default (funcall minibuffer-default-add-function)))
  (let ((minimum (if minibuffer-default
		     (- (if (listp minibuffer-default)
			    (length minibuffer-default)
			  1))
		   0))
	elt minibuffer-returned-to-present)
    (if (and (zerop minibuffer-history-position)
	     (null minibuffer-text-before-history))
	(setq minibuffer-text-before-history
	      (minibuffer-contents-no-properties)))
    (if (< nabs minimum)
	(user-error (if minibuffer-default
                        "End of defaults; no next item"
                      "End of history; no default available")))
    (if (> nabs (if (listp (minibuffer-history-value))
                    (length (minibuffer-history-value))
                  0))
	(user-error "Beginning of history; no preceding item"))
    (unless (memq last-command '(next-history-element
				 previous-history-element))
      (let ((prompt-end (minibuffer-prompt-end)))
        (setq-local minibuffer-temporary-goal-position
                    (cond ((<= (point) prompt-end) prompt-end)
                          ((eobp) nil)
                          (t (point))))))
    (goto-char (point-max))
    (delete-minibuffer-contents)
    (setq minibuffer-history-position nabs)
    (cond ((< nabs 0)
	   (setq elt (if (listp minibuffer-default)
			 (nth (1- (abs nabs)) minibuffer-default)
		       minibuffer-default)))
	  ((= nabs 0)
	   (setq elt (or minibuffer-text-before-history ""))
	   (setq minibuffer-returned-to-present t)
	   (setq minibuffer-text-before-history nil))
	  (t (setq elt (nth (1- minibuffer-history-position)
			    (minibuffer-history-value)))))
    (insert
     (if (and (eq minibuffer-history-sexp-flag (minibuffer-depth))
	      (not minibuffer-returned-to-present))
	 (let ((print-level nil))
	   (prin1-to-string elt))
       elt))
    (goto-char (or minibuffer-temporary-goal-position (point-max)))))