emacs_config/elpa/ivy-0.13.1/ivy.info

This is ivy.info, produced by makeinfo version 6.5 from ivy.texi.

Ivy manual, version 0.13.0

   Ivy is an interactive interface for completion in Emacs.  Emacs uses
completion mechanism in a variety of contexts: code, menus, commands,
variables, functions, etc.  Completion entails listing, sorting,
filtering, previewing, and applying actions on selected items.  When
active, ‘ivy-mode’ completes the selection process by narrowing
available choices while previewing in the minibuffer.  Selecting the
final candidate is either through simple keyboard character inputs or
through powerful regular expressions.

   Copyright (C) 2015-2019 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.3 or any later version published by the Free Software
     Foundation; with no Invariant Sections, no Front-Cover Texts, and
     no Back-Cover Texts.  A copy of the license is included in the
     section entitled "GNU Free Documentation License".
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Ivy: (ivy).           Using Ivy for completion.
END-INFO-DIR-ENTRY


File: ivy.info,  Node: Top,  Next: Introduction,  Up: (dir)

Ivy User Manual
***************

* Menu:

* Introduction::
* Installation::
* Getting started::
* Key bindings::
* Completion Styles::
* Customization::
* Commands::
* API::
* Variable Index::
* Keystroke Index::

— The Detailed Node Listing —

Installation

* Installing from Emacs Package Manager::
* Installing from the Git repository::

Getting started

* Basic customization::

Key bindings

* Global 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 that alter the minibuffer input::
* Other key bindings::
* Hydra in the minibuffer::
* Saving the current completion session to a buffer::

Completion Styles

* ivy--regex-plus::
* ivy--regex-ignore-order::
* ivy--regex-fuzzy::

Customization

* Faces::
* Defcustoms::
* Actions::
* Packages::

Actions

* What are actions?::
* How can different actions be called?::
* How to modify the actions list?::
* Example - add two actions to each command::
* Example - define a new command with several actions::

Example - add two actions to each command

* How to undo adding the two actions::
* How to add actions to a specific command::

Example - define a new command with several actions

* Test the above function with ivy-occur::

Commands

* File Name Completion::
* Buffer Name Completion::
* Counsel commands::

File Name Completion

* Using TRAMP::

API

* Required arguments for ivy-read::
* Optional arguments for ivy-read::
* Example - counsel-describe-function::
* Example - counsel-locate::
* Example - ivy-read-with-extra-properties::



File: ivy.info,  Node: Introduction,  Next: Installation,  Prev: Top,  Up: Top

1 Introduction
**************

Ivy is for quick and easy selection from a list.  When Emacs prompts for
a string from a list of several possible choices, Ivy springs into
action to assist in narrowing and picking the right string from a vast
number of choices.

   Ivy strives for minimalism, simplicity, customizability and
discoverability.

Minimalism
..........

     Uncluttered minibuffer is minimalism.  Ivy shows the completion
     defaults, the number of matches, and 10 candidate matches below the
     input line.  Customize ‘ivy-height’ to adjust the number of
     candidate matches displayed in the minibuffer.

Simplicity
..........

     Simplicity is about Ivy’s behavior in the minibuffer.  It is also
     about the code interface to extend Ivy’s functionality.  The
     minibuffer area behaves as close to ‘fundamental-mode’ as possible.
     ‘SPC’ inserts a space, for example, instead of being bound to the
     more complex ‘minibuffer-complete-word’.  Ivy’s code uses
     easy-to-examine global variables; avoids needless complications
     with branch-introducing custom macros.

Customizability
...............

     Customizability is about being able to use different methods and
     interfaces of completion to tailor the selection process.  For
     example, adding a custom display function that points to a selected
     candidate with ‘>’, instead of highlighting the selected candidate
     with the ‘ivy-current-match’ face (see
     ‘ivy-format-functions-alist’).  Or take the customization of
     actions, say after the candidate function is selected.  ‘RET’ uses
     ‘counsel-describe-function’ to describe the function, whereas ‘M-o
     d’ jumps to that function’s definition in the code.  The ‘M-o’
     prefix can be uniformly used with characters like ‘d’ to group
     similar actions.

Discoverability
...............

     Ivy displays easily discoverable commands through the hydra
     facility.  ‘C-o’ in the minibuffer displays a hydra menu.  It opens
     up within an expanded minibuffer area.  Each menu item comes with
     short documentation strings and highlighted one-key completions.
     So discovering even seldom used keys is simply a matter of ‘C-o’ in
     the minibuffer while in the midst of the Ivy interaction.  This
     discoverability minimizes exiting Ivy interface for documentation
     look-ups.


File: ivy.info,  Node: Installation,  Next: Getting started,  Prev: Introduction,  Up: Top

2 Installation
**************

Install Ivy automatically through Emacs’s package manager, or manually
from Ivy’s development repository.

   Emacs 24.3 is the oldest version to run Ivy.  Emacs 24.4 is the
oldest version that runs Ivy with fancy faces display.

* Menu:

* Installing from Emacs Package Manager::
* Installing from the Git repository::


File: ivy.info,  Node: Installing from Emacs Package Manager,  Next: Installing from the Git repository,  Up: Installation

2.1 Installing from Emacs Package Manager
=========================================

‘M-x’ ‘package-install’ ‘RET’ ‘ivy’ ‘RET’

   Ivy is installed as part of ‘ivy’ package, which is available from
two different package archives, GNU ELPA and MELPA. For the latest
stable version, use the GNU ELPA archives using the above M-x command.

   For current hourly builds, use the MELPA archives.  In MELPA, Ivy is
split into three packages: ‘ivy’, ‘swiper’ and ‘counsel’; you can simply
install ‘counsel’ which will bring in the other two as dependencies.
See the code below for adding MELPA to the list of package archives:

     (require 'package)
     (add-to-list 'package-archives
     	     '("melpa" . "https://melpa.org/packages/"))

   After this do ‘M-x’ ‘package-refresh-contents’ ‘RET’, followed by
‘M-x’ ‘package-install’ ‘RET’ ‘counsel’ ‘RET’.

   For package manager details, see *note (emacs)Packages::.


File: ivy.info,  Node: Installing from the Git repository,  Prev: Installing from Emacs Package Manager,  Up: Installation

2.2 Installing from the Git repository
======================================

Why install from Git?
.....................

        • No need to wait for MELPA’s hourly builds
        • Easy to revert to previous versions
        • Contribute to Ivy’s development; send patches; pull requests

Configuration steps
...................

     First clone the Swiper repository with:

          cd ~/git && git clone https://github.com/abo-abo/swiper
          cd swiper && make compile

     Second, add these lines to the Emacs init file:

          (add-to-list 'load-path "~/git/swiper/")
          (require 'ivy)

     Then, update the code with:

          git pull
          make


File: ivy.info,  Node: Getting started,  Next: Key bindings,  Prev: Installation,  Up: Top

3 Getting started
*****************

First enable Ivy completion everywhere:

     (ivy-mode 1)

   Note: ‘ivy-mode’ can be toggled on and off with ‘M-x’ ‘ivy-mode’.

* Menu:

* Basic customization::


File: ivy.info,  Node: Basic customization,  Up: Getting started

3.1 Basic customization
=======================

Here are some basic settings particularly useful for new Ivy users:

     (setq ivy-use-virtual-buffers t)
     (setq ivy-count-format "(%d/%d) ")

   If you want, you can go without any customizations at all.  The above
settings are the most bang for the buck in terms of customization.  So
users that typically don’t like customize a lot are advised to look at
these settings first.

   For more advanced customizations, refer to ‘M-x describe-variable’
documentation.


File: ivy.info,  Node: Key bindings,  Next: Completion Styles,  Prev: Getting started,  Up: Top

4 Key bindings
**************

* Menu:

* Global key bindings::
* Minibuffer key bindings::


File: ivy.info,  Node: Global key bindings,  Next: Minibuffer key bindings,  Up: Key bindings

4.1 Global key bindings
=======================

Here is a list of commands that are useful to be bound globally, along
with some sample bindings:

Ivy-based interface to standard commands
........................................

          (global-set-key (kbd "C-s") 'swiper-isearch)
          (global-set-key (kbd "M-x") 'counsel-M-x)
          (global-set-key (kbd "C-x C-f") 'counsel-find-file)
          (global-set-key (kbd "M-y") 'counsel-yank-pop)
          (global-set-key (kbd "<f1> f") 'counsel-describe-function)
          (global-set-key (kbd "<f1> v") 'counsel-describe-variable)
          (global-set-key (kbd "<f1> l") 'counsel-find-library)
          (global-set-key (kbd "<f2> i") 'counsel-info-lookup-symbol)
          (global-set-key (kbd "<f2> u") 'counsel-unicode-char)
          (global-set-key (kbd "<f2> j") 'counsel-set-variable)
          (global-set-key (kbd "C-x b") 'ivy-switch-buffer)
          (global-set-key (kbd "C-c v") 'ivy-push-view)
          (global-set-key (kbd "C-c V") 'ivy-pop-view)

Ivy-based interface to shell and system tools
.............................................

          (global-set-key (kbd "C-c c") 'counsel-compile)
          (global-set-key (kbd "C-c g") 'counsel-git)
          (global-set-key (kbd "C-c j") 'counsel-git-grep)
          (global-set-key (kbd "C-c L") 'counsel-git-log)
          (global-set-key (kbd "C-c k") 'counsel-rg)
          (global-set-key (kbd "C-c m") 'counsel-linux-app)
          (global-set-key (kbd "C-c n") 'counsel-fzf)
          (global-set-key (kbd "C-x l") 'counsel-locate)
          (global-set-key (kbd "C-c J") 'counsel-file-jump)
          (global-set-key (kbd "C-S-o") 'counsel-rhythmbox)
          (global-set-key (kbd "C-c w") 'counsel-wmctrl)

Ivy-resume and other commands
.............................

     ‘ivy-resume’ resumes the last Ivy-based completion.

          (global-set-key (kbd "C-c C-r") 'ivy-resume)
          (global-set-key (kbd "C-c b") 'counsel-bookmark)
          (global-set-key (kbd "C-c d") 'counsel-descbinds)
          (global-set-key (kbd "C-c g") 'counsel-git)
          (global-set-key (kbd "C-c o") 'counsel-outline)
          (global-set-key (kbd "C-c t") 'counsel-load-theme)
          (global-set-key (kbd "C-c F") 'counsel-org-file)

   You can also enable ‘counsel-mode’ to make some global key binding
remapping for you.


File: ivy.info,  Node: Minibuffer key bindings,  Prev: Global key bindings,  Up: Key bindings

4.2 Minibuffer key bindings
===========================

Ivy includes several minibuffer bindings, which are defined in the
‘ivy-minibuffer-map’ keymap variable.  The most frequently used ones are
described here.

   ‘swiper’ or ‘counsel-M-x’ add more key bindings through the ‘keymap’
argument to ‘ivy-read’.  These keys, also active in the minibuffer, are
described under their respective commands.

   A key feature of ‘ivy-minibuffer-map’ is its full editing capability
where the familiar ‘C-a’, ‘C-f’, ‘M-d’, ‘M-DEL’, ‘M-b’, ‘M-w’, ‘C-k’,
‘C-y’ key bindings work the same as in ‘fundamental-mode’.

* 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 that alter the minibuffer input::
* Other key bindings::
* Hydra in the minibuffer::
* Saving the current completion session to a buffer::


File: ivy.info,  Node: Key bindings for navigation,  Next: Key bindings for single selection action then exit minibuffer,  Up: Minibuffer key bindings

4.2.1 Key bindings for navigation
---------------------------------

   • ‘C-n’ (‘ivy-next-line’) selects the next candidate
   • ‘C-p’ (‘ivy-previous-line’) selects the previous candidate
   • ‘M-<’ (‘ivy-beginning-of-buffer’) selects the first candidate
   • ‘M->’ (‘ivy-end-of-buffer’) selects the last candidate
   • ‘C-v’ (‘ivy-scroll-up-command’) scrolls up by ‘ivy-height’ lines
   • ‘M-v’ (‘ivy-scroll-down-command’) scrolls down by ‘ivy-height’
     lines

 -- User Option: ivy-wrap
     Specifies the wrap-around behavior for ‘C-n’ and ‘C-p’.  When
     ‘ivy-wrap’ is set to ‘t’, ‘ivy-next-line’ and ‘ivy-previous-line’
     will cycle past the last and the first candidates respectively.

     Wrap-around behavior is off by default.

 -- User Option: ivy-height
     Use this option to adjust the minibuffer height, which also affects
     scroll size when using ‘C-v’ and ‘M-v’ key bindings.

     ‘ivy-height’ is 10 lines by default.


File: ivy.info,  Node: Key bindings for single selection action then exit minibuffer,  Next: Key bindings for multiple selections and actions keep minibuffer open,  Prev: Key bindings for navigation,  Up: Minibuffer key bindings

4.2.2 Key bindings for single selection, action, then exit minibuffer
---------------------------------------------------------------------

Ivy can offer several actions from which to choose which action to run.
This "calling an action" operates on the selected candidate.  For
example, when viewing a list of files, one action could open it for
editing, one to view it, another to invoke a special function, and so
on.  Custom actions can be added to this interface.  The precise action
to call on the selected candidate can be delayed until after the
narrowing is completed.  No need to exit the interface if unsure which
action to run.  This delayed flexibility and customization of actions
extends usability of lists in Emacs.

‘C-m’ or ‘RET’ (‘ivy-done’)
...........................

     Calls the default action and then exits the minibuffer.

‘M-o’ (‘ivy-dispatching-done’)
..............................

     Presents valid actions from which to choose.  When only one action
     is available, there is no difference between ‘M-o’ and ‘C-m’.

‘C-j’ (‘ivy-alt-done’)
......................

     When completing file names, selects the current directory candidate
     and starts a new completion session there.  Otherwise, it is the
     same as ‘ivy-done’.

‘TAB’ (‘ivy-partial-or-done’)
.............................

     Attempts partial completion, extending current input as much as
     possible.  ‘TAB TAB’ is the same as ‘C-j’ (‘ivy-alt-done’).

     Example ERT test:

          (should
           (equal (ivy-with
          	 '(progn
          	   (ivy-read "Test: " '("can do" "can't, sorry" "other"))
          	   ivy-text)
          	 "c <tab>")
          	"can"))

‘C-M-j’ (‘ivy-immediate-done’)
..............................

     Exits with _the current input_ instead of _the current candidate_
     (like other commands).

     This is useful e.g.  when you call ‘find-file’ to create a new
     file, but the desired name matches an existing file.  In that case,
     using ‘C-j’ would select that existing file, which isn’t what you
     want - use this command instead.

‘C-'’ (‘ivy-avy’)
.................

     Uses avy to select one of the candidates on the current candidate
     page.  This can often be faster than multiple ‘C-n’ or ‘C-p’
     keystrokes followed by ‘C-m’.


File: ivy.info,  Node: Key bindings for multiple selections and actions keep minibuffer open,  Next: Key bindings that alter the minibuffer input,  Prev: Key bindings for single selection action then exit minibuffer,  Up: Minibuffer key bindings

4.2.3 Key bindings for multiple selections and actions, keep minibuffer open
----------------------------------------------------------------------------

For repeatedly applying multiple actions or acting on multiple
candidates, Ivy does not close the minibuffer between commands.  It
keeps the minibuffer open for applying subsequent actions.

   Adding an extra meta key to the normal key chord invokes the special
version of the regular commands that enables applying multiple actions.

‘C-M-m’ (‘ivy-call’)
....................

     Is the non-exiting version of ‘C-m’ (‘ivy-done’).

     Instead of closing the minibuffer, ‘C-M-m’ allows selecting another
     candidate or another action.  For example, ‘C-M-m’ on functions
     list invokes ‘describe-function’.  When combined with ‘C-n’,
     function descriptions can be invoked quickly in succession.

‘C-M-o’ (‘ivy-dispatching-call’)
................................

     Is the non-exiting version of ‘M-o’ (‘ivy-dispatching-done’).

     For example, during the ‘counsel-rhythmbox’ completion, press
     ‘C-M-o e’ to en-queue the selected candidate, followed by ‘C-n C-m’
     to play the next candidate - the current action reverts to the
     default one after ‘C-M-o’.

‘C-M-n’ (‘ivy-next-line-and-call’)
..................................

     Combines ‘C-n’ and ‘C-M-m’.  Moves to next line and applies an
     action.

     Comes in handy when opening multiple files from
     ‘counsel-find-file’, ‘counsel-git-grep’, ‘counsel-ag’,
     ‘counsel-rg’, or ‘counsel-locate’ lists.  Just hold ‘C-M-n’ for
     rapid-fire default action on each successive element of the list.

‘C-M-p’ (‘ivy-previous-line-and-call’)
......................................

     Combines ‘C-p’ and ‘C-M-m’.

     Similar to the above except it moves through the list in the other
     direction.

‘ivy-resume’
............

     Recalls the state of the completion session just before its last
     exit.

     Useful after an accidental ‘C-m’ (‘ivy-done’).


File: ivy.info,  Node: Key bindings that alter the minibuffer input,  Next: Other key bindings,  Prev: Key bindings for multiple selections and actions keep minibuffer open,  Up: Minibuffer key bindings

4.2.4 Key bindings that alter the minibuffer input
--------------------------------------------------

‘M-n’ (‘ivy-next-history-element’)
..................................

     Cycles forward through the Ivy command history.

     Ivy updates an internal history list after each action.  When this
     history list is empty, ‘M-n’ inserts symbol (or URL) at point into
     the minibuffer.

‘M-p’ (‘ivy-previous-history-element’)
......................................

     Cycles forward through the Ivy command history.

‘M-i’ (‘ivy-insert-current’)
............................

     Inserts the current candidate into the minibuffer.

     Useful for copying and renaming files, for example: ‘M-i’ to insert
     the original file name string, edit it, and then ‘C-m’ to complete
     the renaming.

‘M-j’ (‘ivy-yank-word’)
.......................

     Inserts the sub-word at point into the minibuffer.

     This is similar to ‘C-s C-w’ with ‘isearch’.  Ivy reserves ‘C-w’
     for ‘kill-region’.  See also ‘ivy-yank-symbol’ and ‘ivy-yank-char’.

‘S-SPC’ (‘ivy-restrict-to-matches’)
...................................

     Deletes the current input, and resets the candidates list to the
     currently restricted matches.

     This is how Ivy provides narrowing in successive tiers.

‘C-r’ (‘ivy-reverse-i-search’)
..............................

     Starts a recursive completion session through the command’s
     history.

     This works just like ‘C-r’ at the bash command prompt, where the
     completion candidates are the history items.  Upon completion, the
     selected candidate string is inserted into the minibuffer.


File: ivy.info,  Node: Other key bindings,  Next: Hydra in the minibuffer,  Prev: Key bindings that alter the minibuffer input,  Up: Minibuffer key bindings

4.2.5 Other key bindings
------------------------

‘M-w’ (‘ivy-kill-ring-save’)
............................

     Copies selected candidates to the kill ring.

     Copies the region if the region is active.


File: ivy.info,  Node: Hydra in the minibuffer,  Next: Saving the current completion session to a buffer,  Prev: Other key bindings,  Up: Minibuffer key bindings

4.2.6 Hydra in the minibuffer
-----------------------------

‘C-o’ (‘hydra-ivy/body’)
........................

     Invokes the hydra menu with short key bindings.

   When Hydra is active, minibuffer editing is disabled and menus
display short aliases:

Short   Normal      Command name
------------------------------------------------
‘o’     ‘C-g’       ‘keyboard-escape-quit’
‘j’     ‘C-n’       ‘ivy-next-line’
‘k’     ‘C-p’       ‘ivy-previous-line’
‘h’     ‘M-<’       ‘ivy-beginning-of-buffer’
‘l’     ‘M->’       ‘ivy-end-of-buffer’
‘d’     ‘C-m’       ‘ivy-done’
‘f’     ‘C-j’       ‘ivy-alt-done’
‘g’     ‘C-M-m’     ‘ivy-call’
‘u’     ‘C-c C-o’   ‘ivy-occur’

   Hydra reduces key strokes, for example: ‘C-n C-n C-n C-n’ is ‘C-o
jjjj’ in Hydra.

   Hydra menu offers these additional bindings:

‘c’ (‘ivy-toggle-calling’)
..........................

     Toggle calling the action after each candidate change.  It modifies
     ‘j’ to ‘jg’, ‘k’ to ‘kg’ etc.

‘m’ (‘ivy-rotate-preferred-builders’)
.....................................

     Rotate the current regexp matcher.

‘>’ (‘ivy-minibuffer-grow’)
...........................

     Increase ‘ivy-height’ for the current minibuffer.

‘<’ (‘ivy-minibuffer-shrink’)
.............................

     Decrease ‘ivy-height’ for the current minibuffer.

‘w’ (‘ivy-prev-action’)
.......................

     Select the previous action.

‘s’ (‘ivy-next-action’)
.......................

     Select the next action.

‘a’ (‘ivy-read-action’)
.......................

     Use a menu to select an action.

‘C’ (‘ivy-toggle-case-fold’)
............................

     Toggle case folding (match both upper and lower case characters for
     lower case input).

   Hydra menu also offers bindings for marking multiple candidates:

Key     Command name
--------------------------------
‘m’     ‘ivy-mark’
‘u’     ‘ivy-unmark’
‘DEL’   ‘ivy-unmark-backward’
‘t’     ‘ivy-toggle-marks’

   The action is called on each marked candidate one by one.


File: ivy.info,  Node: Saving the current completion session to a buffer,  Prev: Hydra in the minibuffer,  Up: Minibuffer key bindings

4.2.7 Saving the current completion session to a buffer
-------------------------------------------------------

‘C-c C-o’ (‘ivy-occur’)
.......................

     Saves the current candidates to a new buffer and exits completion.

   The new buffer is read-only and has a few useful bindings defined.

‘RET’ or ‘f’ (‘ivy-occur-press’)
................................

     Call the current action on the selected candidate.

‘mouse-1’ (‘ivy-occur-click’)
.............................

     Call the current action on the selected candidate.

‘j’ (‘next-line’)
.................

     Move to next line.

‘k’ (‘previous-line’)
.....................

     Move to previous line.

‘a’ (‘ivy-occur-read-action’)
.............................

     Read an action and make it current for this buffer.

‘o’ (‘ivy-occur-dispatch’)
..........................

     Read an action and call it on the selected candidate.

‘q’ (‘quit-window’)
...................

     Bury the current buffer.

   Ivy has no limit on the number of active buffers like these.

   Ivy takes care of naming buffers uniquely by constructing descriptive
names.  For example: ‘*ivy-occur counsel-describe-variable "function$*’.


File: ivy.info,  Node: Completion Styles,  Next: Customization,  Prev: Key bindings,  Up: Top

5 Completion Styles
*******************

Ivy’s completion functions rely on a regex builder - a function that
transforms a string input to a string regex.  All current candidates
simply have to match this regex.  Each collection can be assigned its
own regex builder by customizing ‘ivy-re-builders-alist’.

   The keys of this alist are collection names, and the values are one
of the following:
   • ‘ivy--regex’
   • ‘ivy--regex-plus’
   • ‘ivy--regex-ignore-order’
   • ‘ivy--regex-fuzzy’
   • ‘regexp-quote’

   A catch-all key, ‘t’, applies to all collections that don’t have
their own key.

   The default is:

     (setq ivy-re-builders-alist
           '((t . ivy--regex-plus)))

   This example shows a custom regex builder assigned to file name
completion:

     (setq ivy-re-builders-alist
           '((read-file-name-internal . ivy--regex-fuzzy)
     	(t . ivy--regex-plus)))

   Here, ‘read-file-name-internal’ is a function that is passed as the
second argument to ‘completing-read’ for file name completion.

   The regex builder resolves as follows (in order of priority):
  1. ‘re-builder’ argument passed to ‘ivy-read’.
  2. ‘collection’ argument passed to ‘ivy-read’ is a function and has an
     entry on ‘ivy-re-builders-alist’.
  3. ‘caller’ argument passed to ‘ivy-read’ has an entry on
     ‘ivy-re-builders-alist’.
  4. ‘this-command’ has an entry on ‘ivy-re-builders-alist’.
  5. ‘t’ has an entry on ‘ivy-re-builders-alist’.
  6. ‘ivy--regex’.

* Menu:

* ivy--regex-plus::
* ivy--regex-ignore-order::
* ivy--regex-fuzzy::


File: ivy.info,  Node: ivy--regex-plus,  Next: ivy--regex-ignore-order,  Up: Completion Styles

5.1 ivy–regex-plus
==================

‘ivy--regex-plus’ is Ivy’s default completion method.

   ‘ivy--regex-plus’ matches by splitting the input by spaces and
rebuilding it into a regex.

   As the search string is typed in Ivy’s minibuffer, it is transformed
into valid regex syntax.  If the string is ‘"for example"’, it is
transformed into

     "\\(for\\).*\\(example\\)"

   which in regex terminology matches ‘"for"’ followed by a wild card
and then ‘"example"’.  Note how Ivy uses the space character to build
wild cards.  To match a literal white space, use an extra space.  So to
match one space type two spaces, to match two spaces type three spaces,
and so on.

   As Ivy transforms typed characters into regex strings, it provides an
intuitive feedback through font highlights.

   Ivy supports regexp negation with ‘"!"’.  For example, ‘"define key !
ivy quit"’ first selects everything matching ‘"define.*key"’, then
removes everything matching ‘"ivy"’, and finally removes everything
matching ‘"quit"’.  What remains is the final result set of the negation
regexp.

   Since Ivy treats minibuffer input as a regexp, the standard regexp
identifiers work: ‘"^"’, ‘"$"’, ‘"\b"’ or ‘"[a-z]"’.  The exceptions are
spaces, which translate to ‘".*"’, and ‘"!"’ that signal the beginning
of a negation group.


File: ivy.info,  Node: ivy--regex-ignore-order,  Next: ivy--regex-fuzzy,  Prev: ivy--regex-plus,  Up: Completion Styles

5.2 ivy–regex-ignore-order
==========================

‘ivy--regex-ignore-order’ ignores the order of regexp tokens when
searching for matching candidates.  For instance, the input ‘"for
example"’ will match ‘"example test for"’.


File: ivy.info,  Node: ivy--regex-fuzzy,  Prev: ivy--regex-ignore-order,  Up: Completion Styles

5.3 ivy–regex-fuzzy
===================

‘ivy--regex-fuzzy’ splits each character with a wild card.  Searching
for ‘"for"’ returns all ‘"f.*o.*r"’ matches, resulting in a large number
of hits.  Yet some searches need these extra hits.  Ivy sorts such large
lists using ‘flx’ package’s scoring mechanism, if it’s installed.

   ‘C-o m’ toggles the current regexp builder.


File: ivy.info,  Node: Customization,  Next: Commands,  Prev: Completion Styles,  Up: Top

6 Customization
***************

* Menu:

* Faces::
* Defcustoms::
* Actions::
* Packages::


File: ivy.info,  Node: Faces,  Next: Defcustoms,  Up: Customization

6.1 Faces
=========

‘ivy-current-match’
...................

     Highlights the currently selected candidate.

‘ivy-minibuffer-match-face-1’
.............................

     Highlights the background of the match.

‘ivy-minibuffer-match-face-2’
.............................

     Highlights the first (modulo 3) matched group.

‘ivy-minibuffer-match-face-3’
.............................

     Highlights the second (modulo 3) matched group.

‘ivy-minibuffer-match-face-4’
.............................

     Highlights the third (modulo 3) matched group.

‘ivy-confirm-face’
..................

     Highlights the "(confirm)" part of the prompt.

     When ‘confirm-nonexistent-file-or-buffer’ set to ‘t’, then
     confirming non-existent files in ‘ivy-mode’ requires an additional
     ‘RET’.

     The confirmation prompt will use this face.

     For example:

          (setq confirm-nonexistent-file-or-buffer t)

     Then call ‘find-file’, enter "eldorado" and press ‘RET’ - the
     prompt will be appended with "(confirm)".  Press ‘RET’ once more to
     confirm, or any key to continue the completion.

‘ivy-match-required-face’
.........................

     Highlights the "(match required)" part of the prompt.

     When completions have to match available candidates and cannot take
     random input, the "(match required)" prompt signals this
     constraint.

     For example, call ‘describe-variable’, enter "waldo" and press
     ‘RET’ - "(match required)" is prompted.  Press any key for the
     prompt to disappear.

‘ivy-subdir’
............

     Highlights directories when completing file names.

‘ivy-remote’
............

     Highlights remote files when completing file names.

‘ivy-virtual’
.............

     Highlights virtual buffers when completing buffer names.

     Virtual buffers correspond to bookmarks and recent files list,
     ‘recentf’.

     Enable virtual buffers with:

          (setq ivy-use-virtual-buffers t)

‘ivy-modified-buffer’
.....................

     Highlights modified buffers when switching buffer.

‘ivy-modified-outside-buffer’
.............................

     Highlights buffers modified outside Emacs when switching buffer.

     This takes precedence over ‘ivy-modified-buffer’.


File: ivy.info,  Node: Defcustoms,  Next: Actions,  Prev: Faces,  Up: Customization

6.2 Defcustoms
==============

 -- User Option: ivy-count-format
     A string that specifies display of number of candidates and current
     candidate, if one exists.

     The number of matching candidates by default is shown as a right-
     padded integer value.

     To disable showing the number of candidates:

          (setq ivy-count-format "")

     To also display the current candidate:

          (setq ivy-count-format "(%d/%d) ")

     The ‘format’-style switches this variable uses are described in the
     ‘format’ documentation.

 -- User Option: ivy-display-style
     Specifies highlighting candidates in the minibuffer.

     The default setting is ‘'fancy’ in Emacs versions 24.4 or newer.

     Set ‘ivy-display-style’ to ‘nil’ for a plain minibuffer.

 -- User Option: ivy-on-del-error-function
     Specifies what to do when ‘DEL’ (‘ivy-backward-delete-char’) fails.

     This is usually the case when there is no text left to delete,
     i.e., when ‘DEL’ is typed at the beginning of the minibuffer.

     The default behavior is to quit the completion after ‘DEL’ – a
     handy key to invoke after mistakenly triggering a completion.


File: ivy.info,  Node: Actions,  Next: Packages,  Prev: Defcustoms,  Up: Customization

6.3 Actions
===========

* Menu:

* What are actions?::
* How can different actions be called?::
* How to modify the actions list?::
* Example - add two actions to each command::
* Example - define a new command with several actions::


File: ivy.info,  Node: What are actions?,  Next: How can different actions be called?,  Up: Actions

6.3.1 What are actions?
-----------------------

An action is a function that is called after you select a candidate
during completion.  This function takes a single string argument, which
is the selected candidate.

Window context when calling an action
.....................................

     Currently, the action is executed in the minibuffer window context.
     This means e.g.  that if you call ‘insert’ the text will be
     inserted into the minibuffer.

     If you want to execute the action in the initial window from which
     the completion started, use the ‘with-ivy-window’ wrapper macro.

          (defun ivy-insert-action (x)
            (with-ivy-window
              (insert x)))


File: ivy.info,  Node: How can different actions be called?,  Next: How to modify the actions list?,  Prev: What are actions?,  Up: Actions

6.3.2 How can different actions be called?
------------------------------------------

   • ‘C-m’ (‘ivy-done’) calls the current action.
   • ‘M-o’ (‘ivy-dispatching-done’) presents available actions for
     selection, calls it after selection, and then exits.
   • ‘C-M-o’ (‘ivy-dispatching-call’) presents available actions for
     selection, calls it after selection, and then does not exit.


File: ivy.info,  Node: How to modify the actions list?,  Next: Example - add two actions to each command,  Prev: How can different actions be called?,  Up: Actions

6.3.3 How to modify the actions list?
-------------------------------------

Currently, you can append any amount of your own actions to the default
list of actions.  This can be done either for a specific command, or for
all commands at once.

   Usually, the command has only one default action.  The convention is
to use single letters when selecting a command, and the letter ‘o’ is
designated for the default command.  This way, ‘M-o o’ should be always
equivalent to ‘C-m’.


File: ivy.info,  Node: Example - add two actions to each command,  Next: Example - define a new command with several actions,  Prev: How to modify the actions list?,  Up: Actions

6.3.4 Example - add two actions to each command
-----------------------------------------------

The first action inserts the current candidate into the Ivy window - the
window from which ‘ivy-read’ was called.

   The second action copies the current candidate to the kill ring.

     (defun ivy-yank-action (x)
       (kill-new x))

     (defun ivy-copy-to-buffer-action (x)
       (with-ivy-window
         (insert x)))

     (ivy-set-actions
      t
      '(("i" ivy-copy-to-buffer-action "insert")
        ("y" ivy-yank-action "yank")))

   Then in any completion session, ‘M-o y’ invokes ‘ivy-yank-action’,
and ‘M-o i’ invokes ‘ivy-copy-to-buffer-action’.

* Menu:

* How to undo adding the two actions::
* How to add actions to a specific command::


File: ivy.info,  Node: How to undo adding the two actions,  Next: How to add actions to a specific command,  Up: Example - add two actions to each command

6.3.4.1 How to undo adding the two actions
..........................................

Since ‘ivy-set-actions’ modifies the internal dictionary with new data,
set the extra actions list to ‘nil’ by assigning ‘nil’ value to the ‘t’
key as follows:

     (ivy-set-actions t nil)


File: ivy.info,  Node: How to add actions to a specific command,  Prev: How to undo adding the two actions,  Up: Example - add two actions to each command

6.3.4.2 How to add actions to a specific command
................................................

Use the command name as the key:

     (ivy-set-actions
      'swiper
      '(("i" ivy-copy-to-buffer-action "insert")
        ("y" ivy-yank-action "yank")))


File: ivy.info,  Node: Example - define a new command with several actions,  Prev: Example - add two actions to each command,  Up: Actions

6.3.5 Example - define a new command with several actions
---------------------------------------------------------

     (defun my-action-1 (x)
       (message "action-1: %s" x))

     (defun my-action-2 (x)
       (message "action-2: %s" x))

     (defun my-action-3 (x)
       (message "action-3: %s" x))

     (defun my-command-with-3-actions ()
       (interactive)
       (ivy-read "test: " '("foo" "bar" "baz")
     	    :action '(1
     		      ("o" my-action-1 "action 1")
     		      ("j" my-action-2 "action 2")
     		      ("k" my-action-3 "action 3"))))

   The number 1 above is the index of the default action.  Each action
has its own string description for easy selection.

* Menu:

* Test the above function with ivy-occur::


File: ivy.info,  Node: Test the above function with ivy-occur,  Up: Example - define a new command with several actions

6.3.5.1 Test the above function with ‘ivy-occur’
................................................

To examine each action with each candidate in a key-efficient way, try:

   • Call ‘my-command-with-3-actions’
   • Press ‘C-c C-o’ to close the completion window and move to an
     ivy-occur buffer
   • Press ‘kkk’ to move to the first candidate, since the point is most
     likely at the end of the buffer
   • Press ‘oo’ to call the first action
   • Press ‘oj’ and ‘ok’ to call the second and the third actions
   • Press ‘j’ to move to the next candidate
   • Press ‘oo’, ‘oj’, ‘ok’
   • Press ‘j’ to move to the next candidate
   • and so on...


File: ivy.info,  Node: Packages,  Prev: Actions,  Up: Customization

6.4 Packages
============

‘org-mode’
..........

     ‘org-mode’ versions 8.3.3 or later obey ‘completing-read-function’
     (which ‘ivy-mode’ sets).  Try refiling headings with similar names
     to appreciate ‘ivy-mode’.

‘magit’
.......

     Uses ivy by default if Ivy is installed.

‘find-file-in-project’
......................

     Uses ivy by default if Ivy is installed.

‘projectile’
............

     Projectile requires this setting for ivy completion:

          (setq projectile-completion-system 'ivy)

‘helm-make’
...........

     Helm-make requires this setting for ivy completion.

          (setq helm-make-completion-method 'ivy)

automatically integrated packages
.................................

     Ivy re-uses the following packages if they are installed: ‘avy’,
     ‘amx’ or ‘smex’, ‘flx’, and ‘wgrep’.


File: ivy.info,  Node: Commands,  Next: API,  Prev: Customization,  Up: Top

7 Commands
**********

* Menu:

* File Name Completion::
* Buffer Name Completion::
* Counsel commands::


File: ivy.info,  Node: File Name Completion,  Next: Buffer Name Completion,  Up: Commands

7.1 File Name Completion
========================

Since file name completion is ubiquitous, Ivy provides extra bindings
that work here:

‘C-j’ (‘ivy-alt-done’)
......................

     On a directory, restarts completion from that directory.

     On a file or ‘./’, exit completion with the selected candidate.

‘DEL’ (‘ivy-backward-delete-char’)
..................................

     Restart the completion in the parent directory if current input is
     empty.

‘//’ (‘self-insert-command’)
............................

     Switch to the root directory.

‘~’ (‘self-insert-command’)
...........................

     Switch to the home directory.

‘/’ (‘self-insert-command’)
...........................

     If the current input matches an existing directory name exactly,
     switch the completion to that directory.

‘M-r’ (‘ivy-toggle-regexp-quote’)
.................................

     Toggle between input as regexp or not.

     Switch to matching literally since file names include ‘.’, which is
     for matching any char in regexp mode.
 -- User Option: ivy-extra-directories
     Decide if you want to see ‘../’ and ‘./’ during file name
     completion.

     Reason to remove: ‘../’ is the same as ‘DEL’.

     Reason not to remove: navigate anywhere with only ‘C-n’, ‘C-p’ and
     ‘C-j’.

     Likewise, ‘./’ can be removed.

History
.......

     File history works the same with ‘M-p’, ‘M-n’, and ‘C-r’, but uses
     a custom code for file name completion that cycles through files
     previously opened.  It also works with TRAMP files.

* Menu:

* Using TRAMP::


File: ivy.info,  Node: Using TRAMP,  Up: File Name Completion

7.1.1 Using TRAMP
-----------------

‘~’ (tilde)
...........

     Move to the home directory.  Either the local or the remote one,
     depending on the current directory.  The boolean option
     ‘ivy-magic-tilde’ decides whether the binding to do this is ‘~’ or
     ‘~/’.

‘//’ (double slash)
...................

     Move to the root directory.  Either the local or the remote one,
     depending on the current directory.  Here, you can also select a
     TRAMP connection method, such as ‘ssh’ or ‘scpx’.

‘/ C-j’
.......

     Move the the local root directory.

‘~~’
....

     Move to the local home directory.

   From any directory, with the empty input, inputting ‘/ssh:’ and
pressing ‘C-j’ (or ‘RET’, which is the same thing) completes for host
and user names.

   For ‘/ssh:user@’ input, completes the domain name.

   ‘C-i’ works in a similar way to the default completion.

   You can also get sudo access for the current directory by inputting
‘/sudo::’ ‘RET’.  Using ‘/sudo:’ (i.e.  single colon instead of double)
will result in a completion session for the desired user.

   Multi-hopping is possible, although a bit complex.

Example : connect to a remote host ‘cloud’ and open a file with ‘sudo’ there
............................................................................

        • ‘C-x C-f’ ‘/ssh:cloud|sudo:root:/’.


File: ivy.info,  Node: Buffer Name Completion,  Next: Counsel commands,  Prev: File Name Completion,  Up: Commands

7.2 Buffer Name Completion
==========================

 -- User Option: ivy-use-virtual-buffers
     When non-nil, add ‘recentf-mode’ and bookmarks to
     ‘ivy-switch-buffer’ completion candidates.

     Adding this to Emacs init file:

          (setq ivy-use-virtual-buffers t)
     will add additional virtual buffers to the buffers list for recent
     files.  Selecting such virtual buffers, which are highlighted with
     ‘ivy-virtual’ face, will open the corresponding file.


File: ivy.info,  Node: Counsel commands,  Prev: Buffer Name Completion,  Up: Commands

7.3 Counsel commands
====================

The main advantages of ‘counsel-’ functions over their basic equivalents
in ‘ivy-mode’ are:

  1. Multi-actions and non-exiting actions work.
  2. ‘ivy-resume’ can resume the last completion session.
  3. Customize ‘ivy-set-actions’, ‘ivy-re-builders-alist’.
  4. Customize individual keymaps, such as ‘counsel-describe-map’,
     ‘counsel-git-grep-map’, or ‘counsel-find-file-map’, instead of
     customizing ‘ivy-minibuffer-map’ that applies to all completion
     sessions.


File: ivy.info,  Node: API,  Next: Variable Index,  Prev: Commands,  Up: Top

8 API
*****

The main (and only) entry point is the ‘ivy-read’ function.  It takes
two required arguments and many optional arguments that can be passed by
a key.  The optional ‘:action’ argument is highly recommended for
features such as multi-actions, non-exiting actions, ‘ivy-occur’ and
‘ivy-resume’.

* Menu:

* Required arguments for ivy-read::
* Optional arguments for ivy-read::
* Example - counsel-describe-function::
* Example - counsel-locate::
* Example - ivy-read-with-extra-properties::


File: ivy.info,  Node: Required arguments for ivy-read,  Next: Optional arguments for ivy-read,  Up: API

8.1 Required arguments for ‘ivy-read’
=====================================

‘prompt’
........

     A prompt string normally ending in a colon and a space.
     ‘ivy-count-format’ is prepended to it during completion.

‘collection’
............

     Either a list of strings, a function, an alist or a hash table.

     If a function, then it has to be compatible with ‘all-completions’.


File: ivy.info,  Node: Optional arguments for ivy-read,  Next: Example - counsel-describe-function,  Prev: Required arguments for ivy-read,  Up: API

8.2 Optional arguments for ‘ivy-read’
=====================================

‘predicate’
...........

     Is a function to filter the initial collection.  It has to be
     compatible with ‘all-completions’.  Tip: most of the time, it’s
     simpler to just apply this filter to the ‘collection’ argument
     itself, e.g.  ‘(cl-remove-if-not predicate collection)’.

‘require-match’
...............

     When set to a non-nil value, input must match one of the
     candidates.  Custom input is not accepted.

‘initial-input’
...............

     This string argument is included for compatibility with
     ‘completing-read’, which inserts it into the minibuffer.

     It’s recommended to use the ‘preselect’ argument instead of this.

‘history’
.........

     Name of the symbol to store history.  See ‘completing-read’.

‘preselect’
...........

     Determines which one of the candidates to initially select.

     When set to an integer value, select the candidate with that index
     value.

     When set to any other non-nil value, select the first candidate
     matching this value.  Comparison is first done with ‘equal’.  If
     this fails, and when applicable, match ‘preselect’ as a regular
     expression.

     Every time the input becomes empty, the item corresponding to
     ‘preselect’ is selected.

‘keymap’
........

     A keymap to be composed with ‘ivy-minibuffer-map’.  This keymap has
     priority over ‘ivy-minibuffer-map’ and can be modified at any later
     stage.

‘update-fn’
...........

     Is the function called each time the current candidate changes.
     This function takes no arguments and is called in the minibuffer’s
     ‘post-command-hook’.  See ‘swiper’ for an example usage.

‘sort’
......

     When non-nil, use ‘ivy-sort-functions-alist’ to sort the collection
     as long as the collection is not larger than ‘ivy-sort-max-size’.

‘action’
........

     Is the function to call after selection.  It takes a string
     argument.

‘unwind’
........

     Is the function to call before exiting completion.  It takes no
     arguments.  This function is called even if the completion is
     interrupted with ‘C-g’.  See ‘swiper’ for an example usage.

‘re-builder’
............

     Is a function that takes a string and returns a valid regex.  See
     ‘Completion Styles’ for details.

‘matcher’
.........

     Is a function that takes a regex string and a list of strings and
     returns a list of strings matching the regex.  Any ordinary Emacs
     matching function will suffice, yet finely tuned matching functions
     can be used.  See ‘counsel-find-file’ for an example usage.

‘dynamic-collection’
....................

     When non-nil, ‘collection’ will be used to dynamically generate the
     candidates each time the input changes, instead of being used once
     statically with ‘all-completions’ to generate a list of strings.
     See ‘counsel-locate’ for an example usage.

‘caller’
........

     Is a symbol that uniquely identifies the function that called
     ‘ivy-read’, which may be useful for further customizations.


File: ivy.info,  Node: Example - counsel-describe-function,  Next: Example - counsel-locate,  Prev: Optional arguments for ivy-read,  Up: API

8.3 Example - ‘counsel-describe-function’
=========================================

This is a typical example of a function with a non-async collection,
which is a collection where all the strings in the collection are known
prior to any input from the user.

   Only the first two arguments (along with ‘action’) are essential -
the rest of the arguments are for fine-tuning, and could be omitted.

   The ‘action’ argument could also be omitted - but then ‘ivy-read’
would do nothing except returning the string result, which you could
later use yourself.  However, it’s recommended that you use the ‘action’
argument.

     (defun counsel-describe-function ()
       "Forward to `describe-function'."
       (interactive)
       (ivy-read "Describe function: "
     	    (let (cands)
     	      (mapatoms
     	       (lambda (x)
     		 (when (fboundp x)
     		   (push (symbol-name x) cands))))
     	      cands)
     	    :keymap counsel-describe-map
     	    :preselect (ivy-thing-at-point)
     	    :history 'counsel-describe-symbol-history
     	    :require-match t
     	    :action (lambda (x)
     		      (describe-function
     		       (intern x)))
     	    :caller 'counsel-describe-function))

   Here are the interesting features of the above function, in the order
that they appear:

   • The ‘prompt’ argument is a simple string ending in ": ".
   • The ‘collection’ argument evaluates to a (large) list of strings.
   • The ‘keymap’ argument is for a custom keymap to supplement
     ‘ivy-minibuffer-map’.
   • The ‘preselect’ is provided by ‘ivy-thing-at-point’, which returns
     a symbol near the point.  Ivy then selects the first candidate from
     the collection that matches this symbol.  To select this
     pre-selected candidate, a ‘RET’ will suffice.  No further user
     input is necessary.
   • The ‘history’ argument is for keeping the history of this command
     separate from the common history in ‘ivy-history’.
   • The ‘require-match’ is set to ‘t’ since it doesn’t make sense to
     call ‘describe-function’ on an un-interned symbol.
   • The ‘action’ argument calls ‘describe-function’ on the interned
     selected candidate.
   • The ‘caller’ argument identifies this completion session.  This is
     important, since with the collection being a list of strings and
     not a function name, the only other way for ‘ivy-read’ to identify
     "who’s calling" and to apply the appropriate customizations is to
     examine ‘this-command’.  But ‘this-command’ would be modified if
     another command called ‘counsel-describe-function’.


File: ivy.info,  Node: Example - counsel-locate,  Next: Example - ivy-read-with-extra-properties,  Prev: Example - counsel-describe-function,  Up: API

8.4 Example - ‘counsel-locate’
==============================

This is a typical example of a function with an async collection.  Since
the collection function cannot pre-compute all the locatable files in
memory within reasonable limits (time or memory), it relies on user
input to filter the universe of possible candidates to a manageable size
while also continuing to search asynchronously for possible candidates.
Both the filtering and searching continues with each character change of
the input with rapid updates to the collection presented without idle
waiting times.  This live update will continue as long as there are
likely candidates.  Eventually updates to the minibuffer will stop after
user input, filtering, and searching have exhausted looking for possible
candidates.

   Async collections suit long-running shell commands, such as ‘locate’.
With each new input, a new process starts while the old process is
killed.  The collection is refreshed anew with each new process.
Meanwhile the user can provide more input characters (for further
narrowing) or select a candidate from the visible collection.

     (defun counsel-locate-function (str)
       (or
        (ivy-more-chars)
        (progn
          (counsel--async-command
           (format "locate %s '%s'"
     	      (mapconcat #'identity counsel-locate-options " ")
     	      (counsel--elisp-to-pcre
     	       (ivy--regex str))))
          '("" "working..."))))

     ;;;###autoload
     (defun counsel-locate (&optional initial-input)
       "Call the \"locate\" shell command.
     INITIAL-INPUT can be given as the initial minibuffer input."
       (interactive)
       (ivy-read "Locate: " #'counsel-locate-function
     	    :initial-input initial-input
     	    :dynamic-collection t
     	    :history 'counsel-locate-history
     	    :action (lambda (file)
     		      (with-ivy-window
     			(when file
     			  (find-file file))))
     	    :unwind #'counsel-delete-process
     	    :caller 'counsel-locate))

   Here are the interesting features of the above functions, in the
order that they appear:

   • ‘counsel-locate-function’ takes a string argument and returns a
     list of strings.  Note that it’s not compatible with
     ‘all-completions’, but since we’re not using that here, might as
     well use one argument instead of three.
   • ‘ivy-more-chars’ is a simple function that returns e.g.  ‘'("2
     chars more")’ asking the user for more input.
   • ‘counsel--async-command’ is a very easy API simplification that
     takes a single string argument suitable for
     ‘shell-command-to-string’.  So you could prototype your function as
     non-async using ‘shell-command-to-string’ and ‘split-string’ to
     produce a collection, then decide that you want async and simply
     swap in ‘counsel--async-command’.
   • ‘counsel-locate’ is an interactive function with an optional
     ‘initial-input’.
   • ‘#'counsel-locate-function’ is passed as the ‘collection’ argument.
   • ‘dynamic-collection’ is set to t, since this is an async
     collection.
   • ‘action’ argument uses ‘with-ivy-window’ wrapper, since we want to
     open the selected file in the same window from which
     ‘counsel-locate’ was called.
   • ‘unwind’ argument is set to ‘#'counsel-delete-process’: when we
     press ‘C-g’ we want to kill the running process created by
     ‘counsel--async-command’.
   • ‘caller’ argument identifies this command for easier customization.


File: ivy.info,  Node: Example - ivy-read-with-extra-properties,  Prev: Example - counsel-locate,  Up: API

8.5 Example - ‘ivy-read-with-extra-properties’
==============================================

This is another example to show how to associate additional values to
each displayed strings.

     (defun find-candidates-function (str pred _)
       (let ((props '(1 2))
     	(strs '("foo" "foo2")))
         (cl-mapcar (lambda (s p) (propertize s 'property p))
     	       strs
     	       props)))

     (defun find-candidates ()
       (interactive)
       (ivy-read "Find symbols: "
     	    #'find-candidates-function
     	    :action (lambda (x)
     		      (message "Value: %s" (get-text-property 0 'property x)
     		       ))))

   Here are the interesting features of the above function:

   • ‘find-candidates-function’ builds up a list of strings and
     associates "foo" with the value 1 and "foo2" with 2.
   • ‘find-candidates’ is an interactive function.
   • ‘#'find-candidates’ is passed as the ‘collection’ argument.
   • ‘action’ gets passed the selected string with the associated value.
     It then retrieves that value and displays it.


File: ivy.info,  Node: Variable Index,  Next: Keystroke Index,  Prev: API,  Up: Top

Variable Index
**************

[index]
* Menu:

* ivy-alt-done:                          Key bindings for single selection action then exit minibuffer.
                                                               (line 30)
* ivy-alt-done <1>:                      File Name Completion. (line 12)
* ivy-avy:                               Key bindings for single selection action then exit minibuffer.
                                                               (line 64)
* ivy-backward-delete-char:              File Name Completion. (line 19)
* ivy-call:                              Key bindings for multiple selections and actions keep minibuffer open.
                                                               (line 16)
* ivy-confirm-face:                      Faces.                (line 34)
* ivy-count-format:                      Defcustoms.           (line  6)
* ivy-current-match:                     Faces.                (line  9)
* ivy-dispatching-call:                  Key bindings for multiple selections and actions keep minibuffer open.
                                                               (line 26)
* ivy-dispatching-done:                  Key bindings for single selection action then exit minibuffer.
                                                               (line 24)
* ivy-display-style:                     Defcustoms.           (line 24)
* ivy-done:                              Key bindings for single selection action then exit minibuffer.
                                                               (line 19)
* ivy-extra-directories:                 File Name Completion. (line 45)
* ivy-height:                            Key bindings for navigation.
                                                               (line 21)
* ivy-immediate-done:                    Key bindings for single selection action then exit minibuffer.
                                                               (line 53)
* ivy-insert-current:                    Key bindings that alter the minibuffer input.
                                                               (line 23)
* ivy-kill-ring-save:                    Other key bindings.   (line  9)
* ivy-match-required-face:               Faces.                (line 53)
* ivy-minibuffer-grow:                   Hydra in the minibuffer.
                                                               (line 45)
* ivy-minibuffer-map:                    Minibuffer key bindings.
                                                               (line  6)
* ivy-minibuffer-match-face-1:           Faces.                (line 14)
* ivy-minibuffer-match-face-2:           Faces.                (line 19)
* ivy-minibuffer-match-face-3:           Faces.                (line 24)
* ivy-minibuffer-match-face-4:           Faces.                (line 29)
* ivy-minibuffer-shrink:                 Hydra in the minibuffer.
                                                               (line 50)
* ivy-modified-buffer:                   Faces.                (line 88)
* ivy-modified-outside-buffer:           Faces.                (line 93)
* ivy-next-action:                       Hydra in the minibuffer.
                                                               (line 60)
* ivy-next-history-element:              Key bindings that alter the minibuffer input.
                                                               (line  9)
* ivy-next-line-and-call:                Key bindings for multiple selections and actions keep minibuffer open.
                                                               (line 36)
* ivy-occur:                             Saving the current completion session to a buffer.
                                                               (line  9)
* ivy-occur-click:                       Saving the current completion session to a buffer.
                                                               (line 21)
* ivy-occur-dispatch:                    Saving the current completion session to a buffer.
                                                               (line 41)
* ivy-occur-press:                       Saving the current completion session to a buffer.
                                                               (line 16)
* ivy-occur-read-action:                 Saving the current completion session to a buffer.
                                                               (line 36)
* ivy-on-del-error-function:             Defcustoms.           (line 31)
* ivy-partial-or-done:                   Key bindings for single selection action then exit minibuffer.
                                                               (line 37)
* ivy-prev-action:                       Hydra in the minibuffer.
                                                               (line 55)
* ivy-previous-history-element:          Key bindings that alter the minibuffer input.
                                                               (line 18)
* ivy-previous-line-and-call:            Key bindings for multiple selections and actions keep minibuffer open.
                                                               (line 47)
* ivy-read-action:                       Hydra in the minibuffer.
                                                               (line 65)
* ivy-remote:                            Faces.                (line 71)
* ivy-restrict-to-matches:               Key bindings that alter the minibuffer input.
                                                               (line 40)
* ivy-resume:                            Key bindings for multiple selections and actions keep minibuffer open.
                                                               (line 55)
* ivy-reverse-i-search:                  Key bindings that alter the minibuffer input.
                                                               (line 48)
* ivy-rotate-preferred-builders:         Hydra in the minibuffer.
                                                               (line 40)
* ivy-subdir:                            Faces.                (line 66)
* ivy-toggle-calling:                    Hydra in the minibuffer.
                                                               (line 34)
* ivy-toggle-case-fold:                  Hydra in the minibuffer.
                                                               (line 70)
* ivy-toggle-regexp-quote:               File Name Completion. (line 41)
* ivy-use-virtual-buffers:               Buffer Name Completion.
                                                               (line  6)
* ivy-virtual:                           Faces.                (line 76)
* ivy-wrap:                              Key bindings for navigation.
                                                               (line 14)
* ivy-yank-word:                         Key bindings that alter the minibuffer input.
                                                               (line 32)


File: ivy.info,  Node: Keystroke Index,  Prev: Variable Index,  Up: Top

Keystroke Index
***************

[index]
* Menu:

* /:                                     File Name Completion. (line 35)
* / C-j:                                 Using TRAMP.          (line 24)
* //:                                    File Name Completion. (line 25)
* // <1>:                                Using TRAMP.          (line 17)
* <:                                     Hydra in the minibuffer.
                                                               (line 50)
* >:                                     Hydra in the minibuffer.
                                                               (line 45)
* ~:                                     File Name Completion. (line 30)
* ~ <1>:                                 Using TRAMP.          (line  9)
* ~~:                                    Using TRAMP.          (line 29)
* a:                                     Hydra in the minibuffer.
                                                               (line 65)
* a <1>:                                 Saving the current completion session to a buffer.
                                                               (line 36)
* c:                                     Hydra in the minibuffer.
                                                               (line 34)
* C:                                     Hydra in the minibuffer.
                                                               (line 70)
* C-':                                   Key bindings for single selection action then exit minibuffer.
                                                               (line 64)
* C-c C-o:                               Saving the current completion session to a buffer.
                                                               (line  9)
* C-j:                                   Key bindings for single selection action then exit minibuffer.
                                                               (line 30)
* C-j <1>:                               File Name Completion. (line 12)
* C-m:                                   Key bindings for single selection action then exit minibuffer.
                                                               (line 19)
* C-M-j:                                 Key bindings for single selection action then exit minibuffer.
                                                               (line 53)
* C-M-m:                                 Key bindings for multiple selections and actions keep minibuffer open.
                                                               (line 16)
* C-M-n:                                 Key bindings for multiple selections and actions keep minibuffer open.
                                                               (line 36)
* C-M-o:                                 Key bindings for multiple selections and actions keep minibuffer open.
                                                               (line 26)
* C-M-p:                                 Key bindings for multiple selections and actions keep minibuffer open.
                                                               (line 47)
* C-o:                                   Hydra in the minibuffer.
                                                               (line  9)
* C-r:                                   Key bindings that alter the minibuffer input.
                                                               (line 48)
* DEL:                                   File Name Completion. (line 19)
* f:                                     Saving the current completion session to a buffer.
                                                               (line 16)
* j:                                     Saving the current completion session to a buffer.
                                                               (line 26)
* k:                                     Saving the current completion session to a buffer.
                                                               (line 31)
* m:                                     Hydra in the minibuffer.
                                                               (line 40)
* M-i:                                   Key bindings that alter the minibuffer input.
                                                               (line 23)
* M-j:                                   Key bindings that alter the minibuffer input.
                                                               (line 32)
* M-n:                                   Key bindings that alter the minibuffer input.
                                                               (line  9)
* M-o:                                   Key bindings for single selection action then exit minibuffer.
                                                               (line 24)
* M-p:                                   Key bindings that alter the minibuffer input.
                                                               (line 18)
* M-r:                                   File Name Completion. (line 41)
* M-w:                                   Other key bindings.   (line  9)
* mouse-1:                               Saving the current completion session to a buffer.
                                                               (line 21)
* o:                                     Saving the current completion session to a buffer.
                                                               (line 41)
* q:                                     Saving the current completion session to a buffer.
                                                               (line 46)
* RET:                                   Key bindings for single selection action then exit minibuffer.
                                                               (line 19)
* RET <1>:                               Saving the current completion session to a buffer.
                                                               (line 16)
* s:                                     Hydra in the minibuffer.
                                                               (line 60)
* S-SPC:                                 Key bindings that alter the minibuffer input.
                                                               (line 40)
* TAB:                                   Key bindings for single selection action then exit minibuffer.
                                                               (line 37)
* w:                                     Hydra in the minibuffer.
                                                               (line 55)



Tag Table:
Node: Top1189
Node: Introduction3100
Node: Installation5623
Node: Installing from Emacs Package Manager6073
Node: Installing from the Git repository7187
Node: Getting started8007
Node: Basic customization8314
Node: Key bindings8909
Node: Global key bindings9101
Node: Minibuffer key bindings11575
Node: Key bindings for navigation12807
Node: Key bindings for single selection action then exit minibuffer14014
Node: Key bindings for multiple selections and actions keep minibuffer open16661
Node: Key bindings that alter the minibuffer input19053
Node: Other key bindings20998
Node: Hydra in the minibuffer21376
Node: Saving the current completion session to a buffer23794
Node: Completion Styles25206
Node: ivy--regex-plus26957
Node: ivy--regex-ignore-order28443
Node: ivy--regex-fuzzy28811
Node: Customization29308
Node: Faces29494
Node: Defcustoms31923
Node: Actions33217
Node: What are actions?33543
Node: How can different actions be called?34361
Node: How to modify the actions list?34932
Node: Example - add two actions to each command35592
Node: How to undo adding the two actions36551
Node: How to add actions to a specific command37003
Node: Example - define a new command with several actions37419
Node: Test the above function with ivy-occur38307
Node: Packages39149
Node: Commands40114
Node: File Name Completion40299
Node: Using TRAMP42095
Node: Buffer Name Completion43597
Node: Counsel commands44212
Node: API44859
Node: Required arguments for ivy-read45457
Node: Optional arguments for ivy-read45976
Node: Example - counsel-describe-function49402
Node: Example - counsel-locate52260
Node: Example - ivy-read-with-extra-properties56010
Node: Variable Index57218
Node: Keystroke Index64265

End Tag Table


Local Variables:
coding: utf-8
End: