API Reference

Sublime API View RegionSet Region Edit Window Settings Base Classes EventListener ApplicationCommand WindowCommand TextCommand

Contents

Example Plugins
Several pre-made plugins come with Sublime Text 2, you can find them in the Packages/Default directory:
Packages/Default/delete_word.py Deletes a word to the left or right of the cursor Packages/Default/duplicate_line.py Duplicates the current line Packages/Default/goto_line.py Prompts the user for input, then updates the selection Packages/Default/font.py Shows how to work with settings Packages/Default/mark.py Uses add_regions() to add an icon to the gutter Packages/Default/trim_trailing_whitespace.py Modifies a buffer just before its

saved

Module sublime
Methods
set_timeout(callback, delay)

Return Value
None

Description
Calls the given callback after the given delay (in milliseconds). Callbacks with an equal delay will be run in the order they were added. It is safe to call setTimeout from multiple threads. Sets the message that appears in the status bar. Displays an error dialog to the user. Loads the named settings. The name

status_message(string) error_message(string) load_settings(base_name)

None None Settings

g should include a file name and extension, but not a path. The packages will be searched for files matching the base name, and the results will be collated into the settings object. Subsequent calls to load_settings with the name base_name will return the same object, and not load the settings from disk again. save_settings(base_name) windows() active_window() packages_path() installed_packages_path() get_clipboard() set_clipboard(string) log_commands(flag) None [Window] Window String String String None None Flushes any in-memory changes to the named settings object to disk. Returns a list of all the open windows. Returns the most recently used window. Returns the base path to the packages. Returns the path where all the user's *.sublime-package files are. Returns the contents of the clipboard. Sets the contents of the clipboard. Controls command logging. If enabled, all commands run from key bindings and the menu will be logged to the console. Returns the version number Returns the platform, which may be "osx", "linux" or "windows" Returns the CPU architecture, which may be "x32" or "x64"

version() platform() arch()

String String String

Class sublime.View
Represents a view into a text buffer. Note that multiple views may refer to the same buffer, but they have their own unique selection and geometry. Methods
id() buffer_id() file_name() name()

Return Value
int int String String

Description
Returns a number that uniquely identifies this view. Returns a number that uniquely identifies the buffer underlying this view. The full name file the file associated with the buffer, or None if it doesn't exist on disk. The name assigned to the buffer, if any

set_name(name) is_loading() is_dirty() is_read_only() set_read_only(value) is_scratch() set_scratch(value) settings()

None bool bool bool None bool None Settings

Assigns a name to the buffer Returns true if the buffer is still loading from disk, and not ready for use. Returns true if there are any unsaved modifications to the buffer. Returns true if the buffer may not be modified. Sets the read only property on the buffer. Returns true if the buffer is a scratch buffer. Scratch buffers never report as being dirty. Sets the scratch property on the buffer. Returns a reference to the views settings object. Any changes to this settings object will be private to this view. Returns a reference to the window containing the view. Runs the named TextCommand with the (optional) given arguments. Returns the number of character in the file. Returns the contents of the region as a string. Returns the character to the right of the point. Creates an edit object, demarcating an undo group. A corresponding call to end_edit() is required. Finishes the edit. Inserts the given string in the buffer at the specified point. Returns the number of characters inserted: this may be different if tabs are being translated into spaces in the current buffer. Erases the contents of the region from the buffer. Replaces the contents of the region with the given string. Returns a reference to the selection. Returns the line that contains the point. Returns a modified copy of region such that it starts at the beginning of a line, and ends at the end of a line. Note that it may span several lines. As line(), but the region includes the trailing newline character, if any. As line(), but the region includes the trailing newline character, if any.

window() run_command(string, <args>) size() substr(region) substr(point) begin_edit(<command>, <args>) end_edit(edit) insert(edit, point, string)

Window None int String String Edit Edit int

erase(edit, region) replace(edit, region, string) sel() line(point) line(region)

None None RegionSet Region Region

full_line(point) full_line(region)

Region Region

lines(region) split_by_newlines(region) word(point) word(region)

[Region] [Region] Region Region

Returns a list of lines (in sorted order) intersecting the region. Splits the region up such that each region returned exists on exactly one line. Returns the word that contains the point. Returns a modified copy of region such that it starts at the beginning of a word, and ends at the end of a word. Note that it may span several words. Returns the first Region matching the regex pattern, starting from the given point, or None if it can't be found. The optional flags parameter may be sublime.LITERAL, sublime.IGNORECASE, or the two ORed together. Returns all (non-overlapping) regions matching the regex pattern. The optional flags parameter may be sublime.LITERAL, sublime.IGNORECASE, or the two ORed together. If a format string is given, then all matches will be formatted with the formatted string and placed into the extractions list. Calculates the 0 based line and column numbers of the point. Calculates the character offset of the given, 0 based, row and column. Note that 'col' is interpreted as the number of characters to advance past the beginning of the row. Changes the syntax used by the view. syntax_file should be a name along the lines of Packages/Python/Python.tmLanguage. To retrieve the current syntax, use view.settings().get('syntax'). Returns the extents of the syntax name assigned to the character at the given point. Returns the syntax name assigned to the character at the given point. Returns True iff the selector matches the syntax name assigned to the character at the given point. Scroll the view to show the given point. Scroll the view to show the given region. Scroll the view to show the given region set. Scroll the view to center on the point.

find(pattern, fromPosition, <flags>)

Region

find_all(pattern, <flags>, <format>, <extractions>)

[Region]

rowcol(point) text_point(row, col)

(int, int) int

set_syntax_file(syntax_file)

None

extract_scope(point) scope_name(point) match_selector(point, selector) show(point, <show_surrounds>) show(region, <show_surrounds>) show(region_set, <show_surrounds>) show_at_center(point)

Region String bool None None None None

show_at_center(region) visible_region() add_regions(key, [regions], scope, <icon>, <flags>)

None Region None

Scroll the view to center on the region. Returns the currently visible area of the view. Add a set of regions to the view. If a set of regions already exists with the given key, they will be overwritten. The scope is used to source a color to draw the regions in, it should be the name of a scope, such as "comment" or "string". If the scope is empty, the regions won't be drawn. The optional icon name, if given, will draw the named icons in the gutter next to each region. The icon will be tinted using the color associated with the scope. Valid icon names are dot, circle, bookmark and cross. The optional flags parameter is a bitwise combination of: sublime.DRAW_EMPTY. Draw empty regions with a vertical bar. By default, they aren't drawn at all. sublime.HIDE_ON_MINIMAP. Don't show the regions on the minimap. sublime.DRAW_EMPTY_AS_OVERWRITE. Draw empty regions with a horizontal bar instead of a vertical one. sublime.DRAW_OUTLINED. Draw regions as an outline, rather than filled in. sublime.PERSISTENT. Save the regions in the session. sublime.HIDDEN. Don't draw the regions.

get_regions(key) erase_regions(key) set_status(key, value)

[regions] None None

Return the regions associated with the given key, if any Removed the named regions Adds the status key to the view. The value will be displayed in the status bar, in a comma separated list of all status values, ordered by key. Setting the value to the empty string will clear the status. Returns the previously assigned value associated with the key, if any. Clears the named status. Returns the command name, command arguments, and repeat count for the given history entry, as stored in the undo / redo stack.

get_status(key) erase_status(key) command_history(index, <modifying_only>)

String None (String,Dict,int)

Index 0 corresponds to the most recent command, 1 the command before that, and so on. Positive values for index indicate to look in the redo stack for commands. If the undo / redo history doesn't extend far enough, then (None, None, 0) will be returned. Setting modifying_only to True (the default is False) will only return entries that modified the buffer.

Class sublime.RegionSet
Maintains a set of Regions, ensuring that none overlap. The regions are kept in sorted order. Methods
clear() add(region)

Return Value
None None

Description
Removes all regions. Adds the given region. It will be merged with any intersecting regions already contained within the set. Adds all regions in the given set. Subtracts the region from all regions in the set. Returns true iff the given region is a subset.

add_all(region_set) subtract(region) contains(region)

None None bool

Class sublime.Region
Represents an area of the buffer. Empty regions, where a == b are valid. Constructors
Region(a, b)

Description
Creates a Region with initial values a and b.

Properties
a b

Type
int int

Description
The first end of the region. The second end of the region. May be less that a, in which case the region is a reversed one.

Return

Methods
begin() end() size() empty() cover(region) intersection(region) intersects(region) contains(region) contains(point)

Value
int int int bool Region Region bool bool bool

Description
Returns the minimum of a and b. Returns the maximum of a and b. Returns the number of characters spanned by the region. Always >= 0. Returns true iff begin() == end(). Returns a Region spanning both this and the given regions. Returns the set intersection of the two regions. Returns True iff this == region or both include one or more positions in common. Returns True iff the given region is a subset. Returns True iff begin() <= point <= end().

Class sublime.Edit
Edit objects have no functions, they exist to group buffer modifications. They can be created by view.begin_edit(). Every call to view.begin_end() must have a corresponding call to view.end_edit(), typically wrapped in a try ... finally block. Methods
(no methods)

Return Value

Description

Class sublime.Window
Methods
id() new_file()

Return Value
int View

Description
Returns a number that uniquely identifies this window. Creates a new file. The returned view will be empty, and its is_loaded method will return True. Opens the named file, and returns the corresponding view. If the file is already opened, it will be brought to the front.

open_file(file_name, <flags>)

View

Note that as file loading is asynchronous, operations on the returned view won't be possible until its is_loading() method returns False. The optional flags parameter is a bitwise combination of: sublime.ENCODED_POSITION. Indicates the file_name should be searched for a :row or :row:col suffix sublime.TRANSIENT. Open the file as a preview only: it won't have a tab assigned it until modified active_view() views() num_groups() active_group() focus_group(group) focus_view(view) folders() run_command(string, <args>) show_quick_panel(items, on_done) View [View] int int None None [String] None None Returns the currently edited view. Returns all open views in the window. Returns the number of view groups in the window. Returns the index of the currently selected group. Makes the given group active. Switches to the given view. Returns a list of the currently open folders. Runs the named WindowCommand with the (optional) given arguments. Shows a quick panel, to select an item in a list. on_done will be called once, with the index of the selected item. If the quick panel was cancelled, on_done will be called with an argument of -1. Items may be an array of strings, or an array of string arrays. In the latter case, each entry in the quick panel will show multiple rows. show_input_panel(caption, initial_text, on_done, on_change, on_cancel) View Shows the input panel, to collect a line of input from the user. on_done and on_change, if not None, should both be functions that expect a single string argument. on_cancel should be a function that expects no arguments. The view used for the input widget is returned.

get_output_panel(name)

View

Returns the view associated with the named output panel, created it if required. The output panel can be shown by running the show_panel window command, with the panel argument set to the name with an "output." prefix.

Class sublime.Settings
Methods
get(name) get(name, default) set(name, value) erase(name) has(name) add_on_change(key, on_change) clear_on_change(key)

Return Value
value value None None bool None None

Description
Returns the named setting. Returns the named setting, or default if it's not defined. Sets the named setting. Only primitive types, lists, and dictionaries are accepted. Removes the named setting. Does not remove it from any parent Settings. Returns true iff the named option exists in this set of Settings or one of its parents. Register a callback to be run whenever a setting in this object is changed. Remove all callbacks registered with the given key.

Module sublime_plugin
Methods
(no methods)

Return Value

Description

Class sublime_plugin.EventListener
Note that many of these events are triggered by the buffer underlying the view, and thus the method is only called once, with the first view as the parameter. Methods
on_new(view)

Return Value
None

Description
Called when a new buffer is created.

on_clone(view) on_load(view) on_close(view) on_pre_save(view) on_post_save(view) on_modified(view) on_selection_modified(view) on_activated(view) on_deactivated(view) on_query_context(view, key, operator, operand, match_all)

None None None None None None None None None bool or None

Called when a view is cloned from an existing one. Called when the file is finished loading. Called when a view is closed (note, there may still be other views into the same buffer). Called just before a view is saved. Called after a view has been saved. Called after changes have been made to a view. Called after the selection has been modified in a view. Called when a view gains input focus. Called when a view loses input focus. Called when determining to trigger a key binding with the given context key. If the plugin knows how to respond to the context, it should return either True of False. If the context is unknown, it should return None. operator is one of: sublime.OP_EQUAL. Is the value of the context equal to the operand? sublime.OP_NOT_EQUAL. Is the value of the context not equal to the operand? sublime.OP_REGEX_MATCH. Does the value of the context match the regex given in operand? sublime.OP_NOT_REGEX_MATCH. Does the value of the context not match the regex given in operand? sublime.OP_REGEX_CONTAINS. Does the value of the context contain a substring matching the regex given in operand? sublime.OP_NOT_REGEX_CONTAINS. Does the value of the context not contain a substring matching the regex given in operand? match_all should be used if the context relates to the selections: does every selection have to match (match_all = True), or is at least one matching enough (match_all = Fals)?

Class sublime plugin.ApplicationCommand

C ass sub

e_p ug . pp cat o Co
Methods

a d
Return Value
None bool

Description
Called when the command is run. Returns true if the command is able to be run at this time. The default implementation simply always returns True. Returns true if the command should be shown in the menu at this time. The default implementation always returns True. Returns a description of the command with the given arguments. Used in the menu, if no caption is provided. Return None to get the default description.

run(<args>) is_enabled(<args>)

is_visible(<args>)

bool

description(<args>)

String

Class sublime_plugin.WindowCommand
WindowCommands are instantiated once per window. The Window object may be retrieved via
self.window

Methods
run(<args>) is_enabled(<args>)

Return Value
None bool

Description
Called when the command is run. Returns true if the command is able to be run at this time. The default implementation simply always returns True. Returns true if the command should be shown in the menu at this time. The default implementation always returns True. Returns a description of the command with the given arguments. Used in the menu, if no caption is provided. Return None to get the default description.

is_visible(<args>)

bool

description(<args>)

String

Class sublime_plugin.TextCommand
TextCommands are instantiated once per view. The View object may be retrieved via self.view Methods
run(edit, <args>) is_enabled(<args>)

Return Value
None bool

Description
Called when the command is run. Returns true if the command is able to be run at this time The default

run at this time. The default implementation simply always returns True. is_visible(<args>) bool Returns true if the command should be shown in the menu at this time. The default implementation always returns True. Returns a description of the command with the given arguments. Used in the menus, and for Undo / Redo descriptions. Return None to get the default description.

description(<args>)

String