Sublime Forum

Add custom Markers that will be shown in the Goto Symbol (Cmd+R) window



I’ve been using ST for a couple of years,

I’d like some guidance in first knowing if want I want to accomplish is possible through a plugin development, and if the answer is positive, maybe some reference as to where to start looking to develop this feature.

I would like to include some kind of marker that when placed in code, it includes a new entry in the list that is displayed in the Goto Symbol (Cmd+R) window. The closest example I have now is from Xcode, where in the source code you can include a comment with the “MARK:” keyword and it will render a new section in the top header bar of the editor (which is the equivalent of the goto symbol in ST).

When working with large files this feature would be of tremendous help because it allows to organize the blocks of code based on custom criteria regarding the logical relationships around it and not just the sequence of functions that exist in the file.



The way Goto Symbol works is, scopes are defined in the syntax definition file (.sublime-syntax), and a tmPreferences file defines which of those scopes to index in Goto Symbol.

Sublime Text has a view.add_regions API which will let you color a bit of random text as a particular scope, but it doesn’t affect Goto Symbol.

So the answer is, it is possible, but if you modify the syntax definition and symbol indexing metadata.

Do you have to use Goto Symbol? You can provide the same functionality by showing a quick panel, which you can populate however you want, and navigate to the relevant bit of code when each item is highlighted.



The contents of the symbol list is controlled by a preferences file that tells sublime what scopes should appear in the symbol list for any given language and, optionally, what transformations should be done for display purposes (e.g. to indent the methods in a class).

Such configuration files are tmPreferences files (XML files in Plist format) within a package and which are generally named with names that start with Symbol List. For example, Packages/C++/Symbol List.tmPreferences is one of such files for use in the C++ package (which covers, C, C++ and both flavors of Objective-C). Since the files are Plist files the actual names don’t matter, but this is a convention that makes such files easier to find.

There is some documentation on symbols you can read for more information.

Trivially, if you save the following XML into Packages/C++/Symbol List Pragma.tmPreferences it will add all of the #pragma MARK lines in your source files to the symbol list (current file only), replacing #pragma MARK with " ---- ":

<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
    <string>Symbol List</string>
    <string>(source.c | source.c++ | source.objc | source.objc++) &amp; (meta.preprocessor.c)</string>
            s/#pragma MARK/ ---- /g;

This doesn’t get you all the way there; for one thing, #ifdef and #endif directives are caught with this rule. Additionally it doesn’t visually indent everything that follows which IIRC XCode does. However, it’s a good starting point for seeing what is going on.

If you wanted to actually do this with special single line comments and not a #pragma I believe you would need to enhance the syntax highlighting for the language(s) you’re targetting to match such comments and give them a scope that you can uniquely target.



I was waiting for such feature for a long time, however a similar feature called Find (CMD+F) does the job for me :stuck_out_tongue: (except for the fancy list rendering)
you can simply add your desired keywords (tags) to the comments like
// @myFunction @fooHandler
so basically your marks will be editor independent.