Key bindings
* Global key bindings::
-* minibuffer key bindings::
+* Minibuffer key bindings::
-minibuffer key bindings
+Minibuffer key bindings
* Key bindings for navigation::
-* Key bindings for single selection, action, then exit minibuffer: Key bindings for single selection action then exit minibuffer.
-* Key bindings for multiple selections and actions, keep minibuffer open: Key bindings for multiple selections and actions keep minibuffer open.
+* Key bindings for single selection, action, then exit minibuffer: Key bindings for single selection action then exit minibuffer.
+* Key bindings for multiple selections and actions, keep minibuffer open: Key bindings for multiple selections and actions keep minibuffer open.
* Key bindings that alter minibuffer input::
* Other key bindings::
* Hydra in the minibuffer::
discoverability.
@subsubheading Minimalism
-Uncluttered minibuffer is minimalism. Ivy shows completion
-defaults, number of matches, and 10 candidate matches below the input
-line. Customize @verb{~ivy-length~} to adjust the number of candidate matches
-displayed in the minibuffer.
+Uncluttered minibuffer is minimalism. Ivy shows the completion
+defaults, the number of matches, and 10 candidate matches below the
+input line. Customize @verb{~ivy-length~} to adjust the number of candidate
+matches displayed in the minibuffer.
@subsubheading Simplicity
Simplicity is about Ivy's behavior in the minibuffer. It is also about
@menu
* Global key bindings::
-* minibuffer key bindings::
+* Minibuffer key bindings::
@end menu
@node Global key bindings
(global-set-key (kbd "C-c C-r") 'ivy-resume)
@end lisp
-@node minibuffer key bindings
-@section minibuffer key bindings
+@node Minibuffer key bindings
+@section Minibuffer key bindings
Ivy includes several minibuffer bindings, which are defined in the
@verb{~ivy-minibuffer-map~} keymap variable. The most frequently used ones
under their respective commands.
@menu
* Key bindings for navigation::
-* Key bindings for single selection, action, then exit minibuffer: Key bindings for single selection action then exit minibuffer.
-* Key bindings for multiple selections and actions, keep minibuffer open: Key bindings for multiple selections and actions keep minibuffer open.
+* Key bindings for single selection, action, then exit minibuffer: Key bindings for single selection action then exit minibuffer.
+* Key bindings for multiple selections and actions, keep minibuffer open: Key bindings for multiple selections and actions keep minibuffer open.
* Key bindings that alter minibuffer input::
* Other key bindings::
* Hydra in the minibuffer::
@end lisp
The default @verb{~ivy--regex-plus~} narrowing is always invoked unless
-specified otherwise. For example, file name completion can have its
-own custom completion function:
+specified otherwise. For example, file name completion may have a
+custom completion function:
@lisp
(setq ivy-re-builders-alist
large lists using @verb{~flx~} package's scoring mechanism, if it's
installed.
-@bye
\ No newline at end of file
+@bye
(defface ivy-confirm-face
'((t :foreground "ForestGreen" :inherit minibuffer-prompt))
- "Face used by Ivy for confirmation prompt.")
+ "Face used by Ivy for a confirmation prompt.")
(defface ivy-match-required-face
'((t :foreground "red" :inherit minibuffer-prompt))
- "Face used by Ivy for match required prompt.")
+ "Face used by Ivy for a match required prompt.")
(defface ivy-subdir
'((t (:inherit 'dired-directory)))
(defface ivy-modified-buffer
'((t :inherit 'default))
- "Face used by Ivy for highlighting those buffers visiting files.")
+ "Face used by Ivy for highlighting modified file visiting buffers.")
(defface ivy-remote
'((t (:foreground "#110099")))
:type 'integer)
(defcustom ivy-count-format "%-4d "
- "The style to use for displying the current candidate count for
-`ivy-read'. Set style to \"\" to suppress counts visiblity. Set
-style to \"(%d/%d) \" to display both the index and the count."
+ "The style to use for displaying the current candidate count for `ivy-read'.
+Set this to \"\" to suppress the count visibility.
+Set this to \"(%d/%d) \" to display both the index and the count."
:type '(choice
(const :tag "Count disabled" "")
(const :tag "Count matches" "%-4d ")
string))
(defcustom ivy-wrap nil
- "Wrap around after the first and last candidate."
+ "When non-nil, wrap around after the first and the last candidate."
:type 'boolean)
(defcustom ivy-display-style (unless (version< emacs-version "24.5") 'fancy)
(const :tag "Fancy" fancy)))
(defcustom ivy-on-del-error-function 'minibuffer-keyboard-quit
- "The handler for when `ivy-backward-delete-char' throws --
-usually a quick exit out of the minibuffer."
+ "The handler for when `ivy-backward-delete-char' throws.
+Usually a quick exit out of the minibuffer."
:type 'function)
(defcustom ivy-extra-directories '("../" "./")
caller)
(defvar ivy-last nil
- "The last parameter passed to `ivy-read'.
+ "The last parameters passed to `ivy-read'.
This should eventually become a stack so that you could use
`ivy-read' recursively.")
"History list of candidates entered in the minibuffer.
Maximum length of the history list is determined by the value
-of `history-length'")
+of `history-length'.")
(defvar ivy--directory nil
- "Current directory to use when completing file names.")
+ "Current directory when completing file names.")
(defvar ivy--length 0
"Store the amount of viable candidates.")
"Store the index of the current candidate.")
(defvar ivy-exit nil
- "Store 'done if the completion was successfully selected, otherwise store nil.")
+ "Store 'done if the completion was successfully selected.
+Otherwise, store nil.")
(defvar ivy--all-candidates nil
"Store the candidates passed to `ivy-read'.")
'(add-to-list 'avy-styles-alist '(ivy-avy . pre)))
(defun ivy-avy ()
- "Jump to a current ivy candidate."
+ "Jump to one of the current ivy candidates."
(interactive)
(unless (require 'avy nil 'noerror)
- (error "Avy package is not installed"))
+ (error "Package avy isn't installed"))
(let* ((avy-all-windows nil)
(avy-keys (or (cdr (assq 'ivy-avy avy-keys-alist))
avy-keys))
When SORT is t, use `ivy-sort-functions-alist' for sorting.
-ACTION is a lambda function call after selecting a result. It
+ACTION is a lambda function to call after selecting a result. It
takes a single string argument.
-UNWIND is a lambda function call before exiting.
+UNWIND is a lambda function to call before exiting.
-RE-BUILDER is a lambda function call to transform text into a
+RE-BUILDER is a lambda function to call to transform text into a
regex pattern.
MATCHER is to override matching.
DYNAMIC-COLLECTION is a boolean to specify if the list of
candidates is updated after each input by calling COLLECTION.
-CALLER is symbol to uniquely identify the caller to `ivy-read'.
+CALLER is a symbol to uniquely identify the caller to `ivy-read'.
It is used, along with COLLECTION, to determine which
customizations apply to the current completion session."
(let ((extra-actions (plist-get ivy--actions-list this-command)))
;;;###autoload
(defun ivy-completing-read (prompt collection
- &optional predicate require-match initial-input
- history def _inherit-input-method)
+ &optional predicate require-match initial-input
+ history def _inherit-input-method)
"Read a string in the minibuffer, with completion.
This interface conforms to `completing-read' and can be used for
PREDICATE limits completion to a subset of COLLECTION.
REQUIRE-MATCH is specified with a boolean value. See `completing-read'.
INITIAL-INPUT is a string that can be inserted into the minibuffer initially.
-_HISTORY is currently ignored.
+HISTORY is a list of previously selected inputs.
DEF is the default value.
_INHERIT-INPUT-METHOD is currently ignored."
(setq completing-read-function 'completing-read-default)))
(defun ivy--preselect-index (preselect candidates)
- "Return the index of PRESELECT from CANDIDATES."
+ "Return the index of PRESELECT in CANDIDATES."
(cond ((integerp preselect)
preselect)
((cl-position preselect candidates :test #'equal))
"Store pre-computed regex.")
(defun ivy--split (str)
- "Split STR into a list by single space characters.
-If any remaining consequtive spaces, stick left. This allows for
-\"quote\" N spaces by inputting N+1 spaces."
+ "Split STR into a list by single spaces.
+The remaining spaces stick to their left.
+This allows to \"quote\" N spaces by inputting N+1 spaces."
(let ((len (length str))
start0
(start1 0)
ATTENTION: This is just a proof of concept and may not work as
expected. Besides ignoring the order of the tokens where 'foo'
and 'bar', 'bar' and 'foo' are matched, it also matches multiple
-occurances of 'foo' and 'bar'. To ignore the sort order and avoid
+occurrences of 'foo' and 'bar'. To ignore the sort order and avoid
multiple matches, use `ivy-restrict-to-matches' instead.
"
(let* ((subs (split-string str " +" t))
(constrain-to-field nil (point-max))))))
(defun ivy--set-match-props (str match props)
- "Set STR text proprties that match MATCH to PROPS."
+ "Set STR text properties that match MATCH to PROPS."
(when (string-match match str)
(set-text-properties
(match-beginning 0)
(setq ivy--old-cands (ivy--sort name cands))))))
(defcustom ivy-sort-matches-functions-alist '((t . nil))
- "An alist of functions for sorting after each input change.
+ "An alist of functions used to sort the matching candidates.
-These functions are for sorting matching list of candidates after
-each input change. Sorting is applied repeatedly to the matching
-candidates if the list changes after each input change.
-
-`ivy-sort-functions-alist', on the other hand, sorts the whole
-collection of candidates only once.
+This is different from `ivy-sort-functions-alist', which is used
+to sort the whole collection only once. The functions taken from
+here are instead used on each input change, but they are used
+only on already matching candidates, not on all of them.
The alist KEY is a collection function or t to match previously
not matched collection functions.
(defun ivy-reverse-i-search ()
"Enter a recursive `ivy-read' session using the current history.
-The selected history element will be inserted into the minibufer."
+The selected history element will be inserted into the minibuffer."
(interactive)
(let ((enable-recursive-minibuffers t)
(history (symbol-value (ivy-state-history ivy-last)))
(defvar counsel-git-grep-cmd)
(defun ivy-occur ()
- "Stops completion and puts the current matches into a new buffer.
+ "Stop completion and put the current matches into a new buffer.
The new buffer remembers current action(s).
-While in the *ivy-occur* buffer, selecting a cadidate with RET or
+While in the *ivy-occur* buffer, selecting a candidate with RET or
a mouse click will call the appropriate action for that candidate.
There is no limit on the number of *ivy-occur* buffers."