Icicles - Bookmark Enhancements

iciclesimage
Previous: Icicles - Other Search CommandsIciclesIciclesIndexNext: Icicles - Emacs Tags Enhancements

Bookmark Enhancements

Many of the enhancements described on this page are available only if you also use library bookmark+.el (which I recommend). Bookmark+ is compatible with vanilla Emacs bookmarks across multiple Emacs versions. It enhances the use of bookmarks in many ways. The explanation here does not attempt to describe the Bookmark+ enhancements; it describes only the Icicles features that make use of them.

One of the main Bookmark+ enhancements is support for new bookmark types. Icicles provides type-specific bookmark commands and bookmark-candidate filtering.

In addition, when you complete the names of some kinds of objects, you can use ‘C-x m’ to choose objects of that type. For example, when you use ‘icicle-dired’ (‘C-x d’) to complete a directory name, you can use ‘C-x m’ to choose among your Dired bookmarks. See Accessing Saved Locations (Bookmarks) on the Fly.

Regardless of the bookmark type, another Bookmark+ feature that Icicles takes advantage of is the fact that a bookmark (any bookmark) can save not only a single position but a region, that is, two positions. You can think of this as bookmarking, or saving, regions. When you jump to a region bookmark, the region is activated (if option ‘bmkp-use-region’ is non-‘nil’).

These are the main Icicles bookmarking features:

Each is described in a little more detail below. More generally, however, the Bookmark+ doc is your friend.

Using Tagged Files

Bookmark+ lets you easily tag files with delicious-style tags of your choice. You need not visit the files to do this. Icicles makes this tagging even easier. Tagging a file creates an autofile bookmark that records the tags (metadata). Tags are generally strings, but you can also associate arbitrary EmacsLisp data with them. Besides tagging files, you can add tags to any kind of bookmark.

In Icicle mode, the Bookmark+ keys for tagging and untagging files are bound to multi-commands ‘icicle-tag-a-file’ and ‘icicle-untag-a-file’.

By default, these are on `C-x p t + a’ and ‘C-x p t - a’, respectively. The commands are actually bound to `+ a’ and ‘- a’ in keymap ‘bmkp-tags-map’, and you can of course bind that keymap to any key besides the default ‘C-x p t’. If you bind the keymap to ‘f2’, for instance, then `f2 + a’ and ‘f2 - a’ are all you need.

In addition, all Icicles file commands (and autofile bookmark commands) let you tag or untag files on the fly, during file-name completion, using the keys `C-x a +’ and ‘C-x a -’ respectively (‘a’ for autofile). Similarly, you can use ‘C-x a a’ during file-name completion to create an autofile bookmark for a file without tagging it.

All Icicles file commands also let you narrow the set of matching completions to those files that are tagged in certain ways, by using these keys on the fly:

For example:

  C-x 4 f foo TAB C-x C-t + red RET blue RET RET

‘TAB’ narrows the file-name candidates here to those starting with “foo”. `C-x C-t +’ prompts for one or more tags (”red” and “blue”), then it narrows the candidates to the names of files that are tagged either “red” or “blue” (or both).

You can of course use progressive completion, repeating `C-x C-t +’ to also require tag “yellow” or “purple”, for instance.

There are also several Icicles multi-commands for jumping to tagged files. They are all on the Bookmark+ keymaps ‘bmkp-jump-map’ and ‘bmkp-jump-other-window-map’: prefixes ‘C-x j a’ and ‘C-x 4 j a’(‘a’ for autofile). The latter is for the ‘-other-window’ version of each command.

See Also:

`icicle-find-file-tagged'

Command ‘icicle-find-file-tagged’ (‘C-x j t C-f C-f’) matches tags as part of a multi-completion completion candidate. Each candidate is composed of these fields: an absolute file name plus the file’s tags, all separated by `icicle-list-join-string’ ("^G^J", by default). As always, you can type ‘C-M-j’ to insert this separator into the minibuffer.

For this command, by default `.’ in your input matches any character, including a newline. As always, you can use `C-M-.’ to toggle this (so `.’ does not match newline).

You can match your input against the file name or tags or both. E.g., type:

That assumes that these tags do not also match any file names.

If you need to match against a particular field (e.g. the file name or a specific tag position), then use the field separator. Otherwise, just use progressive completion, as shown above.

E.g., to match only tags and not the filename, start with ‘C-M-j’ to get past the file-name field. To match both file name and tags, type something to match the file name before the ‘C-M-j’. E.g., type:

‘2011 C-M-j red S-SPC blue’ to match files tagged ‘red’ and ‘blue’ that have ‘2011’ in their names

(Command ‘icicle-bookmark-tagged’ (‘C-x j t j’) acts the same as ‘icicle-find-file-tagged’, but for all tagged bookmarks, not just autofiles.)

Jumping to Tagged Files (Other)

The other Icicles commands for jumping to tagged files let you input a set of tags to match, or regexps, one by one. The commands differ only in how this set of patterns is used. There are commands that use the intersection of the matches and commands that use the union.

All of them work the same way: you enter a pattern to match followed by ‘RET’, ending with ‘RET RET’. Intersection is indicated by ‘*’ in the key binding. Union is indicated by `+’. The regexp-matching commands have `%’ in the key binding. And again, there is an ‘-other-window’ version of each, on prefix key ‘C-x 4 j t C-f’ instead of ‘C-x j t C-f’.

See these sections of the Bookmark+ doc for more information about bookmark tags:

Saving Regions and Selecting Them

Saving the region just means bookmarking it. As for any bookmark, it must have a name. When you later jump to a region bookmark, the region is activated (provided option ‘bmkp-use-region’ is non-‘nil’).

Icicles gives you quick ways to save a region and select (activate) a saved region. You can do both using ‘C-x C-x’.

Setting a Bookmark and Jumping to a Bookmark

Just as ‘C-x C-x’ lets you either set or jump to a region bookmark, so ‘C-x r m’ lets you either set or jump to any bookmark. ‘C-x r m’ is the vanilla Emacs key for setting a bookmark. In Icicle mode it is bound by default to command ‘icicle-bookmark-cmd’. By default, whatever keys are normally bound to ‘bookmark-set’ and ‘bmkp-bookmark-set-confirm-overwrite’ (from library Bookmark+) are remapped in Icicle mode to ‘icicle-bookmark-cmd’.

Jumping to a Bookmark

Icicles commands that jump to a bookmark are multi-commands: you can use them to jump to any number of bookmarks in a single invocation. Each jump command acts as a bookmark browser.

As with most Icicles tripping commands, after you jump to a (non-region) bookmark, the cursor position is highlighted using cross hairs, if you also use library crosshairs.el (see CrosshairHighlighting).

Bookmark names are highlighted in buffer ‘*Completions*’ to indicate the bookmark type. The faces used are those defined by Bookmark+.

If option `icicle-show-multi-completion-flag’ is non-‘nil’, then each completion candidate is a multi-completion, with up to three parts: the bookmark name, the bookmark file or buffer name, and any (delicious-style) tags the bookmark has. You can toggle option ‘icicle-show-multi-completion-flag’ (for the next command) using ‘M-m’ during completion.

When using multi-completion candidates, you can match any of the multi-completion parts. For example, you can match all bookmarks that have any tags by typing this when choosing a bookmark:

  C-M-j . * C-M-j S-TAB

Or match all bookmarks whose names match ‘P42’ and whose tags match ‘blue’:

  P 4 2 . * C-M-j . * C-M-j . * b l u e S-TAB

(Each ‘C-M-j’ inserts `^G\n’, which is `icicle-list-join-string’.)

‘C-M-RET’ shows detailed info about the current bookmark completion candidate. ‘C-u C-M-RET’ shows the complete, internal info for the bookmark. Likewise, for the other candidate help keys: ‘C-M-down’ etc. And the mode line always shows summary info about the current bookmark.

During bookmark completion you can sort the candidates in various bookmark-specific ways:

The most general Icicles jump commands are ‘icicle-bookmark’ and ‘icicle-bookmark-other-window’. In Icicle mode these are bound to whatever ‘bookmark-jump’ and ‘bookmark-jump-other-window’ are normally bound to. If you use Bookmark+, the default bindings are ‘C-x j j’ and ‘C-x 4 j j’, respectively.

When you use these commands, you can narrow the completion candidates to bookmarks of a specific type using the following keys:

These same keys are used at the top level for individual jump commands for bookmarks of each of each type. For example, `icicle-bookmark-info’ is bound to ‘C-x j i’. Other-window jump commands are the same, but use the prefix key ‘C-x 4 j’ instead of ‘C-x j’.

Commands ‘icicle-bookmark’ and ‘icicle-bookmark-other-window’ can use a cache for the set of available bookmarks. This improves performance, especially if you have a lot of bookmarks. The downside is that the list of completion candidates is not automatically updated when you add new bookmarks.

By default, this caching is off, so the set of possible bookmark candidates is always up-to-date. You can turn on this caching by setting option `icicle-bookmark-refresh-cache-flag’ to ‘nil’.

Alternatively, you can use a prefix argument to reverse the effect of this option. If you have a lot of bookmarks then I recommend that you customize the option to ‘nil’ and just update it occasionally by using ‘C-u’ for bookmark completion. That will temporarily turn off caching so that the current jump command refreshes (updates) the cache. The default value of the option is ‘t’ only to avoid confusion for new users.

The bookmarks cache is also used for searching bookmarks (see next). The type-specific bookmark jump commands (e.g. ‘icicle-bookmark-info-other-window’) do not use the cache, since they typically use a smaller number of candidates. And the cache is automatically updated whenever you use ‘S-delete’ to delete a candidate bookmark.

See Also: Icicles - Tripping.

Searching Bookmarked Objects

Icicles search (and replace) lets you search across multiple buffers, files, or bookmarks. This is true for nearly all Icicles search commands. You use a plain prefix argument to specify bookmark searching. For command ‘icicle-search’ itself (`C-u C-c `’), you can alternatively use the specific command ‘icicle-search-bookmarks-together’.

When you do this you first choose the bookmarks to search, using completion. Use ‘C-RET’ and similar multi-command actions to choose (use ‘RET’ for the final choice). Once you have chosen the bookmarks, you type a search pattern to narrow the set of candidates.

(Multi-command ‘icicle-bookmark-list’ similarly lets you choose bookmarks (or bookmark names, with a prefix argument). It returns them in a Lisp list.)

When you search the text of a region bookmark, the search is limited to the region.

If you use library Bookmark+, then marking bookmarks in buffer ‘*Bookmark List*’ is another way of choosing them for searching. Mode-specific Icicles search, ‘M-s M-s m’ (in this case, ‘icicle-search-bookmark-list-marked’) searches the marked objects, in this case the targets of the marked bookmarks. (You can similarly use ‘M-s M-s m’ in Ibuffer, BufferMenu, and Dired to search all marked buffers/files using Icicles search.)

In addition to using Icicles search on a set of bookmark targets together, you can use the following Icicles search [multi-commands that are specific to bookmarks:

‘icicle-search-bookmark’ is a general command; the others are each specific to a certain kind of bookmark candidate, and they need library Bookmark+. The last four let you search bookmarks that have a certain set of tags.

All of these commands act the same way. They are multi-commands, so you can use them to search multiple bookmarks. But unlike ‘icicle-search-bookmarks-together’ (`C-u C-c `’) and ‘icicle-search-bookmark-list-marked’ (‘M-s M-s m’), you do not first choose the bookmarks and then search them together. Instead, you search them one at a time, choosing each with a multi-command action.

‘icicle-search-bookmark’ is flexible, letting you specify any set of bookmarks to use as candidates. The candidates are the bookmarks last shown in the ‘*Bookmark List*’ display (list ‘bmkp-sorted-alist’, to be precise).

You can use the Bookmark+ features of ‘*Bookmark List*’ to limit the candidates to bookmarks of a certain type (e.g., only autofiles, using ‘A S’), bookmarks with certain tags (e.g., only those with tags matching a regexp using `T m %’ followed by `>’), and so on. Whatever set of bookmarks are shown (or were last shown) in ‘*Bookmark List*’ are the bookmarks to be searched.

See Also:

Bookmarking Icicles Search Hits

When you use Icicles search (of any kind), you can use `C-x C-M->’ to save the current set of completion candidates (search hits) as an Icicles search-hits bookmark. “Jumping” to such a bookmark during Icicles search (of anything) restores those search hits: `C-x C-M-<’ replaces the current search hits with them, and `C-x C-<’ adds them to the set of current search hits.

Acting On Bookmark Properties

An Emacs bookmark record is a list with the bookmark name as car and a list of bookmark properties as cdr – see variable ‘bookmark-alist’ for a description of the commonly used properties.

When you use an Icicles command that reads a bookmark name, you can use ‘C-S-RET’ (‘icicle-candidate-alt-action’) to apply a function to any property of the current bookmark candidate. You are prompted for the function and the property.

You choose the target property using completion from among those available for the current bookmark candidate. Remember that you can use ‘C-M-RET’ to see a description of the bookmark, which typically describes its most important properties.

You can choose any function symbol using completion, or you can enter a lambda expression. The function chosen must accept the particular property value or else you will see an error message.

The value returned by the function is pretty-printed. If the function you choose is ‘identity’ then the action just pretty-prints the property value, which can be useful, even if trivial.

If you use `Bookmark+’, ‘C-M-RET’ can be particularly useful for acting on bookmark tags or on the text of a snippet bookmark.


Previous: Icicles - Other Search CommandsIciclesIciclesIndexNext: Icicles - Emacs Tags Enhancements

DrewsElispLibraries referenced here: Lisp:icicles.el

CategoryBookmarking CategoryCommands CategoryCompletion CategoryModes CategoryProgrammerUtils CategoryCode CategorySearchAndReplace CategoryShell CategoryRegion