brettlangdon
/
dotfiles
mirror of https://github.com/brettlangdon/dotfiles.git
1
0
Fork 0
Code Issues 0 Projects 0 Releases 0 Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
126 Commits
1 Branch
1.8 GiB
 
 
Tree: 49d4de0678
Branches Tags
${ item.name }
Create branch ${ searchTerm }
from '49d4de0678'
${ noResults }
dotfiles/emacs.d/elpa/swiper-20160115.800/ivy.info

654 lines
24 KiB
Raw Blame History

This is ivy.info, produced by makeinfo version 5.2 from ivy.texi.
Ivy manual, version 0.7.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 © 2015 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, with the Front-Cover Texts
being “A GNU Manual,” and with the Back-Cover Texts as in (a)
below. A copy of the license is included in the section entitled
“GNU Free Documentation License.”
(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
modify this GNU manual.”
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
***************
Ivy manual, version 0.7.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 © 2015 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, with the Front-Cover Texts
being “A GNU Manual,” and with the Back-Cover Texts as in (a)
below. A copy of the license is included in the section entitled
“GNU Free Documentation License.”
(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
modify this GNU manual.”
* Menu:
* Introduction::
* Installation::
* Getting started::
* Key bindings::
* Completion styles::
* Variable 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 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::

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-length’ 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. 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.
* 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’ ‘swiper’ ‘RET’
Ivy is installed as part of ‘swiper’ package. ‘swiper’ 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. See the code
below for adding MELPA to the list of package archives:
(require 'package)
(add-to-list 'package-archives
'("melpa" . "http://melpa.org/packages/"))
After this do ‘M-x’ ‘package-refresh-contents’ ‘RET’, followed by
‘M-x’ ‘package-install’ ‘RET’ ‘swiper’ ‘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:
cd ~/git && git clone https://github.com/abo-abo/swiper
cd swiper && make compile
Then add this to Emacs init:
(add-to-list 'load-path "~/git/swiper/")
(require 'ivy)
To update the code:
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-height 10)
(setq ivy-display-style 'fancy)
(setq ivy-count-format "(%d/%d) ")
For additional 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
=======================
Recommended key bindings are:
Ivy-based interface to standard commands
........................................
(global-set-key (kbd "C-s") 'swiper)
(global-set-key (kbd "M-x") 'counsel-M-x)
(global-set-key (kbd "C-x C-f") 'counsel-find-file)
(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-load-library)
(global-set-key (kbd "<f2> i") 'counsel-info-lookup-symbol)
(global-set-key (kbd "<f2> u") 'counsel-unicode-char)
Ivy-based interface to shell and system tools
.............................................
(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 k") 'counsel-ag)
(global-set-key (kbd "C-x l") 'counsel-locate)
(global-set-key (kbd "C-S-o") 'counsel-rhythmbox)
Ivy-resume and other commands
.............................
‘ivy-resume’ resumes the last Ivy-based completion.
(global-set-key (kbd "C-c C-r") 'ivy-resume)

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 through the ‘keymap’ argument to
‘ivy-read’. These keys, also active in the minibuffer, are described
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 that alter 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
This user option allows to get the wrap-around behavior for ‘C-n’
and ‘C-p’. When set to ‘t’, ‘ivy-next-line’ and
‘ivy-previous-line’ will cycle past the last and the first
candidates respectively.
This behavior is off by default.
-- User Option: ivy-height
Use this variable to adjust the minibuffer height, and therefore
the scroll size for ‘C-v’ and ‘M-v’.

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 exits the
minibuffer.
‘M-o’ (‘ivy-dispatching-done’) presents all available valid actions
from which to choose. When there is only one action available, there is
no difference between ‘M-o’ and ‘C-m’.
‘C-j’ (‘ivy-alt-done’) calls the alternate action, such as completing
a directory name in a file list whereas ‘C-m’ will select that directory
and exit the minibuffer.
Exiting the minibuffer also closes the Ivy window (as specified by
‘ivy-height’). This closing and exiting sequence is conveniently off
when applying multiple actions. Multiple actions and multiple
selections as covered in the next section of this manual.
‘TAB’ (‘ivy-partial-or-done’) attempts partial completion, extending
current input as much as possible.
‘TAB TAB’ is the same as ‘C-j’.
‘C-M-j’ (‘ivy-immediate-done’) is useful when there is no match for
the given input. Or there is an incorrect partial match. ‘C-M-j’ with
‘find-file’ lists ignores the partial match and instead takes the
current input to create a new directory with ‘dired-create-directory’.
‘ivy-immediate-done’ illustrates how Ivy distinguishes between
calling an action on the _currently selected_ candidate and calling an
action on the _current input_.
Invoking avy completion with ‘C-'’ (‘ivy-avy’). ‘C-`’ uses avy’s
visible jump mechanism, which can further reduce Ivy’s line-by-line
scrolling that requires multiple ‘C-n’ or ‘C-p’ keystrokes.

File: ivy.info, Node: Key bindings for multiple selections and actions keep minibuffer open, Next: Key bindings that alter 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 the default
action, ‘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.
‘RET’ exits the minibuffer.
‘ivy-resume’ recalls the state of the completion session just before
its last exit. Useful after an accidental ‘C-m’ (‘ivy-done’).
‘C-M-o’ (‘ivy-dispatching-call’) is a non-exiting version of ‘M-o’
(‘ivy-dispatching-done’) that can accumulate candidates into a queue.
For example, for playback in ‘counsel-rhythmbox’, ‘C-M-o e’ en-queues
the selected candidate, and ‘C-n C-m’ plays the next one in the queue.
‘C-M-n’ (‘ivy-next-line-and-call’) combines ‘C-n’ and ‘C-M-m’.
Applies an action and moves to next line. Comes in handy when opening
multiple files from ‘counsel-find-file’, ‘counsel-git-grep’,
‘counsel-ag’, 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’.
Is the same as above except that it moves through the list in the other
direction.

File: ivy.info, Node: Key bindings that alter 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 minibuffer input
----------------------------------------------
‘M-n’ (‘ivy-next-history-element’) and ‘M-p’
(‘ivy-previous-history-element’) cycle 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-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 sub-word at point into minibuffer.
This is similar to ‘C-s C-w’ with ‘isearch’. Ivy reserves ‘C-w’ for
‘kill-region’.
‘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’) works just like ‘C-r’ at 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 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; when the region is active, copies active region.

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 Hydra menus with key shortcuts.
‘C-o’ or ‘i’ resumes editing.
Hydra reduces key strokes, for example: ‘C-n C-n C-n C-n’ is ‘C-o
jjjj’ in Hydra. Hydra has other benefits besides certain shorter key
bindings:
• ‘<’ and ‘>’ to adjust height of minibuffer,
• describes the current completion state, such as case folding and
the current action.
Minibuffer editing is disabled when Hydra is active.

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;
the list is active in the new buffer.
‘RET’ or ‘mouse-1’ in the new buffer calls the appropriate action on
the selected candidate.
Ivy has no limit on the number of active buffers like these.
Ivy takes care of making these buffer names unique. It applies
descriptive names, for example: ‘*ivy-occur counsel-describe-variable
"function$*’.

File: ivy.info, Node: Completion styles, Next: Variable Index, Prev: Key bindings, Up: Top
5 Completion styles
*******************
Ivy’s completion functions rely on the highly configurable regex
builder.
The default is:
(setq ivy-re-builders-alist
'((t . ivy--regex-plus)))
The default ‘ivy--regex-plus’ narrowing is always invoked unless
specified otherwise. For example, file name completion may have a
custom completion function:
(setq ivy-re-builders-alist
'((read-file-name-internal . ivy--regex-fuzzy)
(t . ivy--regex-plus)))
Ivy’s flexibility extends to using different styles of completion
mechanics (regex-builders) for different types of lists. Despite this
flexibility, Ivy operates within a consistent and uniform interface.
The main regex-builders currently in Ivy are:
* 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 proper 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. For literal white space matching in Ivy, use an extra space: 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.
Standard regexp identifiers work:
"^", "$", "\b" or "[a-z]"
Since Ivy treats minibuffer input as a regexp, standard regexp
identifiers work as usual. 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". Otherwise ‘ivy--regex-plus’
normal behavior is to honor the order of regexp tokens.

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.

File: ivy.info, Node: Variable Index, Prev: Completion styles, Up: Top
6 Variable Index
****************
[index]
* Menu:
* ivy-height: Key bindings for navigation.
(line 22)
* ivy-wrap: Key bindings for navigation.
(line 14)

Tag Table:
Node: Top1354
Node: Introduction3557
Node: Installation5893
Node: Installing from Emacs Package Manager6219
Node: Installing from the Git repository7177
Node: Getting started7877
Node: Basic customization8183
Node: Key bindings8598
Node: Global key bindings8790
Node: Minibuffer key bindings10029
Node: Key bindings for navigation11001
Node: Key bindings for single selection action then exit minibuffer12143
Node: Key bindings for multiple selections and actions keep minibuffer open14709
Node: Key bindings that alter minibuffer input16855
Node: Other key bindings18298
Node: Hydra in the minibuffer18637
Node: Saving the current completion session to a buffer19350
Node: Completion styles20044
Node: ivy--regex-plus20984
Node: ivy--regex-ignore-order22428
Node: ivy--regex-fuzzy22873
Node: Variable Index23306

End Tag Table

Local Variables:
coding: utf-8
End: