Sublime Text Unofficial Documentation

Sublime Text Unofcial Documentation
Release 3.0
guillermooo
July 30, 2014
Contents
1 About This Documentation 3
2 Installation 5
2.1 32 bits or 64 bits? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.3 OS X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.4 Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.5 Living Dangerously... or Not . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3 Basic Concepts 9
3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.2 Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.3 With Great Power Comes A Lot of Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.4 The Data Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.5 The Packages Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.6 The Python Console and the Python API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.7 Packages, Plugins, Resources and Other Things That May Not Make Sense to You Now . . . . . . . 11
3.8 Textmate Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.9 Vi/Vim Emulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.10 Emacs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.11 Be Sublime, My Friend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4 Editing 13
4.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.2 Multiple Selections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.3 Transforming Multiple Selections into Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.4 Column Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.5 Other Ways of Selecting Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.6 Transposing Things . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.7 And much, much more... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
5 Search and Replace 15
5.1 Search and Replace - Single File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.2 Search and Replace - Multiple Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
5.3 Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
6 Build Systems (Batch Processing) 19
6.1 File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
6.2 Where to Store Build Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
i
6.3 Running Build Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
7 File Navigation and File Management 21
7.1 Goto Anything . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
7.2 Sidebar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
7.3 Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
7.4 Notable Settings Related to The Sidebar and Projects . . . . . . . . . . . . . . . . . . . . . . . . . . 22
7.5 Workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
7.6 Panes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
8 Customizing Sublime Text 25
8.1 Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
8.2 Indentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
8.3 Key Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
8.4 Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
9 Extending Sublime Text 31
9.1 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
9.2 Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
9.3 Snippets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
9.4 Completions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
9.5 Command Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
9.6 Syntax Denitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
9.7 Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
9.8 Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
10 Command Line Usage 55
11 Reference 57
11.1 Snippets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
11.2 Syntax Denitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
11.3 Build Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
11.4 Key Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
11.5 Settings (Reference) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
11.6 Command Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
11.7 Completions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
11.8 Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
11.9 Python API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
11.10 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
11.11 Keyboard Shortcuts - Windows/Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
11.12 Keyboard Shortcuts - OSX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
12 Glossary 89
ii
Sublime Text Unofcial Documentation, Release 3.0
Warning: Want even better documentation for Sublime Text?
We are starting a new round of writing and editing to improve this guide in many ways. If you nd it useful, please
support us.
support us.
Contents 1
2 Contents
CHAPTER 1
About This Documentation
This is the unofcial documentation for the Sublime Text editor.
The sublime what? What are you talking about!?
Sublime Text is a text editor for code and prose. It does away with many repetitive tasks so you can focus on your
work. And its fun to use!
If youre coming here for the rst time, we encourage you to read through the Basic Concepts section before you
continue.
Happy learning!
support us.
support us.
3
4 Chapter 1. About This Documentation
CHAPTER 2
Installation
The process of installing Sublime Text is different for each platform.
Make sure to read the conditions for use on the ofcial site. Sublime Text is not free.
2.1 32 bits or 64 bits?
Choose the 64-bit version if youre running a 64-bit operating system, otherwise the 32-bit version.
On Windows, if in doubt, choose the 32-bit version. Modern 64-bit versions of Windows can run 32-bit software.
On Linux run this command in your terminal to check your operating systems type:
uname -m
For OS X, you can ignore this section: there is only one version of Sublime Text for OS X.
2.2 Windows
2.2.1 Portable or Not Portable?
Sublime Text comes in two avors for Windows: normal, and portable. If you need the portable installation, you
probably know already. Otherwise, go with the normal one.
Normal installations separate data between two folders: the installation folder proper, and the data directory. These
concepts are explained later in this guide. Normal installations also integrate Sublime Text with the Windows context
menu.
Portable installations will keep all les Sublime Text needs to run in one single folder. You can then move this folder
around and the editor will still work.
2.2.2 How to Install the Normal Version of Sublime Text
Download the installer, doubleclick on it and follow the onscreen instructions.
2.2.3 How to Install the Portable Version of Sublime Text
Download the package and uncompress it to a folder of your choice. You will nd the sublime_text.exe executable
inside that folder.
5
2.3 OS X
Download and open the .dmg le, and then drag the Sublime Text 3 bundle into the Applications folder.
2.4 Linux
You can download the package and uncompress it manually. Alternatively, you can use the command line.
For i386
cd ~
wget http://c758482.r82.cf2.rackcdn.com/sublime-text_build-3047_i386.deb
For x64
cd ~
wget http://c758482.r82.cf2.rackcdn.com/sublime-text_build-3047_amd64.deb
For i386
cd ~
wget http://c758482.r82.cf2.rackcdn.com/sublime_text_3_build_3047_x32.tar.bz2
tar vxjf sublime_text_3_build_3047_x32.tar.bz2
For x64
cd ~
wget http://c758482.r82.cf2.rackcdn.com/sublime_text_3_build_3047_x64.tar.bz2
tar vxjf sublime_text_3_build_3047_x64.tar.bz2
Now we should move the uncompressed les to an appropriate location.
sudo mv Sublime\ Text\ 3 /opt/
Lastly, we create a symbolic link to use at the command line.
sudo ln -s /opt/Sublime\ Text\ 3/sublime_text /usr/bin/sublime
In Ubuntu, if you also want to add Sublime Text to the Unity luncher, read on.
First we need to create a new le.
sudo sublime /usr/share/applications/sublime.desktop
Then copy the following into it.
[Desktop Entry]
Version=3.0
Name=Sublime Text 3
# Only KDE 4 seems to use GenericName, so we reuse the KDE strings.
# From Ubuntus language-pack-kde-XX-base packages, version 9.04-20090413.
GenericName=Text Editor
Exec=sublime
Terminal=false
Icon=/opt/Sublime Text 3/Icon/48x48/sublime_text.png
Type=Application
Categories=TextEditor;IDE;Development
X-Ayatana-Desktop-Shortcuts=NewWindow
6 Chapter 2. Installation
[NewWindow Shortcut Group]
Name=New Window
Exec=sublime -n
TargetEnvironment=Unity
If youve registered your copy of Sublime Text, but every time you open it youre asked to enter your license, you
should try running this command.
sudo chown -R username:username /home/username/.config /sublime-text-3
Just replace username with your accounts username. This should x the permission error in the case that you opened
up Sublime Text as root when you rst entered the license.
2.5 Living Dangerously... or Not
Sublime Text has three release channels:
Stable (default)
Dev
Nightly
If you are working on a NASA project or are on a tight deadline, keep using the stable releases and stop reading here.
Stable releases are better tested and more reliable for everyday use than the others. They come out roughly once a
month. The majority of users will want to use stable releases only.
The dev and nightly channels are unstable, which likely means that builds published through them will contain bugs
and not work reliably. They are updated more often than stable releases.
Dev builds are available for everyone. On average, theyre released twice a month. While not yet ready for everyday
use, they showcase new features in a mostly unbroken fashion.
Finally, nightly builds are the bleeding edge, with frequent updates and also frequent problems of various degrees of
severity. They are fun to try out, but do so at your own risk. Nightly builds are only available for registered users.
support us.
support us.
2.5. Living Dangerously... or Not 7
8 Chapter 2. Installation
CHAPTER 3
Basic Concepts
3.1 Overview
To fully understand the rest of this guide, you need to be familiar with the concepts presented in this section.
3.2 Conventions
Written from the perspective of a Windows user, most instructions will only require trivial changes to work on other
platforms.
Relative paths, like Packages/User, start at the data directory unless otherwise noted. The data directory is explained
further below.
We assume default key bindings when indicating keyboard shortcuts. If youre using a non-English keyboard layout,
note that some key bindings wont match your locales keyboard. This is due to the way Sublime Text maps keys
to commands.
3.3 With Great Power Comes A Lot of Questions
Unquestionably a versatile tool for programmers, you dont need to be one in order to use Sublime Text, or even to
congure it extensively. If youre a hacker, however, you are in for a great many pleasant surprises: Sublime Text
can be innitely customized and extended. You can start using it efciently out of the box, but spending some time
tailoring it to your exact needs will make it even better.
This guide will teach you how to congure Sublime Text.
Sublime Text cant be mastered in a day, but its built on a handful of pervasive ideas that make for a consistent and
easily understandable system once all the pieces come together.
In the following paragraphs, well outline key aspects that may not click in your mind until youve spent some time
using the editor. Experiment, look around in this guide and, eventually, everything will fall into place.
3.4 The Data Directory
Nearly all of the interesting les for users live under the data directory. This is a platform-dependent location:
Windows: %APPDATA%\Sublime Text 3
9
OS X: ~/Library/Application Support/Sublime Text 3
Linux: ~/.cong/sublime-text-3
For portable installations, look inside Sublime Text 3/Data. Here, the Sublime Text 3 part refers to the directory to
which youve extracted the compressed portable les.
Note that only in portable installations does a directory named Data exist. For the remaining installation types, the
data directory is the location indicated above.
3.5 The Packages Directory
This is a key directory: all resources for supported programming and markup languages are stored here. A package
is a directory or zip le containing related les having a special meaning for Sublime Text.
You can access the packages directory from the main menu (Preferences | Browse Packages...), or by means of an API
call: sublime.packages_path(). In this guide, we refer to this location as Packages, packages path, packages
folder or packages directory.
3.5.1 The User Package
Packages/User is a catch-all directory for custom plugins, snippets, macros, etc. Consider it your personal area within
the packages folder. Sublime Text will never overwrite the contents of Packages/User during upgrades.
3.6 The Python Console and the Python API
This information is especially interesting for programmers. For other users, you just need to know that Sublime Text
enables users with programming skills to add their own features to the editor. (So go learn how to program; its great
fun!)
Sublime Text comes with an embedded Python interpreter. Its an useful tool to inspect the editors settings and to
quickly test API calls while developing plugins.
To open the Python console, press Ctrl+ or select View | Show Console from the main menu.
Confused? Lets try again more slowly:
Python is a programming language known to be easy for beginners and very powerful at the same time. API is
short for Application Programming Interface, which is a fancy way of saying that Sublime Text 3 is prepared to be
programmed by the user. Put differently, Sublime Text gives the user access to its internals through Python. Finally, a
console is a little window inside Sublime Text that lets you type in short snippets of Python code and run them. The
console also shows text output by Sublime Text or its plugins.
3.6.1 Your Systems Python vs the Sublime Text 3 Embedded Python
Sublime Text 3 comes with its own Python interpreter and its separate from your systems Python installation.
The embedded interpreter is intended only to interact with the plugin API, not for general development.
10 Chapter 3. Basic Concepts
3.7 Packages, Plugins, Resources and Other Things That May Not
Make Sense to You Now
Almost every aspect of Sublime Text can be extended or customized. For now, this is all you need to understand. This
vast exibility is the reason why you will learn about so many conguration les: there simply must be a place to
specify all your preferences.
Among other things, you can modify the editors behavior, add macros and snippets, extend menus... and even create
whole new features where feature means anything you can think of. OK, right, there might be things you cant do,
but youre denitely spoiled for choice.
All these conguration les were referring to are simple text les following a special structure or format: JSON
predominates, but youll nd some XML les, and Python les too for the more advanced extensibility options.
In this guide, for brevity, we refer collectively to all these disparate conguration les as resources.
Sublime Text will look for resources inside the packages folder. And what is a package, you ask? Well talk at length
about them, but the short version is that, to keep things tidy, the editor has a notion of a package, which is a folder
containing resources that belong together (maybe they all help compose emails faster, write HTML efciently, enhance
the coding experience for C, Ruby, Go...).
3.8 Textmate Compatibility
This information is mainly useful for Textmate expats whove found a new home in Sublime Text. Textmate is an
editor for the Mac.
Sublime Text compatibility with Textmate bundles is good excluding commands, which are incompatible. Addition-
ally, Sublime Text requires all syntax denitions to have the .tmLanguage extension, and all preferences les to have
the .tmPreferences extension. This means that .plist les will be ignored, even if they are located under a Syntaxes or
Preferences subdirectory.
3.9 Vi/Vim Emulation
This information is mainly useful for dinosaurs and people who like to drop the term RSI in conversations. Vi is an
ancient modal editor that lets the user perform all operations from the keyboard. Vim, a modern version of vi, is still
in widespread use.
Sublime Text provides vi emulation through the Vintage package. The Vintage package is ignored by default. Read
more about Vintage in the ofcial documentation.
An evolution of Vintage called Vintageous offers a better Vi editing experience and is updated more often than Vintage.
Vintageous is an open source project.
3.10 Emacs
This information is hardly useful for anyone. Emacs is... Well, nobody really knows what emacs is, but some people
edit text with it.
If you are an emacs user, youre probably not reading this.
3.7. Packages, Plugins, Resources and Other Things That May Not Make Sense to You Now 11
3.11 Be Sublime, My Friend
Borrowing from Bruce Lees wisdom, Sublime Text can become almost anything you need it to be. In skilled hands,
blah, blah, blah.
Empty your mind; be sublime, my friend.
support us.
support us.
12 Chapter 3. Basic Concepts
CHAPTER 4
Editing
4.1 Overview
Sublime Text is brim-full of editing features. This topic just scratches the surface of whats possible.
4.2 Multiple Selections
Multiple selections let you make sweeping changes to your text efciently. Any praise about multiple selections is an
understatement. This is why:
Select some text and press Ctrl + D to add more instances. If you want to skip the current instance, press Ctrl
+ K, Ctrl + D.
If you go too far, press Ctrl + U to deselect the current instance.
4.3 Transforming Multiple Selections into Lines
Ctrl + L expands the selections to the end of the line. Ctrl + Shift + L splits the selections into lines.
You can copy multiple selected lines to a separate buffer, edit them there, select the content again as multiple lines and
then paste them back into place in the rst buffer.
4.4 Column Selection
You can select a rectangular area of a le. Column selection makes use of multiple selections.
Its possible to add blocks of text to or remove them from the selection.
4.4.1 Using the Mouse
Windows
Select Block Right Mouse Button +
Add to Selection Ctrl + Right Mouse Button +
Remove from Selection Alt + Right Mouse Button +
Linux
13
Add to Selection Ctrl + Right Mouse Button +
Remove from Selection Alt + Right Mouse Button +
OS X
Add to Selection + Right Mouse Button +
Remove from Selection + + Right Mouse Button +
4.4.2 Using the Keyboard
Windows Ctrl + Alt + Up and Ctrl + Alt + Down
Linux Alt + + Up and Alt + + Down
OS X + + Up and + + Down
4.5 Other Ways of Selecting Text
The list is long; all available options can be found under Selection. To name a few:
Select subwords (Alt + Shift + <arrow>)
Expand selection to brackets (Ctrl + Shift + M)
Expand selection to indentation (Ctrl + Shift + J)
Expand selection to scope (Ctrl + Shift + Space)
4.6 Transposing Things
Need to swap two letters or, better yet, two words? Experiment with Ctrl + T.
4.7 And much, much more...
The Edit, Selection, Find and Goto menus are good places to look for handy editing tools. You might end up using
just a few of them, but the rest will still be there for when you need them.
support us.
support us.
14 Chapter 4. Editing
CHAPTER 5
Search and Replace
Sublime Text features two main types of search:
support us.
5.1 Search and Replace - Single File
5.1.1 Searching
To open the search panel for the active le, press Ctrl + F. Some options and actions available through this panel
can be controlled from the keyboard:
Toggle Regular Expressions Alt + R
Toggle Case Sensitivity Alt + C
Toggle Exact Match Alt + W
Find Next Enter
Find Previous Shift + Enter
Find All Alt + Enter
5.1.2 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 le and dismiss the search
panel for you. Choosing between this panel or the regular search panel is mainly a matter of preference.
5.1.3 Replacing Text
To open the replace planel, press Ctrl + H. Some actions available through this panel can be controlled from the
keyboard.
Replace All Ctrl + Alt + Enter
15
5.1.4 Tips
Other Ways of Searching in Files
Goto Anything provides the # operator to search in the active le. The search term will be the text following the
operator.
Other Search-Related Key Bindings
These key bindings work when the search panel is hidden.
Search Forward Using Most Recent Pattern F3
Search Backwards Using Most Recent Pattern Shift + F3
Select All Matches Using Most Recent Pattern Alt + F3
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.
support us.
support us.
5.2 Search and Replace - Multiple Files
5.2.1 Searching
To open the search panel for les, press Ctrl + Shift + F. You can use the keyboard to control some search
panel options and search actions:
Toggle Regular Expressions Alt + R
Toggle Case Sensitivity Alt + C
Toggle Exact matches Alt + W
Find Next Enter
5.2.2 Search Scope
The Where eld in the search panel determines search scope. You can dene scopes in several ways:
Adding individual directories (Unix-style paths, even on Windows)
Adding/excluding les based on a pattern
Adding symbolic locations (<open folders>, <open files>)
It is also possible to combine these lters using commas; for example:
16 Chapter 5. Search and Replace
/C/Users/Joe/Top Secret,-*.html,<open les>
Press the ... button in the search panel to display a menu containing these options.
5.2.3 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
5.2.4 Navigating Results
If the search yields matches, you can move through the sequence using the following key bindings:
Next Match F4
Previous Match Shift + F4
support us.
Well examine them in turn, but rst lets talk about a powerful tool for searching text: regular expressions.
5.3 Regular Expressions
Regular Expressions nd complex patterns in text. To take full advantage of the search and replace facilities in Sublime
Text, you should at least learn the basics of regular expressions. In this guide we wont explain how to use regular
expressions.
Typing out regular expression gets boring fast, and saying it is even more annoying, so instead nerds usually shorten
that to regexp or regex.
This is how a regex might look:
(?:Sw|P)i(?:tch|s{2})\s(?:it\s)?of{2}!
Regexes are known to hurt peoples feelings.
To use regular expressions in Sublime Text, you rst need to activate them in the various search panels. The search
term will otherwise be interpreted literally.
Sublime Text uses the Boost syntax for regular expressions.
support us.
support us.
5.3. Regular Expressions 17
18 Chapter 5. Search and Replace
CHAPTER 6
Build Systems (Batch Processing)
Build systems let you run your les through external programs like make, tidy, interpreters, etc.
Executables called from build systems must be in your PATH. For more information about making sure the PATH seen
by Sublime Text is set correctly, see Troubleshooting Build Systems.
6.1 File Format
Build systems are JSON les and have the extension .sublime-build.
6.1.1 Example
Heres an example of a build system:
{
"cmd": ["python", "-u", "$file"],
"file_regex": "^[ ]
*
File \"(...
*
?)\", line ([0-9]
*
)",
"selector": "source.python"
}
cmd Required. This option contains the actual command line to be executed:
python -u /path/to/current/file.ext
file_regex A Perl-style regular expression to capture error information from an external programs output. This
information is used to help you navigate through error instances with F4.
selector If the Tools | Build System | Automatic option is set, Sublime Text will automatically nd the corre-
sponding build system for the active le by matching selector to the les scope.
In addition to options, you can use some variables in build systems too, as we have done above with $file, which
expands to the active buffers lename.
6.2 Where to Store Build Systems
Build systems must be located somewhere under the Packages folder (e.g. Packages/User). Many packages include
their own build systems.
19
6.3 Running Build Systems
Build systems can be run by pressing F7 or from Tools | Build.
See also:
Reference for build systems Complete documentation on all available options, variables, etc.
support us.
support us.
20 Chapter 6. Build Systems (Batch Processing)
CHAPTER 7
File Navigation and File Management
7.1 Goto Anything
Use Goto Anything to navigate your projects les swiftly. (More about projects later.)
To open Goto Anything, press Ctrl+P. As you type into the input area, all le names of les open within the editor
(and of les in added folders too) will be searched, and a preview of the best match will be shown. This preview is
transient; that is, it wont become the actual active view until you perform some operation on it. Transient views go
away when you press Esc. You will see transient views in other situations too.
Goto Anything lives up to its nametheres more to it than searching les:
To perform a fuzzy text search, append # and keep typing, like so:
isl#trsr
This makes Sublime Text perform a fuzzy search for trsr in les whose name loosely matches isl. For example, you
could nd the word treasure inside a le named island.txt.
To perform a fuzzy search quickly in the active view, you can press Ctrl+;.
By the way, fuzzy searches can detect transposed characters for clumsy ngers.
And theres more:
To search symbols in the active view, press Ctrl+R. As in the case of #, the @ operator can be used after le names
too.
To go to a line number, press Ctrl+G. Again, the operator : can be used after le names, just as # and @.
Note that searching for symbols will only work if the active le type has symbols dened for it. Symbols are dened
in .tmLanguage les.
7.2 Sidebar
The sidebar gives you an overview of the active project. Files and folders added to the sidebar will be available in
Goto Anything as well as for project-wide actions (like project-wide searches).
Projects and the sidebar are closely related. Its important to note that theres always an active project, whether its
explicit or implicit.
To toggle the sidebar, press Ctrl+K, Ctrl+B.
21
The sidebar can be navigated with the arrow keys, but rst you need to give it the focus by pressing Ctrl+0. To
return the focus to the view, press Esc. Alternatively, you can use the mouse to the same effect.
Files opened from the sidebar create semi-transient views. Unlike transient views, semi-transient views show up as a
new tab. You will be able to tell semi-transient views from other views because their tab text is shown in italics. When
a new semi-transient view is opened, any existing semi- transient view in the same pane gets automatically closed.
The sidebar provides basic le management operations through its context menu.
7.3 Projects
Projects group sets of les and folders to keep your work organized. Set up a project by adding folders in a way that
suits you, and then save your new conguration.
To save a project, go to Project | Save Project As....
To switch projects quickly, press Ctrl+Alt+P.
Project data is stored in JSON les with a .sublime-project extension. Wherever theres a .sublime-project le, you
may nd one or more .sublime-workspace les. Workspaces are explained later.
Project les can dene settings specic to that project. More information in the ofcial documentation.
You can open a project from the command line by passing the .sublime- project le as an argument to the Sublime
Text executable.
Project les are meant to be committed to source code repositories.
7.4 Notable Settings Related to The Sidebar and Projects
These options control which les are shown in the sidebar and included in project-wide actions, such as searching
les.
folder_exclude_patterns le_exclude_patterns binary_le_patterns
To see a detailed description of their purpose, open the default settings le (Default/Preferences.sublime-settings) via
the Command Palette (Ctrl+P).
7.5 Workspaces
Workspaces can be seen as different views into the same project. For example, you may want to have only a selected
few les open while working on Feature A. Or perhaps you use a different pane layout when youre writing tests, etc.
Workspaces help in these situations.
**Workspaces behave very much like projects. To create a new workspace, select **Project | New Workspace for
Project. To save the active workspace, select **Project | Save Workspace As....
Workspaces data is stored in JSON les with the .sublime-workspace extension.
Contrary to .sublime-project les, .sublime-workspace les are not meant to be shared or edited manually. Never
commit .sublime-workspace les into a source code repository.
To switch between different workspaces, use Ctrl+Alt+P, exactly as you do with projects.
As with projects, you can open a workspace from the command line by passing the desired .sublime-workspace le
as an argument to the Sublime Text executable.
22 Chapter 7. File Navigation and File Management
7.6 Panes
Panes are groups of views. In Sublime Text you can have multiple panes open at the same time.
To create a new pane, press Ctrl+K, Ctrl+Up. To close a pane, press Ctrl+K, Ctrl+Down.
Further pane management commands can be found under View | Layout and related submenus.
support us.
support us.
7.6. Panes 23
24 Chapter 7. File Navigation and File Management
CHAPTER 8
Customizing Sublime Text
Sublime Text can be fully customized. In the following topics, we outline the most common options. In particular, we
dont cover themes and color schemes, an immensely congurable area of Sublime Text.
support us.
8.1 Settings
Sublime Text stores conguration data in .sublime-settings les. Flexibility comes at the price of a slightly complex
system for applying settings. However, heres a rule of thumb:
Always place your personal settings les under Packages/User to guarantee they will take precedence over any other
conicting settings les.
With that out of the way, lets unveil, to please masochistic readers, the mysteries of how settings work.
8.1.1 Format
Settings les use JSON and have the .sublime-settings extension.
8.1.2 Types of Settings
The purpose of each .sublime-settings le 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 le is controlling.
For example, le type settings need to carry the name of the .tmLanguage syntax denition for the le type. Thus, for
the
.py le type, whose syntax denition is contained in Python.tmLanguage, the corresponding settings le
would be called Python.sublime-settings.
Also, some settings les only apply to specic platforms. This can be inferred from the lenames: Preferences
(Windows).sublime-settings, Preferences (Linux).sublime-settings, etc.
This is important: Platform-specic settings les in the Packages/User folder are ignored. In this way, you can be
sure that a single Platform-specic settings le will override all others.
25
8.1.3 How to Access and Edit Common Settings Files
Unless you need very ne-grained control over settings, you can access the main conguration les through the
Preferences | Settings - User and Preferences | Settings - More menu items. Editing Preferences - Settings Default
isnt a smart thing to do, because changes will be reverted with every update to the software. However, you can use
that le for reference: it contains comments explaining the purpose of all available global and le type settings.
8.1.4 Order of Precedence of .sublime-settings Files
The same settings le (such as Python.sublime-settings) can appear in multiple places. All settings dened in identi-
cally named les will be merged together and overwritten according to predened rules. See Merging and Order of
Precedence for more information.
Let us remember again that any given settings le in Packages/User ultimately overrides every other settings le of
the same name.
In addition to settings les, Sublime Text maintains session datasettings for the particular set of les being currently
edited. Session data is updated as you work on les, so if you adjust settings for a particular le in any way (mainly
through API calls), they will be recorded in the session and will take precedence over any applicable .sublime-settings
les.
To check the value of a setting for a particular le being edited, use view.settings().get(<setting_name>) from the
console.
Finally, its also worth noting that some settings may be automatically adjusted for you. Keep this in mind if youre
puzzled about some settings 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 les
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 le
Auto adjusted settings
8.1.5 Global Editor Settings and Global File Settings
These settings are stored in Preferences.sublime-settings and Preferences (<platform>).sublime-settings les. The
defaults can be found in Packages/Default.
Valid names for <platform> are Linux, OSX, and Windows.
8.1.6 File Type Settings
If you want to target a specic le type, name the .sublime-settings le after the le types syntax denition. For
example, if our syntax denition was called Python.tmLanguage, wed need to call our settings le Python.sublime-
settings.
26 Chapter 8. Customizing Sublime Text
Settings les for specic le types usually live in packages, like Packages/Python, but there can be multiple settings
les in separate locations for the same le type.
Similarly to global settings, one can establish platform-specic settings for le 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 le-type-specic settings le has precedence over every global settings le affecting
the le type.
8.1.7 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 le in Packages/User.
support us.
support us.
8.2 Indentation
See also:
Indentation Ofcial Sublime Text Documentation.
support us.
support us.
8.3 Key Bindings
See also:
Reference for key bindings Complete documentation on key bindings.
Key bindings let you map sequences of key presses to actions.
8.2. Indentation 27
8.3.1 File Format
Key bindings are dened in JSON and stored in .sublime-keymap les. In order to integrate better with each
platform, there are separate key map les for Linux, OSX and Windows. Only key maps for the corresponding
platform will be loaded.
Example
Heres an excerpt from the default key map for Windows:
[
{ "keys": ["ctrl+shift+n"], "command": "new_window" },
{ "keys": ["ctrl+o"], "command": "prompt_open_file" }
]
8.3.2 Dening 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 dened 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 les for merging.
8.3.3 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.
Passing Arguments
Arguments are specied in the args key:
{ "keys": ["shift+enter"], "command": "insert", "args": {"characters": "\n"} }
Here, \n is passed to the insert command when you press Shift+Enter.
Contexts
Contexts determine whether a given key binding will be enabled based on the carets position or some other state.
{ "keys": ["escape"], "command": "clear_fields", "context":
[
{ "key": "has_next_field", "operator": "equal", "operand": true }
]
}
This key binding translates to clear snippet elds and resume normal editing if there is a next eld available. Thus,
unless you are cycling through snippet elds, pressing ESC will not trigger this key binding. (However, something
else might occur instead if ESC happens to be bound to a different context tooand thats likely to be the case for
ESC.)
support us.
support us.
8.4 Menus
No documentation is available about this topic.
But heres Bruce Lee, screaming
support us.
support us.
support us.
8.4. Menus 29
CHAPTER 9
Extending Sublime Text
The following topics show various ways in which Sublime Text can be extended with additional functionality.
support us.
9.1 Commands
Commands are ubiquitous in Sublime Text: key bindings, menu items and macros all work through the command
system. They are found in other places too.
Some commands are implemented in the editors core, but many of them are provided as Python plugins. Every
command can be called from a Python plugin.
9.1.1 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.
9.1.2 Anatomy of a Command
Commands have a name separated by underscores (snake_case) like hot_exit, and can take a dictionary of argu-
ments 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")
See also:
Reference for commands Command reference.
31
support us.
support us.
9.2 Macros
Macros are a basic automation facility comprising sequences of commands. Use them whenever you need to repeat
the exact same steps to perform an operation.
Macro les are JSON les with the extension .sublime-macro. Sublime Text ships with a few macros providing
core functionality, such as line and word deletion. You can nd these under Tools | Macros.
9.2.1 How to Record Macros
To start recording a macro, press Ctrl+q and subsequently execute the desired steps one by one. When youre done,
press Ctrl+q again to stop the macro recorder. Your new macro wont be saved to a le, 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 le 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 le, will be ignored.
9.2.2 How to Edit Macros
As an alternative to recording a macro, you can edit it by hand. Just save a new le with the extension
.sublime-macro under Packages/User and add commands to it. Macro les 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 youre editing a macro by hand, you need to escape quotation marks, blank spaces and backslashes by preceding
them with \.
9.2.3 Where to Store Macros
Macro les can be stored in any package folder, and then will show up under Tools | Macros | <PackageName>.
support us.
32 Chapter 9. Extending Sublime Text
support us.
9.3 Snippets
Whether you are coding or writing the next vampire best-seller, youre likely to need certain short fragments of text
again and again. Use snippets to save yourself tedious typing. Snippets are smart templates that will insert text for
you, adapting it to their context.
To create a new snippet, select Tools | New Snippet... Sublime Text will present you with a skeleton for it.
Snippets can be stored under any packages folder, but to keep it simple while youre learning, you can save them to
your Packages/User folder.
9.3.1 Snippets File Format
Snippets typically live in a Sublime Text package. They are simplied XML les with the extension
sublime-snippet. For instance, you could have a greeting.sublime-snippet inside an Email pack-
age.
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>

<tabTrigger>xyzzy</tabTrigger>

<scope>source.python</scope>

<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. Lets see all of these parts in turn.
content The actual snippet. Snippets can range from simple to fairly complex templates. Well 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 wont work if you dont 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 undened variable into the string like this: ]]$NOT_DEFINED>. This modied string passes
through the XML parser without closing the content elements <![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 le content will be written as ]]> when you
trigger the snippet.
9.3. Snippets 33
tabTrigger Denes 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.
Note: In the interest of brevity, were only including the content elements text in examples unless otherwise
noted.
9.3.2 Snippet Features
Environment Variables
Snippets have access to contextual information in the form of environment variables. Sublime Text automatically sets
the values of the variables listed below.
You can also add your own variables to provide extra information. These custom variables are dened in
.sublime-options les.
Lets see a simple example of a snippet using variables:
====================================
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
====================================
Fields
With the help of eld markers, you can cycle through positions within the snippet by pressing the Tab key. Fields are
used to walk you through the customization of a snippet after its been inserted.
First Name: $1
Second Name: $2
Address: $3
In the example above, the cursor will jump to $1 if you press Tab once. If you press Tab a second time, it will
advance to $2, etc. You can also move backwards in the series with Shift+Tab. If you press Tab after the highest
tab stop, Sublime Text will place the cursor at the end of the snippets content, enabling you to resume normal editing.
If you want to control where the exit point should be, use the $0 mark.
You can break out of the eld cycle any time by pressing Esc.
Mirrored Fields
Identical eld markers mirror each other: when you edit the rst one, the rest will be populated in real time with the
same value.
First Name: $1
Second Name: $2
Address: $3
User name: $1
In this example, User name will be lled out with the same value as First Name.
Placeholders
By expanding the eld syntax a little bit, you can dene default values for a eld. Placeholders are useful whenever
theres a general case for your snippet, but you still want to keep it customizable.
First Name: ${1:Guillermo}
Second Name: ${2:Lpez}
Address: ${3:Main Street 1234}
User name: $1
Variables can be used as placeholders:
First Name: ${1:Guillermo}
Second Name: ${2:Lpez}
Address: ${3:Main Street 1234}
User name: ${4:$TM_FULLNAME}
And you can nest placeholders within other placeholders too:
Test: ${1:Nested ${2:Placeholder}}
Substitutions
Warning: This section is a draft and may contain inaccurate information.
In addition to the placeholder syntax, tab stops can specify more complex operations with substitutions. Use substitu-
tions to dynamically generate text based on a mirrored tab stop.
The substitution syntax has the following syntaxes:
${var_name/regex/format_string/}
${var_name/regex/format_string/options}
var_name The variable name: 1, 2, 3...
regex Perl-style regular expression: See the Boost library reference for regular expressions.
format_string See the Boost library reference for format strings.
options
Optional. May be any of the following:
i Case-insensitive regex.
g Replace all occurrences of regex.
9.3. Snippets 35
m Dont ignore newlines in the string.
With substitutions you can, for instance, underline text effortlessly:
Original: ${1:Hey, Joe!}
Transformation: ${1/./=/g}
# Output:
Original: Hey, Joe!
Transformation: =========
support us.
support us.
9.4 Completions
See also:
Reference for completions Complete documentation on all available options.
Sublime Text Documentation Ofcial documentation on this topic.
In the spirit of IDEs, completions suggest terms and insert snippets. Completions work through the completions list
or, optionally, by pressing Tab.
Note that, in the broader sense of words that Sublime Text will look up and insert for you, completions arent limited
to completions les, because other sources contribute to the list of words to be completed, namely:
Snippets
API-injected completions
Buffer contents
However, the most explicit way Sublime Text provides you to feed it completions is by means of
.sublime-completions les. This topic deals with the creation of a .sublime-completions le as well
as with the interactions among all sources for completions.
9.4.1 File Format
Completions are JSON les with the .sublime-completions extension. Entries in completions les can contain
either snippets or plain strings.
Example
Heres an excerpt from Sublime Texts 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>" }
]
}
scope Determines when the completions list will be populated with this list of completions. See Scopes for more
information.
In the example above, weve only used trigger-based completions, but completions les support simple completions
too. Simple completions are just plain strings. Expanding our example with a few simple completions results in a list
like this:
{
"completions":
[
{ "trigger": "acronym", "contents": "<acronym>$0</acronym>" },
"ninja",
"robot",
"pizza"
]
}
9.4.2 Sources for Completions
Completions not only originate in .sublime-completions les. Here is the exhaustive list of sources for com-
pletions:
Snippets
.sublime-completions les
Words in buffer
Priority of Sources for Completions
This is the order in which completions are prioritized:
Snippets
Words in the buffer
9.4. Completions 37
Snippets will always win if the current prex matches their tab trigger exactly. For the rest of the completion sources,
a fuzzy match is performed. Furthermore, snippets always lose with fuzzy matches.
But this is relevant only when the completion is inserted automatically. When a list of completions is shown, snippets
will still be listed alongside the other items, even if the prex only partially matches the snippets tab triggers.
9.4.3 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.
The Completions List
The completions list (Ctrl+spacebar) does its work in two ways: by bringing up a list of suggested words to be
completed, or by inserting the best match directly.
If the choice of best completion is ambiguous, an interactive list will be presented to the user, who then will have
to select an item himself. Unlike other items, snippets in this list are displayed in the format: <tab_trigger> :
<name>, where <tab_trigger> and <name> are variable.
Using Ctrl+spacebar, the completion choice will be automatic only if the list of completion candidates can be
narrowed down to one unambiguous choice, given the current prex.
Tab-Completed Completions
If you want to be able to tab-complete completions, the setting tab_completion must be true, which is the
default. Snippets tab-completion is unaffected by this setting: they always will be completed, or not, according to
their tab trigger.
With tab_completion enabled, completion of items is always automatic. This means, unlike the case of the
completions list, that Sublime Text will always make the decision for you. The rules for selecting the best completion
are the same as described above, but in case of ambiguity, Sublime Text will insert the item it deems most suitable.
Inserting a Literal Tab Character
When tab_completion is enabled, you can press Shift+Tab to insert a literal tab character.
support us.
support us.
9.5 Command Palette
See also:
Reference for Command Palette Complete documentation on the command palette options.
9.5.1 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 les. Usually, commands that dont warrant creating a
key binding of their own are good candidates for inclusion in a .sublime- commands les.
By default, the command palette includes many useful commands, and provides convenient access to individual set-
tings as well as settings les.
9.5.2 File Format (Commands Files)
Commands les use JSON and have the .sublime-commands extension.
Heres 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.
9.5.3 How to Use the Command Palette
1. Press Ctrl+Shift+P
2. Select command
The command palette lters entries by context. This means that whenever you open it, you wont always see all the
commands dened in every .sublime-commands le.
support us.
<<<<<<< Updated upstream Want even better documentation for Sublime Text?
We are starting a new round of writing and editing to improve this guide in many ways. If you nd it useful,
please support us.
9.5. Command Palette 39
We are starting a new round of writing and editing to improve this guide in many ways. If you nd it
useful, please support us.
>>>>>>> Stashed changes
9.6 Syntax Denitions
Syntax denitions make Sublime Text aware of programming and markup languages. Most noticeably, they work
together with colors to provide syntax highlighting. Syntax denitions dene scopes that divide the text in a buffer
into named regions. Several editing features in Sublime Text make extensive use of this ne-grained contextual
information.
Essentially, syntax denitions consist of regular expressions used to nd text, as well as more or less arbitrary, dot-
separated strings called scopes or scope names. For every occurrence of a given regular expression, Sublime Text
gives the matching text its corresponding scope name.
9.6.1 Prerequisites
In order to follow this tutorial, you will need to install AAAPackageDev, a package intended to ease the creation of
new syntax denitions for Sublime Text. It lives in a public Mercurial repository at Bitbucket.
Download the latest .sublime-package le and install it as described in Installation of .sublime-package Files.
Mercurial and Bitbucket
Mercurial is a distributed version control system (DVCS). Bitbucket is an online service that provides hosting for
Mercurial repositories. If you want to install Mercurial, there are freely available command-line and graphical
clients.
9.6.2 File format
Sublime Text uses property list (Plist) les to store syntax denitions. However, because editing XML les is a cum-
bersome task, well use JSON instead, and convert it to Plist format afterwards. This is where the AAAPackageDev
package (mentioned above) comes in.
Note: If you experience unexpected errors during this tutorial, chances are AAAPackageDev is to blame. Dont
immediately think your problem is due to a bug in Sublime Text.
By all means, do edit the Plist les by hand if you prefer to work in XML, but always keep in mind their differing
needs in regards to escape sequences, etc.
9.6.3 Scopes
Scopes are a key concept in Sublime Text. Essentially, they are named text regions in a buffer. They dont 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 carets
position in the le. If the carets current position matches the snippets scope selector, Sublime Text res it off.
Otherwise, nothing happens.
Scopes vs Scope Selectors
Theres a slight difference between scopes and scope selectors: scopes are the names dened in a syntax de-
nition, while scope selectors are used in items like snippets and key bindings to target scopes. When creating a
new syntax denition, you care about scopes; when you want to constrain a snippet to a certain scope, you use a
scope selector.
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. Textmates online manual contains
further information about scope selectors thats useful for Sublime Text users too.
9.6.4 How Syntax Denitions Work
At their core, syntax denitions are arrays of regular expressions paired with scope names. Sublime Text will try to
match these patterns against a buffers 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 rules matching attempt (save for a few exceptions). In practical terms, this means that
you should take care to go from more specic rules to more general ones when you create a new syntax denition.
Otherwise, a greedy regular expression might swallow parts youd like to have styled differently.
Syntax denitions from separate les can be combined, and they can be recursively applied too.
9.6.5 Your First Syntax Denition
By way of example, lets create a syntax denition for Sublime Text snippets. Well be styling the actual snippet
content, not the .sublime-snippet le.
Note: Since syntax denitions are primarily used to enable syntax highlighting, well use the phrase to style to mean
to break down a source code le into scopes. Keep in mind, however, that colors are a different thing from syntax
denitions and that scopes have many more uses besides syntax highlighting.
Here are the elements we want to style in a snippet:
Variables ($PARAM1, $USER_NAME...)
Simple elds ($0, $1...)
Complex elds with placeholders (${1:Hello})
Nested elds (${1:Hello ${2:World}!})
Escape sequences (\\$, \\<...)
Illegal sequences ($, <...)
Note: Before continuing, make sure youve installed the AAAPackageDev package as explained above.
9.6. Syntax Denitions 41
Creating A New Syntax Denition
To create a new syntax denition, follow these steps:
Go to Tools | Packages | Package Development | New Syntax Denition
Save the new le in your Packages/User folder as a .JSON-tmLanguage le.
You now should see a le like this:
{ "name": "Syntax Name",
"scopeName": "source.syntax_name",
"fileTypes": [""],
"patterns": [
],
"uuid": "ca03e751-04ef-4330-9a6b-9b99aae1c418"
}
Lets examine now the key elements.
uuid Located at the end, this is a unique identier for this syntax denition. Each new syntax denition gets its own
uuid. Dont modify them.
name The name that Sublime Text will display in the syntax denition drop-down list. Use a short, descriptive name.
Typically, you will use the name of the programming language you are creating the syntax denition for.
scopeName The top level scope for this syntax denition. It takes the form source.<lang_name> or
text.<lang_name>. For programming languages, use source. For markup and everything else, use
text.
fileTypes This is a list of le extensions. When opening les of these types, Sublime Text will automatically
activate this syntax denition for them.
patterns A container for your patterns.
For our example, ll the template with the following information:
{ "name": "Sublime Snippet (Raw)",
"scopeName": "source.ssraw",
"fileTypes": ["ssraw"],
"patterns": [
],
}
Note: JSON is a very strict format, so make sure to get all the commas and quotes right. If the conversion to Plist
fails, take a look at the output panel for more information on the error. Well explain later how to convert a syntax
denition in JSON to Plist.
9.6.6 Analyzing Patterns
The patterns array can contain several types of elements. Well look at some of them in the following sections. If
you want to learn more about patterns, refer to Textmates online manual.
Regular Expressions Syntax In Syntax Denitions
Sublime Text uses Onigurumas syntax for regular expressions in syntax denitions. Several existing syntax
denitions make use of features supported by this regular expression engine that arent part of perl-style regular
expressions, hence the requirement for Oniguruma.
Matches
Matches take this form:
{ "match": "[Mm]y \s+[Rr]egex",
"name": "string.ssraw",
"comment": "This comment is optional."
}
match A regular expression Sublime Text will use to nd matches.
name The name of the scope that should be applied to any occurrences of match.
comment An optional comment about this pattern.
Lets go back to our example. Make it look like this:
"patterns": [
],
}
That is, make sure the patterns array is empty.
Now we can begin to add our rules for Sublime snippets. Lets start with simple elds. These could be matched with
a regex like so:
\$[0-9]+
# or...
\$\d+
However, because were writing our regex in JSON, we need to factor in JSONs own escaping rules. Thus, our
previous example becomes:
\\$\\d+
With escaping out of the way, we can build our pattern like this:
{ "match": "\\$\\d+",
"name": "keyword.source.ssraw",
"comment": "Tab stops like $1, $2..."
}
Choosing the Right Scope Name
Naming scopes isnt obvious sometimes. Check the Textmate online manual for guidance on scope names. It
is important to re-use the basic categories outlined there if you want to achieve the highest compatibility with
existing colors.
Colors have hardcoded scope names in them. They could not possibly include every scope name you can think
of, so they target the standard ones plus some rarer ones on occasion. This means that two colors using the same
syntax denition may render the text differently!
Bear in mind too that you should use the scope name that best suits your needs or preferences. Itd be perfectly
ne to assign a scope like constant.numeric to anything other than a number if you have a good reason to
do so.
And we can add it to our syntax denition too:
"patterns": [
{ "match": "\\$\\d+",
}
],
}
Were now ready to convert our le to .tmLanguage. Syntax denitions use Textmates .tmLanguage extension
for compatibility reasons. As explained above, they are simply XML les, but in Plist format.
Follow these steps to perform the conversion:
Select Json to tmLanguage in Tools | Build System
Press F7
A .tmLanguage le will be generated for you in the same folder as your .JSON-tmLanguage le
Sublime Text will reload the changes to the syntax denition
You have now created your rst syntax denition. Next, open a new le and save it with the extension .ssraw. The
buffers syntax name should switch to Sublime Snippet (Raw) automatically, and you should get syntax highlighting
if you type $1 or any other simple snippet eld.
Lets proceed to creating another rule for environment variables.
{ "match": "\\$[A-Za-z][A-Za-z0-9_]+",
"comment": "Variables like $PARAM1, $TM_SELECTION..."
}
Repeat the above steps to update the .tmLanguage le, and restart Sublime Text.
Fine Tuning Matches
You might have noticed, for instance, that the entire text in $PARAM1 is styled the same way. Depending on your
needs or your personal preferences, you may want the $ to stand out. Thats where captures come in. Using
captures, you can break a pattern down into components to target them individually.
Lets rewrite one of our previous patterns to use captures:
{ "match": "\\$([A-Za-z][A-Za-z0-9_]+)",
"name": "keyword.ssraw",
"captures": {
"1": { "name": "constant.numeric.ssraw" }
},
}
Captures introduce complexity to your rule, but they are pretty straightforward. Notice how numbers refer to paren-
thesized groups left to right. Of course, you can have as many capture groups as you want.
Arguably, youd want the other scope to be visually consistent with this one. Go ahead and change it too.
Begin-End Rules
Up to now weve been using a simple rule. Although weve seen how to dissect patterns into smaller components,
sometimes youll want to target a larger portion of your source code that is clearly delimited by start and end marks.
Literal strings enclosed by quotation marks or other delimiting constructs are better dealt with by begin-end rules.
This is a skeleton for one of these rules:
{ "name": "",
"begin": "",
"end": ""
}
Well, at least in their simplest version. Lets take a look at one that includes all available options:
{ "name": "",
"begin": "",
"beginCaptures": {
"0": { "name": "" }
},
"end": "",
"endCaptures": {
"0": { "name": "" }
},
"patterns": [
{ "name": "",
"match": ""
}
],
"contentName": ""
}
Some elements may look familiar, but their combination might be daunting. Lets see them individually.
begin Regex for the opening mark for this scope.
end Regex for the end mark for this scope.
beginCaptures Captures for the begin marker. They work like captures for simple matches. Optional.
endCaptures Same as beginCaptures but for the end marker. Optional.
contentName Scope for the whole matched region, from the begin marker to the end marker (inclusive). Effec-
tively, this will create nested scopes for beginCaptures, endCaptures and patterns dened within
this rule. Optional.
patterns An array of patterns to match only against the begin-ends contentthey arent matched against the text
consumed by begin or end themselves.
Well use this rule to style nested complex elds in snippets:
{ "name": "variable.complex.ssraw",
"begin": "(\\$)(\\{)([0-9]+):",
"beginCaptures": {
"1": { "name": "keyword.ssraw" },
},
"patterns": [
{ "include": "$self" },
{ "name": "string.ssraw",
"match": "."
}
],
"end": "\\}"
}
This is the most complex pattern well see in this tutorial. The begin and end keys are self-explanatory: they dene
a region enclosed between ${<NUMBER>: and }. beginCaptures further divides the begin mark into smaller
scopes.
The most interesting part, however, is patterns. Recursion, and the importance of ordering, have nally made their
appearance here.
Weve seen above that elds can be nested. In order to account for this, we need to style nested elds recursively.
Thats what the include rule does when we furnish it the $self value: it recursively applies our entire syntax
denition the text captured by our begin-end rule. This portion excludes the text individually consumed by the regexes
for begin and end.
Remember, matched text is consumed; thus, it is excluded from the next match attempt.
To nish off complex elds, well style placeholders as strings. Since weve already matched all possible tokens inside
a complex eld, we can safely tell Sublime Text to give any remaining text (.) a literal string scope.
Final Touches
Lastly, lets style escape sequences and illegal sequences, and then we can wrap up.
{ "name": "constant.character.escape.ssraw",
"match": "\\\\(\\$|\\>|\\<)"
},
{ "name": "invalid.ssraw",
"match": "(\\$|\\<|\\>)"
}
The only hard thing here is getting the number of escape characters right. Other than that, the rules are pretty straight-
forward if youre familiar with regular expressions.
However, you must take care to place the second rule after any others matching the $ character, since otherwise you
may not get the desired results.
Also, even after adding these two additional rules, note that our recursive begin-end rule from above continues to work
as expected.
At long last, heres the nal syntax denition:
"patterns": [
{ "match": "\\$(\\d+)",
"captures": {
},
},
{ "match": "\\$([A-Za-z][A-Za-z0-9_]+)",
"captures": {
},
},
"begin": "(\\$)(\\{)([0-9]+):",
"beginCaptures": {
"1": { "name": "keyword.ssraw" },
},
"patterns": [
"match": "."
}
],
"end": "\\}"
},
"match": "\\\\(\\$|\\>|\\<)"
},
"match": "(\\$|\\>|\\<)"
}
],
}
There are more available constructs and code reuse techniques, but the above explanations should get you started with
the creation of syntax denitions.
support us.
support us.
9.7 Plugins
See also:
API Reference More information on the Python API.
Plugins Reference More information about plugins.
This section is intended for users with programming skills.
Sublime Text can be extended through Python plugins. Plugins build features by reusing existing commands or creating
new ones. Plugins are a logical entity, rather than a physical one.
9.7.1 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.
9.7.2 Where to Store Plugins
Sublime Text will look for plugins only in these places:
Installed Packages (only .sublime-package les)
Packages
Packages/<pkg_name>/
As a consequence, any plugin nested deeper in Packages wont be loaded.
Keeping plugins directly under Packages is discouraged. Sublime Text sorts packages in a predened way before
loading them, so if you save plugin les directly under Packages you might get confusing results.
9.7.3 Your First Plugin
Lets write a Hello, World! plugin for Sublime Text:
1. Select Tools | New Plugin... in the menu.
2. Save to Packages/User/hello_world.py.
Youve just written your rst plugin! Lets 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.
9.7.4 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 les, macros, etc.
Sublime Text Commands derive from the
*
Command classes dened 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. Well discuss
those topics in later sections.
Before moving on, though, well look at how we invoked the new command: rst 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 its
often useful when youre 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.
Conventions for Command Names
You may have noticed that our command is named ExampleCommand, but we passed the string example to the
API call instead. This is necessary because Sublime Text standardizes command names by stripping the Command
sufx and separating PhrasesLikeThis with underscores, like so: phrases_like_this.
New commands should follow the same naming pattern.
9.7.5 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.
Shared Traits of Commands
All commands need to implement a .run() method in order to work. Additionally, they can receive an arbitrarily
long number of keyword parameters.
Note: Parameters to commands must be valid JSON values due to how ST serializes them internally.
Window Commands
Window commands operate at the window level. This doesnt mean that you cant manipulate views from window
commands, but rather that you dont need views in order for window commands to be available. For instance, the
built-in command new_file is dened as a WindowCommand so it works even when no view is open. Requiring a
view to exist in that case wouldnt make sense.
Window command instances have a .window attribute to point to the window instance that created them.
9.7. Plugins 49
The .run() method of a window command doesnt require any positional parameter.
Window commands are able to route text commands to their windows active view.
Text Commands
Text commands operate at the view level, so they require a view to exist in order to be available.
Text command instances have a .view attribute pointing to the view instance that created them.
The .run() method of text commands requires an edit instance as its rst positional argument.
Text Commands and the edit Object
The edit object groups modications to the view so that undo and macros work sensibly.
Note: Contrary to older versions, Sublime Text 3 doesnt allow programmatic control over edit objects. The API is in
charge of managing their life cycle. Plugin creators must ensure that all modifying operations occur inside the .run
method of new text commands. To call existing commands, you can use view.run_command(<cmd_name>,
<args>) or similar API calls.
Responding to Events
Any command deriving from EventListener will be able to respond to events.
Another Plugin Example: Feeding the Completions List
Lets create a plugin that fetches data from Googles Autocomplete service and then feeds it to the Sublime Text
completions list. Please note that, as ideas for plugins go, this a very bad one.
import sublime, sublime_plugin
from xml.etree import ElementTree as ET
from urllib.request 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
Note: Make sure you dont keep this plugin around after trying it or it will interfere with Sublime Texts autocomple-
tion.
9.7.6 Learning the API
In order to create plugins, you need to get acquainted with the Sublime Text API and the available commands. Docu-
mentation 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 rst 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
le to be able to peek at the sample code easily.
support us.
support us.
9.8 Packages
Packages are simply folders under Packages, or zip archives with the .sublime-package extension saved under
Installed Packages.
Heres a list of typical resources that can be found inside packages:
build systems (.sublime-build)
key maps (.sublime-keymap)
macros (.sublime-macro)
menus (.sublime-menu)
plugins (.py)
preferences (.tmPreferences)
settings (.sublime-settings)
syntax denitions (.tmLanguage)
snippets (.sublime-snippet)
themes (.sublime-theme)
Some packages may include support les for other packages or core features. For example, the spell checker uses
$PATH_TO_SUBLIME_TEXTPackagesLanguage - English.sublime-package as a data store for English dictionaries.
9.8.1 Types of Packages
In this guide, we classify packages under different categories. This classication is articial and useful just for clarity
when discussing this topic. Sublime Text doesnt use this classication 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.
9.8. Packages 51
user packages Installed by the user to extend Sublime Texts 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-packages
Its worth noting that by third party we mainly refer to users of other editors, such as Textmate.
9.8.2 Package Installation
Ultimately, installing a package is simply a matter of copying a folder containing Sublime Text resources to
Packages, or a .sublime-package le to Installed Packages. The only thing that varies is how you obtain and
copy these les.
Installing Packages vs Installed Packages
Note that installing a package actually doesnt make that package a Sublime Text installed package. Installed
packages are .sublime-package les residing in the Installed Packages folder. In this guide, we
use install a package to mean either copying a package to Packages or a .sublime-package le to Installed
Packages. We hope to come up with a less confusing terminology in the future to explain this!
Installation of .sublime-package Files
Copy the .sublime-package le to the Installed Packages folder and restart Sublime Text. If the
Installed Packages folder doesnt exist, you can create it.
Note that .sublime-package les simply are .zip archives with a custom le extension.
Installation of Packages from a Version Control System
Explaining how to use version control systems (VCSs) is outside the scope of this guide, but there are many user
packages available free of charge on public repositories like GitHub and Bitbucket.
Also, a Sublime Text organization at GitHub is open to contributors.
9.8.3 Packages and Magic
Sublime Text deals with packages without much hidden magic. There are two notable exceptions: Macros dened 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.
The User Package
Usually, unpackaged resources are stored in Packages/User. If you have a few loose snippets, macros or
plugins, this is a good place to keep them.
Merging and Order of Precedence
Packages/Default and Packages/User receive special treatment when merging les (e.g. .sublime-keymap and .sublime-
settings les). Before merging can take place, the les have to be arranged in some order. To that end, Sublime Text
sorts them alphabetically by name, with the exception of the Default and User folders. Files contained in Default will
always go to the front of the list, and those in User, to the end.
9.8.4 Ignored Packages
To temporarily disable packages, you can add them to the ignored_packages list in your
Packages/User/Preferences.sublime-settings le.
9.8.5 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.
Reverting Sublime Text to Its Default Conguration
To revert Sublime Text to its default conguration, delete the data directory and restart the editor. Keep in mind that
the Installed Packages folder will be deleted too, so youll lose all your installed packages.
Always make sure to back up your data before taking an extreme measure like this one.
Reverting Sublime Text to a fresh state solves many problems that appear to be due to bugs in Sublime Text but are in
fact caused by misbehaving plugins.
9.8.6 The Installed Packages Directory
You will nd this folder in the data directory. It contains a copy of every sublime-package installed. It is used to
restore Packages.
support us.
support us.
support us.
9.8. Packages 53
CHAPTER 10
Command Line Usage
See also:
OS X Command Line Ofcial Sublime Text Documentation
support us.
support us.
55
56 Chapter 10. Command Line Usage
CHAPTER 11
Reference
This section contains concise technincal information about Sublime Text. It is intended mainly as a quick reference
for advanced users who want to modify Sublime Texts default behavior.
If youre looking for a gentler introduction to any of these topics, try the general index.
support us.
11.1 Snippets
11.1.1 Compatibility with Textmate
Generally, Sublime Text snippets are compatible with Textmate snippets.
11.1.2 File Format
Snippet les are XML les 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.
11.1.3 Escape Sequences
\$ Literal $.
57
11.1.4 Environment Variables
$PARAM1 .. $PARAMn Arguments passed to the insertSnippet command.
$SELECTION The text that was selected when the snippet was triggered.
$TM_CURRENT_LINE Content of the line the cursor was in when the snippet was triggered.
$TM_CURRENT_WORD Current word under the cursor when the snippet was triggered.
$TM_FILENAME Filename of the le being edited including extension.
$TM_FILEPATH Path to the le being edited.
$TM_FULLNAME Users user name.
$TM_LINE_INDEX Column where the snippet is being inserted, 0 based.
$TM_LINE_NUMBER Row where the snippet is being inserted, 1 based.
$TM_SELECTED_TEXT An alias for $SELECTION.
$TM_SOFT_TABS YES if translateTabsToSpaces is true, otherwise NO.
$TM_TAB_SIZE Spaces per-tab (controlled by the tabSize option).
11.1.5 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 snippets content element.
Fields with the same name mirror each other.
11.1.6 Placeholders
Fields with a default value.
Syntax: ${1:PLACE_HOLDER} .. ${n:PLACE_HOLDER}
Fields and placeholders can be combined, and nested within other placeholders.
11.1.7 Substitutions
Syntax:
${var_name/regex/format_string/}
${var_name/regex/format_string/options}
var_name The name of the eld 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 Dont ignore newlines in the string.
58 Chapter 11. Reference
support us.
support us.
11.2 Syntax Denitions
Warning: This topic is a draft and may contain wrong information.
11.2.1 Compatibility with Textmate
Generally, Sublime Text syntax denitions are compatible with Textmate language les.
11.2.2 File Format
Textmate syntax denitions are Plist les with the tmLanguage extension. However, for convenience in this refer-
ence document, JSON is shown instead.
"patterns": [
{ "match": "\\$(\\d+)",
"captures": {
},
},
{ "match": "\\$([A-Za-z][A-Za-z0-9_]+)",
"captures": {
},
},
"begin": "(\\$)(\\{)([0-9]+):",
"beginCaptures": {
"1": { "name": "keyword.control.ssraw" },
},
"patterns": [
"match": "."
}
],
"end": "\\}"
},
"match": "\\\\(\\$|\\>|\\<)"
},
"match": "(\\$|\\>|\\<)"
}
],
}
name Descriptive name for the syntax denition. Shows up in the syntax denition dropdown menu located in the
bottom right of the Sublime Text interface. Its usually the name of the programming language or equivalent.
scopeName Name of the top-level scope for this syntax denition. Either source.<lang> or text.<lang>.
Use source for programming languages and text for everything else.
fileTypes An array of le type extensions for which this syntax automatically should be activated. Include the
extensions without the leading dot.
uuid Unique indentier for this syntax denition. Currently ignored.
foldingStartMarker Currently ignored. Used for code folding.
foldingStopMarker Currently ignored. Used for code folding.
patterns Array of patterns to match against the buffers text.
repository Array of patterns abstracted out from the patterns element. Useful to keep the syntax denition tidy
as well as for specialized uses like recursive patterns. Optional.
11.2.3 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. Renement 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
"match": "\\\\(\\$|\\>|\\<)"
"comment". "Sequences like \$, \> and \<"
}
// With captures
{ "match": "\\$(\\d+)",
"captures": {
},
}
include Includes items in the repository, other syntax denitions or the current one.
References:
$self The current syntax denition.
#itemName itemName in the repository.
source.js External syntax denitions.
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 Denes 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:
"begin": "(\\$)(\\{)([0-9]+):",
"beginCaptures": {
"1": { "name": "keyword.control.ssraw" },
},
"patterns": [
"match": "."
}
],
"end": "\\}"
}
11.2.4 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" },
"3": { "name": "keyword.other.powershell" }
}
},
{ "match": "(?<!\\w)\\d+(d)?(mb|kb|gb)?(?!\\w)",
"name": "constant.numeric.powershell",
"captures": {
"2": { "name": "keyword.other.powershell" }
}
}
]
},
"scriptblock": {
"begin": "\\{",
"end": "\\}",
"name": "meta.scriptblock.powershell",
"patterns": [
{ "include": "$self" }
]
},
}
11.2.5 Escape Sequences
Be sure to escape JSON/XML sequences as needed.
support us.
support us.
11.3 Build Systems
Build systems let you run your les through external programs without leaving Sublime Text, and see the output they
generate.
Build systems consist of twoor optionally threeparts:
Conguration data in JSON format (the .sublime-build le contents)
A Sublime Text command driving the build process
An optional, external executable le (script or binary le)
Essentially, .sublime-build les are conguration data for an external program, as well as for a Sublime Text command
(just mentioned). In them, you specify the switches, options and environment information you want forwarded.
The Sublime Text command then receives the data stored in the .sublime-build le. At this point, it can do whatever
it needs to do, to build the les. By default, build systems will use the exec command implemented by Pack-
ages/Default/exec.py. As explained below, you can override this command.
Finally, the external program may be a shell script youve created to process your les, or a well-known utility like
make or tidy. Usually, these executable les will receive paths to les or directories, along with switches and options
to run with.
Note that build systems can but dont need to call external programs; a valid build system could be implemented
entirely in Python in a Sublime Text command.
11.3.1 File Format
.build-system les use JSON. Heres an example:
{
"cmd": ["python", "-u", "$file"],
"file_regex": "^[ ]
*
File \"(...
*
?)\", line ([0-9]
*
)",
"selector": "source.python"
}
11.3.2 Options
cmd Array containing the command to run and its desired arguments. If you dont specify an absolute path, the
external program will be searched in your PATH, one of your systems 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.
11.3. Build Systems 63
line_regex Optional. If file_regex doesnt 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 le and line to go to.
selector Optional. Used when Tools | Build System | Automatic is set to true. Sublime Text uses this scope
selector to nd 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 conguration data specied in the .build-system le.
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 le.
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 systems 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 systems settings.
variants Optional. A list of dictionaries of options to override the main build systems options. Variant names
will appear in the Command Palette for easy access if the build systems selector matches for the active le.
name Only valid inside a variant (see variants). Identies 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 denition.
Capturing Error Output with file_regex
The file_regex option uses a Perl-style regular expression to capture up to four elds of error information from
the build programs output, namely: lename, line number, column number and error message. Use groups in the
pattern to capture this information. The lename eld and the line number eld are required.
When error information is captured, you can navigate to error instances in your projects les with F4 and Shift+F4.
If available, the captured error message will be displayed in the status bar.
Platform-specic Options
The windows, osx and linux elements let you provide platform-specic data in the build system. Heres an
example:
{
"cmd": ["ant"],
"file_regex": "^
*
\\[javac\\] (.+):([0-9]+):() (.
*
)$",
"working_dir": "${project_path:${folder}}",
"selector": "source.java",
"windows":
{
"cmd": ["ant.bat"]
}
}
In this case, ant will be executed for every platform except Windows, where ant.bat will be used instead.
Variants
Heres a contrived example of a build system with variants:
{
"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"
}
]
}
Given these settings, Ctrl + B would run the date command, Crtl + Shift + B would run the Python interpreter and the
remaining variants would appear in the Command Palette whenever the build system was active.
11.3.3 Build System Variables
Build systems expand the following variables in .sublime-build les:
$file_path The directory of the current le, e.g., C:\Files.
$file The full path to the current le, e.g., C:\Files\Chapter1.txt.
$file_name The name portion of the current le, e.g., Chapter1.txt.
$file_extension The extension portion of the current le, e.g., txt.
$file_base_name The name-only portion of the current le, e.g., Document.
$packages The full path to the Packages folder.
$project The full path to the current project le.
$project_path The directory of the current project le.
$project_name The name portion of the current project le.
$project_extension The extension portion of the current project le.
$project_base_name The name-only portion of the current project le.
Placeholders for Variables
Features found in snippets can be used with these variables. For example:
11.3. Build Systems 65
${project_name:Default}
This will emit the name of the current project if there is one, otherwise Default.
${file/\.php/\.txt/}
This will emit the full path of the current le, replacing .php with .txt.
11.3.4 Running Build Systems
Select the desired build system from Tools | Build System, and then select Tools | Build or press F7.
11.3.5 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 proles in shells.
To solve this issue, make sure you set the desired PATH so that graphical applications such as Sublime Text can nd
it. See the links below for more information.
Alternatively, you can use the path element in .sublime-build les to override the PATH used to locate the executable
specied 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.
See also:
Managing Environment Variables in Windows Search Microsoft knowledge base for this topic.
Setting environment variables in OSX StackOverow topic.
support us.
support us.
11.4 Key Bindings
Key bindings map key presses to commands.
11.4.1 File Format
Key bindings are stored in .sublime-keymap les and dened in JSON. All key map lenames need to follow this
pattern: Default (<platform>).sublime-keymap. Otherwise, Sublime Text will ignore them.
Platform-Specic Key Maps
Each platform gets its own key map:
Default (Windows).sublime-keymap
Default (OSX).sublime-keymap
Default (Linux).sublime-keymap
Separate key maps exist to abide by different vendor-specic HCI guidelines.
Structure of a Key Binding
Key maps are arrays of key bindings. Below youll nd valid elements in key bindings.
keys An array of case-sensitive keys to be pressed. Modiers can be specied with the + sign. Chords are built by
adding elements to the array, e.g. ["ctrl+k","ctrl+j"]. Ambiguous chords are resolved with a timeout.
command Name of the command to be executed.
args Dictionary of arguments to be passed to command. Keys must be the names of parameters to command.
context Array of contexts to selectively enable the key binding. All contexts must be true for the key binding to
trigger. See Structure of a Context below.
Heres an example illustrating most of the features outlined above:
{ "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 }
]
}
Structure of a Context
key Name of a context operand to query.
operator Type of test to perform against key.
operand Value against which the result of key is tested.
match_all Requires the test to succeed for all selections. Defaults to false.
Context Operands
auto_complete_visible Returns true if the autocomplete list is visible.
has_next_field Returns true if a next snippet eld is available.
has_prev_field Returns true if a previous snippet eld is available.
num_selections Returns the number of selections.
overlay_visible Returns true if any overlay is visible.
panel_visible Returns true if any panel is visible.
11.4. Key Bindings 67
following_text Restricts the test just to the text following the caret.
preceding_text Restricts the test just to the text preceding the caret.
selection_empty Returns true if the selection is an empty region.
setting.x Returns the value of the x setting. x can be any string.
text Restricts the test just to the selected text.
selector Returns the current scope.
panel_has_focus Returns true if the current focus is on a panel.
panel Returns true if the panel given as operand is visible.
Context Operators
equal, not_equal Test for equality.
regex_match, not_regex_match Match against a regular expression.
regex_contains, not_regex_contains Match against a regular expression (containment).
11.4.2 Command Mode
Sublime Text provides a command_mode setting to prevent key presses from being sent to the buffer. This is useful
when emulating Vims modal behavior.
11.4.3 Bindable Keys
Keys may be specied literally or by name. Heres 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
11.4. Key Bindings 69
f20
sysreq
break
context_menu
browser_back
browser_forward
browser_refresh
browser_stop
browser_search
browser_favorites
browser_home
Modiers
shift
ctrl
alt
super (Windows key, Command key...)
Warning about Bindable Keys
If youre developing a package, keep this in mind:
Ctrl+Alt+<alphanum> should not be used for any Windows key bindings.
Option+<alphanum> should not be used for any OS X key bindings.
In both cases, the users ability to insert non-ASCII characters would be compromised.
If you are the end-user, you are free to remap those key combinations.
11.4.4 Keeping Key Maps Organized
Sublime Text ships with default key maps under Packages/Default. Other packages may include their own key
map les. 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 les for merging.
11.4.5 International Keyboards
Due to the way Sublime Text maps key names to physical keys, there might be a mismatch between the two.
11.4.6 Troubleshooting
To enable command logging, see sublime.log_commands(ag). This may help in debugging key maps.
support us.
support us.
11.5 Settings (Reference)
11.5.1 Global Settings
Target le: Global.sublime-settings.
theme Theme to be used. Accepts a le 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 les 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 lters are opened from Finder, or by dragging onto the dock
icon, this controls whether a new window is created or not.
11.5.2 File Settings
Target les: Base File.sublime-settings, <file_type>.sublime-settings.
Whitespace and Indentation
auto_indent Toggles automatic indentation.
tab_size Number of spaces a tab is considered equal to.
translate_tabs_to_spaces Determines whether to replace a tab character with tab_size number of spaces
when Tab is pressed.
use_tab_stops If translate_tabs_to_spaces is true, will make Tab and Backspace insert/delete
tab_size number of spaces per key press.
trim_automatic_white_space Toggles deletion of white space added by auto_indent.
11.5. Settings (Reference) 71
detect_indentation Set to false to disable detection of tabs vs. spaces whenever a buffer is loaded. If set to
true, it automatically will modify translate_tabs_to_spaces and tab_size.
draw_white_space Valid values: none, selection, all.
trim_trailing_white_space_on_save Set to true to remove white space on save.
Visual Settings
color_scheme Sets the colors used for text highlighting. Accepts a path rooted at the data directory (for example,
Packages/Color Scheme - Default/Monokai Bright.tmTheme).
font_face Font face to be used for editable text.
font_size Size of the font for editable text.
font_options Valid values: bold, italic, no_antialias, gray_antialias,
subpixel_antialias, directwrite (Windows).
gutter Toggles display of gutter.
rulers Columns in which to display vertical rules. Accepts a list of numeric values (such as [79, 89, 99]) or
a single numeric value (for example, 79).
draw_minimap_border Set to true to draw a border around the minimaps region corresponding to the the
views currently visible text. The active color schemes minimapBorder key controls the borders color.
highlight_line Set to false to stop highlighting lines with a cursor.
line_padding_top Additional spacing at the top of each line, in pixels.
line_padding_bottom Additional spacing at the bottom of each line, in pixels.
scroll_past_end Set to false to disable scrolling past the end of the buffer. If true, Sublime Text will leave
a wide, empty margin between the last line and the bottom of the window.
line_numbers Toggles display of line numbers in the gutter.
word_wrap If set to false, long lines will be clipped instead of wrapped. Scroll the screen horizontally to see the
clipped text.
wrap_width If greater than 0, wraps long lines at the specied column as opposed to the window width. Only takes
effect if word_wrap is set to true.
indent_subsequent_lines If set to false, wrapped lines will not be indented. Only takes effect if
word_wrap is set to true.
draw_centered If set to true, text will be drawn centered rather than left-aligned.
match_brackets Set to false to disable underlining the brackets surrounding the cursor.
match_brackets_content Set this to false if youd rather have brackets highlighted only when the cursor is
next to one.
match_brackets_square Set to false to stop highlighting square brackets. Only takes effect if
match_brackets is true.
match_bracktets_braces Set to false to stop highlighting curly brackets. Only takes effect if
match_bracktets_angle Set to false to stop highlighting angle brackets. Only takes effect if
Automatic Behavior
auto_match_enabled Toggles automatic pairing of quotes, brackets, etc.
save_on_focus_lost Set to true to save les automatically when switching to a different le or application.
find_selected_text If true, the selected text will be copied into the nd panel when its shown.
word_separators Characters considered to divide words for actions like advancing the cursor, etc. Not used for
every context where a notion of a word separator is useful (for example, word wrapping). In some contexts, the
text might be tokenized based on other criteria (for example, the syntax denition rules).
ensure_newline_at_eof_on_save Always adds a new line at the end of the le if not present when saving.
System and Miscellaneous Settings
is_widget Returns true if the buffer is an input eld in a dialog, as opposed to a regular buffer.
spell_check Toggles the spell checker.
dictionary Word list to be used by the spell checker. Accepts a path rooted at the data directory (such as
Packages/Language - English/en_US.dic). You can add more dictionaries.
fallback_encoding The encoding to use when the encoding cant be determined automatically. ASCII, UTF-8
and UTF-16 encodings will be detected automatically .
default_line_ending Determines what characters to use to designate new lines. Valid values: system (OS-
dependant), windows (CRLF) and unix (LF).
tab_completion Determines whether pressing Tab will insert completions.
Build and Error Navigation Settings
result_file_regex Regular expression used to extract error information from some output dumped into a view
or output panel. Follows the same rules as error capturing in build systems.
result_line_regex Regular expression used to extract error information from some output dumped into a view
or output panel. Follows the same rules as error capturing in build systems.
result_base_dir Folder to start looking for offending les based on information extracted with
result_file_regex and result_line_regex.
build_env List of paths to add to build systems by default.
File and Directory Settings
default_dir Sets the default save folder for the view.
Input Settings
command_mode If set to true, the buffer will ignore key strokes. Useful when emulating Vims modal behavior.
support us.
11.5. Settings (Reference) 73
support us.
11.6 Command Palette
The command palette is fed entries with .sublime-commands les.
11.6.1 File Format (.sublime-commands Files)
Heres 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.
11.6.2 How to Use the Command Palette
1. Press Ctrl+Shift+P
2. Select command
Entries are ltered by current context. Not all entries will be visible at all times.
support us.
support us.
11.7 Completions
Completions provide an IDE-like functionality to insert dynamic content through the completions list or by pressing
Tab.
11.7.1 File Format
Completions are JSON les with the .sublime-completions extension.
11.7.2 Where to Store Completions
Completions les can be stored anywhere under Packages. They can be included in .sublime-package archives
too. If youre dening completions for your own use, Packages/User is the right place to keep them.
11.7.3 Structure of a Completions List
scope Determines whether the completions are to be sourced from this le. See Scopes for more information.
completions Array of completions.
Heres an excerpt from the html completions:
{
"completions":
[
{ "trigger": "acronym", "contents": "<acronym>$0</acronym>" }
]
}
11.7.4 Types of Completions
Plain Strings
Plain strings are equivalent to an entry where the trigger is identical to the contents:
"foo"
# is equivalent to:
{ "trigger": "foo", "contents": "foo" }
Trigger-based Completions
trigger Text that will be displayed in the completions list and will cause the contents to be inserted when
validated.
contents Text to be inserted in the buffer. Can use snippet features.
11.7. Completions 75
11.7.5 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 nal list:
Snippets
Words in the buffer
Priority of Sources for Completions
Snippets
Words in buffer
Snippets will only be automatically completed against an exact match of their tab trigger. Other sources for comple-
tions are ltered with a case insensitve fuzzy search instead.
11.7.6 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
Note: The current selection in the completions list can in fact be validated with any punctuation sign that isnt itself
bound to a snippet.
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.
11.7.7 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 dened in .sublime-snippet les, 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.
Inserting a Literal Tab
If tab_completion is true, you can press Shift+Tab after a prex to insert a literal tab character.
support us.
support us.
11.8 Plugins
See also:
API Reference More information on the Python API.
Plugins are Python scripts implementing
*
Command classes from sublime_plugin.
11.8.1 Where to Store Plugins
Sublime Text will look for plugins in these places:
Packages
Packages/<pkg_name>
.sublime-package les
Plugin les nested deeper in Packages wont 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.
11.8.2 Conventions for Command Names
By convention, Sublime Text command class names are sufxed with Command and written as
NamesLikeThisCommand.
However, command names are automatically transformed fromNamesLikeThisCommand to name_like_this.
Thus, ExampleCommand would become example, and AnotherExampleCommand would become
another_example.
In names for classes dening commands, use NameLikeThisCommand. To call a command from the API, use the
standardized name_like_this.
11.8.3 Types of Commands
sublime_plugin.WindowCommand
sublime_plugin.TextCommand
sublime_plugin.EventListener
11.8. Plugins 77
Instances of WindowCommand have a .window attribute pointing to the window instance that created them. Simi-
larly, instances of TextCommand have a .view attribute.
Shared Traits for Commands
All commands must implement a .run() method.
All commands can receive an arbitrarily long number of keyword arguments that must be valid JSON types.
11.8.4 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 commands name, .run_command
accepts a dictionary whose keys are the names of valid parameters for said command:
window.run_command("echo", {"Tempus": "Irreparabile", "Fugit": "."})
11.8.5 Command Arguments
All user-provided arguments to commands must be valid JSON types.
11.8.6 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 nished.
Contrary to earlier versions of Sublime Text, the edit objects 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.
11.8.7 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.
A Word of Warning about EventListener
Expensive operations in event listeners can cause Sublime Text to become unresponsive, especially in events
triggered frequently, like on_modified() and on_selection_modified(). Be careful of how much
work is done in these and dont implement events you dont need, even if they just pass.
11.8.8 Sublime Text and the Python Standard Library
Sublime Text ships with a trimmed down standard library.
11.8.9 Automatic Plugin Reload
Sublime Text will reload top-level Python modules as they change (perhaps because you are editing a .py le within
Packages). By contrast, Python subpackages wont be reloaded automatically, and this can lead to confusion while
youre developing plugins. Generally speaking, its best to restart Sublime Text after youve made changes to plugin
les, so all changes can take effect.
11.8.10 Multithreading
Only the set_timeout() function is safe to call from different threads.
support us.
support us.
11.9 Python API
See also:
Ofcial Documentation API documentation.
11.9.1 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: eld
4. Check Use Buffer option
5. Search API name
6. F4
7. Study relevant source code
support us.
support us.
11.9. Python API 79
11.10 Commands
11.10.1 Overview
This list of commands is a work in progress.
11.10.2 About Paths in Command Arguments
Some commands take paths as parameters. Among these, some support snippet-like syntax, while others dont. A
command of the rst 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.
Variables in Paths as Arguments
The same variables available to build systems are expanded in arguments to commands. See Build System Variables
for more information.
11.10.3 Commands
build Runs a build system.
variant [String]: Optional. The name of the variant to be run.
run_macro_le Runs a .sublime-macro le.
le [String]: Path to the macro le.
insert_snippet Inserts a snippet from a string or .sublime-snippet le.
contents [String]: Snippet as a string to be inserted.
name [String]: Path to the .sublime-snippet le to be inserted.
insert Inserts a string.
characters [String]: String to be inserted.
move Advances the caret by predened 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 predened 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_le Switches between two les 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_le Closes the active view and, under certain circumsances, the whole application. XXX Sounds kinda wrong.
save Saves the active le.
prompt_save_as Prompts for a new le name and saves the active le.
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 dont think this
is very clear or even true.
select_all Select the views content.
split_selection_into_lines Unsurprisingly, it splits the selection into lines.
single_selection Collapses multiple selections into a single selection.
clear_elds Breaks out of the active snippet eld cycle.
hide_panel Hides the active panel.
11.10. Commands 81
cancel [Bool]: Noties the panel to restore the selection to what it
was when the panel was opened. (Only incremental nd 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_eld Advances the caret to the text snippet eld in the current snippet eld cycle.
prev_eld Moves the caret to the previous snippet eld in the current snippet eld cycle.
commit_completion Inserts into the buffer the item thats 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 predined limits.
to [Enum]: Values: bol, hardbol, eol, hardeol, bof, eof, brackets, line.
nd_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_les [Bool]: If using the goto overlay, start by displaying les rather than an empty widget.
text [String]: The initial contents to put in the overlay.
show_panel Shows a panel.
panel [Enum]: Values: incremental_nd, nd, replace, nd_in_les, console
reverse [Bool]: Whether to search backwards in the buffer.
toggle [Bool]: Whether to hide the panel if its already visible.
nd_next Finds the next occurrence of the current search term.
nd_prev Finds the previous occurrence of the current search term.
nd_under Finds the next occurrence of the current selection or the current word.
nd_under_prev Finds the previous occurrence of the current selection or the current word.
nd_all_under Finds all occurrences of the current selection or the current word.
slurp_nd_string Copies the current selection or word into the nd eld of the nd panel.
slurp_replace_string Copies the current selection or word into the replace eld of the nd 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 carets 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 rst rulers column.
width [Int]: Species the column at which lines should be wrapped.
upper_case Makes the selection upper case.
lower_case Makes the selection lower case.
11.10. Commands 83
title_case Capitalizes the selections rst 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.
support us.
support us.
11.11 Keyboard Shortcuts - Windows/Linux
11.11.1 Editing
Windows
Ctrl + Alt + Up Column selection up
Ctrl + Alt + Down Column selection down
Linux
Alt + + Up Column selection up
Alt + + Down Column selection down
11.11.2 Navigation/Goto Anywhere
Keypress Command
Ctrl + P Quick-open les by name
Ctrl + R Goto symbol
Ctrl + ; Goto word in current le
Ctrl + G Goto line in current le
11.11.3 General
Keypress Command
Ctrl + + P Command prompt
Ctrl + KB Toggle side bar
Ctrl + + Alt + P Show scope in status bar
11.11.4 Find/Replace
Keypress Command
Ctrl + F Find
Ctrl + H Replace
Ctrl + + F Find in les
11.11.5 Tabs
Keypress Command
Ctrl + + t Open last closed tab
Ctrl + PgUp Cycle up through tabs
Ctrl + PgDn Cycle down through tabs
Ctrl + Find in les
Alt + [NUM] Switch to tab number [NUM] where [NUM] <= number of tabs
11.11.6 Split window
Keypress Command
Alt + + 2 Split view into two columns
Alt + + 1 Revert view to single column
Alt + + 5 Set view to grid (4 groups)
Ctrl + [NUM] Jump to group where num is 1-4
Ctrl + + [NUM] Move le to specied group where num is 1-4
11.11.7 Bookmarks
Keypress Command
Ctrl + F2 Toggle bookmark
F2 Next bookmark
+ F2 Previous bookmark
Ctrl + + F2 Clear bookmarks
11.11. Keyboard Shortcuts - Windows/Linux 85
11.11.8 Text manipulation
Keypress Command
Ctrl + KU Transform to Uppercase
Ctrl + KL Transform to Lowercase
support us.
support us.
11.12 Keyboard Shortcuts - OSX
11.12.1 Editing
Keypress Command
+ X Delete line
+ Insert line after
+ + Insert line before
+ + Move line/selection up
+ + Move line/selection down
+ L Select line - Repeat to select next lines
+ D Select word - Repeat select others occurrences
+ M Jump to closing parentheses Repeat to jump to opening parentheses
+ + M Select all contents of the current parentheses
+ K, + K Delete from cursor to end of line
+ K + Delete from cursor to start of line
+ ] Indent current line(s)
+ [ Un-indent current line(s)
+ + D Duplicate line(s)
+ J Join line below to the end of the current line
+ / Comment/un-comment current line
+ + / Block comment current selection
+ Y Redo, or repeat last keyboard shortcut command
+ + V Paste and indent correctly
+ Space Select next auto-complete suggestion
+ U Soft undo; jumps to your last change before undoing change when repeated
+ + Up Column selection up
+ + Down Column selection down
+ + W Wrap Selection in html tag
11.12.2 Navigation/Goto Anywhere
Keypress Command
+ P Quick-open les by name
+ R Goto symbol
Goto word in current le
+ G Goto line in current le
11.12.3 General
Keypress Command
+ + P Command prompt
+ K, + B Toggle side bar
+ + P Show scope in status bar
11.12.4 Find/Replace
Keypress Command
+ F Find
+ + F Replace
+ + F Find in les
11.12.5 Tabs
Keypress Command
+ + t Open last closed tab
^ + Tab Cycle up through tabs
+ ^ + Tab Cycle down through tabs
Find in les
11.12.6 Split window
Keypress Command
+ + 2 Split view into two columns
+ + 1 Revert view to single column
+ + 5 Set view to grid (4 groups)
+ [NUM] Jump to group where num is 1-4
+ + [NUM] Move le to specied group where num is 1-4
11.12.7 Bookmarks
Keypress Command
+ F2 Toggle bookmark
F2 Next bookmark
+ F2 Previous bookmark
+ + F2 Clear bookmarks
11.12. Keyboard Shortcuts - OSX 87
11.12.8 Text manipulation
support us.
support us.
support us.
CHAPTER 12
Glossary
buffer Data of a loaded le and additional metadata, associated with one or more views. The distinction between
buffer and view is technical. Most of the time, both terms can be used interchangeably.
view Graphical display of a buffer. Multiple views can show the same buffer.
plugin A feature impemented in Python, which can consist of a single command or multiple commands. It can be
contained in one .py le or many .py les.
package This term is ambiguous in the context of Sublime Text, because it can refer to a Python package (unlikely),
a folder inside Packages or a .sublime-package le. Most of the time, it means a folder inside Packages
containing resources that belong together, which build a new feature or provide support for a programming or
markup language.
panel An input/output widget, such as a search panel or the output panel.
overlay An input widget of a special kind. For example, Goto Anything is an overlay.
support us.
support us.
89

Sublime Text Unofficial Documentation

Uploaded by

Copyright:

Available Formats

Sublime Text Unofficial Documentation

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Sublime Text Unofficial Documentation

Uploaded by

Copyright:

Available Formats

Sublime Text Unofcial Documentation

You might also like