TagsEpsilon provides a facility to remember which file defines a particular subroutine or procedure. This can come in handy if your program consists of several source files. Epsilon can remember this kind of information for you by using "tags". A tag instructs Epsilon to look for a particular function at a certain position in a certain file.
The goto-tag command on Ctrl-X <Period> prompts for the name of a function and jumps immediately to the definition of the routine. You can use completion (see Completion & Defaults) while typing the tag name, or press "?" to select from a list of tags. (Epsilon also shows the defining file of each tag.)
If you don't give a name, goto-tag goes to the next tag with
the same name as the last tag you gave it. If the same tag occurs
several times (for example, if you tag several separate files that
each define a
The pluck-tag command on Ctrl-X <Comma> first retrieves the routine name adjacent to or to the right of point, then jumps to that routine's definition.
If the file containing the definition appears in a window already, Epsilon will change to that window. Otherwise, Epsilon uses the find-file command to read the file into a buffer and displays it in the current window. Then Epsilon jumps to the definition, positioning its first line near the top of the window. You can set the window line to receive the first line of the definition via the show-tag-line variable. It says how many lines down the definition should go.
You can tell Epsilon to display the definition in a particular window,
instead of letting Epsilon decide, by running goto-tag or
pluck-tag with a numeric prefix argument of zero. Then these
commands will prompt for a key to indicate the window. Press an arrow
key to display the definition in the next window in that direction.
Press n or p to display the definition in the next or previous window
in the window order. Type the period character
Before Epsilon moves to the tag, it sets a temporary bookmark at your old position, just like the set-bookmark command on Alt-/. After goto-tag or pluck-tag, press Alt-J or Ctrl-<NumStar> to move back to your previous position.
Normally, you have to tell Epsilon beforehand which files to look in. The tag-files command on Ctrl-X Alt-<Period> prompts for a file name or file pattern such as *.c and makes a tag for each routine in the file. It knows how to recognize routines in C, C++, Java, Perl, Visual Basic, Python, PHP and many other languages. (Using EEL, you can teach Epsilon to tag additional languages. See Tagging Internals.) If you tag a previously tagged file, the new tags replace all the old tags for that file. You can use extended file patterns to tag files in multiple directories; see Extended file patterns. To easily tag just the current file, press Alt-g at the prompt. When Epsilon can't find a tag, it tries retagging the current file before giving up; that means if your program is confined to one file, you don't have to tag it first. Set tag-ask-before-retagging nonzero if you want Epsilon to ask first.
In Perl, PHP, Visual Basic, and Python, Epsilon tags subroutine
definitions. In C, C++, Java, EEL and other C-like languages,
tag-files normally tags subroutine and variable definitions,
typedef definitions, structure and union member and tag definitions,
enum constants, and
You can also set up tag-files to include declarations by
default, by setting the tag-declarations variable. If zero
(the default), tag-files only tags definitions. If one,
Epsilon tags function declarations as well. If two, Epsilon tags
variable declarations (which use the
Set tag-case-sensitive nonzero if you want tagging to consider MAIN, Main and main to be distinct tags. By default, typing "main" will find any of these.
Epsilon can maintain separate groups of tags, each in a separate file. The select-tag-file command on Ctrl-X Alt-<Comma> prompts for the name of a tag file, and uses that file for tag definitions.
When Epsilon needs to find a tag file, it searches for a file
in the current directory, then in its parent directory,
then in that directory's parent, and so forth, until it reaches the
root directory or finds a file "default.tag". If Epsilon finds no
file with that name, it creates a new tag file in the
current directory. To force Epsilon to create a new tag file in the
current directory, even if a tag file exists in a parent directory,
use the select-tag-file command. Once Epsilon loads a tag file,
it continues to use that tag file until you use the
select-tag-file command to select a new one, or delete the
buffer named "
You can set the variable initial-tag-file to a relative pathname like "myfile.tag", if you want Epsilon to search for that file, or you can set it to an absolute pathname if you want Epsilon to use the same tag file no matter which directory you use.
The tag system can also use .bsc files from Microsoft Visual Studio 4.1 and later. To use .bsc files, you must set your compiler to generate them, then use the Alt-x configure-epsilon command to download and install the DLL file that matches your compiler version. See Source Code Browsing Interface for details. Finally, use the select-tag-file command on Ctrl-X Alt-<Comma> to select your .bsc file.
When Epsilon uses a .bsc file, the commands tag-files, retag-files, clear-tags, sort-tags, and the variables tag-case-sensitive, tag-relative, want-sorted-tags, and tag-by-text do not apply. See Microsoft compiler documentation for information on generating .bsc and .sbr files.
The retag-files command makes Epsilon rescan all the files represented in the current tag file and generate a new set of tags for each, replacing any prior tags. The clear-tags command makes Epsilon forget about all the tags in the current tag file. See the tag-options variable if you want the tag-files command to clear old tags automatically. The untag-files command displays a list of all files mentioned in the current tag file; you can edit the list by deleting any file names that shouldn't be included, and when you press Ctrl-X Ctrl-Z, Epsilon will forget all tags that refer to the file names you deleted.
When Epsilon records a tag, it stores the character position and the text of the line at the tag position. If the tag doesn't appear at the remembered character offset, Epsilon searches for the defining line. And if that doesn't work (perhaps because its defining line has changed) Epsilon retags the file and tries again. This means that once you tag a file, it should rarely prove necessary to retag it, even if you edit the file. To save space in the tag file, you can have Epsilon record only the character offset, by setting the variable tag-by-text to zero. Because this makes Epsilon's tagging mechanism faster, it's a good idea to turn off tag-by-text before tagging any very large set of files that rarely changes.
By default, Epsilon sorts the tag list whenever it needs to display a list of tag names for you to choose from. Although Epsilon tries to minimize the time taken to sort this list, you may find it objectionable if you have many tags. Instead, you can set the want-sorted-tags variable to 0, and sort the tags manually, whenever you want, using the sort-tags command. You can also tell Epsilon not to automatically save its tag file by setting the auto-save-tags variable to zero.
Epsilon normally stores file names in its tag file in relative format, when possible. This means if you rename or copy a directory that contains some source files and a tag file for them, the tag file will still work fine. If you set the variable tag-relative to 0, Epsilon will record each file name with an absolute pathname instead.