: [[image:iciclesimage]]

|| *Previous:*  [[Icicles - Info Enhancements]] || '''[[Icicles]]''' || IciclesIndex || *Next:* [[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, [[buffer]]s, or [[bookmark]]s.






[:BookmarksForProjects]
== Bookmarks for Project Access and Organization ==

If you use '''[[Bookmark+]]''' (library <tt>[[bookmark+.el]]</tt>), then you can use
bookmarks of various types, including the following, to help
manage software projects:

* [[Dired]] buffers, with specific sets of files and subdirectories
 that are marked or omitted, and using specific listing switches.

* `##*Bookmark List*##' buffers, with specific sets of bookmarks that
  are marked or hidden.

* Multiple alternative ''bookmark files''.  For example, use a
  different one for each project.  Or use different ones for
  subprojects and use them together for a full project.

* [[DeskTop]]s, which include sets of [[variable]]s and visited [[buffer]]s
  and files.

* Composite, or sequence, bookmarks, which ''combine'' other
  bookmarks.

You can also associate ''tags'', in the [[http://delicious.com|del.icio.us]] sense, with most
types of bookmarks.  (Such tags are unrelated to the Emacs
source-code tags that use [[tags file]]s.)  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]].










[:TagsFileProject]
== 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-command]]s 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'''
[[Icicles - File Name Input#ReadingFileNames|Commands that Read File Names]].











[:NavigatingCode]
== 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 [[TagsFile|tags file]] is just a saved index for project files.)

'''See Also:'''

* [[Icicles - Other Search Commands#IciclesImenu|Icicles Imenu]]
* [[Icicles - Emacs Tags Enhancements]]
* [[Icicles - Other Search Commands#IciclesCompileOrGrep|Compile/Grep Search]]










[:SearchingProjectFiles]
== 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 - Bookmark Enhancements#SearchingBookmarkedObjects|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
[[Icicles - Search-And-Replace|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.










[:DefiningAndSavingSets]
== 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.

[new:DrewAdams:2010-04-03 01:23 UTC]
'''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 <tt>[[bookmark+.el]]</tt>).
Bookmarking features are described elsewhere, but they work in
concert with '''Icicles''' to offer very good project support.
See [[Icicles - Bookmark Enhancements]].
[new]

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 ''[[buffer]]s'', use [[command]]s `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]], [[Icicles - Nutshell View#ChippingAway|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 [[Icicles - Dired Enhancements#SaveMarkedNamesHereAndBelow|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 [[fileset]]s and use those the same way. An '''Icicles''' cache-file set of saved file names can include Emacs filesets -- see [[Icicles - Persistent Completions#Filesets|Filesets and Icicles Saved Completion Sets]].

'''See Also:'''

* [[Icicles - Candidate Sets]]
* [[Icicles - Persistent Completions]]
* [[Icicles - Bookmark Enhancements]]
* [[Icicles - Progressive Completion]]
* [[Icicles - Nutshell View#ChippingAway| Chipping Away the Non-Elephant]]
* [[Icicles - File-Name Input#MatchFileContent|Match File Names and File Content Too]]
* [[Icicles - Dired Enhancements#SaveFilesAsCandidates|Icicles - Save Marked Names as Completion Candidates]]











[:RetrievingSavedProject]
== 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 <tt>[[bookmark+.el]]</tt> then you can open a project that
is defined by a set of bookmarks, by doing one of the following:

* Using a project-specific ''bookmark file''.

* Using a ''bookmark-list bookmark'' (it records a `##*Bookmark List*##'
  buffer state, including which bookmarks are marked or omitted).

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]].

[:icicle-grep-saved-file-candidates]
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 <tt>[[dired+.el]]</tt> (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 [[TagsFile|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]
== 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-command]]s,
'''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 Enhancements]] || '''[[Icicles]]''' || IciclesIndex || *Next:* [[Icicles - Complex Completions]] ||




DrewsElispLibraries referenced here: Lisp:icicles.el


CategoryCommands
CategoryHelp
CategoryCompletion
CategoryRegexp
CategoryModes
CategoryProgrammerUtils
CategoryCode
CategorySearchAndReplace
CategoryShell
CategoryProject