Comment Marks
Goto Symbol but for bookmarks written as code comments with configurable special characters.
Details
Installs
- Total 817
- Win 531
- Mac 131
- Linux 155
Dec 21 | Dec 20 | Dec 19 | Dec 18 | Dec 17 | Dec 16 | Dec 15 | Dec 14 | Dec 13 | Dec 12 | Dec 11 | Dec 10 | Dec 9 | Dec 8 | Dec 7 | Dec 6 | Dec 5 | Dec 4 | Dec 3 | Dec 2 | Dec 1 | Nov 30 | Nov 29 | Nov 28 | Nov 27 | Nov 26 | Nov 25 | Nov 24 | Nov 23 | Nov 22 | Nov 21 | Nov 20 | Nov 19 | Nov 18 | Nov 17 | Nov 16 | Nov 15 | Nov 14 | Nov 13 | Nov 12 | Nov 11 | Nov 10 | Nov 9 | Nov 8 | Nov 7 | |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Windows | 0 | 1 | 0 | 0 | 2 | 0 | 0 | 0 | 0 | 0 | 1 | 1 | 0 | 0 | 0 | 1 | 0 | 0 | 1 | 0 | 0 | 0 | 0 | 2 | 0 | 0 | 0 | 0 | 0 | 1 | 1 | 0 | 0 | 1 | 0 | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 2 | 0 | 0 |
Mac | 0 | 0 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 0 |
Linux | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
Readme
- Source
- raw.githubusercontent.com
Comment Marks
Set bookmarks or section headings simply with comments and a special character.
Will probably require sublime restart after installation
Comment Marks are highlighted below (using Sublime Text Find) in a piece of example code
Running the Goto Comment Mark
Command (see Usage below) will provide the searchable quickpanel seen below which will take you to the selected comment.
Example
def my_function():
retun 'hello world'
# > Main
def main():
my_function()
# >> Main trigger
if __name__ == '__main__':
main()
In the python code above, two marks or sections are set (Main
and Main trigger
) by using >
characters in comments.
The number of >
characters defines what level the section has much like hashes for headings in a markdown file.
Usage
- Command Palette:
Goto Comment Mark
- No Key binding is set by default.
- To set user key bindings, go to the
Sublime Text
menu, thenPreferences
>Package Settings
>Comment Marks
>Key Bindings
- You will see examples on the left and your user key bindings configuration file on the right. Feel free to copy-paste across.
- To set user key bindings, go to the
Trailing Comment Characters
- Some syntaxes (eg
C
orHTML
) use delimiting characters for comments rather than using a single character or symbol and line endings.- eg
/* A comment in C */
. Here, the*/
in the end is what is meant by “trailing comment characters”.
- eg
- By default,
Comment Marks
includes the trailing comment characters as being part of the Comment Mark presents them in the command palette. - Alternatively, the trailing comment marks can be trimmed out.
- To enable this, alter the setting
trim_trailing_comment_chars
value totrue
(it's default is false). See configuration below.- The trailing characters that are trimmed by default, and for specific scopes, are configurable also.
Design
Aims:
- Provide a simple but effective and flexible approach to creating, searching and navigating to arbitrary “bookmarks” in a file.
- Make the process easy, lightweight and essentially editor independent.
- Use a plugin that is simple but configurable and hopefully performant.
This plugin is similar to Table of comments
(see Page on Package Control).
Differences:
- Simpler functionality and code base (hopefully so that it is more easily hacked by users)
- Uses
python 3.8
, and is therefore compatible only withSublime Text v4
- Uses
- More configurable (I think)
- Faster (in my experience)
- Specifically, I'm referring to the time from running the
Goto Comment Mark
command and seeing the quick panel of “bookmarks” (and the equivalent inTable of comments
). - If this plugin is faster, it's probably due to these reasons:
- regex paterns are prepared on plugin load, not when the commands are run
- plugin is relatively minimal
- uses
python 3.8
andf-strings
, which may provide noticeable performance gains.
- Specifically, I'm referring to the time from running the
Configuration
- Go to
Preferences
>Package Settings
>Comment Marks
>Settings
, which will open the default settings on the left your custom settings on the right.- Extensive comments in the settings
json
file should provide sufficient guidance.
- Extensive comments in the settings
Current default settings:
{
// Restarting Sublime will probably be necessary for settings to take effect
// The command "Comment Marks: Reload Settings" (run from the command palette)
// should apply any changes to the settings without needing to restart.
// If that does not work, restarting will be a more reliable means of doing so.
// > look ... there are Comment Marks in here :)
// > Basic Visual Settings
// Character to use in comments for creating Comment Marks
// Use repeats of this character to create Comment Marks of increasingly "lower levels"
// like in markdown
"default_level_char": ">",
// Control the formatting of Comment Marks in the Command Palette
// Numeric keys signify what level of Comment Mark the formatting applies to, or
// more specifically, the number of "default_level_char" characters
// that have been repeated.
// The string value is what will replace the level_chars in the quick panel ...
// ... note the spaces which create indentation in the Command Palette.
"level_char_format_sub": {
"1": "",
"2": " - ",
"3": " -- ",
"4": " -- ",
"5": " -- ",
"6": " -- ",
},
// >> Scope specific comment mark character (like level_char above)
// Custom level char for specific scopes, if you want to use a different
// character in particular scopes (so it looks better or clearer, for instance).
// To find the scope of a file, hit CTRL+SHIFT+P, and see the top line, or
// in control panel, run `view.syntax().scope`
"level_chars": {
// "source.python": ">",
// "source.c": ">"
},
// >> Trimming trailing comments (for languages like CSS, HTML, C)
// Whether to trim the trailing characters of a comment (such as */ in CSS)
// Default is false, as somewhat experimental.
// Feel tree to turn on, but if there are problems with this, you can turn it off
"trim_trailing_comment_chars": true,
// What trailing characters to trim for specific scopes/syntaxes (such as */ in CSS).
// These are searched for at the end of every comment mark and stripped if found.
// Default characters are defined in another setting below.
// SO YOU DO NOT NEED TO TOUCH THIS SETTING.
// But if a specific syntax isn't covered by the default settings,
// you can provide the specific trailing characters below for the specific syntax/scope.
// To find the scope of a file, hit CTRL+SHIFT+P, and see the top line, or
// in the control panel, run `view.syntax().scope`.
// You must provide a list of strings, even if providing only a single string.
"scope_comment_trailing_chars": {
// "source.css": ["*/"]
},
// Default characters used as a fallback when no scope-specific characters
// are defined above.
// Each one is searched, one after the other, using a regex OR operator ("|")
// Relying on these is the intended behaviour, YOU DO NOT NEED TO PROVIDE
// SCOPE-SPECIFIC CHARACTERS ABOVE.
// Feel free to adjust or augment this list as you see fit, though you
// might alter the behaviour of the plugin by doing so.
// Must provide a list of strings, even if only one string.
"default_scope_comment_trailing_chars": ["*/", "-->"],
// > Customising the detection of comments
// >> Introduction (rant)
// The plubin finds Comment Marks as follows:
// 1. Uses regex patterns that ...
// 2. Search for lines that start with some combination of whitespace and comment
// characters
// 3. And also generally search for multiple alternative comment characters
// 4. Then, the pattern searches for the level character defined here (eg, ">")
// 5. And finally everything that follows (ie, the "heading" you've written)
// As programming languages have different syntaxes for comments, this plugin's
// default settings define multiple comment characters which are searched as alternatives.
// This works well most of the time, but maybe something is off for a particular syntax
// or you use it in a particular way.
// The settings below allow you to manipulate what characters are searched for
// within files of a particular syntax/scope.
// These characters will then be placed into a larger regex pattern
// (to take care of whitespace) etc.
// If you want, with "custom_comment_start_patterns", you can set the full regex for
// what defines a comment line in a particular syntax/scope,
// where the plugin will add the rest of the needed regex
// for searching for the headings of the comment marks and the level characters (">") etc.
// >> Defining comment characters
// If the default list of comment characters doesn't cover a syntax that
// you're working with (or there's a bug), you can specify the comment character
// for a particular syntax or scope directly here.
// These comment characters are put together into a larger pattern that
// presumes these characters can occur 1 or more times (using regex `+`) ...
// ... see the `source.python` example in custom_comment_start_patterns
// below for what this pattern looks like for python.
// When a file's scope is not here, default characters (defined below) are used instead
// where the first character/sequence found is used.
// Must provide a list of strings, even if only one string.
"scope_comment_chars": {
"source.python": ["#"],
"source.json.sublime.keymap": ["/"]
},
// Default characters used as the fallback when no scope-specific characters
// are defined above.
// There is no need to specify scope-specific characters, relying on these
// default characters is the intended functionality of the plugin.
// You really shouldn't need to alter these, but just in case, you can.
// Doing so may break the plugin though!
// Must provide a list of strings, even if only one string.
"default_scope_comment_chars": ["#", "/", "/*", "%", "<!--", "-"],
// >> Comment regex pattern override
// Provide specific regex patterns for detecting comments for specific scopes.
// REQUIRES KNOWING REGEX.
// These patterns will COMPLETELY OVERRIDE those automatically generated from
// the characters in scope_comment_chars.
// This setting is available if it's necessary to rectify the default behaviour
// either because of a bug, a special need, or a syntax that has not been accounted for.
// Also, it will result in a simpler regex pattern for any scope provided for, which
// could be somewhat more performant (though probably not noticeably).
// A valid example for python is provided for demonstration.
// Must provide a list of strings, even if only one string.
// WARNING ... these patterns are not interpretted as python raw strings, so to use the
// the backslash character ("\") in regex, you'll have to escape it with the python
// escape character, which is the same ("\").
// EG, to match an asterisk with regex requires escaping it ("\*") as the asterisk
// is an operator in regex. BUT, because python interprets the backslash as an escape
// character, it also needs to be escaped ("\\") resulting in "\\*" to match an asterisk.
// Absurdly, to match a backslash in regex requires "\\", ie an escaped escape chararacter,
// and to do it here with a python string requires escaping both of those backslashes,
// ie "\\\\".
"custom_comment_start_patterns": {
"source.python": ["^[ \t]*#+"]
},
}
Changelog
0.1.11
- Filter out trailing comment characters (such as in
CSS
) from Command Palette items- Done only for displaying in the command palette.
- Made optional with current default of being off (false).
- Reorganise settings into a more logical order
- Make workings of settings more “modular”
- separate defaults from scope-specific settings
- allow scope specific level character and comment character settings to be orthogonal to each other. Any scope-specific setting for either parameter (level char or comment char) when there is no setting for the other for the same scope, will simply take the default.