     [file emacsver.texi not included]

Interactive Do
**************

This file documents the Ido package for GNU Emacs.

Copyright © 2013-2014 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.''

Overview
********

This document describes a set of features that can interactively do things with buffers and files.  All the features are described here in detail.

The Ido package can let you switch between buffers and visit files and directories with a minimum of keystrokes.  It is a superset of Iswitchb, the interactive buffer switching package by Stephen Eglen.

This package was originally written by Kim F. Storm, based on the iswitchb.el package by Stephen Eglen.

Activation
==========

This package is distributed with Emacs, so there is no need to install any additional files in order to start using it.  To activate, use M-x ido-mode.

You may wish to add the following expressions to your initialization file (see The Emacs Initialization File (GNU Emacs Manual)), if you make frequent use of features from this package.

     (require 'ido)
     (ido-mode t)

Working Directories
===================

Working directories are directories where files have most recently been opened.  The current directory is inserted at the front of this ido-work-directory-list whenever a file is opened with ido-find-file and other file-related functions.

 -- User Option: ido-max-work-directory-list
     This user option specifies maximum number of working directories to record.

 -- User Option: ido-max-dir-file-cache
     This user option specifies maximum number of working directories to be cached.  This is the size of the cache of file-name-all-completions results.  Each cache entry is time stamped with the modification time of the directory.  Some systems, like MS-Windows, have unreliable directory modification times, so you may choose to disable caching on such systems, or explicitly refresh the cache contents using the command ido-reread-directory (usually C-l) in the minibuffer.

Matching
********

This section describes features of this package that have to do with various kinds of matching: among buffers, files, and directories.

Interactive Substring Matching
==============================

As you type in a substring, the list of buffers or files currently matching the substring are displayed as you type.  The list is ordered so that the most recent buffers or files visited come at the start of the list.

The buffer or file at the start of the list will be the one visited when you press RET.  By typing more of the substring, the list is narrowed down so that gradually the buffer or file you want will be at the top of the list.  Alternatively, you can use C-s and C-r (or the right and left arrow keys) to rotate buffer or file names in the list until the one you want is at the top of the list.

Completion is also available so that you can see what is common to all of the matching buffers or files as you type.

For example, if there are two buffers called 123456 and 123, with 123456 the most recent, when using ido-switch-buffer, you first of all get presented with the list of all the buffers

     Buffer: {123456 | 123}

If you then press 2:

     Buffer: 2[3]{123456 | 123}

The list in {...} are the matching buffers, most recent first (buffers visible in the current frame are put at the end of the list by default).  At any time you can select the item at the head of the list by pressing RET.  You can also put the first element at the end of the list by pressing C-s or <right>, or bring the last element to the head of the list by pressing C-r or <left>.

The item in [...] indicates what can be added to your input by pressing TAB (ido-complete).  In this case, you will get "3" added to your input.

So, press TAB:

     Buffer: 23{123456 | 123}

At this point, you still have two matching buffers.  If you want the first buffer in the list, you can simply press RET.  If you want the second in the list, you can press C-s to move it to the top of the list and then press RET to select it.

However, if you type 4, you'll only have one match left:

     Buffer: 234[123456]

Since there is only one matching buffer left, it is given in [] and it is shown in the ido-only-match face (ForestGreen).  You can now press TAB or RET to go to that buffer.

If you want to create a new buffer named 234, you can press C-j (ido-select-text) instead of TAB or RET.

If instead, you type a:

     Buffer: 234a [No match]

There are no matching buffers.  If you press RET or TAB, you can be prompted to create a new buffer called 234a.

Of course, where this function comes in really useful is when you can specify the buffer using only a few keystrokes.  In the above example, the quickest way to get to the 123456 file would be just to type 4 and then RET (assuming there isn't any newer buffer with 4 in its name).

Likewise, if you use C-x C-f (ido-find-file), the list of files and directories in the current directory is provided in the same fashion as the buffers above.  The files and directories are normally sorted in alphabetical order, but the most recently visited directory is placed first to speed up navigating to directories that you have visited recently.

In addition to scrolling through the list using <right> and <left>, you can use <up> and <down> to quickly scroll the list to the next or previous subdirectory.

To go down into a subdirectory, and continue the file selection on the files in that directory, simply move the directory to the head of the list and hit RET.

To go up to the parent directory, delete any partial file name already specified (e.g. using DEL) and hit DEL.

To go to the root directory (on the current drive), enter two slashes. On MS-DOS or Windows, to select the root of another drive, enter X:/ where X is the drive letter.  To go to the home directory, enter ~/.  To enter Dired for this directory, use C-d.

You can also visit files on other hosts using the ange-ftp notations /host: and /user@host:.

You can type M-p and M-n to change to previous/next directories from the history, M-s to search for a file matching your input, and M-k to remove the current directory from the history.

If for some reason you cannot specify the proper file using ido-find-file, you can press C-f to enter the normal find-file.  You can also press C-b to drop into ido-switch-buffer.

Prefix Matching
===============

The standard way of completion with *nix shells and Emacs is to insert a prefix and then hitting TAB (or another completion key). Cause of this behavior has become second nature to a lot of Emacs users Ido offers in addition to the default substring matching method (look above) also the prefix matching method.  The kind of matching is the only difference to the description of the substring matching above.

You can toggle prefix matching with C-p (ido-toggle-prefix).

For example, if you have two buffers 123456 and 123 then hitting 2 does not match because 2 is not a prefix in any of the buffer names.

Flexible Matching
=================

 -- User Option: ido-enable-flex-matching
     If non-nil, Ido will do flexible string matching.  Flexible matching means that if the entered string does not match any item, any item containing the entered characters in the given sequence will match.

If ido-enable-flex-matching is non-nil, Ido will do a more flexible matching (unless regexp matching is active) to find possible matches among the available buffer or file names if no matches are found using the normal prefix or substring matching.

The flexible matching implies that any item which simply contains all of the entered characters in the specified sequence will match.

For example, if you have four files alpha, beta, gamma, and delta, entering aa will match alpha and gamma, while ea matches beta and delta.  If prefix matching is also active, aa only matches alpha, while ea does not match any files.

Regular Expression Matching
===========================

There is limited provision for regexp matching within Ido, enabled through ido-enable-regexp (toggle with C-t).  This allows you to type [ch]$ for example and see all file names ending in c or h.

 -- User Option: ido-enable-regexp
     If the value of this user option is non-nil, Ido will do regexp matching.  The value of this user option can be toggled within ido-mode using ido-toggle-regexp.

Please notice: Ido-style completion is inhibited when you enable regexp matching.

Highlighting
************

The highlighting of matching items is controlled via ido-use-faces.  The faces used are ido-first-match, ido-only-match and ido-subdir.

Coloring of the matching item was suggested by Carsten Dominik.

Hidden Buffers and Files
************************

Normally, Ido does not include hidden buffers (whose name starts with a space) and hidden files and directories (whose name starts with .) in the list of possible completions.  However, if the substring you enter does not match any of the visible buffers or files, Ido will automatically look for completions among the hidden buffers or files.

You can toggle display of the hidden buffers and files with C-a (ido-toggle-ignore).

Customization
*************

You can customize the ido group to change Ido functionality:

     M-x customize-group RET ido RET

or customize a certain variable:

     M-x customize-variable RET ido-xxxxx

To modify the keybindings, use the ido-setup-hook.  For example:

     (add-hook 'ido-setup-hook 'ido-my-keys)

     (defun ido-my-keys ()
      "Add my keybindings for Ido."
      (define-key ido-completion-map " " 'ido-next-match))

Changing List Order
===================

By default, the list of current files is most recent first, oldest last, with the exception that the files visible in the current frame are put at the end of the list.  A hook exists to allow other functions to order the list.  For example, if you add:

     (add-hook 'ido-make-buffer-list-hook 'ido-summary-buffers-to-end)

then all files matching "Summary" are moved to the end of the list. (I find this handy for keeping the INBOX Summary and so on out of the way.)  It also moves files matching output\*$ to the end of the list (these are created by AUCTeX when compiling.)  Other functions could be made available which alter the list of matching files (either deleting or rearranging elements.)

Find File At Point
==================

Find File At Point, also known generally as ``ffap'', is an intelligent system for opening files, and URLs.

The following expression will make Ido guess the context:

     (setq ido-use-filename-at-point 'guess)

You can disable URL ffap support by toggling ido-use-url-at-point.

 -- User Option: ido-use-url-at-point
     If the value of this user option is non-nil, Ido will look for a URL at point.  If found, call find-file-at-point to visit it.

Ignoring Buffers and Files
==========================

Ido is capable of ignoring buffers, directories, files and extensions using regular expression.

 -- User Option: ido-ignore-buffers
     This variable takes a list of regular expressions for buffers to ignore in ido-switch-buffer.

 -- User Option: ido-ignore-directories
     This variable takes a list of regular expressions for (sub)directories names to ignore in ido-dired and ido-find-file.

 -- User Option: ido-ignore-files
     This variable takes a list of regular expressions for files to ignore in ido-find-file.

 -- User Option: ido-ignore-unc-host-regexps
     This variable takes a list of regular expressions matching UNC hosts to ignore.  The letter case will be ignored if ido-downcase-unc-hosts is non-nil.

To make Ido use completion-ignored-extensions you need to enable it:

     (setq ido-ignore-extensions t)

Now you can customize completion-ignored-extensions as well. Go ahead and add all the useless object files, backup files, shared library files and other computing flotsam you don't want Ido to show.

Please notice: Ido will still complete the ignored elements if it would otherwise not show any other matches.  So if you type out the name of an ignored file, Ido will still let you open it just fine.

Miscellaneous Customization
===========================

 -- User Option: ido-mode
     This user option determines for which functional group (buffer and files) Ido behavior should be enabled.

 -- User Option: ido-case-fold
     If the value of this user option is non-nil, searching of buffer and file names should ignore case.

 -- User Option: ido-show-dot-for-dired
     If the value of this user option is non-nil, always put .  as the first item in file name lists.  This allows the current directory to be opened immediately with Dired

 -- User Option: ido-enable-dot-prefix
     If the value of this user option is non-nil, Ido will match leading dot as prefix.  I.e., hidden files and buffers will match only if you type a dot as first char (even if ido-enable-prefix is nil).

 -- User Option: ido-confirm-unique-completion
     If the value of this user option is non-nil, even a unique completion must be confirmed.  This means that ido-complete (TAB) must always be followed by ido-exit-minibuffer (RET) even when there is only one unique completion.

 -- User Option: ido-cannot-complete-command
     When ido-complete can't complete any more, it will run the command specified by this user option.  The most useful values are ido-completion-help, which pops up a window with completion alternatives, or ido-next-match or ido-prev-match, which cycle the buffer list.

 -- User Option: ido-max-file-prompt-width
     This user option specifies the upper limit of the prompt string.  If its value is an integer, it specifies the number of characters of the string.  If its value is a floating point number, it specifies a fraction of the frame width.

 -- User Option: ido-max-window-height
     If the value of this user option is non-nil, its value will override the variable max-mini-window-height, which is the maximum height for resizing mini-windows (the minibuffer and the echo area).  If it's a floating point number, it specifies a fraction of the mini-window frame's height.  If it's an integer, it specifies the number of lines.

 -- User Option: ido-record-commands
     If the value of this user option is non-nil, Ido will record commands in the variable command-history.  Note that non-Ido equivalent is recorded.

 -- User Option: ido-all-frames
     This user option will be passed to walk-windows as its ALL-FRAMES argument when Ido is finding buffers.  See Cyclic Ordering of Windows (GNU Emacs Lisp Reference Manual).

 -- User Option: ido-minibuffer-setup-hook
     This hook variable contains Ido-specific customization of minibuffer setup.  It is run during minibuffer setup if Ido is active, and is intended for use in customizing ido for interoperation with other packages.

Miscellaneous
*************

After C-x b (ido-switch-buffer), the buffer at the head of the list can be killed by pressing C-k.  If the buffer needs saving, you will be queried before the buffer is killed.

Likewise, after C-x C-f, you can delete (i.e., physically remove) the file at the head of the list with C-k.  You will always be asked for confirmation before deleting the file.

If you enter C-x b to switch to a buffer visiting a given file, and you find that the file you are after is not in any buffer, you can press C-f to immediately drop into ido-find-file.  And you can switch back to buffer selection with C-b.

You can also use Ido in your Emacs Lisp programs:

     (setq my-pkgs (list "CEDET" "Gnus" "Rcirc" "Tramp" "Org" "all-of-them"))
     (ido-completing-read "What's your favorite package? " my-pkgs)

All Matching
============

If you have many matching files, they may not all fit onto one line of the minibuffer.  Normally, the minibuffer window will grow to show you more of the matching files (depending on the value of the variables resize-mini-windows and max-mini-window-height).  If you want Ido to behave differently from the default minibuffer resizing behavior, set the variable ido-max-window-height.

Also, to improve the responsiveness of Ido, the maximum number of matching items is limited to 12, but you can increase or removed this limit via the ido-max-prospects user option.

To see a full list of all matching buffers in a separate buffer, hit ? or press TAB when there are no further completions to the substring.  Repeated TAB presses will scroll you through this separate buffer.

Replacement
===========

ido-read-buffer and ido-read-file-name have been written to be drop in replacements for the normal buffer and file name reading functions read-buffer and read-file-name.

To use ido for all buffer and file selections in Emacs, customize the variable ido-everywhere.

Other Packages
==============

If you don't want to rely on the ido-everywhere functionality, ido-read-buffer, ido-read-file-name, and ido-read-directory-name can be used by other packages to read a buffer name, a file name, or a directory name in the Ido way.

GNU Free Documentation License
******************************

     [file doclicense.texi not included]