Table of Contents¶

Searching¶

Keyboard shortcuts related to the search panel:

Incremental Search¶

Keyboard shortcuts related to the incremental search panel:

The only difference between this panel and the regular search panel lies in the behavior of the Enter key. In incremental searches, it will select the next match in the file and dismiss the search panel for you. Choosing between this panel or the regular search panel is a matter of preference.

Replacing Text¶

Keyboard shortcuts related to the replace panel:

Tips¶

Multiline Search¶

You can type in multiline search patterns into search panels. To enter newline characters, press Ctrl + Enter.

Note that search panels are resizable too.

Searching¶

Keyboard shortcuts related to Find in Files:

Search Scope¶

The Where field in Find in Files limits the search scope. You can define scopes in several ways:

• Adding individual directories (Unix-style paths, even on Windows)
• Adding/excluding files based on wildcards
• Adding symbolic locations (<open folders>, <open files>...)

It is also possible to combine these filters using commas; for example:

Press the ... button in the search panel to display a menu containing scope options.

Results Format¶

In the search panel, you can customize how results are displayed. These are the available options:

• Show in separate view
• Show context

Navigating Results¶

If the search yields matches, you can move through the sequence using the following key bindings:

Format¶

Settings files use JSON and have the .sublime-settings extension.

Types of Settings¶

The name of each .sublime-settings file determines its purpose. Names can be descriptive (like Preferences (Windows).sublime-settings or Minimap.sublime-settings), or they can be related to what the settings file is controlling. For example, file type settings need to carry the name of the .tmLanguage syntax definition for the file type. Thus, for the .py file type, whose syntax definition is contained in Python.tmLanguage, the corresponding settings files would be called Python.sublime-settings.

Also, some settings files only apply to specific platforms. This can be inferred from the file names, e.g. Preferences (platform).sublime-settings. Valid names for platform are Windows, Linux, OSX.

This is important: Platform-specific settings files in the Packages/User folder are ignored. This way, you can be sure a single settings file overrides all the others.

Settings changes are usually updated in real time, but you may have to restart Sublime Text in order to load new settings files.

How to Access and Edit Common Settings Files¶

Unless you need very fine-grained control over settings, you can access the main configuration files through the Preferences | Settings - User and Preferences | Settings - More menu items. Editing Preferences | Settings - Default is discouraged, because changes will be reverted with every update to the software. However, you can use that file for reference: it contains comments explaining the purpose of all available global and file type settings.

Order of Precedence of .sublime-settings Files¶

The same settings file (such as Python.sublime-settings) can appear in multiple places. All settings defined in identically named files will be merged together and overwritten according to predefined rules. See Merging and Order of Precedence for more information.

Let us remember again that any given settings file in Packages/User ultimately overrides every other settings file of the same name.

In addition to settings files, Sublime Text maintains session data—settings for the particular set of files being currently edited. Session data is updated as you work on files, so if you adjust settings for a particular file in any way (mainly through API calls), they will be recorded in the session and will take precedence over any applicable .sublime-settings files.

To check the value of a setting for a particular file being edited, use view.settings().get("setting_name") from the console.

Finally, it’s also worth noting that some settings may be automatically adjusted for you. Keep this in mind if you’re puzzled about some setting’s value. For instance, this is the case for certain whitespace-related settings and the syntax setting.

Below, you can see the order in which Sublime Text would process a hypothetical hierarchy of settings for Python files on Windows:

• Packages/Default/Preferences.sublime-settings
• Packages/Default/Preferences (Windows).sublime-settings
• Packages/User/Preferences.sublime-settings
• Packages/Python/Python.sublime-settings
• Packages/User/Python.sublime-settings
• Session data for the current file
• Auto adjusted settings

See The Settings Hierarchy for a full example of the order of precedence.

Global Editor Settings and Global File Settings¶

These settings are stored in Preferences.sublime-settings and Preferences (platform).sublime-settings files. The defaults can be found in Packages/Default.

Valid names for platform are Windows, Linux, OSX.

File Type Settings¶

If you want to target a specific file type, name the .sublime-settings file after the file type’s syntax definition. For example, if our syntax definition +was called Python.tmLanguage, we’d need to call our settings file Python.sublime-settings.

Settings files for specific file types usually live in packages, like +:file:Packages/Python, but there can be multiple settings files in separate locations for the same file type.

Similarly to global settings, one can establish platform-specific settings for file types. For example, Python (Linux).sublime-settings would only be consulted only under Linux.

Also, let us emphasize that under Pakages/User only Python.sublime-settings would be read, but not any Python (platform).sublime-settings variant.

Regardless of its location, any file-type-specific settings file has precedence over a global settings file affecting file types.

The Settings Hierarchy¶

Below, you can see the order in which Sublime Text would process a hypothetical hierarchy of settings for Python files on Windows:

• Packages/Default/Preferences.sublime-settings
• Packages/Default/Preferences (Windows).sublime-settings
• Packages/AnyOtherPackage/Preferences.sublime-settings
• Packages/AnyOtherPackage/Preferences (Windows).sublime-settings
• Packages/User/Preferences.sublime-settings
• Settings from the current project
• Packages/Python/Python.sublime-settings
• Packages/Python/Python (Windows).sublime-settings
• Packages/User/Python.sublime-settings
• Session data for the current file
• Auto-adjusted settings

Where to Store User Settings (Once Again)¶

Whenever you want to save settings, especially if they should be preserved between software updates, place the corresponding .sublime-settings file in Packages/User.

File Format¶

Key bindings are defined in JSON and stored in .sublime-keymap files.

In the same package, separate keymap files for Linux, OSX and Windows may exist for better OS integration.

[
   { "keys": ["ctrl+shift+n"], "command": "new_window" },
   { "keys": ["ctrl+o"], "command": "prompt_open_file" }
]

Defining and Overriding Key Bindings¶

Sublime Text ships with default key bindings (for example, Packages/Default/Default (Windows).sublime-keymap). In order to override default key bindings or add new ones, use a separate keymap file with higher precedence: for example, Packages/User/Default (Windows).sublime-keymap.

See Merging and Order of Precedence for more information.

Advanced Key Bindings¶

Simple key bindings consist of a sequence of one or more keys mapped to a command. However, there are more complex syntaxes for passing arguments to commands and restricting key bindings to specific contexts.

{ "keys": ["shift+enter"], "command": "insert", "args": {"characters": "\n"} }

{ "keys": ["escape"], "command": "clear_fields", "context":
   [
      { "key": "has_next_field", "operator": "equal", "operand": true }
   ]
}

{ "keys": ["ctrl+k", "ctrl+v"], "command": "paste_from_history" }

Command Dispatching¶

Normally, commands are bound to the application object, a window object or a view object. Window objects, however, will dispatch commands based on input focus, so you can issue a view command from a window object and the correct view instance will be found for you.

Anatomy of a Command¶

Commands have a name separated by underscores (snake_case) like hot_exit, and can take a dictionary of arguments whose keys must be strings and whose values must be JSON types. Here are a few examples of commands run from the Python console:

view.run_command("goto_line", {"line": 10})
view.run_command('insert_snippet', {"contents": "<$SELECTION>"})
view.window().run_command("prompt_select_project")

How to Record Macros¶

To start recording a macro, press Ctrl+q and subsequently execute the desired steps one by one. When you’re done, press Ctrl+q again to stop the macro recorder. Your new macro won’t be saved to a file, but kept in the macro buffer instead. Now you will be able to run the recorded macro by pressing Ctrl+Shift+q, or save it to a file by selecting Tools | Save macro...

Note that the macro buffer will remember only the latest recorded macro. Also, macros only record commands sent to the buffer: window-level commands, such creating a new file, will be ignored.

How to Edit Macros¶

As an alternative to recording a macro, you can edit it by hand. Just save a new file with the .sublime-macro extension under Packages/User and add commands to it. Macro files have this format:

[
    {"command": "move_to", "args": {"to": "hardeol"}},
    {"command": "insert", "args": {"characters": "\n"}}
]

See the Commands section for more information on commands.

If you’re editing a macro by hand, you need to escape quotation marks, blank spaces and backslashes by preceding them with \.

Where to Store Macros¶

Macro files can be stored in any package folder, and then will show up under Tools | Macros | <PackageName>.

Key Binding for Macros¶

Macro files can be bound to key combinations by passing the macro file path to the run_macro_file command like so:

{"keys": ["super+alt+l"], "command": "run_macro_file", "args": {"file": "res://Packages/User/Example.sublime-macro"}}

Snippets File Format¶

Snippets typically live in a Sublime Text package. They are simplified XML files with the extension .sublime-snippet. For instance, you could have a greeting.sublime-snippet inside an Email package.

The structure of a typical snippet is as follows (including the default hints Sublime Text inserts for your convenience):

<snippet>
    <content><![CDATA[Type your snippet here]]></content>
    <!-- Optional: Tab trigger to activate the snippet -->
    <tabTrigger>xyzzy</tabTrigger>
    <!-- Optional: Scope the tab trigger will be active in -->
    <scope>source.python</scope>
    <!-- Optional: Description to show in the menu -->
    <description>My Fancy Snippet</description>
</snippet>

The snippet element contains all the information Sublime Text needs in order to know what to insert, whether to insert and when. Let’s look at each of these parts in turn.

content

The actual snippet. Snippets can range from simple to fairly complex templates. We’ll look at examples of both later.

Keep the following in mind when writing your own snippets:

• If you want to get a literal $, you have to escape it like this: \$.
• When writing a snippet that contains indentation, always use tabs. When the snippet is inserted, the tabs will be transformed into spaces if the option translateTabsToSpaces is true.
• The content must be included in a <![CDATA[…]]> section. Snippets won’t work if you don’t do this!
• The content of your snippet must not contain ]]> because this string of characters will prematurely close the <![CDATA[…]]> section, resulting in an XML error. To work around this pitfall, you can insert an undefined variable into the string like this: ]]$NOT_DEFINED>. This modified string passes through the XML parser without closing the content element’s <![CDATA[…]]> section, but Sublime Text will replace $NOT_DEFINED with an empty string before inserting the snippet into your file. In other words, ]]$NOT_DEFINED> in your snippet file content will be written as ]]> when you trigger the snippet.

tabTrigger

Defines the sequence of keys that must be pressed to insert this snippet. After typing this sequence, the snippet will kick in as soon as you hit the Tab key.

A tab trigger is an implicit key binding.

scope

Scope selector determining the context where the snippet will be active. See Scopes for more information.

description

Used when showing the snippet in the Snippets menu. If not present, Sublime Text defaults to the file name of the snippet.

With this information, you can start writing your own snippets as described in the next sections.

Snippet Features¶

=================================
USER NAME:          $TM_FULLNAME
FILE NAME:          $TM_FILENAME
 TAB SIZE:          $TM_TAB_SIZE
SOFT TABS:          $TM_SOFT_TABS
=================================

# Output:
=============================
USER NAME:          guillermo
FILE NAME:          test.txt
 TAB SIZE:          4
SOFT TABS:          YES
=============================

First Name: $1
Second Name: $2
Address: $3

First Name: $1
Second Name: $2
Address: $3
User name: $1

First Name: ${1:Guillermo}
Second Name: ${2:López}
Address: ${3:Main Street 1234}
User name: $1

First Name: ${1:Guillermo}
Second Name: ${2:López}
Address: ${3:Main Street 1234}
User name: ${4:$TM_FULLNAME}

Test: ${1:Nested ${2:Placeholder}}

      Original: ${1:Hey, Joe!}
Transformation: ${1/./=/g}

# Output:

      Original: Hey, Joe!
Transformation: =========

Transformation: ${1/^(\w)|(?:_(\w))/(?1\u$1:)(?2 \u$2:)/g}
      Original: ${1:text_in_snail_case}

# Output:

Transformation: Text In Snail Case
      Original: text_in_snail_case

How to Use Completions¶

There are two methods for using completions. Even though, when screening them, the priority given to completions always stays the same, the two methods produce different results.

Completions can be inserted in two ways:

• through the completions list (Ctrl + Spacebar), or
• by pressing Tab.

The Completions List¶

To use the completions list:

1. Press Ctrl + Spacebar or just type something.
2. Optionally, press Ctrl + Spacebar again to select the next entry or use up and down arrow keys.
3. Press Enter or Tab to validate selection (depending on the auto_complete_commit_on_tab setting)
4. Optionally, press Tab repeatedly to insert the next available completion.

Note

If the completions list was opened explicitly, the current selection in the completions list can also be validated with any punctuation sign that isn’t itself bound to a snippet (e.g. .).

When the list of completion candidates can be narrowed down to one unambiguous choice given the current prefix, this one completion will be validated automatically the moment you trigger the completion list.

Hints¶

Additionally, you may see a trigger hint on the right side of a completion’s trigger in the completions list. This can be used as a preview of the completion’s content.

The above is in fact a snippet and expands to $arrayName = array('' => , );.

Triggers and Contents¶

Completions not sourced from the text in the current file may provide a trigger that is different to the content they will insert if selected. This is commonly used for function completions where the content also includes the function’s signature.

For example, completing array_map from the PHP completions will result in array_map(callback, arr1):

You may notice in the animation that the cursor automatically selected callback. This is because completions support the same features as snippets with fields and placeholders. For more details, refer to Snippet Features.

l|
some text with l|
l| and.l|

l|
some text with la|
l| andl|

Sources for Completions and their Priorities¶

These are the sources for completions the user can control, in the order they are prioritized:

1. Snippets
2. API-injected completions via on_query_completions()
3. Completions files

Additionally, the following completions are folded into the final list:

4. Words in the buffer

Snippets will always win when the current prefix matches their tab trigger exactly. For the rest of the completion sources, a fuzzy match is performed. Furthermore, snippets always lose in a fuzzy match.

When a list of completions is shown, snippets will still be listed alongside the other items, even if the prefix only partially matches the snippets’ tab triggers.

Overview¶

The command palette bound to Ctrl+Shift+P is an interactive list whose purpose is to execute commands. The command palette is fed by entries in .sublime-commands files. Usually, commands that don’t warrant creating a key binding of their own are good candidates for inclusion in a .sublime- commands files.

By default, the command palette includes many useful commands, and provides convenient access to individual settings as well as settings files.

File Format (Commands Files)¶

Commands files use JSON and have the .sublime-commands extension.

Here’s an excerpt from Packages/Default/Default.sublime-commands:

[
    { "caption": "Project: Save As", "command": "save_project_as" },
    { "caption": "Project: Close", "command": "close_project" },
    { "caption": "Project: Add Folder", "command": "prompt_add_folder" },

    { "caption": "Preferences: Default File Settings", "command": "open_file", "args": {"file": "${packages}/Default/Base File.sublime-settings"} },
    { "caption": "Preferences: User File Settings", "command": "open_file", "args": {"file": "${packages}/User/Base File.sublime-settings"} },
    { "caption": "Preferences: Default Global Settings", "command": "open_file", "args": {"file": "${packages}/Default/Global.sublime-settings"} },
    { "caption": "Preferences: User Global Settings", "command": "open_file", "args": {"file": "${packages}/User/Global.sublime-settings"} },
    { "caption": "Preferences: Browse Packages", "command": "open_dir", "args": {"dir": "$packages"} }
]

caption

Text for display in the command palette.

command

Command to be executed.

args

Arguments to pass to command.

How to Use the Command Palette¶

1. Press Ctrl+Shift+P
2. Select command

The command palette filters entries by context. This means that whenever you open it, you won’t always see all the commands defined in every .sublime-commands file.

Prerequisites¶

In order to follow this tutorial, you will need to install AAAPackageDev, a package intended to ease the creation of new syntax definitions for Sublime Text. Follow the installation notes in the “Getting Started” section of the readme.

File format¶

Sublime Text uses property list (Plist) files to store syntax definitions. However, because editing XML files is a cumbersome task, we’ll use YAML instead and convert it to Plist format afterwards. This is where the AAAPackageDev package (mentioned above) comes in.

By all means, do edit the Plist files by hand if you prefer to work in XML, but always keep in mind their differing needs in regards to escape sequences, many XML tags etc.

Scopes¶

Scopes are a key concept in Sublime Text. Essentially, they are named text regions in a buffer. They don’t do anything by themselves, but Sublime Text peeks at them when it needs contextual information.

For instance, when you trigger a snippet, Sublime Text checks the scope bound to the snippet and looks at the caret’s position in the file. If the caret’s current position matches the snippet’s scope selector, Sublime Text fires it off. Otherwise, nothing happens.

Scopes can be nested to allow for a high degree of granularity. You can drill down the hierarchy very much like with CSS selectors. For instance, thanks to scope selectors, you could have a key binding activated only within single quoted strings in Python source code, but not inside single quoted strings in any other language.

Sublime Text inherits the idea of scopes from Textmate, a text editor for Mac. Textmate’s online manual contains further information about scope selectors that’s useful for Sublime Text users too. In particular, Color Schemes make extensive use of scopes to style every aspect of a language in the desired color.

How Syntax Definitions Work¶

At their core, syntax definitions are arrays of regular expressions paired with scope names. Sublime Text will try to match these patterns against a buffer’s text and attach the corresponding scope name to all occurrences. These pairs of regular expressions and scope names are known as rules.

Rules are applied in order, one line at a time. Rules are applied in the following order:

1. The rule that matches at the first position in a line
2. The rule that comes first in the array

Each rule consumes the matched text region, which therefore will be excluded from the next rule’s matching attempt (save for a few exceptions). In practical terms, this means that you should take care to go from more specific rules to more general ones when you create a new syntax definition. Otherwise, a greedy regular expression might swallow parts you’d like to have styled differently.

Syntax definitions from separate files can be combined, and they can be recursively applied too.

Your First Syntax Definition¶

By way of example, let’s create a syntax definition for Sublime Text snippets. We’ll be styling the actual snippet content, not the whole .sublime-snippet file.

Here are the elements we want to style in a snippet:

• Variables ($PARAM1, $USER_NAME...)
• Simple fields ($0, $1...)
• Complex fields with placeholders (${1:Hello})
• Nested fields (${1:Hello ${2:World}!})
• Escape sequences (\\$, \\<...)
• Illegal sequences ($, <...)

Here are the elements we don’t want to style because they are too complex for this example:

• Variable Substitution (${1/Hello/Hi/g})

# [PackageDev] target_format: plist, ext: tmLanguage
---
name: Syntax Name
scopeName: source.syntax_name
fileTypes: []
uuid: 0da65be4-5aac-4b6f-8071-1aadb970b8d9

patterns:
-
...

# [PackageDev] target_format: plist, ext: tmLanguage
---
name: Sublime Snippet (Raw)
scopeName: source.ssraw
fileTypes: [ssraw]
uuid: 0da65be4-5aac-4b6f-8071-1aadb970b8d9

patterns:
-
...

Analyzing Patterns¶

The patterns array can contain several types of element. We’ll look at some of them in the following sections. If you want to learn more about patterns, refer to Textmate’s online manual.

match: (?i:m)y \s+[Rr]egex
name: string.format
comment: This comment is optional.

# [PackageDev] target_format: plist, ext: tmLanguage
---
name: Sublime Snippet (Raw)
scopeName: source.ssraw
fileTypes: [ssraw]
uuid: 0da65be4-5aac-4b6f-8071-1aadb970b8d9

patterns:
-
...

\$[0-9]+
# or...
\$\d+

name: keyword.other.ssraw
match: \$\d+
comment: Tab stops like $1, $2...

# [PackageDev] target_format: plist, ext: tmLanguage
---
name: Sublime Snippet (Raw)
scopeName: source.ssraw
fileTypes: [ssraw]
uuid: 0da65be4-5aac-4b6f-8071-1aadb970b8d9

patterns:
- comment: Tab stops like $1, $2...
  name: keyword.other.ssraw
  match: \$\d+
...

comment: Variables like $PARAM1, $TM_SELECTION...
name: keyword.other.ssraw
match: \$[A-Za-z][A-Za-z0-9_]+

comment: Variables like $PARAM1, $TM_SELECTION...
name: keyword.other.ssraw
match: \$([A-Za-z][A-Za-z0-9_]+)
captures:
  '1': {name: constant.numeric.ssraw}

name:
begin:
end:

name:
contentName:
begin:
beginCaptures:
  '0': {name: }
  # ...
end:
endCaptures:
  '0': {name: }
  # ...
patterns:
- name:
  match:
# ...

name: variable.complex.ssraw
contentName: string.other.ssraw
begin: '(\$)(\{)([0-9]+):'
beginCaptures:
  '1': {name: keyword.other.ssraw}
  '3': {name: constant.numeric.ssraw}
end: \}
patterns:
- include: $self
- name: support.other.ssraw
  match: .

- comment: Sequences like \$, \> and \<
  name: constant.character.escape.ssraw
  match: \\[$<>]

- comment: Unescaped and unmatched magic characters
  name: invalid.illegal.ssraw
  match: '[$<>]'

# [PackageDev] target_format: plist, ext: tmLanguage
---
name: Sublime Snippet (Raw)
scopeName: source.ssraw
fileTypes: [ssraw]
uuid: 0da65be4-5aac-4b6f-8071-1aadb970b8d9

patterns:
- comment: Tab stops like $1, $2...
  name: keyword.other.ssraw
  match: \$(\d+)
  captures:
    '1': {name: constant.numeric.ssraw}

- comment: Variables like $PARAM1, $TM_SELECTION...
  name: keyword.other.ssraw
  match: \$([A-Za-z][A-Za-z0-9_]+)
  captures:
    '1': {name: constant.numeric.ssraw}

- name: variable.complex.ssraw
  begin: '(\$)(\{)([0-9]+):'
  beginCaptures:
    '1': {name: keyword.other.ssraw}
    '3': {name: constant.numeric.ssraw}
  end: \}
  patterns:
  - include: $self
  - name: support.other.ssraw
    match: .

- comment: Sequences like \$, \> and \<
  name: constant.character.escape.ssraw
  match: \\[$<>]

- comment: Unescaped and unmatched magic characters
  name: invalid.illegal.ssraw
  match: '[$<>]'
...

Prerequisites¶

In order to write plugins, you must be able to program in Python. At the time of this writing, Sublime Text used Python 3.

Where to Store Plugins¶

Sublime Text will look for plugins only in these places:

• Installed Packages (only .sublime-package files)
• Packages
• Packages/<pkg_name>/

As a consequence, any plugin nested deeper in Packages won’t be loaded.

Keeping plugins directly under Packages is discouraged. Sublime Text sorts packages in a predefined way before loading them, so if you save plugin files directly under Packages you might get confusing results.

Your First Plugin¶

Let’s write a “Hello, World!” plugin for Sublime Text:

1. Select Tools | New Plugin... in the menu.
2. Save to Packages/User/hello_world.py.

You’ve just written your first plugin! Let’s put it to use:

1. Create a new buffer (Ctrl+n).
2. Open the Python console (Ctrl+`).
3. Type: view.run_command("example") and press enter.

You should see the text “Hello, World!” in the newly created buffer.

Analyzing Your First Plugin¶

The plugin created in the previous section should look roughly like this:

import sublime, sublime_plugin

class ExampleCommand(sublime_plugin.TextCommand):
    def run(self, edit):
        self.view.insert(edit, 0, "Hello, World!")

Both the sublime and sublime_plugin modules are provided by Sublime Text; they are not part of the Python standard library.

As we mentioned earlier, plugins reuse or create commands. Commands are an essential building block in Sublime Text. They are simply Python classes that can be called in similar ways from different Sublime Text facilities, like the plugin API, menu files, macros, etc.

Sublime Text Commands derive from the *Command classes defined in sublime_plugin (more on this later).

The rest of the code in our example is concerned with particulars of TextCommand or with the API. We’ll discuss those topics in later sections.

Before moving on, though, we’ll look at how we invoked the new command: first we opened the Python console and then we issued a call to view.run_command(). This is a rather inconvenient way of calling commands, but it’s often useful when you’re in the development phase of a plugin. For now, keep in mind that your commands can be accessed through key bindings and by other means, just like other commands.

Types of Commands¶

You can create the following types of commands:

• Window commands (sublime_plugin.WindowCommand)
• Text commands (sublime_plugin.TextCommand)

When writing plugins, consider your goal and choose the appropriate type of commands.

import sublime, sublime_plugin

from xml.etree import ElementTree as ET
import urllib

GOOGLE_AC = r"http://google.com/complete/search?output=toolbar&q=%s"

class GoogleAutocomplete(sublime_plugin.EventListener):
    def on_query_completions(self, view, prefix, locations):
        elements = ET.parse(
            urllib.request.urlopen(GOOGLE_AC % prefix)
        ).getroot().findall("./CompleteSuggestion/suggestion")

        sugs = [(x.attrib["data"],) * 2 for x in elements]

        return sugs

Learning the API¶

In order to create plugins, you need to get acquainted with the Sublime Text API and the available commands. Documentation on both is scarce at the time of this writing, but you can read existing code and learn from it.

In particular, the Packages/Default contains many examples of undocumented commands and API calls. Note that you will first have to extract its content to a folder if you want to take a look at the code within. As an exercise, you can try creating a build system to do that on demand, and a project file to be able to peek at the sample code easily.

Overview¶

A package is a container for resources.

Package Locations (and Abbreviations)¶

There are three locations for storing packages for different purposes.

• Packages can be folders under Data/Packages (short: Packages)

• or zip archives with the .sublime-package extension located under Data/Installed Packages (short: Installed Packages) or any of its subdirectories.

• Additionally, Sublime Text provides a set of default packages as zip archives in Application/Packages (short: Shipped Packages), where Application refers to the folder where the Sublime Text executable resides.

  This folder is not intended to be modified by the user.

Package Contents¶

Typical resources found in packages include:

Some packages may hold support files for other packages or for core features. For example, the spell checker uses Installed Packages/Language - English.sublime-package as a data store for English dictionaries.

Types of Packages¶

In this guide, we categorize packages for clarity when discussing this topic, but Sublime Text doesn’t use this terminology and you don’t need to learn it.

shipped packages
default packages

A set of packages that Sublime Text ships with. Some of these packages are core packages, while others enhance Sublime Text to support common programming languages out of the box.

Examples: Default, Python, Java, C++, Markdown.

Located in Shipped Packages.

core packages

Sublime Text requires these packages in order to function properly.

Complete list: Default, Theme - Default, Color Scheme - Default, Text, Language - English.

They are part of the shipped packages and located in Shipped Packages.

user packages

Installed or created by the user to extend Sublime Text’s functionality. They are not part of Sublime Text, and are always contributed by users or third parties.

Example: User.

Located in Packages and Installed Packages.

installed packages

A subtype of user packages.

Installed packages are .sublime-package archives and usually maintained by a package manager.

Located in Installed Packages.

Note

Due to the unfortunate name of this folder, talking about installing packages in Sublime Text is confusing.

Sometimes, in this guide, by installing we mean ‘adding a user/third party package to Sublime Text’ (in any form), and sometimes we use the term in its stricter sense of ‘copying a .sublime-package archive to Installed Packages‘.

override packages

A special type of user packages.

Override packages serve the purpose of customizing packages that are distributed as .sublime-package files. They are effectively injected into the original package and do not stand-alone.

See Customizing or Overriding Packages for details.

Located in Packages.

Note that by third party we also refer to users of other editors, notably Textmate, as Sublime Text and Textmate share some types of resource files that can be reused without modification.

Managing Packages¶

Customizing or Overriding Packages¶

Since packages in .sublime-package zip archives are read-only, you cannot modify them directly. However, Sublime Text allows you to create an override package that will effectively inject files into the original archive without modifying the archive itself.

To create an override package, create a new folder under Packages and name it after the .sublime-package file you want to override, excluding the extension. Any file you create in this package will take precedence over any identically named file in the original package.

Python plugins in override packages are able to use relative imports for accessing other modules in the corresponding .sublime-package file as if they were part of it.

Merging and Order of Precedence¶

Package precedence is important for merging certain resources, for example, .sublime-keymap and .sublime-settings files, and for loading plugins (.py files).

If an override package exists for a .sublime-package package, it will be loaded at the same time as the .sublime-package archive.

Sublime Text loads packages in this order:

1. Packages/Default;
2. shipped packages in lexicographical order;
3. installed packages in lexicographical order;
4. all remaining user packages, except for Packages/User, that did not override anything, in lexicographical order;
5. Packages/User

Reverting Sublime Text to Its Default Configuration¶

Reverting Sublime Text to a fresh state solves many problems that appear to be bugs in Sublime Text but are in fact caused by misbehaving packages and plugins.

To revert Sublime Text to its default configuration and remove all your settings and configurations, delete the data directory and restart the editor. Keep in mind that the Installed Packages folder will be deleted too, so you’ll lose all your installed packages.

Always make sure to back up your data before taking an extreme measure like this one!

Compatibility with Textmate¶

Generally, Sublime Text syntax definitions are compatible with Textmate language files.

File Format¶

Textmate syntax definitions are Plist files with the tmLanguage extension. However, for convenience in this reference document, YAML is shown instead.

Additionally, Sublime Text also understands the hidden-tmLanguage extension, which can not be selected by the user but only by set by plugins. “Find in Files” makes use of this. The downsite is that these can not be included by import statements in other language definitions.

---
name: Sublime Snippet (Raw)
scopeName: source.ssraw
fileTypes: [ssraw]
uuid: 0da65be4-5aac-4b6f-8071-1aadb970b8d9

patterns:
- comment: Tab stops like $1, $2...
  name: keyword.other.ssraw
  match: \$\d+

- comment: Variables like $PARAM1, $TM_SELECTION...
  name: keyword.other.ssraw
  match: \$([A-Za-z][A-Za-z0-9_]+)
  captures:
    '1': {name: constant.numeric.ssraw}

- name: variable.complex.ssraw
  begin: '(\$)(\{)([0-9]+):'
  beginCaptures:
    '1': {name: keyword.other.ssraw}
    '3': {name: constant.numeric.ssraw}
  end: \}
  patterns:
  - include: $self
  - name: support.other.ssraw
    match: .

- name: constant.character.escape.ssraw
  match: \\[$<>]

- name: invalid.illegal.ssraw
  match: '[$<>]'
...

name

Descriptive name for the syntax definition. Shows up in the syntax definition dropdown menu located in the bottom right of the Sublime Text interface. It’s usually the name of the programming language or equivalent.

scopeName

Name of the topmost scope for this syntax definition. Either source.<lang> or text.<lang>. Use source for programming languages and text for markup and everything else.

fileTypes

This is a list of file extensions (without the leading dot). When opening files of these types, Sublime Text will automatically activate this syntax definition for them. Optional.

uuid

Unique indentifier for this syntax definition. Currently ignored.

patterns

Array of patterns to match against the buffer’s text.

repository

Array of patterns abstracted out from the patterns element. Useful to keep the syntax definition tidy as well as for specialized uses like recursive patterns or re-using the same pattern. Optional.

The Patterns Array¶

Elements contained in the patterns array.

match

Contains the following elements:

match	Pattern to search for.
name	Optional. Scope name to be assigned to matches of match.
comment	Optional. For information only.
captures	Optional. Refinement of match. See below.

In turn, captures can contain n of the following pairs of elements (note that 0 refers to the whole match):

0..n	Name of the group referenced. Must be a string.
name	Scope to be assigned to the group.

Examples:

# Simple

- comment: Sequences like \$, \> and \<
  name: constant.character.escape.ssraw
  match: \\[$<>]

# With captures

- comment: Tab stops like $1, $2...
  name: keyword.other.ssraw
  match: \$(\d+)
  captures:
    '1': {name: constant.numeric.ssraw}

include

Includes items in the repository, other syntax definitions or the current one.

References:

$self	The current syntax definition.
#itemName	itemName in the repository.
source.js	External syntax definitions.

Examples:

# Requires presence of DoubleQuotedStrings element in the repository.
- include: '#DoubleQuotedStrings'

# Recursively includes the complete current syntax definition.
- include: $self

# Includes and external syntax definition.
- include: source.js

begin..end

Defines a scope potentially spanning multiple lines

Contains the following elements (only begin and end are required):

name	Scope name for the content including the markers.
contentName	Scope name for the content excluding the markers.
begin	The start marker pattern.
end	The end marker pattern.
name	Scope name for the whole region.
beginCaptures	captures for begin. See captures.
endCaptures	captures for end. See captures.
patterns	Array of patterns to be matched against the content.

Example:

name: variable.complex.ssraw
begin: '(\$)(\{)([0-9]+):'
beginCaptures:
  '1': {name: keyword.other.ssraw}
  '3': {name: constant.numeric.ssraw}
end: \}
patterns:
- include: $self
- name: support.other.ssraw
  match: .

Repository¶

Can be referenced from patterns or from itself in an include element. See include for more information.

The repository can contain the following elements:

repository:

  # Simple elements
  elementName:
    match: some regexp
    name:  some.scope.somelang

  # Complex elements
  otherElementName:
    patterns:
    - match: some regexp
      name:  some.scope.somelang
    - match: other regexp
      name:  some.other.scope.somelang

Examples:

repository:
  numericConstant:
    patterns:
    - name: constant.numeric.double.powershell
      match: \d*(?<!\.)(\.)\d+(d)?(mb|kb|gb)?
      captures:
        '1': {name: support.constant.powershell}
        '2': {name: support.constant.powershell}
        '3': {name: keyword.other.powershell}
    - name: constant.numeric.powershell
      match: (?<!\w)\d+(d)?(mb|kb|gb)?(?!\w)
      captures:
        '1': {name: support.constant.powershell}
        '2': {name: keyword.other.powershell}

  scriptblock:
    name: meta.scriptblock.powershell
    begin: \{
    end: \}
    patterns:
    - include: $self

Escape Sequences¶

Be sure to escape JSON/XML sequences as needed.

For YAML, additionally make sure that you didn’t unintentionally start a new scalar by not using quotes for your strings. Examples that won’t work as expected:

match: [aeiou]

include: #this-is-actually-a-comment

match: "#"\w+""

Overview¶

Color schemes define the colors used to highlight source code in Sublime Text views and to style different elements found in the editing area: background, foreground, selection, caret...

File Format¶

Color scheme files use the Property List format and have the .tmTheme extension.

The file format of color scheme files is inherited from Textmate.

Where to Store Color Schemes¶

You can keep color scheme files anywhere under Packages (even inside directories nested multiple levels deep).

By convention, directories containing a set of color scheme files have the Color Scheme - prefix. For example: Color Scheme - Default.

The file names of all available color schemes are displayed in the Preferences → Color Scheme menu.

Structure of a Color Scheme File¶

Color scheme files are based on the Property List format. All color scheme files share the same topmost structure.

Colors can be expressed in the following formats: #RRGGBB, #RGB.

Most elements controlling colors accept an alpha channel value: #RRGGBBAA.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
   <key>name</key>
   <string>Monokai</string>
   <key>settings</key>
   <array>
   ... INSERT AWESOME COLORS HERE ...
   </array>
   <key>uuid</key>
   <string>D8D5E82E-3D5B-46B5-B38E-8C841C21347D</string>
</dict>
</plist>

<array>
   <dict>
      <key>settings</key>
      <dict>
         <key>background</key>
         <string>#272822</string>
         <key>caret</key>
         <string>#F8F8F0</string>
         ...
      </dict>
   </dict>
...
</array>

<array>
   ...
   <dict>
      <key>name</key>
      <string>Comment</string>
      <key>scope</key>
      <string>comment</string>
      <key>settings</key>
      <dict>
         <key>foreground</key>
         <string>#75715E</string>
      </dict>
   </dict>
   ...
</array>

Sublime Text Settings Related to Color Schemes¶

File Format¶

Key bindings are stored in .sublime-keymap files and defined in JSON. Keymap files may be located anywhere in a package.

{ "keys": ["shift+enter"], "command": "insert_snippet", "args": {"contents": "\n\t$0\n"}, "context":
   [
      { "key": "setting.auto_indent", "operator": "equal", "operand": true },
      { "key": "selection_empty", "operator": "equal", "operand": true, "match_all": true },
      { "key": "preceding_text", "operator": "regex_contains", "operand": "\\{$", "match_all": true },
      { "key": "following_text", "operator": "regex_contains", "operand": "^\\}", "match_all": true }
   ]
}

Command Mode¶

Sublime Text provides a command_mode setting to prevent key presses from being sent to the buffer. This is useful, for example, to emulate Vim’s modal behavior.

Key bindings not intended for command mode (generally, all of them) should include a context like this:

{"key": "setting.command_mode", "operand": false}

This way, plugins legitimately using command mode will be able to define appropriate key bindings without interference.

Bindable Keys¶

Keys in key bindings may be specified literally or by name. If using a name doesn’t work in your case, try a literal value.

Here’s the list of all valid names:

• up
• down
• right
• left
• insert
• home
• end
• pageup
• pagedown
• backspace
• delete
• tab
• enter
• pause
• escape
• space
• keypad0
• keypad1
• keypad2
• keypad3
• keypad4
• keypad5
• keypad6
• keypad7
• keypad8
• keypad9
• keypad_period
• keypad_divide
• keypad_multiply
• keypad_minus
• keypad_plus
• keypad_enter
• clear
• f1
• f2
• f3
• f4
• f5
• f6
• f7
• f8
• f9
• f10
• f11
• f12
• f13
• f14
• f15
• f16
• f17
• f18
• f19
• f20
• sysreq
• break
• context_menu
• browser_back
• browser_forward
• browser_refresh
• browser_stop
• browser_search
• browser_favorites
• browser_home

Order of Preference for Key Bindings¶

Key bindings in a keymap file are evaluated from the bottom to the top. The first matching context wins.

Keeping Keymaps Organized¶

Sublime Text ships with default keymaps under Packages/Default. Other packages may include keymap files of their own.

The recommended storage location for your personal keymap files is Packages/User.

See Merging and Order of Precedence for more information.

International Keyboards¶

Due to the way Sublime Text maps key names to physical keys, key names may not correspond to physical keys in keyboard layouts other than US English.

Troubleshooting¶

To enable logging related to keymaps, see:

• sublime.log_commands(flag).
• sublime.log_input(flag).

This may help in debugging keymaps.

Global Settings¶

These settings can only be modified from Preferences.sublime-settings and Preferences (platform).sublime-settings.

theme

Theme to be used. Accepts a file base name (e. g.: Default.sublime-theme).

scroll_speed

Set to 0 to disable smooth scrolling. Set to a value between 0 and 1 to scroll slower, or set to a value larger than 1 to scroll faster.

hot_exit

Exiting the application or window with an associated project with hot_exit enabled will cause it to close immediately without prompting. Unsaved modifications and open files will be preserved and restored when next starting.

remember_open_files

Determines whether to reopen the buffers that were open when Sublime Text was last closed.

open_files_in_new_window

OS X only. When filters are opened from Finder, or by dragging onto the dock icon, this controls if a new window is created or not.

close_windows_when_empty

Close windows as soon as the last file is closed, unless there’s a folder open within the window.

show_full_path

Show the full path to files in the title bar.

preview_on_click

If true, preview file contents when clicking on a file in the side bar. Double clicking or editing the preview will open the file and assign it a tab.

folder_exclude_patterns

Excludes the matching folders from the side bar, GoTo Anything, etc.

file_exclude_patterns

Excludes the matching files from the side bar, GoTo Anything, etc.

binary_file_patterns

Excludes the matching files from GoTo Anything and Find in Files but not the side bar.

show_tab_close_buttons

If false, hides the tabs’ close buttons until the mouse hovers over the tab.

mouse_wheel_switches_tabs

If true, scrolling the mouse wheel will cause tabs to switch if the cursor is in the tab area.

open_files_in_new_window

OS X only. When filters are opened from Finder, or by dragging onto the dock icon, this controls whether a new window is created or not.

ignored_packages

A list of packages that will be ignored (not loaded).

File Settings¶

File Format¶

Completions are JSON files with the .sublime-completions extension. Entries in completions files can contain either snippet-like strings or plain text.

{
   "scope": "text.html - source - meta.tag, punctuation.definition.tag.begin",

   "completions":
   [
      { "trigger": "a", "contents": "<a href=\"$1\">$0</a>" },
      { "trigger": "abbr\t<abbr>", "contents": "<abbr>$0</abbr>" },
      { "trigger": "acronym", "contents": "<acronym>$0</acronym>" }
   ]
}

"foo"
// is equivalent to:
{ "trigger": "foo", "contents": "foo" }

{ "trigger": "foo", "contents": "foobar" },
{ "trigger": "foo\ttest", "contents": "foobar" }

Overview¶

Sublime Text provides basic support for symbol navigation (jumping to class and function definitions, etc.). Symbol navigation can be enabled for any type of file.

The symbol navigation framework in Sublime Text is strictly text-based. No lexical or syntactical analysis is performed.

Format¶

Symbols are defined using metadata files. Because symbol definition files are commonly required by packages, they are discussed separately in this page for convenience.

Just as regular metadata files, symbol definition files have the .tmPreferences extension and use the Property List format. The file name is ignored by Sublime Text.

Defining Symbols¶

Sublime Text features two types of symbol list: a local symbol list (active file) and a global symbol list (project-wide). Using symbol definition files, you can target both individually.

Symbol definition files use scope selectors to capture symbols in source code files.

Several symbol definition files can coexist in the same package. For example, two symbol definition files could work in tandem: one would define all symbols, and a second one could selectively hide some of them if they were uninteresting for users.

Let’s see an example of a symbol definition file:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
   <key>name</key>
   <string>Symbol List</string>
   <key>scope</key>
   <string>source.python meta.function.python, source.python meta.class.python</string>
   <key>settings</key>
   <dict>
      <key>showInSymbolList</key>
      <integer>1</integer>
   </dict>
</dict>
</plist>

Using the file above, Sublime Text would scan source code files for scope names source.python meta.function.python and source.python meta.class.python, and text within would be indexed as symbols. The showInSymbolList setting tells Sublime Text to use the local symbol list.

Text Transformations¶

It is possible to apply transformations to symbols before they are displayed to the user. Symbol transformations consist of text substitutions defined as regular expressions using the Oniguruma syntax.

This is an example of a text substitution:

s/class\s+([A-Za-z_][A-Za-z0-9_]*.+?\)?)(\:|$)/$1/g;

In this case, a captured symbol such as class FooBar(object) would show up as FooBar(object) in the symbol list.

Let’s expand our previous example to use a symbol transformation:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
   <key>name</key>
   <string>Symbol List</string>
   <key>scope</key>
   <string>source.python meta.function.python, source.python meta.class.python</string>
   <key>settings</key>
   <dict>
      <key>showInSymbolList</key>
      <integer>1</integer>
      <key>symbolTransformation</key>
      <string>
         s/class\s+([A-Za-z_][A-Za-z0-9_]*.+?\)?)(\:|$)/$1/g;
         s/def\s+([A-Za-z_][A-Za-z0-9_]*\()(?:(.{0,40}?\))|((.{40}).+?\)))(\:)/$1(?2:$2)(?3:$4…\))/g;
      </string>
   </dict>
</dict>
</plist>

Structure of a Symbol Definition File¶

All metadata files share the same topmost structure, which is inherited from the Property List format.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
   ...
</dict>
</plist>

These are all the valid elements in a symbol definition file:

name

Optional. Name of the symbol definition. Ignored by Sublime Text.

<key>name</key>
<string>Some arbitrary name goes here</string>

scope

Comma-separated list of scope names that Sublime Text will use to capture symbols in files.

<key>scope</key>
<string>source.python meta.function.python, source.python meta.class.python</string>

settings

Required. A container for settings.

<key>settings</key>
<dict>
   ...
</dict>

uuid

Optional. A unique identifier for the file. Ignored by Sublime Text.

<key>uuid</key>
<string>BC062860-3346-4D3B-8421-C5543F83D11F</string>

settings Subelements¶

showInSymbolList

Optional. Links symbols to the local symbol list. Valid values are 0 or 1. If 0, the corresponding symbols will not be displayed.

<key>showInSymbolList</key>
<integer>1</integer>

showInIndexedSymbolList

Optional. Links symbols to the global symbol list. Valid values are 0 or 1. If 0, the corresponding symbols will not be displayed.

<key>showInIndexedSymbolList</key>
<integer>1</integer>

symbolTransformation

Optional. Targets the local symbol list. Semicolon-separated list of text substitutions expressed as regular expressions using the Oniguruma syntax. Whitespace between substitution instructions is ignored.

<key>symbolTransformation</key>
<string>
   s/class\s+([A-Za-z_][A-Za-z0-9_]*.+?\)?)(\:|$)/$1/g;
   s/def\s+([A-Za-z_][A-Za-z0-9_]*\()(?:(.{0,40}?\))|((.{40}).+?\)))(\:)/$1(?2:$2)(?3:$4…\))/g;
</string>

symbolIndexTransformation

Optional. Targets the global symbol list. Semicolon-separated list of text substitutions expressed as regular expressions using the Oniguruma syntax. Whitespace between substitution instructions is ignored.

<key>symbolIndexTransformation</key>
<string>
   s/class\s+([A-Za-z_][A-Za-z0-9_]*.+?\)?)(\:|$)/$1/g;
   s/def\s+([A-Za-z_][A-Za-z0-9_]*\()(?:(.{0,40}?\))|((.{40}).+?\)))(\:)/$1(?2:$2)(?3:$4…\))/g;
</string>

Navigating Symbols¶

Once symbols are defined, you can navigate them using standard key bindings:

Overview¶

Sublime Text provides a default command to comment and uncomment lines of code. This command can be enabled for any type of file using metadata files.

File Format¶

Comment markers are defined using metadata files. However, because metadata for comment markers is commonly required by packages, it’s discussed separately in this page for convenience.

Just as regular metadata files, comment metadata files have the .tmPreferences extension and use the Property List format. The file name is ignored by Sublime Text.

Example¶

Let’s see a basic example of a comment metadata file:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
   <key>name</key>
   <string>Miscellaneous</string>
   <key>scope</key>
   <string>source.python</string>
   <key>settings</key>
   <dict>
      <string></string>
      <key>shellVariables</key>
      <array>
         <dict>
            <key>name</key>
            <string>TM_COMMENT_START</string>
            <key>value</key>
            <string># </string>
         </dict>
      </array>
   </dict>
</dict>
</plist>

In the example we’ve highlighted some parts that are specific to comment metadata files.

Structure of a Comment Metadata File¶

All comment metadata files share the same topmost structure, which is inherited from Property List format:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
   ...
</dict>
</plist>

These are all the valid elements in a comment metadata file:

name

Optional. Name of the metadata. Ignored by Sublime Text.

<key>name</key>
<string>Shell Variables</string>

scope

Required. Comma-separated list of scope selectors to determine in which context the metadata should be active.

In most cases you’ll use the base scope for a particular syntax.

<key>scope</key>
<string>source.python</string>

settings

Required. A container for settings.

<key>settings</key>
<dict>
   ...
</dict>

uuid

Optional. A unique identifier for the file. Ignored by Sublime Text.

<key>uuid</key>
<string>BC062860-3346-4D3B-8421-C5543F83D11F</string>

settings Subelements¶

shellVariables

Required. Container for comment markers.

<key>shellVariables</key>
<array>
   ...
</array>

shellVariables Subelements¶

TM_COMMENT_START

Defines a default comment marker.

To define additional comment markers, name them TM_COMMENT_START_2, TM_COMMENT_START_3, etc.

<dict>
   <key>name</key>
   <string>TM_COMMENT_START</string>
   <key>value</key>
   <string># </string>
</dict>

TM_COMMENT_END

Optional. Defines an end comment marker. If omitted, TM_COMMENT_START will be treated as a line comment marker.

If present and a corresponding start comment marker can be found, the pair is treated as block comment markers.

To define additional end comment markers, name them TM_COMMENT_END_2, TM_COMMENT_END_3, etc.

<dict>
   <key>name</key>
   <string>TM_COMMENT_END_2</string>
   <key>value</key>
   <string>*/</string>
</dict>

TM_COMMENT_DISABLE_INDENT

Optional. Valid values are yes and no. Disables indentation for the TM_COMMENT_START marker.

To target other group of markers, use TM_COMMENT_DISABLE_INDENT_2, etc.

<dict>
   <key>name</key>
   <string>TM_COMMENT_DISABLE_INDENT</string>
   <key>value</key>
   <string>yes</string>
</dict>

Example¶

Here’s a more complete example of a comment metadata file using some of the features just discussed:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
   <dict>
      <key>shellVariables</key>
      <array>
         <dict>
            <key>name</key>
            <string>TM_COMMENT_START</string>
            <key>value</key>
            <string>// </string>
         </dict>
         <dict>
            <key>name</key>
            <string>TM_COMMENT_START_2</string>
            <key>value</key>
            <string>/*</string>
         </dict>
         <dict>
            <key>name</key>
            <string>TM_COMMENT_END_2</string>
            <key>value</key>
            <string>*/</string>
         </dict>
      </array>
   </dict>
   <key>uuid</key>
   <string>BC062860-3346-4D3B-8421-C5543F83D11F</string>
</dict>
</plist>

Related Keyboard Shortcuts¶

Once comment metadata has been defined, you can use standard key bindings to comment and uncomment lines of code.

Overview¶

Metadata are parameters that can be assigned to certain text sections using scope selectors.

These paremeters can be used for many purposes; for example:

• specifying the current comment markers, even within embedded source code, so that you can toggle comments in any syntax,
• defining rules for auto-indentation,
• marking symbols that Sublime Text will allow you to browse to quickly.

Furthermore, snippets can access metadata declared in the shellVariables setting, which allows you to create a snippet that has different contents depending on where it’s used.

File Format¶

Metadata files have the .tmPreferences extension and use the Property List format. The file name is ignored by Sublime Text.

Metadata files are inherited from TextMate.

Example¶

Here’s an example of a metadata file:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
   <key>name</key>
   <string>JavaScript Metadata</string>
   <key>scope</key>
   <string>source.js</string>
   <key>settings</key>
   <dict>
      <key>decreaseIndentPattern</key>
      <string>^(.*\*/)?\s*\}.*$</string>
      <key>increaseIndentPattern</key>
      <string>^.*\{[^}"']*$</string>

      <key>bracketIndentNextLinePattern</key>
      <string>(?x)
      ^ \s* \b(if|while|else)\b [^;]* $
      | ^ \s* \b(for)\b .* $
      </string>
   </dict>
   <dict>
      <key>shellVariables</key>
      <array>
         <dict>
            <key>name</key>
            <string>TM_COMMENT_START</string>
            <key>value</key>
            <string>// </string>
         </dict>
         <dict>
            <key>name</key>
            <string>TM_COMMENT_START_2</string>
            <key>value</key>
            <string>/*</string>
         </dict>
         <dict>
            <key>name</key>
            <string>TM_COMMENT_END_2</string>
            <key>value</key>
            <string>*/</string>
         </dict>
      </array>
   </dict>
   <key>uuid</key>
   <string>BC062860-3346-4D3B-8421-C5543F83D11F</string>
</dict>
</plist>

The example file combines several types of metadata.

Structure of a Metadata File¶

All metadata files share the same topmost structure, which is inherited from the Property List format.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
   ...
</dict>
</plist>

Sublime Text uses the following topmost keys in metadata files; all others are ignored by default.

name

Optional. Name of the metadata. Ignored by Sublime Text.

<key>name</key>
<string>Shell Variables</string>

scope

Required. Scope selector to determine in which context the metadata should be available.

<key>scope</key>
<string>source.python</string>

settings

Required. Container for settings.

<key>settings</key>
<dict>
   ...
</dict>

uuid

Optional. A unique identifier for the file. Ignored by Sublime Text.

<key>uuid</key>
<string>BC062860-3346-4D3B-8421-C5543F83D11F</string>

Subelements of settings¶

The settings element can contain subelements for different purposes, which will be grouped in the following sections.

Some subelements have certain functionality associated with them by default, while others can only be accessed via the API.

<dict>
   <key>name</key>
   <string>BOOK_OPENING</string>
   <key>value</key>
   <string>Once upon a time...</string>
</dict>

Related API Functions¶

To extract metadata information from plugin code, you can use the view.meta_info(key, point) API call.

File Format (.sublime-commands Files)¶

Here’s an excerpt from Packages/Default/Default.sublime-commands: