Icicles - Support for Projects

Previous: Icicles - Info EnhancementsIciclesIciclesIndexNext: Icicles - Complex Completions

Icicles Support for Projects

This page mainly provides pointers to other sections of the Icicles doc that describe features that can help you work with a project that involves multiple files, buffers, or bookmarks.

Bookmarks for Project Access and Organization

If you use Bookmark+ (library bookmark+.el), then you can use bookmarks of various types, including the following, to help manage software projects:

You can also associate tags, in the del.icio.us sense, with most types of bookmarks. (Such tags are unrelated to the Emacs source-code tags that use tags files.) A bookmark can have any number of tags, and multiple bookmarks can have the same tag, which means you can use them to organize their target objects. And tags can be more than just names: they can be user-defined attributes, with EmacsLisp objects as their values.

These and other Bookmark+ features give you different ways to save, restore, filter, access, and otherwise organize projects, as collections of information about source-code components and related software.

Icicles enhances access to such features. See Icicles - Bookmark Enhancements.

A Tags File Can Define a Project

One simple kind of a project includes the files that are in or under a single directory. Such a project is limited, but it can often be useful, and it has the advantage of being supported by several existing Emacs features.

Another simple kind of project includes the files that are listed in a given Emacs tags file. This is obviously more complex and flexible than a directory listing.

Icicles provides multi-commands for visiting one or more files that are listed in the current tags table: ‘icicle-find-file-in-tags-table’ and ‘icicle-find-file-in-tags-table-other-window’.

See also Commands that Read File Names.

Navigating Among Code Definitions

For software projects, you need to be able to navigate among code definitions. ImenuMode and EmacsTags features are useful for this, as are GrepMode and CompilationMode buffers. Icicles improves all of these. (A tags file is just a saved index for project files.)

See Also:

Searching Project Files

Searching within your project is another area where Icicles can help. Icicles search is both search and navigation. Navigating among tags (definitions) that match a regexp is also really searching, and the same is true for ImenuMode and GrepMode navigation.

See also Icicles - Search Commands, Overview and its subsections for information about the many ways that you can use Icicles search to access parts of your projects.

See also Icicles - Dired Enhancements for an easy way to search marked files in Dired with Icicles search.

See also Icicles - Searching Bookmarked Objects for ways to search bookmarked objects, including the files that have a given set of del.icio.us-style tags and the bookmarks that are marked in a given bookmark-list state.

And do not forget that all uses of Icicles search also let you do search-and-replace on the fly. This applies to ‘grep’ results, searching marked files in Dired, tags navigation, and Imenu navigation. You can at any time replace the current search hit or just the part of it that matches your current input.

Defining and Saving Sets of Files or Buffers

Let’s assume that you have one or more sets of files or buffers that you use frequently. For each such set of objects, you create an Emacs option whose value is a list of the file or buffer names (strings). Later, you use the option value to refer to those objects by name. This brings you back to the context of working with just those particular files or buffers that belong to your project. You can search such sets or navigate among their objects. Icicles has a number of features that can help with these tasks.

Note: Bookmarks are also persistent references to files and buffers, and you can use sets of bookmarks similarly. Bookmarking is a vanilla Emacs feature. Being able to manipulate explicit sets of bookmarks is a Bookmark+ feature (library bookmark+.el). Bookmarking features are described elsewhere, but they work in concert with Icicles to offer very good project support. See Icicles - Bookmark Enhancements.

Before you can name and save a set of file or buffer names, you must define its members: pick the file or buffer names that you want to belong to a given project. Icicles can help with this.

For buffers, use commands ‘icicle-add-buffer-config’ and ‘icicle-remove-buffer-config’ to define one or more buffer configurations. These are named sets of buffers, sort functions, and other parameters that control completion of buffer names. Thereafter, you can use command ‘icicle-buffer-config’ to choose a configuration to be current.

To define a set of files, you use Icicles completion against file names. You can use progressive completion, chip away the non-elephant, and so on, to get just the file names you want.

For this completion, you can use a command that calls ‘read-file-name’, and so matches relative file names using the the current default directory. Or you can use a command that calls ‘completing-read’, and so matches file names only as ordinary strings, that is, with no notion that they are file names. In the latter case, the file names are often absolute, which means that you can match not only file names but also directory components.

Examples of the former type are ‘icicle-find-file’ and ‘icicle-find-file-read-only’ (‘C-x C-r’ by default). Examples of the latter type are ‘icicle-find-file-absolute’, ‘icicle-find-file-in-tags-table’, ‘icicle-recent-file’, and ‘icicle-locate-file’. Command ‘icicle-file’ (bound to ‘C-x C-f’ by default) lets you do both, depending on the prefix argument.

You save a set of file and directory names the same way you save any set of completion candidates. You can save all of the names that match your current input. You can add a set of names or individual names to a set of names that you have already saved.

In addition, you can save the names of the marked files and subdirectories in Dired persistently as a project.

Your project is not only files that are all in the same directory, of course. If you use library Dired+ then you can also save all of the marked file names in the current directory and in marked subdirectories, recursively – see Save Marked Names Here and Below.

Even if you do not use Dired+, with Icicles you can easily save file names from multiple directories in the same set. And you can include directory names as well, for use later with commands that operate on directories.

Finally, you can also save file names as Emacs filesets and use those the same way. An Icicles cache-file set of saved file names can include Emacs filesets – see Filesets and Icicles Saved Completion Sets.

See Also:

Retrieving and Reusing a Saved Project

This section could also be called Using Retrieved Saved Sets.

You retrieve a set of saved file names (a project) the same way you retrieve any saved set of completion candidates. That is, you access the files defined for your project by retrieving their names during completion, to serve as the current set of completion candidates. This odd feature is unique to Icicles.

There’s nothing much more to say about this, except that you should be taking advantage of it now ;-). Define and save a set of project files (or buffers), and later use just those files, staying within the bounds of your project for your navigation, search, compilation, etc. needs. Even if the files you use in a given project are scattered all over your file system, Icicles lets you access them together as a named unit. For more information, see Icicles - Candidate Sets.

If you use library bookmark+.el then you can open a project that is defined by a set of bookmarks, by doing one of the following:

You can also open Dired for a project or for a list of file names saved non-persistently as completion candidates – only those files are listed in the Dired buffer. See Icicles - Dired Enhancements.

You can also run ‘grep’ on a saved list of file names using ‘M-s M-s g’ (command ‘icicle-grep-saved-file-candidates’). If you use library dired+.el (see DiredPlus), then you can also ‘grep’ the files in a project or saved list of file names by opening it in Dired and then using ‘M-g’ (‘diredp-do-grep’).

Finally, note that among the sets of completion candidates that you can save are Icicles search hits. That’s right. Icicles search lets you search multiple buffers, files, or bookmarks, and you can save selected search hits or all matching hits for later use. When you save search hits, Icicles records the buffer or file names and the hit locations within those buffers or files. When you retrieve such a saved set to access its hits, Icicles automatically takes you to the proper files.

A related feature is being able to filter tags definitions and then save the filtered hit list. This works the same way, and it gives you the equivalent of per-project tags files: A saved hit list acts just like a custom tags file when you reuse it. And unlike some of your project files, a tags file does not change often, so saved hit sets stay accurate longer.

Semantics? Roll Your Own?

I no longer develop software. I just putz around with EmacsLisp for my own enjoyment, entertainment, and enlightenment. So I do not use things like ECB (EmacsCodeBrowser) or SemanticBovinator. I do not use any IDE that has knowledge of a particular programming language. The Icicles commands I’ve written therefore use little or no semantic or language information; they rely upon syntax for the most part, and they are essentially language-agnostic (i.e. ignorant).

But you are a different story. If you use, say, Semantic, you could write a little EmacsLisp code to take advantage of Icicles in combination with Semantic’s parser information. With complete ignorance of Semantic, I dare say it would not be hard. If you can get an alist of completion candidates for something from Semantic in some context, then you can exploit all of the Icicles features: apropos completion, progressive completion, multi-commands, Icicles search, and so on. Likewise for any other IDE that plays well with Emacs and for any other programming language support. Think about it. Others would appreciate your contribution.

Icicles provides lots of features for EmacsLisp programmers. The end-user commands I’ve written using some of those features are really just a demonstration of what you can do. Try rolling your own Icicles commands. See Also: Icicles - Note to Programmers.

Previous: Icicles - Info EnhancementsIciclesIciclesIndexNext: Icicles - Complex Completions

DrewsElispLibraries referenced here: Lisp:icicles.el

CategoryCommands CategoryHelp CategoryCompletion CategoryRegexp CategoryModes CategoryProgrammerUtils CategoryCode CategorySearchAndReplace CategoryShell CategoryProject