CtagsSideKick plugin documentation

Description

CtagsSideKick is a SideKick service that provides a tag tree for the current buffer based on the output of the "Exuberant ctags" tool, to simplify navigation in the current buffer.

CtagsSideKick is an enhanced version of the CodeBrowser plugin, that uses SideKick instead of displaying its own dockable. A little bit of code was inherited from the CodeBrowser, but this is mostly a rewrite. CtagsSideKick provides several features that do not exist in CodeBrowser, mainly grouping tags by namespace (e.g. grouping class members under the their class), and icons representing the tag type (function/variable/...). These are especially useful when there are several tags of the same name in the buffer. On the other hand, there are several features of the CodeBrowser plugin that are not provided by CtagsSideKick, mainly the buffer switcher. CtagsSideKick works a little differently than CodeBrowser: It uses line numbers rather than regular expressions for navigation. This has both advantages and disadvantages. Navigation may not work correctly if the buffer is not parsed after modification, however it will work correctly for tags defined several times in the buffer with exact same lines (e.g. a "mouseMoved" method defined in several different classes using the exact same header line).

Usage

To use CtagsSideKick, open the SideKick dockable using Plugins->CtagsSideKick->Sidekick. Once open, you can click the small triangle near the top left corner and select the side on which to dock it.

By default, CtagsSideKick registers itself as a SideKick service for the C, C++, and Java edit modes. You can also use it for many other modes (since "ctags" supports many languages), but for other modes you'd have to select "ctags" from the combo-box at the top right corner of the Sidekick dockable. (Or, if you want to use it permanently for other modes, use the SideKick plugin options to associate the "ctags" parser with the desired modes.)

Options

CtagsSideKick provides the following options through Plugins->Plugin Options->CtagsSideKick:

• ctags path: Here you should specify the full path to your 'ctags' executable.
• Sort tags by name: Select this option to sort the tags by name, or deselect it to sort the tags by their position in the buffer.
• When sorting, folders precede leafs: This is useful when grouping by namespace and sorting by name. Select this option if you want namespaces (classes/structs/...) to be shown above non-namespace tags, or deselect it to show all tags under a namespace sorted by name. For example, if you have a class "A", a class "B" nested inside "A" (A.B), and a member "a" inside A, selecting this option will put "B" on top of "a" (because "B" is a namespace tag), and deselecting it will put "a" on top of "B" (because "a" is alphabetically smaller than "B").
• Group tags by: There are 3 different tree presentations.
  1. Grouping by kind is the same as the CodeBrowser plugin. All functions will be under a "function" parent, all classes under "class", and so on - a simple 2-level deep tree.
  2. Grouping by namespace (multi-level) will put every tag under its namespace - e.g. "A.f()" will have two nodes - one for the class "A" and one for method "f()". The method node will be under the class node.
  3. Finally, grouping by namespace (flat) flattens nested namespaces by concatenating their names with the namespace-separator character. E.g. in C++, a function 'f' in a class 'B' that's nested inside a class 'A' will create a node "A::B" in the tree (for class B) and put the node for 'f' under it.
• Show icons: Select this option to show icons specifying the tag type near each tag, deselect it to show the tags with no icons.

Useful ctags.cnf for jEdit users

Exuberant ctags can be configured by placing some default rules in either $HOME/.ctags or %USERPROFILE%/ctags.cnf (windows only). Placing these options into your ctags configuration file will make sidekick behave a little better for ant, html, and C++ files. In particular, C++ users will see function declarations as well as definitions, which will make sidekick much more useful when parsing header files. For ant build.xml files, we will see type-groupings of elements, to help separate the <target> from <property> elements.

--langdef=ant
--regex-ant=/<property[ \t]*name[ \t]*=[ \t]*\"([^\"]+)/\1/Properties/i
--regex-ant=/<target[ \t]*name[ \t]*=[ \t]*\"([^\"]+)/\1/Targets/i
--regex-ant=/<path[ \t]*id[ \t]*=[ \t]*\"([^\"]+)/\1/Paths/i
--regex-ant=/<taskdef[ \t]*id[ \t]*=[ \t]*\"([^\"]+)/\1/Taskdefs/i
--regex-ant=/<typedef[ \t]*id[ \t]*=[ \t]*\"([^\"]+)/\1/Typedefs/i
--langdef=xml
--langmap=xml:.xml
--regex-xml=/<([^ \t]+)[ \t]*(\w+)[ \t]*=[ \t]*\"([^\"]+)/\1 \3/XML Tags/i
--extra=+q
--fields=+i
--langdef=html
--langmap=html:.html
--regex-html=/<([^>]+)>/\1/HTML Tags/i
--c++-kinds=+p

Enjoy!