Icicles - Inserting Text from Cursor

Previous: Icicles - Nutshell ViewIciclesIciclesIndexNext: Icicles - Background on Input Completion

Inserting Text Found Near the Cursor

Most of Icicles is about completing text that you type in the minibuffer against some set of possible completion candidates. This particular feature is not. It is related only in the sense that it is also about inputting text that is already available elsewhere. If you want to get quickly into the heart of what Icicles is mainly about, then you can skip this page and come back later.

Some Emacs commands provide, as the default value for minibuffer input, a word or other text at the cursor position (aka “point”). You can insert this default value in the minibuffer with ‘M-n’. Icicles option `icicle-default-value’ can be used to automatically insert the default value into the minibuffer as an initial value, if you prefer that optional behavior (I do; many people do not).

Sometimes you would like to use the text at the cursor, but the command asking for input does not let you retrieve that text as the default value. For example, if the text at point is a file name, you might like to use it with ‘C-x C-f’ to open that file. Or, if the text is a URL, you might want to visit it using a Web browser.

FFAP: Find File At Point

Some Emacs libraries, such as FindFileAtPoint (`ffap.el’), have as their specific purpose to help you do this. “Ffap” stands for ‘find-file-at-point’, the main command in that library. It tries to interpret the text at point and “do the right thing” with it: visit a file, open a URL in a Web browser, and so on.

If you like, you can use library `ffap.el’ with Icicles. All Icicles features are then available during file-name and URL completion. And if you like `ffap.el’, you might also like to try my extension library ffap-.el. However, if you use ffap with Icicles, you might not want to use the ffap key bindings, preferring the Icicles bindings or the standard Emacs bindings for keys such as ‘C-x C-f’. (In that case, do not call function ‘ffap-bindings’.)

Icicles provides a couple of simple ways to take advantage of ‘ffap-guesser’, which is the ffap function that guesses which string at the cursor position you want to grab, without sacrificing any key bindings to ffap. One way is to use `M-.’ (command ‘icicle-insert-string-at-point’) at any time in the minibuffer. It grabs text at or near the cursor and yanks it into the minibuffer. One of the alternative types of thing it grabs is whatever text ‘ffap-guesser’ guesses.

Proxy Candidates, `M-.'

Another way is to use one of the proxy completion candidates ‘*point file name*’ or ‘*mouse-2 file name*’ whenever Emacs asks you to input a file name (provided option ‘icicle-add-proxy-candidates-flag’ is non-‘nil’ – toggle with `C-M-_’). The former picks up the file name at point, just like `M-.’. The latter lets you click a file name anywhere with ‘mouse-2’ to pick up the name.

Using `M-.’ or a proxy candidate on demand, instead of binding keys to ffap commands, lets you control which buffer text you use as minibuffer input and how that text should be interpreted (file name, URL, and so on). You can change the behavior of `M-.’ (which string-inserting functions are used) by customizing user option `icicle-thing-at-point-functions’.

See Also: Completions Display for more about using proxy candidates.

Repeat `M-.' To Grab More or Different

Actually, `M-.’ acts differently if you use it successively. Successive uses of `M-.’ grab and insert either 1) alternative bits of text (different text “things”) or 2) successive bits of text. The default behavior is #1, but you can change this choice by customizing option `icicle-default-thing-insertion’ (setting it to ‘more-of-the-same’, instead of ‘alternatives’).

As an example of grabbing successive bits of text (#2), suppose that the cursor is at the beginning of the word “use” in the previous paragraph. Then, during minibuffer input, suppose that you use `M-. M-. M-.’. Each time you hit `M-.’, another word is inserted in the minibuffer:

  use it
  use it successively

The rest of this section is a bit technical, so you might want to skip it if you are reading the Icicles doc for the first time. It details the behavior and definitions of options `icicle-default-thing-insertion’ and `icicle-thing-at-point-functions’, and how to temporarily override those settings interactively.

Option `icicle-thing-at-point-functions’ controls which text at or near the cursor `M-.’ inserts into the minibuffer. It is a cons cell, that is, an ordered pair:

If either the car or cdr is empty, then the other alone determines the behavior of `M-.’. Otherwise, option `icicle-default-thing-insertion’ determines whether the car or the cdr is used by `M-.’.

For example, if the value of ‘icicle-default-thing-insertion’ is ‘alternatives’ (the default value), then repeated use of `M-.’ inserts a different kind of thing at point each time. By default, these are the thing types, in order:

  1. ‘non-nil-symbol-name-nearest-point’ (*) or ‘symbol-at-point’
  2. ‘word-nearest-point’ (*) or the word at point
  3. ‘list-nearest-point-as-string’, the first enclosing list (*)
  4. ‘list-nearest-point-as-string’, the second enclosing list (*)
  5. ‘list-nearest-point-as-string’, the third enclosing list (*)
  6. ‘ffap-guesser’
  7. ‘thing-at-point-url-at-point’

The alternatives marked with an asterisk (*) are available only if you use library ThingAtPoint+. Alternative ‘ffap-guesser’ is used only if you use library ffap.el.

The first alternative inserts text that has the syntax of an EmacsLisp symbol name. In practice, this can also be a file name or a URL – it can include characters such as -, /, +, ., :, @, and _.

The second alternative inserts a word, which includes letters, ', and -.

The third, fourth, and fifth alternatives insert a (non-‘nil’) list that is around point - three different enclosing levels.

The sixth alternative inserts whatever ‘ffap-guesser’ returns: a file name or a URL at point.

The seventh alternative inserts a URL at point, adding prefix `http://’ if needed.

This means that you can quickly pick up a symbol name, a list, a file name, or a URL at point.

If you use library ThingAtPoint+ then the first two alternatives pick up the symbol or word nearest point – the cursor need not be exactly on the symbol or word.

You can of course add to or replace any of the alternatives that are provided by default.

If you set ‘icicle-default-thing-insertion’ to ‘more-of-the-same’ instead of ‘alternatives’, then repeated use of `M-.’ inserts successive words into the minibuffer, as shown in the example above.

You need not make a final choice once and for all between ‘alternatives’ and ‘more-of-the-same’. You can also make an interactive choice by using a prefix argument (‘C-u’) at any time to override the value of ‘icicle-default-thing-insertion’.

If you use plain ‘C-u’, then `M-.’ flips the behavior specified by ‘icicle-default-thing-insertion’.

If you use a numeric prefix argument N (not just plain ‘C-u’), then:

So for example, returning to the example above, with the cursor at the beginning of the word “use” in the first paragraph of this section, if you used `M-- M-. M-. M-.’, then the successive insertions in the example above would be as follows:

  differently if
  differently if you

And if you instead used `M--3 M-.’, then you would immediately insert ‘differently if you’.

There are thus lots of possibilities when you use `M-.’ repeatedly. You need not bother with them until you need them. You can build up to using them all gradually.

Resolve File Names

Finally, something that is not directly related to the topic of this page, but fits here as well as anywhere: you can use ‘C-x C-f’ in the minibuffer to resolve a file name to its true, absolute name. Yes, that’s the same key that is bound at top level to ‘icicle-file’ or ‘find-file’ or whatever, but this is about its use when you are already in the minibuffer.

‘C-x C-f’ (‘icicle-resolve-file-name’), replaces a file name at or near point (in the minibuffer) with its true, absolute name. (For it to work near point, as well as at point, you need library thingatpt+.el.) If the file name is relative, it first converts it to absolute (using the default directory). It then converts an absolute name that is a symbolic link to its target name. You can use this anytime in the minibuffer, and you can use it on multiple parts of the same minibuffer input (e.g. shell command arguments). (This feature does not work for Emacs 20 or 21.)

See Also:

Previous: Icicles - Nutshell ViewIciclesIciclesIndexNext: Icicles - Background on Input Completion

DrewsElispLibraries referenced here: Lisp:ffap-.el, Lisp:icicles.el, Lisp:thingatpt+.el

CategoryCommands CategoryCompletion CategoryModes CategoryDirectories CategoryFiles CategoryProgrammerUtils CategoryCode