Sublime Text is programmable with Python scripts. Plugins reuse existing commands or create new ones to build a feature. Plugins are a logical entity, rather than a physical one.
Where to Store Plugins¶
Sublime Text will look for plugins directly in these places:
Consequently, any plugin nested deeper in
Packages won’t be loaded.
Keeping plugins just under
Packages is discouraged, because Sublime Text
sorts packages in a predefined way before loading them. So, you might get
confusing results if your plugins live outside a package.
Your First Plugin¶
Let’s write a “Hello, World!” plugin for Sublime Text:
- Select Tools | New Plugin… in the menu.
- Save to
You’ve just written your first plugin! Let’s put it to use:
- Create a new buffer (
- Open the Python console (
view.run_command("example")and press enter.
You should see the text “Hello, World!” in your new buffer.
Analyzing Your First Plugin¶
The plugin created in the previous section should look roughly like this:
import sublime, sublime_plugin class ExampleCommand(sublime_plugin.TextCommand): def run(self, edit): self.view.insert(edit, 0, "Hello, World!")
sublime_plugin modules are provided by
All new commands derive from the
*Command classes defined in
(more on this later).
The rest of the code is concerned with the particulars of
TextCommand or with
the API. We’ll discuss those topics in later sections.
Before moving on, though, we’ll look at how we invoked the new command. First we
opened the Python console, and then we issued a call to
is rather an inconvenient way of using plugins, but it’s often useful when
you’re in the development phase of a plugin. For now, keep in mind that your commands
can be accessed both through key bindings and by other means, just like other commands.
Conventions for Command Names¶
You might have noticed that our command is defined with the name
but we pass the string
example to the API call instead. This is necessary because
Sublime Text normalizes command names, stripping the
Command suffix and
CamelCasedPhrases with underscores, like this:
New commands should follow the CamelCase pattern for class names.
Types of Commands¶
You can create the following types of commands:
- Application commands (
- Window commands (
- Text commands (
When writing plugins, consider your goal and choose the appropriate type of commands for your plugin.
Application commands derive from
can be executed with
Window commands operate at the window level. This doesn’t mean you can’t
manipulate views from window commands, but rather that you don’t need views
in order for window commands to be available. For instance, the built-in
new_file is defined as a
WindowCommand so it works, even when no
view is open. Requiring a view to exist in that case wouldn’t make sense.
Window command instances have a
.window attribute to point to the window
instance that created them.
.run() method of a window command needn’t be passed any positional arguments.
Text commands operate at the buffer level, so they require a buffer to exist in order to be available.
View command instances have a
.view attribute pointing to the view instance
that created them.
.run() method of a text command needs to accept an
edit instance as
the first positional argument.
Text Commands and the
The edit object groups any modifications to the view so as to enable undo and macros to work sensibly.
You are responsible for creating and closing edit objects. To do
so, you can call
For convenience, the currently open
edit object gets passed to text
run method automatically.
View methods require an edit object.
Responding to Events¶
Any command deriving from
EventListener will be able to respond to events.
Another Plugin Example: Feeding the Completions List¶
Let’s create a plugin that fetches data from Google’s 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 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
Make sure you don’t keep this plugin around after trying it or it will interfere with Sublime Text’s autocompletion.
Learning the API¶
In order to create plugins, you need to get acquainted with the Sublime Text
API and the available commands. Documentation on both is scarce at the time of
this writing, but you can read existing code and learn from it too. In
Packages/Default folder contains many examples of
undocumented commands and API calls.