| jEdit CtagsInterface Plugin Guide | (November 18 2012) |
Table of Contents
Table of Contents
The CtagsInterfacePlugin provides three dockables, a Tag List, a Tag Preview and a Progress. It also provides a number of operations that allow you to quickly jump from one file location to another in the editor, based on the context of the caret, and the indexed tag information obtained from the Exuberant Ctags executable. And finally, it provides a plugin interface through which other jEdit plugins can easily access ctags data.
CtagsInterface will happily index all files in your project or source
tree, unless you tell it otherwise.
Under Plugin Options - CtagsInterface - General you will
find a field for specifying
Ctags Invocation Options. The options required
for smooth running of CtagsInterface are
--fields=+anzKiSl
, in addition, as shown below, you can specify that only certain file types are scanned and indexed. Read the manual pages of exuberant ctags for more information about the options available.
--languages=c,c++,java,python
CtagsInterface uses a Lucene index to keep track of tag data from multiple origins (currently projects, trees, archives and source and tag files). provides three panes for defining which origins should be indexed: , and .
The first step is to add the origins that you want to be tagged. Tagging is done in the background, you can continue working with jEdit meanwhile. The tagging progress is shown in the Progress dockable, in a tab of a tabbed pane. When done, you can lookup tags from the origins you have added.
You can add projects two ways. From the ProjectViewer, right click on the project and , or from .
Similarly, you can add trees and archives from . You can also add source files and trees from the file system browser context menu: .
Lastly source and tag files can be added from and the source file currently in your buffer can be added through the action. Tags files can be added with the action .
Tags can be removed from the index using the options pane, actions in or the ProjectViewer context menu
By default, tag lookup will search the entire tag index for matching tags, including all added origins.
When using jEdit with ProjectViewer, you might be working with a set of files, and have to frequently check another set of files that you are reusing. This means that you will probably want to restrict your search to only the origins that are related to your project.
By editing the properties of the current project, you can see a Dependencies pane, which allows you to set the related projects, trees/archives or files on an individual project basis. While running the Tag Preview, or performing a Jump to Tag while working in a project that has dependencies set, CtagsInterface should restrict its searches to tag data from only those dependencies.
This is especially useful in the case where there are many origins indexed in the tags index that are not related to each other.
In addition, when the option to 'Match tags with language of current
buffer' is selected searches will be restricted to tags whose language
matches that of the file in the current buffer. File extension is used to do
this matching and the mapping can be seen by calling ctags with the
--list-maps option. If the source file's language hasn't
been tagged and this option is selected searches will return nothing, to fix
this retag your source files including the 'l' flag in the ctags
--fields option.
Table of Contents
Add Current File . Tags the file in the current buffer and adds it to the index.
Update Current File . Updates the file in the current buffer in the index, doesn't add the file as an origin if it's already in the index.
Remove Current File . Removes the tags from the file in the current buffer and their origin from the index.
Remove All Tags . Removes all tags and their origins from the index.
Jump to tag . Opens the file that the tag currently under the caret originates from and moves the caret to the tag definition within that file.
Tag Preview Current . Previews the tag currently under the caret in the Tag Preview dockable. Useful when the "Follow caret" Tag Preview option is deselected
Search tag by substring . Provides a dialog to conduct a substring search of the tag index, results returned in a pop-up.
Search tag by prefix . Provides a dialog to conduct a prefix search of the tag index, results returned in a pop-up.
Tag all projects . This does exactly what it says: it goes through every project that ProjectViewer knows about, and tags their files, adding the tag data to the embedded index.
Suggest completion options . Suggests code-completion options from the tag index. This includes completion of function calls, using SuperAbbrevs for conveniently filling-in the parameter values.
Run Query . Provides a dialog for running queries on the tag index using the Lucene query syntax.
Show Query Dialog . Provides a dialog and results pane for running queries on the tag index using the Lucene query syntax.
In addition to these built-in actions, CtagsInterface allows you to create dynamic Actions, which are custom Lucene queries, which can be bound to keyboard shortcuts. Each such Lucene query should retrieve a list of tags from the index. There are 3 types of dynamic actions:
Jump to tag - execute the query and show the list of tags it retrieved in the Tag List dockable, allowing you to jump to any of them. In case the query returns a single tag, the dynamic action jumps to it directly, without showing it in the dockable.
Search prefix - execute the query and show the "Prefix search" popup so you can choose a tag from the query results using its prefix.
Search string - execute the query and show the "Prefix search" popup so you can choose a tag from the query results using a substring.
To manage (create/delete/modify) dynamic actions, select the Actions pane in the plugin options. To define a new dynamic action, click the + button. You will be asked to provide a name for the action and a Lucene query. The action name you provide should not contain spaces, as it is used to define an ordinary edit action. The Lucene query can make use of the following keywords:
{tag}: The tag being looked up
{project}: The name of the active project
Here are a few examples:
_name:{tag} AND kind:function AND origin:{project}
_name:{tag} AND kind:prototype AND origin:{project}
There are three dockables that you can use from CtagsInterface.
Tag List . When jump to tag is invoked, if there is more than one possible match, the Tag List dockable is displayed, where you can preview and select the choices of jump locations.
Tag Preview . This dockable is used to preview tags currently being edited, and has an option to update automatically (after a configurable delay) whenever the caret is moved over a location that is a known symbol in the tag index. The dockable has an optional gutter with numbers and folding that matches the mode used in the previewed buffer. In addition CtagsSideKick can be forced as the fold handler if it's been installed. Using this and the option to collapse all folds allows for a more compact preview that's restricted to lines that have been parsed by CtagsSideKick. This can be modified by specifying which kinds of tags CtagsSideKick includes in . For instance adding
--java-kinds=cmp
to the invocation option will lead to folds being added around the classes, methods and packages of java files when they are previewed. See
--list-kinds
in the ctags documentation for more information.
Progress . This dockable shows the progress of tagging activities in a tabbed pane. Each activity has its own tab. By default, a tab closes automatically a few seconds after the activity is over, but you can configure this in the General option pane. You can close a tab manually by middle-clicking the tab title or clicking the Close button in the dockable.
CtagsInterface also offers services to other plugins, such as ClassBrowser and CodeHelper:
Queries of the tag index
Jumping to tags
Since the CtagsInterface manages the tag information and runs ctags, other plugins do not need to call/depend on ctags directly. This also means that in the future, the CtagsInterface may be extended to work with other code-indexing tools.
For a list of changes in this plugin, see the change log.