Utags.vdm
Lookup from tags database

The utags.vdm macro is used to lookup symbols from the tags database created with ctags.vdm or with an external ctags program.

Put the tags file in the root of your project's folder structure. This way, it is found even if you are editing a file in one of the sub-folders. Utags.vdm searches for the tags file first from current file's directory, then from it's parent directory, then from the parent directory of that directory, and so on. If tags file is not found, an error message is diplayed on status line and the macro exits.

To lookup for a symbol (function, macro or constant), put cursor on the symbol in your source file and run utags.vdm.
To run utags.vdm, either

The file that contains the definition of the function, macro or constant is now opened and cursor is moved to correct location in the file.

If no symbol name is found at cursor location when you call Utags.vdm, a dialog box opens to inform you about this. You can then enter the symbol in the input field (or paste it from clipboard by pressing Ctrl-V). This allows you to search for a symbol that is not called in the currently open file. Or click [ Cancel ] and then move cursor to symbol location in the source file and try again.

If a (small) block is highlighted when utags.vdm is called, the block is used as symbol name. This allows you to specify exactly what you are searching for.

If there are multiple instances of the definition (e.g. different versions of the same file, or different versions of a function using #if's), the first instance is located immediatelly, but in addition, a message such as "Match 1 of 3" is displayed on status line. You can then call Utags again to show the next occurrence, and so on (the cursor must be on the function name, of course). After the last occurrence is displayed, the first occurrence is displayed again.

Utags.vdm has multi-level return function. Each time you jump to function/symbol definition using utags.vdm, the original location is stored in file utag_stack.tmp. You can then return to original location by pressing the hotkey (Ctrl-Shift-F12 recommended, see below). There is no limit in how many levels of return can be stored in the stack.

Utags.vdm returns to previous location only if that file is still open in Vedit. If the file is not open, utags.vdm skips that location and fetches previous location from the stack. When no more return locations are in the stack, message "No more files to return to" is displayed on status line.

For easy access to Utags.vdm and Ctags.vdm, add calls for the macros in your User Menu, and then add keyboard shortcuts for those menu items. For details, see Setting up User Menu and Keyboard shortcuts.

Configuring utags.vdm

You can change the vay utags.vdm works by editing options near the beginning of utags.vdm
#60 = 1		//#60 determines what is done when the symbol is found:
1 - Simply switch to the symbol's definition file.
2 - Cascade all windows with symbol's definition file on top.
3 - Switch to the symbol's definition file; assign Ctrl-Shft-F12 to switch back to original file.

If option 3 is selected, help window is displayed on bottom of the screen giving information about the key configuration. The help window remains visible as long as there are items in the return stack.

In most cases, option 0 is the best choice. Option 3 is not needed if you have configured the Ctrl-Shft-F12 key by default (see the link above).

#68 = 0		//#68 can be set for compatibility with TAGS file created by other utility.
0 - Normal mode (tags file created by ctags.vdm)
1 - Compatibility mode. Remove quote characters '\' from search string (regular expressions)

Compatibility with other Ctags tools

Utags.vdm is compatible with tags files created with Unix ctags facility or other Ctags tools. However, note the following details about tags file structure:

Ctags.vdm does not quote any characters inside the search string. If you are using tags database created with some other ctags tool, it may contain quote characters (\). In this case, you need to configure utags.vdm to remove quote characters by setting register #68 = 1, as described in "Configuring utags.vdm" above.


See also:

CTAGS Symbol lookup - General information about ctags facility.
Ctags.vdm - Setting up tags database
Setting up User Menu and Keyboard shortcuts