1 ;;; ivy.el --- Incremental Vertical completYon -*- lexical-binding: t -*-
3 ;; Copyright (C) 2015 Free Software Foundation, Inc.
5 ;; Author: Oleh Krehel <ohwoeowho@gmail.com>
6 ;; URL: https://github.com/abo-abo/swiper
8 ;; Package-Requires: ((emacs "24.1"))
11 ;; This file is part of GNU Emacs.
13 ;; This file is free software; you can redistribute it and/or modify
14 ;; it under the terms of the GNU General Public License as published by
15 ;; the Free Software Foundation; either version 3, or (at your option)
18 ;; This program is distributed in the hope that it will be useful,
19 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
20 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 ;; GNU General Public License for more details.
23 ;; For a full copy of the GNU General Public License
24 ;; see <http://www.gnu.org/licenses/>.
28 ;; This package provides `ivy-read' as an alternative to
29 ;; `completing-read' and similar functions.
31 ;; There's no intricate code to determine the best candidate.
32 ;; Instead, the user can navigate to it with `ivy-next-line' and
33 ;; `ivy-previous-line'.
35 ;; The matching is done by splitting the input text by spaces and
36 ;; re-building it into a regex.
37 ;; So "for example" is transformed into "\\(for\\).*\\(example\\)".
42 "Incremental vertical completion."
45 (defface ivy-current-match
46 '((t (:inherit highlight)))
47 "Face used by Ivy for highlighting first match.")
49 (defcustom ivy-height 10
50 "Number of lines for the minibuffer window."
53 (defcustom ivy-count-format "%-4d "
54 "The style of showing the current candidate count for `ivy-read'.
55 Set this to nil if you don't want the count."
58 (defcustom ivy-wrap nil
59 "Whether to wrap around after the first and last candidate."
65 (defvar ivy-minibuffer-map
66 (let ((map (make-sparse-keymap)))
67 (define-key map (kbd "C-m") 'ivy-done)
68 (define-key map (kbd "C-n") 'ivy-next-line)
69 (define-key map (kbd "C-p") 'ivy-previous-line)
70 (define-key map (kbd "C-s") 'ivy-next-line-or-history)
71 (define-key map (kbd "C-r") 'ivy-previous-line-or-history)
72 (define-key map (kbd "SPC") 'self-insert-command)
73 (define-key map (kbd "DEL") 'ivy-backward-delete-char)
74 (define-key map (kbd "M-<") 'ivy-beginning-of-buffer)
75 (define-key map (kbd "M->") 'ivy-end-of-buffer)
76 (define-key map (kbd "M-n") 'ivy-next-history-element)
77 (define-key map (kbd "M-p") 'ivy-previous-history-element)
78 (define-key map (kbd "C-g") 'minibuffer-keyboard-quit)
80 "Keymap used in the minibuffer.")
82 (defvar ivy-history nil
83 "History list of candidates entered in the minibuffer.
85 Maximum length of the history list is determined by the value
86 of `history-length', which see.")
90 "Exit the minibuffer with the selected candidate."
92 (delete-minibuffer-contents)
93 (unless (zerop ivy--length)
95 (setq ivy-exit 'done))
98 (defun ivy-beginning-of-buffer ()
99 "Select the first completion candidate."
103 (defun ivy-end-of-buffer ()
104 "Select the last completion candidate."
106 (setq ivy--index (1- ivy--length)))
108 (defun ivy-next-line ()
109 "Select the next completion candidate."
111 (if (>= ivy--index (1- ivy--length))
113 (ivy-beginning-of-buffer))
114 (cl-incf ivy--index)))
116 (defun ivy-next-line-or-history ()
117 "Select the next completion candidate.
118 If the input is empty, select the previous history element instead."
120 (when (string= ivy-text "")
121 (ivy-previous-history-element 1))
122 (if (>= ivy--index (1- ivy--length))
124 (ivy-beginning-of-buffer))
125 (cl-incf ivy--index)))
127 (defun ivy-previous-line ()
128 "Select the previous completion candidate."
130 (if (zerop ivy--index)
133 (cl-decf ivy--index)))
135 (defun ivy-previous-line-or-history ()
136 "Select the previous completion candidate.
137 If the input is empty, select the previous history element instead."
139 (when (string= ivy-text "")
140 (ivy-previous-history-element 1))
141 (if (zerop ivy--index)
144 (cl-decf ivy--index)))
146 (defun ivy-previous-history-element (arg)
147 "Forward to `previous-history-element' with ARG."
149 (previous-history-element arg)
150 (move-end-of-line 1))
152 (defun ivy-next-history-element (arg)
153 "Forward to `next-history-element' with ARG."
155 (next-history-element arg)
156 (move-end-of-line 1))
158 (defun ivy-backward-delete-char ()
159 "Forward to `backward-delete-char'.
160 On error (read-only), quit without selecting."
163 (backward-delete-char 1)
165 (minibuffer-keyboard-quit))))
168 (defun ivy-read (prompt collection &optional initial-input update-fn preselect)
169 "Read a string in the minibuffer, with completion.
171 PROMPT is a string to prompt with; normally it ends in a colon
172 and a space. When PROMPT contains %d, it will be updated with
173 the current number of matching candidates.
175 COLLECTION is a list of strings.
177 If INITIAL-INPUT is non-nil, insert it in the minibuffer initially.
179 UPDATE-FN is called each time the current candidate(s) is changed.
181 If PRESELECT is non-nil select the corresponding candidate out of
182 the ones that match INITIAL-INPUT."
183 (cl-case (length collection)
189 (ivy--preselect-index
190 collection initial-input preselect))
192 (setq ivy--old-re nil)
193 (setq ivy--old-cands nil)
195 (setq ivy--all-candidates collection)
196 (setq ivy--update-fn update-fn)
198 (setq ivy--default (or (thing-at-point 'symbol) ""))
200 (cond ((string-match "%.*d" prompt)
202 ((string-match "%.*d" ivy-count-format)
203 (concat ivy-count-format prompt))
207 (minibuffer-with-setup-hook
208 #'ivy--minibuffer-setup
209 (let ((res (read-from-minibuffer
215 (when (eq ivy-exit 'done)
218 (cons ivy-text (delete ivy-text ivy-history)))
220 (remove-hook 'post-command-hook #'ivy--exhibit)))))
222 (defun ivy--preselect-index (candidates initial-input preselect)
223 "Return the index in CANDIDATES filtered by INITIAL-INPUT for PRESELECT."
228 (string-match initial-input x))
232 (string-match preselect x))
236 "Stores the user's string as it is typed in.")
239 "Store 'done if the completion was successfully selected.
240 Otherwise, store nil.")
244 (defvar ivy--subexps 0
245 "Number of groups in the current `ivy--regex'.")
247 (defvar ivy--regex-hash
248 (make-hash-table :test 'equal)
249 "Store pre-computed regex.")
251 (defun ivy--regex (str)
252 "Re-build regex from STR in case it has a space."
253 (let ((hashed (gethash str ivy--regex-hash)))
256 (setq ivy--subexps (car hashed)))
258 (let ((subs (split-string str " +" t)))
259 (if (= (length subs) 1)
261 (setq ivy--subexps 0)
264 (setq ivy--subexps (length subs))
266 (lambda (x) (format "\\(%s\\)" x))
272 (defun ivy--minibuffer-setup ()
273 "Setup ivy completion in the minibuffer."
274 (set (make-local-variable 'completion-show-inline-help) nil)
275 (set (make-local-variable 'minibuffer-default-add-function)
277 (list ivy--default)))
278 (use-local-map (make-composed-keymap ivy-minibuffer-map
279 (current-local-map)))
280 (setq-local max-mini-window-height ivy-height)
281 (add-hook 'post-command-hook #'ivy--exhibit nil t)
282 ;; show completions with empty input
285 (defvar ivy--all-candidates nil
286 "Store the candidates passed to `ivy-read'.")
289 "Store the index of the current candidate.")
291 (defvar ivy--length 0
292 "Store the amount of viable candidates.")
294 (defvar ivy--current ""
295 "Current candidate.")
297 (defvar ivy--default nil
298 "Default initial input.")
300 (defvar ivy--update-fn nil
301 "Current function to call when current candidate(s) update.")
304 "Return the current minibuffer input."
305 ;; assume one-line minibuffer input
306 (buffer-substring-no-properties
307 (minibuffer-prompt-end)
308 (line-end-position)))
310 (defun ivy--cleanup ()
311 "Delete the displayed completion candidates."
313 (goto-char (minibuffer-prompt-end))
314 (delete-region (line-end-position) (point-max))))
316 (defvar ivy--prompt nil
317 "Store the format-style prompt.
318 When non-nil, it should contain one %d.")
320 (defun ivy--insert-prompt ()
321 "Update the prompt according to `ivy--prompt'."
323 (let ((inhibit-read-only t)
324 (n-str (format ivy--prompt ivy--length)))
326 (goto-char (point-min))
327 (delete-region (point-min) (minibuffer-prompt-end))
330 '(front-sticky t rear-nonsticky t field t read-only t face minibuffer-prompt)
333 ;; get out of the prompt area
334 (constrain-to-field nil (point-max)))))
336 (defun ivy--exhibit ()
337 "Insert Ivy completions display.
338 Should be run via minibuffer `post-command-hook'."
339 (setq ivy-text (ivy--input))
341 (let ((text (ivy-completions
343 ivy--all-candidates))
347 (funcall ivy--update-fn))
349 ;; Do nothing if while-no-input was aborted.
355 (defvar ivy--old-re nil
356 "Store the old regexp.")
358 (defvar ivy--old-cands nil
359 "Store the candidates matched by `ivy--old-re'.")
361 (defun ivy--add-face (str face)
362 "Propertize STR with FACE.
363 `font-lock-append-text-property' is used, since it's better than
364 `propertize' or `add-face-text-property' in this case."
365 (font-lock-append-text-property 0 (length str) 'face face str)
368 (defun ivy-completions (name candidates)
369 "Return as text the current completions.
370 NAME is a string of words separated by spaces that is used to
372 CANDIDATES is a list of strings."
373 (let* ((re (ivy--regex name))
374 (cands (if (and (equal re ivy--old-re)
377 (setq ivy--old-re re)
380 (lambda (x) (string-match re x))
382 (tail (nthcdr ivy--index ivy--old-cands))
385 (setq ivy--length (length cands))
386 (when (and tail ivy--old-cands)
388 (null (setq idx (cl-position (pop tail) cands
390 (setq ivy--index (or idx 0)))
391 (setq ivy--old-cands cands)
392 (when (>= ivy--index ivy--length)
393 (setq ivy--index (max (1- ivy--length) 0)))
396 (let* ((half-height (/ ivy-height 2))
397 (start (max 0 (- ivy--index half-height)))
398 (end (min (+ start (1- ivy-height)) ivy--length))
399 (cands (cl-subseq cands start end))
400 (index (min ivy--index half-height (1- (length cands)))))
401 (setq ivy--current (copy-sequence (nth index cands)))
402 (setf (nth index cands)
403 (ivy--add-face ivy--current 'ivy-current-match))
404 (concat "\n" (mapconcat
406 (if (> (length s) ww)
407 (concat (substring s 0 (- ww 3)) "...")