Sublime Text 2 is programmable with Python scripts. Plugins reuse existing commands or create new ones to build a feature. Plugins are rather a logical entity than a physical one.
Sublime Text 2 will look for plugins in these places:
Consequently, any plugin nested deeper in Packages won’t be loaded.
Keeping plugins right under Packages is discouraged, because Sublime Text sorts packages in a predefined way before loading them. Thus, you might get confusing results if your plugins live outside of a package.
Let’s write a “Hello, World!” plugin for Sublime Text 2:
You’ve just written your first plugin. Let’s put it to use:
You should see the text “Hello, World!” in your new 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!")
The sublime and sublime_plugin modules are both provided by Sublime Text 2.
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 the TextCommand or the API that we’ll discuss in the next sections.
Before moving on, though, we’ll look at how we called the new command: We first opened the python console, and then 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. For now, keep in mind that your commands can be accessed through key bindings or other means, just as other commands are.
You might have noticed that our command is defined with the name ExampleCommand, but we pass the string example to the API call instead. This is necessary because Sublime Text 2 normalizes command names by stripping the Command suffix and separating CamelCasedPhrases with underscores, like this: camel_cased_phrases.
New commands should follow the pattern mentioned above for class names.
You can create the following types of commands:
When writing plugins, consider your goal and choose the appropriate type of commands for your plugin.
Application commands derive from sublime_plugin.ApplicationCommand and can be executed with sublime.run_command().
Window commands operate at the window level. This doesn’t mean that you cannot manipulate views from window commands, but rather that you don’t need views to exist in order for window commands to be available. For instance, the built-in command new_file is defined as a WindowCommand so it works too when no view is open. Requiring a view to exist in that case wouldn’t make sense.
Window command instances have a .window attribute pointing to the window instance that created them.
The .run() method of a window command does not need to take any required arguments.
Text commands operate at the buffer level and 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 a text command needs to take an edit instance as a first positional argument.
The edit object groups modifications to the view so undo and macros work in a sensible way. You are responsible for creating and closing edit objects. To do so, you can call view.begin_edit() and edit.end_edit(). Text commands get passed an open edit object in their run method for convenience. Additionally, many View methods require an edit object.
Any command deriving from EventListener will be able to respond to events.
Let’s create a plugin that fetches data from Google Autocomplete service and feeds it to Sublime Text 2 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 interefere with the autocompletion system.
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 Packages/Default folder contains many examples of undocumented commands and API calls.