The Symbol lookup plugin allows you index your sources as well as the system headers
allowing to perform quick lookups of symbols.
With an index you can:
- Quickly navigate to a declaration of a function, variable, #define, typedef, class etc.,
opening the enclosing header file — this way you can for instance read the header
comments about that particular function, examine the parameters, navigate around to
examine related APIs etc.
- Quickly navigate to a definition of a function, allowing you to look at it's source
- Complete a function or class name with a keyboard shortcut
In addition, the index file maintained by the Symbols plugin can be used to help
the Smart Open Selection (Command-D)
command and Open Quickly find the file you are looking for faster.
Option-clicking a symbol in Eddie will attempt to open the header file where the symbol was declared. Placing a cursor anywhere on the symbol (or selecting it or it's part) and pressing Control-Option-/ will also attempt to look up the symbol in an index and open the header file where this symbol was defined. If there is more than one declaration of the symbol (common for instance with C++ overloaded methods or virtuals), Eddie will show a popup window with a list of all the header files that declare it.
To look up a definition of a function Control-Option-clicking the corresponding symbol in an Eddie document. If the symbol is found in the index, the corresponding source file will be opened, revealing the function definition. As with declarations, when multiple definitions are available, a popup window shows up, allowing you to pick the one you are interested in. Command-Option-/ lets you look up a function definition from with a keyboard shortcut.
Symbol completion works much like Tab completion in the Shell Windows (or bash). Type a portion of a symbol (and press Control-Period if you disabled the "Auto-complete symbols while typing" checkbox). If the typed portion of a symbol is recognized, either the rest of the symbol will fill in or a popup window will show with all the possible completions, allowing you to choose one. Instead of picking a completion from the window you can also type one or two more letters to narrow the choices and repeat.
Here is an overview of all the shortcuts and mouse commands:
Shortcut |
Mouse click |
Command |
Control-Option-/ |
Option-Click a symbol |
Look up declaration |
Command-Control-/ |
Control-Option-Click a symbol |
Look up definition |
Command-Shift-Option-/ |
Show the symbol lookup dialog and enter symbol to look up |
|
Control-. |
Complete a symbol |
Symbol lookup depends on the presence of the index (tags) files. Typically there is one tags file for the system headers and one tags file for the project you are working on.
The system header tags file is located at
~/Library/Caches/com.el34.eddie/SystemHeaderTags
The local tags file is typically located at the top level folder of your project's
source tree in the file tags. If used, Eddie tries to place the tags file into your build folder.
When looking up a symbol, the Symbols plugin first locates the two index (tags) files. It searches the parent directory of the document you are looking up a symbol in for the local tags file. If it can't find it there, it walks up the parent directories until it finds one. When the local tags file is found, the Symbols plugin then looks up the requested text pattern in both the system and local tags.
If neither of the tags files exist, the Symbols plugin offers to create them. You may also generate or update the files from the Symbols plugin button menu — To generate the system header tags choose the "Create or update system tags" menu item. This usually takes a little under a minute or so.
To create the local tags file, choose "Create local tags" from the Symbols button menu and point Eddie to the top level folder of your project source hierarchy. The Symbols plugin can detect that the index file is out of date as it opens header files for a given symbol match. It can't always tell that the tags file needs updating though -- for instance if you try to look up a declaration for a function that you just added, it is not in the tags file yet and Eddie will think it's just an unknown symbol. If this is happening, you can just use the "Update local tags" menu item to re-generate the local tags file. Depending on your project size, this usually only takes a second or two.
There are a number of parameters that control the generation of the local and system tags. These can be changed in the Symbols pane in the Preferences window.
Here you can control exactly which hierarchies get scanned when indexing system headers.
Further, you may specify a subset of directories to avoid indexing to reduce the size of the index and exclude symbols that you never use in your coding.
You may specify which files get included in the scan when building the local index. (You could add .cc, .h++ here or remove .py, as needed).
You also have the option of specifying any preprocessor macros that could interfere with recognizing function declarations. The AVAILABLE_MAC_OS_X_VERSION... macros are an example of such a macro and a whole set of them is included here by default.
$(SDK) is a symbolic value that evaluates to the path of your current SDK, typically it is a synonym for `xcrun -sdk macosx --show-sdk-path` which you can use in it's place (or any other command in back-ticks, it will be evaluated when needed).
Note: did you know that if you press Command while looking at help labels for controls, some controls will show you a more verbose version of the help text? The Symbols preference pane uses these for some extra detailed description for these tweaky settings.You may prefer to generate the tags files by hand — in fact Eddie calls the cplustags tool when generating these, you can do the same yourself and fine-tune the parameters that you pass to the tool. If you are so inclined (or if you are curious how this works), you can still use some help here — select the "Help create tags in Worksheet" menu item in the Symbols button menu. It will paste commands to generate local and system tags into your worksheet. These are pretty much the same exact commands that Eddie runs for you when choose to create or update the tags files by just using the respective menu commands. Here you can modify the commands to your liking and execute them yourself.