Lugaru's Epsilon
Programmer's
Editor

Context:
Epsilon User's Manual and Reference
   Commands by Topic
      Getting Help
         Info Mode
         Web-based Epsilon Documentation
      Moving Around
         . . .
         Searching
         Bookmarks
         Tags
         Source Code Browsing Interface
         Comparing
      Changing Text
         Inserting and Deleting
         Killing Text
         Clipboard Access
         . . .
         Hex Mode
      . . .

Previous   Up    Next
Bookmarks  Commands by Topic   Source Code Browsing Interface


Epsilon User's Manual and Reference > Commands by Topic > Moving Around >

Tags

Epsilon 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 main() function), use this to get to the other tag references, or press "?" after typing the tag name to select the correct file from a list. If you give goto-tag a nonzero numeric argument, it goes to the next tag without even asking for a name. When there are several instances of a single tag, you can also use Ctrl-<NumPlus> and Ctrl-<NumMinus> to move among them.

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 . to force the definition to appear in the current window. Press 2 or 5 to split the current window horizontally or vertically, respectively, and display the definition in the new window, or 1 to delete all windows but the current one, or z to run the zoom-window command first.

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 #define constants. But it doesn't tag declarations (variables that use extern, function declarations without a body). With a numeric prefix argument, Epsilon includes these too. (Typically you'd do this for header files when you don't have source code for the function definitions--system files and library files, for instance.)

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 extern keyword). If three, Epsilon tags both types of declarations. Using a prefix argument with tag-files temporarily sets tag-declarations to three, so it tags everything it can. You can also set the tag-which-items variable to make tagging skip certain types of items, such as structure tag names or #define constants. Set tag-c-preprocessor-skip-pat to make Epsilon skip certain #if blocks when tagging C mode files.

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 "-tags" (causing Epsilon to search again the next time you use a tagging command).

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.

Standard bindings:

  Ctrl-X <Period>  goto-tag
 Ctrl-X <Comma>  pluck-tag
 Ctrl-X Alt-<Period>  tag-files
 Ctrl-X Alt-<Comma>  select-tag-file
 Ctrl-<NumPlus>  next-tag
 Ctrl-<NumMinus>  previous-tag
   retag-files
   clear-tags
   untag-files
   sort-tags
 



Previous   Up    Next
Bookmarks  Commands by Topic   Source Code Browsing Interface


Lugaru Copyright (C) 1984, 2012 Lugaru Software Ltd. All Rights Reserved.