You can write plugins for Sublime Text in Python. Plugins build features by reusing existing commands or creating new ones. Plugins are a logical entity, rather than a physical one.
In order to write plugins, you must be able to program in Python. Sublime Text uses Python 3.
Sublime Text will look for plugins directly in these places:
Therefore, any plugin nested deeper in Packages won’t be loaded.
Keeping plugins just under Packages is discouraged. Sublime Text sorts packages in a predefined way before loading them, so if you save plugins directly under Packages, you might get confusing results if your plugins live outside a package.
Let’s write a “Hello, World!” plugin for Sublime Text:
You’ve just written your first plugin! Let’s put it to use:
You should see the text “Hello, World!” in the newly created buffer.
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.
All new commands derive from the *Command classes defined in sublime_plugin (more on this later).
The rest of the code is concerned with particulars of TextCommand or with the API. We’ll discuss those topics in later sections.
Before moving on, though, we’ll look at how we invoked the new command. First we opened the Python console, and then we issued a call to view.run_command(). This is a rather inconvenient way of 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 through key bindings and by other means, just like other commands.
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 suffix and separating PhrasesLikThis with underscores, like so: phrases_like_this.
New commands should follow the same naming pattern.
You can create the following types of commands:
When writing plugins, consider your goal and choose the appropriate type of commands for your plugin.
Window commands operate at the window level. This doesn’t mean that 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 command 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.
The .run() method of a window command doesn’t require any positional parameter.
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.
The .run() method of text commands requires and edit instance as its first positional argument.
The edit object groups any modifications to the view so that undo and macros work sensibly.
Note: Contrary to older versions, Sublime Text 3 doesn’t allow programmatic control over edit objects. The API is in charge of managing them. Plugin creators must ensure that all modifying operations occur inside the .run method of a text command if they are creating a new one. Obviously, you can also use view.run_command to call existing commands.
Any command deriving from EventListener will be able to respond to events.
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.
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 particular, the $PATH_TO_SUBLIME/Packages/Default.sublime-package contains many examples of undocumented commands and API calls. Note that you will first have to extract it to a folder if you want to take a look at its contents.