Sublime Text Unofficial Documentation¶

Searching¶

To open the search panel for the active file, press Ctrl + F. Some options and actions available through this panel can be controlled from the keyboard:

Incremental Search¶

The incremental search panel is bound to Ctrl + I. The only difference with 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 mainly a matter of preference.

Replacing Text¶

To open the replace planel, press Ctrl + H. Some actions available through this panel can be controlled from the keyboard.

Tips¶

Searching¶

To open the search panel for files, press Ctrl + Shift + F. You can use the keyboard to control some search panel options and search actions:

Search Scope¶

The Where field in the search panel determines search scope. You can define scopes in several ways:

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

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

/C/Users/Joe/Top Secret,-*.html,<open files>

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

Results Format¶

In the search panel, you can customize the display of results with the following options:

• Show in Separate Buffer/Output Panel
• 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 purpose of each .sublime-settings file is determined by its name. These 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 file would be called Python.sublime-settings.

Also, some settings files only apply to specific platforms. This can be inferred from the filenames: Preferences (Windows).sublime-settings, Preferences (Linux).sublime-settings, etc.

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

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 isn’t a smart thing to do, 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

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 Linux, OSX, and Windows.

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 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 be consulted only under Linux.

Also, let us stress that, under Packages/User, only Python.sublime-settings would be read, but not any Python (<platform>).sublime-settings variants.

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

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 order to integrate better with each platform, there are separate key map files for Linux, OSX and Windows. Only key maps for the corresponding platform will be loaded.

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

Defining and Overriding Key Bindings¶

Sublime Text ships with a default key map (for example, Packages/Default/Default (Windows).sublime-keymap). In order to override the key bindings defined there, or to add new ones, you can store them in a separate key map of higher precedence: for example Packages/User/Default (Windows).sublime-keymap.

See Merging and Order of Precedence for more information on how Sublime Text sorts files for merging.

Advanced Key Bindings¶

Simple key bindings consist of a key combination and a command to be executed. However, there are more complex syntaxes for passing arguments and contextual awareness.

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

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

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 extension .sublime-macro under PackagesUser and add commands to it. Macro files have this format:

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

See the ../core/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>.

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 see all 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 document. 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 for displaying the snippet in the Snippets menu. If unavailable, Sublime Text defaults to the 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: =========

File Format¶

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

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

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

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

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

                "ninja",
                "robot",
                "pizza"
        ]
}

Sources for Completions¶

Completions not only originate in .sublime-completions files. Here is the exhaustive list of sources for completions:

• Snippets
• API-injected completions
• .sublime-completions files
• Words in buffer

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, as explained next.

Completions can be inserted in two ways:

• Through the completions list (Ctrl+spacebar).
• By pressing Tab.

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. It lives in a public Mercurial repository at Bitbucket.

Download the latest .sublime-package file and install it as described in Installation of .sublime-package Files.

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 JSON 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, 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.

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. 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 .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 ($, <...)

{ "name": "Syntax Name",
  "scopeName": "source.syntax_name",
  "fileTypes": [""],
  "patterns": [
  ],
  "uuid": "ca03e751-04ef-4330-9a6b-9b99aae1c418"
}

{   "name": "Sublime Snippet (Raw)",
    "scopeName": "source.ssraw",
    "fileTypes": ["ssraw"],
    "patterns": [
    ],
    "uuid": "ca03e751-04ef-4330-9a6b-9b99aae1c418"
}

Analyzing Patterns¶

The patterns array can contain several types of elements. 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": "[Mm]y \s+[Rr]egex",
  "name": "string.ssraw",
  "comment": "This comment is optional."
}

{ "name": "Sublime Snippet (Raw)",
  "scopeName": "source.ssraw",
  "fileTypes": ["ssraw"],
  "patterns": [
  ],
  "uuid": "ca03e751-04ef-4330-9a6b-9b99aae1c418"
}

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

\\$\\d+

{ "match": "\\$\\d+",
  "name": "keyword.source.ssraw",
  "comment": "Tab stops like $1, $2..."
}

{   "name": "Sublime Snippet (Raw)",
    "scopeName": "source.ssraw",
    "fileTypes": ["ssraw"],
    "patterns": [
        { "match": "\\$\\d+",
          "name": "keyword.source.ssraw",
          "comment": "Tab stops like $1, $2..."
        }
    ],
    "uuid": "ca03e751-04ef-4330-9a6b-9b99aae1c418"
}

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

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

{ "name": "",
  "begin": "",
  "end": ""
}

{ "name": "",
  "begin": "",
  "beginCaptures": {
    "0": { "name": "" }
  },
  "end": "",
  "endCaptures": {
    "0": { "name": "" }
  },
  "patterns": [
     {  "name": "",
        "match": ""
                  }
  ],
  "contentName": ""
}

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

{  "name": "constant.character.escape.ssraw",
   "match": "\\\\(\\$|\\>|\\<)"
},

{  "name": "invalid.ssraw",
   "match": "(\\$|\\<|\\>)"
}

{   "name": "Sublime Snippet (Raw)",
    "scopeName": "source.ssraw",
    "fileTypes": ["ssraw"],
    "patterns": [
        { "match": "\\$(\\d+)",
          "name": "keyword.ssraw",
          "captures": {
              "1": { "name": "constant.numeric.ssraw" }
           },
          "comment": "Tab stops like $1, $2..."
        },

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

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

        { "name": "constant.character.escape.ssraw",
          "match": "\\\\(\\$|\\>|\\<)"
        },

        { "name": "invalid.ssraw",
          "match": "(\\$|\\>|\\<)"
        }
    ],
    "uuid": "ca03e751-04ef-4330-9a6b-9b99aae1c418"
}

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
from urllib import urlopen

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(
                        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 $PATH_TO_SUBLIME/Packages/Default.sublime-package 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.

Types of Packages¶

In this guide, we classify packages under different categories. This classification is artificial and useful just for clarity when discussing this topic. Sublime Text doesn’t use this classification in any way.

core packages

Required packages for proper functioning.

shipped packages

Included in every installation, though technically not required. They enhance Sublime Text out of the box. May have been contributed by users or third parties.

user packages

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

installed packages

Packages stored under Installed Packages as .sublime-package‘s

It’s worth noting that by third party we mainly refer to users of other editors, such as Textmate.

Package Installation¶

Ultimately, installing a package is simply a matter of copying a folder containing Sublime Text resources to Packages, or a .sublime-package file to Installed Packages. The only thing that varies is how you obtain and copy these files.

Packages and Magic¶

Sublime Text deals with packages without much hidden magic. There are two notable exceptions: Macros defined in any package automatically appear under Tools | Macros | <Your Package>, and snippets from any package appear under Tools | Snippets | <Your Package>.

However, Sublime Text follows some rules for packages. For instance, Package/User will never be clobbered during updates to the software.

Ignored Packages¶

To temporarily disable packages, you can add them to the ignored_packages list in your Packages/User/Preferences.sublime-settings file.

Restoring Packages¶

Sublime Text keeps a copy of all installed packages so it can recreate them as needed. This means it can reinstall core packages, shipped packages and, potentially, user packages alike. However, only user packages installed as sublime-packages are added to its registry of installed packages. Packages installed in alternative ways will be lost completely if you delete them.

The Installed Packages Directory¶

You will find this folder in the data directory. It contains a copy of every sublime-package installed. It is used to restore Packages.

Compatibility with Textmate¶

Generally, Sublime Text snippets are compatible with Textmate snippets.

File Format¶

Snippet files are XML files with the sublime-snippet extension.

<snippet>
    <content><![CDATA[]]></content>
    <tabTrigger></tabTrigger>
    <scope></scope>
    <description></description>
</snippet>

content

Actual snippet content.

tabTrigger

Implicit key binding for this snippet. The last key (implicit) is TAB.

scope

Scope selector to activate this snippet.

description

Friendly description to be used when the snippet is shown as a menu item.

Escape Sequences¶

\$

Literal $.

Environment Variables¶

Fields¶

Marked positions to cycle through, by pressing TAB or SHIFT + TAB.

Syntax: $1 .. $n

$0

Exit mark. The position where normal text editing should be resumed. By default, Sublime Text implicitly sets this mark at the end of the snippet’s content element.

Fields with the same name mirror each other.

Placeholders¶

Fields with a default value.

Syntax: ${1:PLACE_HOLDER} .. ${n:PLACE_HOLDER}

Fields and placeholders can be combined, and nested within other placeholders.

Substitutions¶

Syntax:

• ${var_name/regex/format_string/}
• ${var_name/regex/format_string/options}

var_name

The name of the field to base the substitution on: 1, 2, 3...

regex

Perl-style regular expression: See the Boost library documentation for more on regular expressions.

format_string

See the Boost library documentation for more on format strings.

options

Optional. Any of the following:

i

Case-insensitive regex.

g

Replace all occurrences of regex.

m

Don’t ignore newlines in the string.

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, JSON is shown instead.

{ "name": "Sublime Snippet (Raw)",
  "scopeName": "source.ssraw",
  "fileTypes": ["ssraw"],
  "patterns": [
      { "match": "\\$(\\d+)",
        "name": "keyword.ssraw",
        "captures": {
            "1": { "name": "constant.numeric.ssraw" }
         },
        "comment": "Tab stops like $1, $2..."
      },
      { "match": "\\$([A-Za-z][A-Za-z0-9_]+)",
        "name": "keyword.ssraw",
        "captures": {
            "1": { "name": "constant.numeric.ssraw" }
         },
        "comment": "Variables like $PARAM1, $TM_SELECTION..."
      },
      { "name": "variable.complex.ssraw",
        "begin": "(\\$)(\\{)([0-9]+):",
        "beginCaptures": {
            "1": { "name": "keyword.control.ssraw" },
            "3": { "name": "constant.numeric.ssraw" }
         },
         "patterns": [
            { "include": "$self" },
            { "name": "string.ssraw",
              "match": "."
            }
         ],
         "end": "\\}"
      },
      { "name": "constant.character.escape.ssraw",
        "match": "\\\\(\\$|\\>|\\<)"
      },
      { "name": "invalid.ssraw",
        "match": "(\\$|\\>|\\<)"
      }
  ],
  "uuid": "ca03e751-04ef-4330-9a6b-9b99aae1c418"
}

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 top-level scope for this syntax definition. Either source.<lang> or text.<lang>. Use source for programming languages and text for everything else.

fileTypes

An array of file type extensions for which this syntax automatically should be activated. Include the extensions without the leading dot.

uuid

Unique indentifier for this syntax definition. Currently ignored.

foldingStartMarker

Currently ignored. Used for code folding.

foldingStopMarker

Currently ignored. Used for code folding.

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. Optional.

The Patterns Array¶

Elements contained in the patterns array.

match

Contains the following elements:

match	Pattern to search for.
name	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:

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

Examples:

// Simple

{ "name": "constant.character.escape.ssraw",
  "match": "\\\\(\\$|\\>|\\<)"
  "comment". "Sequences like \$, \> and \<"
}

// With captures

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

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 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:

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	patterns to be matched against the content.
contentName	Scope name for the content excluding the markers.

Example:

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

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:

• Simple elements:

  "elementName": {
    "match":  "some regexp",
    "name":   "some.scope.somelang"
  }
  

• Complex elements:

  "elementName": {
    "patterns": [
      { "match":  "some regexp",
        "name":   "some.scope.somelang"
      },
      { "match":  "other regexp",
        "name":   "some.other.scope.somelang"
      }
    ]
  }
  

Examples:

"repository": {
  "numericConstant": {
    "patterns": [
      { "match":  "\\d*(?<!\\.)(\\.)\\d+(d)?(mb|kb|gb)?",
        "name":   "constant.numeric.double.powershell",
        "captures": {
          "1": { "name": "support.constant.powershell" },
          "2": { "name": "support.constant.powershell" },
          "3": { "name": "keyword.other.powershell" }
          }
      },
      { "match":  "(?<!\\w)\\d+(d)?(mb|kb|gb)?(?!\\w)",
        "name":   "constant.numeric.powershell",
        "captures": {
          "1": { "name": "support.constant.powershell" },
          "2": { "name": "keyword.other.powershell" }
          }
      }
    ]
  },
  "scriptblock": {
    "begin":  "\\{",
    "end":    "\\}",
    "name":   "meta.scriptblock.powershell",
    "patterns": [
      { "include": "$self" }
    ]
  },
}

Escape Sequences¶

Be sure to escape JSON/XML sequences as needed.

File Format¶

.build-system files use JSON. Here’s an example:

{
    "cmd": ["python", "-u", "$file"],
    "file_regex": "^[ ]*File \"(...*?)\", line ([0-9]*)",
    "selector": "source.python"
}

Options¶

cmd

Array containing the command to run and its desired arguments. If you don’t specify an absolute path, the external program will be searched in your PATH, one of your system’s environmental variables.

On Windows, GUIs are supressed.

file_regex

Optional. Regular expression (Perl-style) to capture error output of cmd. See the next section for details.

line_regex

Optional. If file_regex doesn’t match on the current line, but line_regex exists, and it does match on the current line, then walk backwards through the buffer until a line matching file regex is found, and use these two matches to determine the file and line to go to.

selector

Optional. Used when Tools | Build System | Automatic is set to true. Sublime Text uses this scope selector to find the appropriate build system for the active view.

working_dir

Optional. Directory to change the current directory to before running cmd. The original current directory is restored afterwards.

encoding

Optional. Output encoding of cmd. Must be a valid Python encoding. Defaults to UTF-8.

target

Optional. Sublime Text command to run. Defaults to exec (Packages/Default/exec.py). This command receives the configuration data specified in the .build-system file.

Used to override the default build system command. Note that if you choose to override the default command for build systems, you can add arbitrary variables in the .sublime-build file.

env

Optional. Dictionary of environment variables to be merged with the current process’ before passing them to cmd.

Use this element, for example, to add or modify environment variables without modifying your system’s settings.

shell

Optional. If true, cmd will be run through the shell (cmd.exe, bash...).

path

Optional. This string will replace the current process’ PATH before calling cmd. The old PATH value will be restored after that.

Use this option to add directories to PATH without having to modify your system’s settings.

variants

Optional. A list of dictionaries of options to override the main build system’s options. Variant ``name``s will appear in the Command Palette for easy access if the build system’s selector matches for the active file.

name

Only valid inside a variant (see variants). Identifies variant build systems. If name is Run, the variant will show up under the Tools | Build System menu and be bound to Ctrl + Shift + B.

syntax

Optional. When provided, the build system output will be formatted with the provided syntax definition.

{
    "cmd": ["ant"],
    "file_regex": "^ *\\[javac\\] (.+):([0-9]+):() (.*)$",
    "working_dir": "${project_path:${folder}}",
    "selector": "source.java",

    "windows":
    {
        "cmd": ["ant.bat"]
    }
}

{
    "selector": "source.python",
    "cmd": ["date"],

    "variants": [

        { "cmd": ["ls -l *.py"],
          "name": "List Python Files",
          "shell": true
        },

        { "cmd": ["wc", "$file"],
          "name": "Word Count (current file)"
        },

        { "cmd": ["python", "-u", "$file"],
          "name": "Run"
        }
    ]
}

Build System Variables¶

Build systems expand the following variables in .sublime-build files:

${project_name:Default}

${file/\.php/\.txt/}

Running Build Systems¶

Select the desired build system from Tools | Build System, and then select Tools | Build or press F7.

Troubleshooting Build Systems¶

Build systems will look for executables in your PATH, unless you specify an absolute path to the executable. Therefore, your PATH variable must be set correctly.

On some operating systems, the value of PATH may vary between terminal windows and graphical applications. Thus, in your build system, even if the command you are using works in the command line, it may not work from Sublime Text. This is due to user profiles in shells.

To solve this issue, make sure you set the desired PATH so that graphical applications such as Sublime Text can find it. See the links below for more information.

Alternatively, you can use the path element in .sublime-build files to override the PATH used to locate the executable specified in cmd. This new value for PATH will be in effect only as long as your build system is running. After that, the old PATH will be restored.

File Format¶

Key bindings are stored in .sublime-keymap files and defined in JSON. All key map filenames need to follow this pattern: Default (<platform>).sublime-keymap. Otherwise, Sublime Text will ignore them.

{ "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 when emulating Vim’s modal behavior.

Bindable Keys¶

Keys may be specified literally or by name. Here’s the list of 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

Keeping Key Maps Organized¶

Sublime Text ships with default key maps under Packages/Default. Other packages may include their own key map files. The recommended storage location for your personal key map is Packages/User.

See Merging and Order of Precedence for information about how Sublime Text sorts files for merging.

International Keyboards¶

Due to the way Sublime Text maps key names to physical keys, there might be a mismatch between the two.

Troubleshooting¶

To enable command logging, see sublime.log_commands(flag). This may help in debugging key maps.

Global Settings¶

Target file: Global.sublime-settings.

theme

Theme to be used. Accepts a file base name (for example, Default.sublime-theme).

remember_open_files

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

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.

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.

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.

File Settings¶

Target files: Base File.sublime-settings, <file_type>.sublime-settings.

File Format (.sublime-commands Files)¶

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. Note that to locate the packages folder you need to use a snippet-like variable: ${packages} or $packages. This differs from other areas of the editor due to different implementations in the lower layers.

How to Use the Command Palette¶

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

Entries are filtered by current context. Not all entries will be visible at all times.

File Format¶

Completions are JSON files with the .sublime-completions extension.

Where to Store Completions¶

Completions files can be stored anywhere under Packages. They can be included in .sublime-package archives too. If you’re defining completions for your own use, Packages/User is the right place to keep them.

Structure of a Completions List¶

scope

Determines whether the completions are to be sourced from this file. See Scopes for more information.

completions

Array of completions.

Here’s an excerpt from the html completions:

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

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

        ]
}

Types of Completions¶

"foo"

# is equivalent to:

{ "trigger": "foo", "contents": "foo" }

Sources for Completions¶

These are the sources for completions the user can control:

• .sublime-completions
• EventListener.on_query_completions()

Additionally, other completions are folded into the final list:

• Snippets
• Words in the buffer

The Completions List¶

To use the completions list:

• Press Ctrl+spacebar to open
• Optionally, press Ctrl+spacebar again to select next entry
• Press Enter or Tab to validate selection

Snippets show up in the completions list following the pattern: <tab_trigger> : <name>. For the other completions, you will see just the text to be inserted.

If the list of completions can be narrowed down to one choice, the autocomplete dialog will be bypassed and the corresponding content will be inserted right away according to the priority rules stated above.

Enabling and Disabling Tab Completion for Completions¶

The tab_completion setting is true by default. Set it to false if you want Tab to stop sourcing the most likely completion. This setting has no effect on triggers defined in .sublime-snippet files, so snippets will always be inserted after a Tab.

With tab_completion on, the same order of priority stated above applies, but, unlike the case of the completions list, Sublime Text always will insert a completion, even if faced with an ambiguous choice.

Where to Store Plugins¶

Sublime Text will look for plugins in these places:

• Packages
• Packages/<pkg_name>
• .sublime-package files

Plugin files nested deeper in Packages won’t be loaded.

All plugins should live inside a folder of their own and not directly under Packages. This will spare you confusions when Sublime Text attempts to sort packages for loading.

Conventions for Command Names¶

By convention, Sublime Text command class names are suffixed with Command and written as NamesLikeThisCommand.

However, command names are automatically transformed from NamesLikeThisCommand to name_like_this. Thus, ExampleCommand would become example, and AnotherExampleCommand would become another_example.

In names for classes defining commands, use NameLikeThisCommand. To call a command from the API, use the standardized name_like_this.

Types of Commands¶

• sublime_plugin.WindowCommand
• sublime_plugin.TextCommand
• sublime_plugin.EventListener

Instances of WindowCommand have a .window attribute pointing to the window instance that created them. Similarly, instances of TextCommand have a .view attribute.

How to Call Commands from the API¶

Depending on the type of command, use a reference to a View or a Window and call <object>.run_command('command_name'). In addition to the command’s name, .run_command accepts a dictionary whose keys are the names of valid parameters for said command:

window.run_command("echo", {"Tempus": "Irreparabile", "Fugit": "."})

Command Arguments¶

All user-provided arguments to commands must be valid JSON types.

Text Commands and the edit Object¶

Text commands receive and edit object passed to them by Sublime Text.

All actions done within an edit are grouped as a single undo action. Callbacks such as on_modified() and on_selection_modified() are called when the edit is finished.

Contrary to earlier versions of Sublime Text, the edit object’s life time is now managed solely by the editor. Plugin authors must ensure to perform all editing operations within the run() method of text commands so that macros and repeating commands work as expected.

To call other commands from your own commands, use the run_command() function.

Responding to Events¶

Any subclass of EventListener will be able to respond to events. You cannot make a class derive both from EventListener and from any other type of command.

Sublime Text and the Python Standard Library¶

Sublime Text ships with a trimmed down standard library.

Automatic Plugin Reload¶

Sublime Text will reload top-level Python modules as they change (perhaps because you are editing a .py file within Packages). By contrast, Python subpackages won’t be reloaded automatically, and this can lead to confusion while you’re developing plugins. Generally speaking, it’s best to restart Sublime Text after you’ve made changes to plugin files, so all changes can take effect.

Multithreading¶

Only the set_timeout() function is safe to call from different threads.

Exploring the API¶

A quick way to see the API in action:

1. Add Packages\Default (Preferences | Browse Packages...) to your project.
2. CTRL + SHIFT + F
3. Enter *.py in the In Files: field
4. Check Use Buffer option
5. Search API name
6. F4
7. Study relevant source code

Overview¶

This list of commands is a work in progress.

About Paths in Command Arguments¶

Some commands take paths as parameters. Among these, some support snippet-like syntax, while others don’t. A command of the first kind would take a parameter like ${packages}/SomeDir/SomeFile.Ext whereas a command of the second kind would take a parameter like Packages/SomeDir/SomeFile.Ext.

Generally, newer commands support the snippet-like syntax.

Often, relative paths in arguments to commands are assumed to start at the Data directory.

Commands¶

build

Runs a build system.

• variant [String]: Optional. The name of the variant to be run.

run_macro_file

Runs a .sublime-macro file.

• file [String]: Path to the macro file.

insert_snippet

Inserts a snippet from a string or .sublime-snippet file.

• contents [String]: Snippet as a string to be inserted.
• name [String]: Path to the .sublime-snippet file to be inserted.

insert

Inserts a string.

• characters [String]: String to be inserted.

move

Advances the caret by predefined units.

• by [Enum]: Values: characters, words, word_ends, subwords, subword_ends, lines, pages, stops.
• forward [Bool]: Whether to advance or reverse in the buffer.
• word_begin [Bool]
• empty_line [Bool]
• punct_begin [Bool]
• separators [Bool]

move_to

Advances the caret to predefined locations.

• to [Enum]: Values: bol, eol, bof, eof, brackets.
• extend [Bool]: Whether to extend the selection. Defaults to false.

new_window

Opens a new window.

close_window

Closes the active window.

switch_file

Switches between two files with the same name and different extensions.

• extensions [[String]]: Extensions (without leading dot) for which switching will be enabled.

close

Closes the active view.

close_file

Closes the active view and, under certain circumsances, the whole application. XXX Sounds kinda wrong.

save

Saves the active file.

prompt_save_as

Prompts for a new file name and saves the active file.

toggle_sidebar

Shows or hides the sidebar.

toggle_full_screen

Toggles full screen mode on or off.

toggle_distraction_free

Toggles distraction free mode on or off.

left_delete

Deletes the character right before the caret.

right_delete

Deletes the character right after the caret.

undo

Undoes the latest action.

redo

Reapplies the latest undone action.

redo_or_repeat

Performs the latest action again.

soft_undo

Undoes each action stepping through granular edits.

soft_redo

Redoes each action stepping through granular edits.

cut

Removes the selected text and sends it to the system clipboard. Put differently, it cuts.

copy

Sends the selected text to to the system clipboard.

paste

Inserts the clipboard contents after the caret.

paste_and_indent

Inserts the clipboard contents after the caret and indents contextually.

select_lines

Adds a line to the current selection.

• forward [Bool]: Whether to add the next or previous line. Defaults to true.

scroll_lines

Scrolls lines in the view.

• amount [Float]: Positive values scroll lines down and negative values scroll lines up.

prev_view

Switches to the previous view.

next_view

Switches to the next view.

next_view_in_stack

Switches to the most recently active view.

previous_view_in_stack

Switches to the view that was active before the most recently active view. I don’t think this is very clear or even true.

select_all

Select the view’s content.

split_selection_into_lines

Unsurprisingly, it splits the selection into lines.

single_selection

Collapses multiple selections into a single selection.

clear_fields

Breaks out of the active snippet field cycle.

hide_panel

Hides the active panel.

• cancel [Bool]: Notifies the panel to restore the selection to what it

was when the panel was opened. (Only incremental find panel.)

hide_overlay

Hides the active overlay. Show the overlay using the show_overlay command.

hide_auto_complete

Hides the auto complete list.

insert_best_completion

Inserts the best completion that can be inferred from the current context. XXX Probably useless. XXX

• default [String]: String to insert failing a best completion.

replace_completion_with_next_completion

XXX Useless for users. XXX

reindent

XXX ??? XXX

indent

Increments indentation.

next_field

Advances the caret to the text snippet field in the current snippet field cycle.

prev_field

Moves the caret to the previous snippet field in the current snippet field cycle.

commit_completion

Inserts into the buffer the item that’s currently selected in the auto complete list. XXX Probably not useful for users. XXX

unindent

Unindents.

toggle_overwrite

Toggles overwriting on or off.

expand_selection

Extends the selection up to predifined limits.

• to [Enum]: Values: bol, hardbol, eol, hardeol, bof, eof, brackets, line.

find_under_expand

Adds a new selection based on the current selection or expands the selection to the current word.

close_tag

Surrounds the current inner text with the appropiate tags.

toggle_record_macro

Starts or stops the macro recorder.

run_macro

Runs the macro stored in the macro buffer.

show_overlay

Shows the requested overlay. Use the hide_overlay command to hide it.

• overlay [Enum]:

  The type of overlay to show. Possible values:

  • goto: Show the Goto Anything overlay.
  • command_palette: Show the command palette.

• show_files [Bool]: If using the goto overlay, start by displaying files rather than an empty widget.

• text [String]: The initial contents to put in the overlay.

show_panel

Shows a panel.

• panel [Enum]: Values: incremental_find, find, replace, find_in_files, console
• reverse [Bool]: Whether to search backwards in the buffer.
• toggle [Bool]: Whether to hide the panel if it’s already visible.

find_next

Finds the next occurrence of the current search term.

find_prev

Finds the previous occurrence of the current search term.

find_under

Finds the next occurrence of the current selection or the current word.

find_under_prev

Finds the previous occurrence of the current selection or the current word.

find_all_under

Finds all occurrences of the current selection or the current word.

slurp_find_string

Copies the current selection or word into the “find” field of the find panel.

slurp_replace_string

Copies the current selection or word into the “replace” field of the find and replace panel.

next_result

Advance to the next captured result.

prev_result

Move to the previous captured result.

toggle_setting

Toggles the value of a boolean setting.

• setting [String]: The name of the setting to be toggled.

next_misspelling

Advance to the next misspelling

prev_misspelling

Move to the previous misspelling.

swap_line_down

Swaps the current line with the line below.

swap_line_up

Swaps the current line with the line above.

toggle_comment

Comments or uncomments the active lines.

• block [Bool]: Whether to use a block comment.

join_lines

Joins the current line with the next one.

duplicate_line

Duplicates the current line.

auto_complete

Opens the auto comeplete list.

replace_completion_with_auto_complete

XXX Useless for users. XXX

show_scope_name

Shows the name for the caret’s scope in the status bar.

exec

Runs an external process asynchronously.

XXX Document all options.

transpose

Makes stuff dance.

sort_lines

Sorts lines.

• case_sensitive [Bool]: Whether the sort should be case sensitive.

set_layout

XXX

focus_group

XXX

move_to_group

XXX

select_by_index

XXX

next_bookmark

Select the next bookmarked region.

prev_bookmark

Select the previous bookmarked region.

toggle_bookmark

Sets or unsets a bookmark for the active region(s). (Bookmarks can be accessed via the regions API using "bookmarks" as the key.)

clear_bookmarks

Removes all bookmarks.

select_all_bookmarks

Selects all bookmarked regions.

wrap_lines

Wraps lines. By default, it wraps lines at the first ruler’s column.

• width [Int]: Specifies the column at which lines should be wrapped.

upper_case

Makes the selection upper case.

lower_case

Makes the selection lower case.

title_case

Capitalizes the selection’s first character and turns the rest into lower case.

swap_case

Swaps the case of each character in the selection.

set_mark

XXX

select_to_mark

XXX

delete_to_mark

XXX

swap_with_mark

XXX

yank

XXX

show_at_center

XXX

increase_font_size

Increases the font size.

decrease_font_size

Decreases the font size.

fold

XXX

unfold

XXX

fold_by_level

XXX

context_menu

Shows the context menu.

Editing¶

Navigation/Goto Anywhere¶

General¶

Find/Replace¶

Tabs¶

Split window¶

Bookmarks¶

Text manipulation¶

Editing¶

Navigation/Goto Anywhere¶

General¶

Find/Replace¶

Tabs¶

Split window¶

Bookmarks¶

Text manipulation¶