diff --git a/www.sublimetext.com/docs/3/api_reference.html b/www.sublimetext.com/docs/3/api_reference.html index 6958ca4..eabe95c 100644 --- a/www.sublimetext.com/docs/3/api_reference.html +++ b/www.sublimetext.com/docs/3/api_reference.html @@ -1,32 +1,52 @@ API Reference -Sublime API -View -Selection -Region -Edit -Window -Settings -Base Classes -EventListener -ApplicationCommand -WindowCommand -TextCommand +General Information +Example Plugins +Plugin Lifecycle +Threading +Types +Core Components +sublime Module +View Class +Selection Class +Region Class +Phantom Class +PhantomSet Class +Edit Class +Window Class +Settings Class +Plugin Extension Points +sublime_plugin Module +EventListener Class +ApplicationCommand Class +WindowCommand Class +TextCommand Class +General Information Example Plugins Several pre-made plugins come with Sublime Text, you can find them in the Default package: 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/exec.py Uses phantoms to display errors inline Packages/Default/font.py Shows how to work with settings +Packages/Default/goto_line.py Prompts the user for input, then updates the selection Packages/Default/mark.py Uses add_regions() to add an icon to the gutter +Packages/Default/show_scope_name.py Uses a popup to show the scope names at the caret Packages/Default/trim_trailing_whitespace.py Modifies a buffer just before its saved Plugin Lifecycle At importing time, plugins may not call any API functions, with the exception of sublime.version(), sublime.platform(), sublime.architecture() and sublime.channel(). If a plugin defines a module level function plugin_loaded(), this will be called when the API is ready to use. Plugins may also define plugin_unloaded(), to get notified just before the plugin is unloaded. Threading All API functions are thread-safe, however keep in mind that from the perspective of code running in an alternate thread, application state will be changing while the code is running. -Module sublime -MethodsReturn ValueDescription +Types +This documentation generally refers to simply Python data types. Some type names are classes documented herein, however there are also a few custom type names that refer to construct with specific semantics: +location: a tuple of (str, str, (int, int)) that contains information about a location of a symbol. The first string is the absolute file path, the second is the file path relative to the project, the third element is a two-element tuple of the row and column. +point: an int that represents the offset from the beginning of the editor buffer. The View methods text_point() and rowcol() allow converting to and from this format. +value: any of the Python data types bool, int, float, str, list or dict. +vector: a tuple of (float, float) representing x and y coordinates. +sublime Module +Methods +Return Value +Description set_timeout(callback, delay) None Runs the callback in the main thread after the given delay (in milliseconds). Callbacks with an equal delay will be run in the order they were added. @@ -43,29 +63,29 @@ bool Displays an ok / cancel question dialog to the user. If ok_title is provided, this may be used as the text on the ok button. Returns True if the user presses the ok button. yes_no_cancel_dialog(string, <yes_title>, <no_title>) -Int +int Displays a yes / no / cancel question dialog to the user. If yes_title and/or no_title are provided, they will be used as the text on the corresponding buttons on some platforms. Returns sublime.DIALOG_YES, sublime.DIALOG_NO or sublime.DIALOG_CANCEL. load_resource(name) -String +str Loads the given resource. The name should be in the format Packages/Default/Main.sublime-menu. load_binary_resource(name) bytes Loads the given resource. The name should be in the format Packages/Default/Main.sublime-menu. find_resources(pattern) -[String] +[str] Finds resources whose file name matches the given pattern. encode_value(value, <pretty>) -String +str Encode a JSON compatible value into a string representation. If pretty is set to True, the string will include newlines and indentation. decode_value(string) value Decodes a JSON string into an object. If the string is invalid, a ValueError will be thrown. expand_variables(value, variables) value -Expands any variables in the string value using the variables defined in the dictionary variables. value may also be an array or dict, in which case the structure will be recursively expanded. Strings should use snippet syntax, for example: expand_variables("Hello, ${name}", {"name": "Foo"}) +Expands any variables in the string value using the variables defined in the dictionary variables. value may also be a list or dict, in which case the structure will be recursively expanded. Strings should use snippet syntax, for example: expand_variables("Hello, ${name}", {"name": "Foo"}) load_settings(base_name) Settings -Loads the named settings. The name 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. +Loads the named settings. The name 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 base_name will return the same object, and not load the settings from disk again. save_settings(base_name) None Flushes any in-memory changes to the named settings object to disk. @@ -76,26 +96,26 @@ Window Returns the most recently used window. packages_path() -String -Returns the base path to the packages. +str +Returns the path where all the user's loose packages are located. installed_packages_path() -String -Returns the path where all the user's *.sublime-package files are. +str +Returns the path where all the user's .sublime-package files are located. cache_path() -String +str Returns the path where Sublime Text stores cache files. get_clipboard(<size_limit>) -String +str Returns the contents of the clipboard. size_limit is there to protect against unnecessarily large data, defaults to 16,777,216 characters set_clipboard(string) None Sets the contents of the clipboard. score_selector(scope, selector) -Int +int Matches the selector against the given scope, returning a score. A score of 0 means no match, above 0 means a match. Different selectors may be compared against the same scope: a higher score means the selector is a better match for the scope. run_command(string, <args>) None -Runs the named ApplicationCommand with the (optional) given arguments. +Runs the named ApplicationCommand with the (optional) given args. log_commands(flag) None Controls command logging. If enabled, all commands run from key bindings and the menu will be logged to the console. @@ -106,15 +126,15 @@ None Controls result regex logging. This is useful for debugging regular expressions used in build systems. version() -String +str Returns the version number platform() -String +str Returns the platform, which may be "osx", "linux" or "windows" arch() -String +str Returns the CPU architecture, which may be "x32" or "x64" -Class sublime.View +sublime.View Class 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. MethodsReturn ValueDescription id() @@ -124,49 +144,49 @@ int Returns a number that uniquely identifies the buffer underlying this view. file_name() -String +str The full name file the file associated with the buffer, or None if it doesn't exist on disk. name() -String +str The name assigned to the buffer, if any set_name(name) None Assigns a name to the buffer is_loading() bool -Returns true if the buffer is still loading from disk, and not ready for use. +Returns True if the buffer is still loading from disk, and not ready for use. is_dirty() bool -Returns true if there are any unsaved modifications to the buffer. +Returns True if there are any unsaved modifications to the buffer. is_read_only() bool -Returns true if the buffer may not be modified. +Returns True if the buffer may not be modified. set_read_only(value) None Sets the read only property on the buffer. is_scratch() bool -Returns true if the buffer is a scratch buffer. Scratch buffers never report as being dirty. +Returns True if the buffer is a scratch buffer. Scratch buffers never report as being dirty. set_scratch(value) None Sets the scratch property on the buffer. settings() Settings -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 view's settings object. Any changes to this settings object will be private to this view. window() Window Returns a reference to the window containing the view. run_command(string, <args>) None -Runs the named TextCommand with the (optional) given arguments. +Runs the named TextCommand with the (optional) given args. size() int Returns the number of character in the file. substr(region) -String +str Returns the contents of the region as a string. substr(point) -String +str Returns the character to the right of the point. insert(edit, point, string) int @@ -206,16 +226,16 @@ 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. classify(point) int -Classifies pt, returning a bitwise OR of zero or more of these flags: -CLASS_WORD_START -CLASS_WORD_END -CLASS_PUNCTUATION_START -CLASS_PUNCTUATION_END -CLASS_SUB_WORD_START -CLASS_SUB_WORD_END -CLASS_LINE_START -CLASS_LINE_END -CLASS_EMPTY_LINE +Classifies point, returning a bitwise OR of zero or more of these flags: +sublime.CLASS_WORD_START +sublime.CLASS_WORD_END +sublime.CLASS_PUNCTUATION_START +sublime.CLASS_PUNCTUATION_END +sublime.CLASS_SUB_WORD_START +sublime.CLASS_SUB_WORD_END +sublime.CLASS_LINE_START +sublime.CLASS_LINE_END +sublime.CLASS_EMPTY_LINE find_by_class(point, forward, classes, <separators>) Region Finds the next location after point that matches the given classes. If forward is False, searches backwards instead of forwards. classes is a bitwise OR of the sublime.CLASS_XXX flags. separators may be passed in, to define what characters should be considered to separate words. @@ -225,53 +245,44 @@ expand_by_class(region, classes, <separators>) Region Expands region to the left and right, until each side lands on a location that matches classes. classes is a bitwise OR of the sublime.CLASS_XXX flags. separators may be passed in, to define what characters should be considered to separate words. -find(pattern, fromPosition, <flags>) +find(pattern, start_point, <flags>) Region -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 the first region matching the regex pattern, starting from start_point, or None if it can't be found. The optional flags parameter may be sublime.LITERAL, sublime.IGNORECASE, or the two ORed together. find_all(pattern, <flags>, <format>, <extractions>) [Region] 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. rowcol(point) (int, int) -Calculates the 0 based line and column numbers of the point. +Calculates the 0-based line and column numbers of the point. text_point(row, col) int -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. +Calculates the character offset of the given, 0-based, row and col. Note that col is interpreted as the number of characters to advance past the beginning of the row. set_syntax_file(syntax_file) None 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'). extract_scope(point) Region -Returns the extent of the syntax name assigned to the character at the given point. +Returns the extent of the syntax scope name assigned to the character at the given point. scope_name(point) -String -Returns the syntax name assigned to the character at the given point. +str +Returns the syntax scope name assigned to the character at the given point. score_selector(point, selector) -Int -Matches the selector against the scope at the given location, returning a score. A score of 0 means no match, above 0 means a match. Different selectors may be compared against the same scope: a higher score means the selector is a better match for the scope. +int +Matches the selector against the scope at the given point, returning a score. A score of 0 means no match, above 0 means a match. Different selectors may be compared against the same scope: a higher score means the selector is a better match for the scope. find_by_selector(selector) -[Regions] +[Region] Finds all regions in the file matching the given selector, returning them as a list. -show(point, <show_surrounds>) -None -Scroll the view to show the given point. -show(region, <show_surrounds>) +show(location, <show_surrounds>) None -Scroll the view to show the given region. -show(region_set, <show_surrounds>) +Scroll the view to show the given location, which may be a point, Region or Selection. +show_at_center(location) None -Scroll the view to show the given region set. -show_at_center(point) -None -Scroll the view to center on the point. -show_at_center(region) -None -Scroll the view to center on the region. +Scroll the view to center on the location, which may be a point or Region. visible_region() Region Returns the currently visible area of the view. viewport_position() -Vector +vector Returns the offset of the viewport in layout coordinates. set_viewport_position(vector, <animate<) None @@ -295,29 +306,29 @@ point Converts a window position to a text position line_height() -real +float Returns the light height used in the layout em_width() -real +float Returns the typical character width used in the layout add_regions(key, [regions], <scope>, <icon>, <flags>) None 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 icon name may also be a full package relative path, such as Packages/Theme - Default/dot.png. 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_NO_FILL. Disable filling the regions, leaving only the outline. -sublime.DRAW_NO_OUTLINE. Disable drawing the outline of the regions. -sublime.DRAW_SOLID_UNDERLINE. Draw a solid underline below the regions. -sublime.DRAW_STIPPLED_UNDERLINE. Draw a stippled underline below the regions. -sublime.DRAW_SQUIGGLY_UNDERLINE. Draw a squiggly underline below the regions. -sublime.PERSISTENT. Save the regions in the session. -sublime.HIDDEN. Don't draw the regions. -The underline styles are exclusive, either zero or one of them should be given. If using an underline, DRAW_NO_FILL and DRAW_NO_OUTLINE should generally be passed in. +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_NO_FILL: Disable filling the regions, leaving only the outline. +sublime.DRAW_NO_OUTLINE: Disable drawing the outline of the regions. +sublime.DRAW_SOLID_UNDERLINE: Draw a solid underline below the regions. +sublime.DRAW_STIPPLED_UNDERLINE: Draw a stippled underline below the regions. +sublime.DRAW_SQUIGGLY_UNDERLINE: Draw a squiggly underline below the regions. +sublime.PERSISTENT: Save the regions in the session. +sublime.HIDDEN: Don't draw the regions. +The underline styles are exclusive, either zero or one of them should be given. If using an underline, sublime.DRAW_NO_FILL and sublime.DRAW_NO_OUTLINE should generally be passed in. get_regions(key) -[regions] +[Region] Return the regions associated with the given key, if any erase_regions(key) None @@ -326,13 +337,13 @@ None 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. get_status(key) -String +str Returns the previously assigned value associated with the key, if any. erase_status(key) None Clears the named status. command_history(index, <modifying_only>) -(String,Dict,int) +(str, dict, int) Returns the command name, command arguments, and repeat count for the given history entry, as stored in the undo / redo stack. 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. @@ -346,37 +357,37 @@ bool Folds the given region, returning False if it was already folded unfold(region) -[regions] +[Region] Unfolds all text in the region, returning the unfolded regions unfold([regions]) -[regions] +[Region] Unfolds all text in the regions, returning the unfolded regions encoding() -String +str Returns the encoding currently associated with the file set_encoding(encoding) None Applies a new encoding to the file. This encoding will be used the next time the file is saved. line_endings() -String +str Returns the line endings used by the current file. set_line_endings(line_endings) None Sets the line endings that will be applied when next saving. overwrite_status() -Bool +bool Returns the overwrite status, which the user normally toggles via the insert key. set_overwrite_status(enabled) None Sets the overwrite status. -symbols(line_endings) -[(Region, String)] +symbols() +[(Region, str)] Extract all the symbols defined in the buffer. show_popup_menu(items, on_done, <flags>) None Shows a pop up menu at the caret, to select an item in a list. on_done will be called once, with the index of the selected item. If the pop up menu was cancelled, on_done will be called with an argument of -1. -items is an array of strings. -flags currently only has no option. +items is a list of strings. +flags it currently unused. show_popup(content, <flags>, <location>, <max_width>, <max_height>, <on_navigate>, <on_hide>) None Shows a popup displaying HTML content. @@ -400,7 +411,7 @@ is_auto_complete_visible() bool Returns if the auto complete menu is currently visible. -Class sublime.Selection +sublime.Selection Class Maintains a set of Regions, ensuring that none overlap. The regions are kept in sorted order. MethodsReturn ValueDescription clear() @@ -409,16 +420,16 @@ add(region) None Adds the given region. It will be merged with any intersecting regions already contained within the set. -add_all(region_set) +add_all(regions) None -Adds all regions in the given set. +Adds all regions in the given list or tuple. subtract(region) None Subtracts the region from all regions in the set. contains(region) bool -Returns true iff the given region is a subset. -Class sublime.Region +Returns True iff the given region is a subset. +sublime.Region Class Represents an area of the buffer. Empty regions, where a == b are valid. ConstructorsDescription Region(a, b) @@ -445,7 +456,7 @@ Returns the number of characters spanned by the region. Always >= 0. empty() bool -Returns true iff begin() == end(). +Returns True iff begin() == end(). cover(region) Region Returns a Region spanning both this and the given regions. @@ -454,32 +465,57 @@ Returns the set intersection of the two regions. intersects(region) bool -Returns True iff this == region or both include one or more positions in common. +Returns True iff self == region or both include one or more positions in common. contains(region) bool Returns True iff the given region is a subset. contains(point) bool Returns True iff begin() <= point <= end(). -Class sublime.Edit -Edit objects have no functions, they exist to group buffer modifications. -Edit objects are passed to TextCommands, and are not user createable. Using an invalid Edit object, or an Edit object from a different view, will cause the functions that require them to fail. +sublime.Phantom Class +Represents an HTML-based decoration to display non-editable content interspersed in a View. Used with PhantomSet to actually add the +phantoms to the View. Once a Phantom has been constructed and added to the View, changes to the attributes will have no effect. +Constructors +Description +Phantom(region, content, layout, <on_navigate>) +Creates a phantom attached to a region. The content is HTML to be processed by minihtml. +layout must be one of: +sublime.LAYOUT_INLINE: Display the phantom in between the region and the point following. +sublime.LAYOUT_BELOW: Display the phantom in space below the current line, left-aligned with the region. +sublime.LAYOUT_BLOCK: Display the phantom in space below the current line, left-aligned with the beginning of the line. +on_navigate is an optional callback that should accept a single string parameter, that is the href attribute of the link clicked. +sublime.PhantomSet Class +A collection that manages Phantoms and the process of adding them, updating them and removing them from the View. +Constructors +Description +PhantomSet(view, <key>) +Creates a PhantomSet attached to a view. key is a string to group Phantoms together. MethodsReturn ValueDescription +update(phantoms) +None +phantoms should be a list of phantoms. +The .region attribute of each existing phantom in the set will be updated. New phantoms will be added to the view and phantoms not in phantoms list will be deleted. +sublime.Edit Class +Edit objects have no functions, they exist to group buffer modifications. +Edit objects are passed to TextCommands, and can not be created by the user. Using an invalid Edit object, or an Edit object from a different View, will cause the functions that require them to fail. +Methods +Return Value +Description (no methods) -Class sublime.Window +sublime.Window Class MethodsReturn ValueDescription id() int Returns a number that uniquely identifies this window. new_file() View -Creates a new file. The returned view will be empty, and its is_loaded method will return True. +Creates a new file. The returned view will be empty, and its is_loaded() method will return True. open_file(file_name, <flags>) View Opens the named file, and returns the corresponding view. If the file is already opened, it will be brought to the front. 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 +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 find_open_file(file_name) View Finds the named file in the list of open files, and returns the corresponding View, or None if no such file is open. @@ -508,7 +544,7 @@ None Switches to the given view. get_view_index(view) -(group, index) +(int, int) Returns the group, and index within the group of the view. Returns -1 if not found. set_view_index(view, group, index) None @@ -518,82 +554,61 @@ Show a message in the status bar. is_menu_visible() bool -Returns true if the menu is visible. +Returns True if the menu is visible. set_menu_visible(flag) None Controls if the menu is visible. is_sidebar_visible() bool -Returns true if the sidebar will be shown when contents are available. +Returns True if the sidebar will be shown when contents are available. set_sidebar_visible(flag) None Sets the sidebar to be shown or hidden when contents are available. get_tabs_visible() bool -Returns true if tabs will be shown for open files. +Returns True if tabs will be shown for open files. set_tabs_visible(flag) None Controls if tabs will be shown for open files. is_minimap_visible() bool -Returns true if the minimap is enabled. +Returns True if the minimap is enabled. set_minimap_visible(flag) None Controls the visibility of the minimap. is_status_bar_visible() bool -Returns true if the status bar will be shown. +Returns True if the status bar will be shown. set_status_bar_visible(flag) None Controls the visibility of the status bar. folders() -[String] +[str] Returns a list of the currently open folders. project_file_name() -String +str Returns name of the currently opened project file, if any. project_data() -Dictionary +dict Returns the project data associated with the current window. The data is in the same format as the contents of a .sublime-project file. set_project_data(data) None Updates the project data associated with the current window. If the window is associated with a .sublime-project file, the project file will be updated on disk, otherwise the window will store the data internally. run_command(string, <args>) None -Runs the named Command with the (optional) given arguments. Window.run_command is able to run both any sort of command, dispatching the command via input focus. -displayArgs is optional, and will default to the list given for args. -The optional flags parameter is a bitwise combination of: -sublime.QUICK_PANEL_FILES. Indicates that the args correspond to file names, which changes how they're drawn. -sublime.QUICK_PANEL_MULTI_SELECT. Enables Ctrl+Enter to select all displayed items in the quick panel, up to a maximum of 16. -sublime.QUICK_PANEL_NO_MULTI_SELECT_SAFETY_CHECK. Used in conjunction with the above, removes the 16 item limit. -sublime.QUICK_PANEL_UPDATE_ONLY. When asynchronously updating the panel, ignore the update call if the panel has been closed. -sublime.QUICK_PANEL_MONOSPACE_FONT. Use a monospace font to draw the quick panel. -showSelectPanel(displayArgs, onSelect, onCancel, flags, <key>, <selectedIndex>) -None -Shows the quick panel, populated with displayArgs. -onSelect will be run for each item selected, with the index of the item passed in as a parameter. -onCancel will be run if the panel is closed without any items being selected. -The flags parameter should be 0, or a bitwise combination of: -sublime.SELECT_PANEL_FILES. Indicates that the args correspond to file names, which changes how they're drawn. -sublime.SELECT_PANEL_MULTI_SELECT. Enables Ctrl+Enter to select all displayed items in the quick panel, up to a maximum of 16. -sublime.SELECT_PANEL_NO_MULTI_SELECT_SAFETY_CHECK. Used in conjunction with the above, removes the 16 item limit. -sublime.SELECT_PANEL_UPDATE_ONLY. When asynchronously updating the panel, ignore the update call if the panel has been closed. -sublime.SELECT_PANEL_MONOSPACE_FONT. Use a monospace font to draw the quick panel. -key should be used if updating the list asynchronously, or left blank otherwise. -selectedIndex should be the index of the item to be initially selected, or omitted otherwise. ---> +Runs the named WindowCommand with the (optional) given args. This method is able to run any sort of command, dispatching the command via input focus. show_quick_panel(items, on_done, <flags>, <selected_index>, <on_highlighted>) None 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. -Flags is a bitwise OR of sublime.MONOSPACE_FONT and sublime.KEEP_OPEN_ON_FOCUS_LOST +items may be a list of strings, or a list of string lists. In the latter case, each entry in the quick panel will show multiple rows. +flags is a bitwise OR of sublime.MONOSPACE_FONT and sublime.KEEP_OPEN_ON_FOCUS_LOST on_highlighted, if given, will be called every time the highlighted item in the quick panel is changed. 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. create_output_panel(name, <unlisted>) View -Returns the view associated with the named output panel, creating 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. +Returns the view associated with the named output panel, creating 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. The optional unlisted parameter is a boolean to control if the output panel should be listed in the panel switcher. find_output_panel(name) View or None @@ -602,48 +617,47 @@ None Destroys the named output panel, hiding it if currently open. active_panel() -string or None +str or None Returns the name of the currently open panel, or None if no panel is open. Will return built-in panel names (e.g. "console", "find", etc) in addition to output panels. panels() -[string] +[str] Returns a list of the names of all panels that have not been marked as unlisted. Includes certain built-in panels in addition to output panels. lookup_symbol_in_index(symbol) -[Location] +[location] Returns all locations where the symbol is defined across files in the current project. lookup_symbol_in_open_files(symbol) -[Location] +[location] Returns all locations where the symbol is defined across open files. extract_variables() -Dictionary +dict Returns a dictionary of strings populated with contextual keys: -packages, platform, file, file_path, file_name, file_base_name, file_extension, folder, project, project_path, project_name, project_base_name, project_extension. This dictionary is suitable for passing to sublime.expand_variables(). -Class sublime.Settings -MethodsReturn ValueDescription -get(name) -value -Returns the named setting. -get(name, default) +packages, platform, file, file_path, file_name, file_base_name, file_extension, folder, project, project_path, project_name, project_base_name, project_extension. This dict is suitable for passing to sublime.expand_variables(). +sublime.Settings Class +Methods +Return Value +Description +get(name, <default>) value -Returns the named setting, or default if it's not defined. +Returns the named setting, or default if it's not defined. If not passed, default will have a value of None. set(name, value) None -Sets the named setting. Only primitive types, lists, and dictionaries are accepted. +Sets the named setting. Only primitive types, lists, and dicts are accepted. erase(name) None Removes the named setting. Does not remove it from any parent Settings. has(name) bool -Returns true iff the named option exists in this set of Settings or one of its parents. +Returns True iff the named option exists in this set of Settings or one of its parents. add_on_change(key, on_change) None Register a callback to be run whenever a setting in this object is changed. clear_on_change(key) None Remove all callbacks registered with the given key. -Module sublime_plugin +sublime_plugin Module MethodsReturn ValueDescription (no methods) -Class sublime_plugin.EventListener +sublime_plugin.EventListener Class 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. MethodsReturn ValueDescription on_new(view) @@ -707,10 +721,10 @@ None Called when a view loses input focus. Runs in a separate thread, and does not block the application. on_text_command(view, command_name, args) -(new_command_name, new_args) +(str, dict) Called when a text command is issued. The listener may return a (command, arguments) tuple to rewrite the command, or None to run the command unmodified. on_window_command(window, command_name, args) -(new_command_name, new_args) +(str, dict) Called when a window command is issued. The listener may return a (command, arguments) tuple to rewrite the command, or None to run the command unmodified. post_text_command(view, command_name, args) None @@ -722,39 +736,39 @@ bool or None 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 = False)? +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 == False)? on_hover(view, point, hover_zone) None Called when the user's mouse hovers over a view for a short period. point is the closest point in the view to the mouse location. The mouse may not actually be located adjacent based on the value of hover_zone: -sublime.HOVER_TEXT. When the mouse is hovered over text. -sublime.HOVER_GUTTER. When the mouse is hovered over the gutter. -sublime.HOVER_MARGIN. When the mouse is hovered in whitespace to the right of a line. -Class sublime_plugin.ApplicationCommand +sublime.HOVER_TEXT: When the mouse is hovered over text. +sublime.HOVER_GUTTER: When the mouse is hovered over the gutter. +sublime.HOVER_MARGIN: When the mouse is hovered in whitespace to the right of a line. +sublime_plugin.ApplicationCommand Class MethodsReturn ValueDescription run(<args>) None Called when the command is run. is_enabled(<args>) bool -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 is able to be 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 True if the command should be shown in the menu at this time. The default implementation always returns True. is_checked(<args>) bool -Returns true if a checkbox should be shown next to the menu item. The .sublime-menu file must have the checkbox attribute set to true for this to be used. +Returns True if a checkbox should be shown next to the menu item. The .sublime-menu file must have the checkbox attribute set to true for this to be used. description(<args>) -String +str 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. -Class sublime_plugin.WindowCommand +sublime_plugin.WindowCommandClass WindowCommands are instantiated once per window. The Window object may be retrieved via self.window MethodsReturn ValueDescription run(<args>) @@ -762,14 +776,14 @@ Called when the command is run. is_enabled(<args>) bool -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 is able to be 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 True if the command should be shown in the menu at this time. The default implementation always returns True. description(<args>) -String +str 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. -Class sublime_plugin.TextCommand +sublime_plugin.TextCommand Class TextCommands are instantiated once per view. The View object may be retrieved via self.view MethodsReturn ValueDescription run(edit, <args>) @@ -777,12 +791,12 @@ Called when the command is run. is_enabled(<args>) bool -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 is able to be 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 True if the command should be shown in the menu at this time. The default implementation always returns True. description(<args>) -String +str 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. want_event() bool diff --git a/www.sublimetext.com/docs/3/auto_complete.html b/www.sublimetext.com/docs/3/auto_complete.html index d5e0ffc..d329694 100644 --- a/www.sublimetext.com/docs/3/auto_complete.html +++ b/www.sublimetext.com/docs/3/auto_complete.html @@ -3,11 +3,11 @@ Auto Complete Auto complete shows the completion popup as you type, so you can fill in long words by typing only a few characters. It's enabled by default for source code and HTML (but only after entering a < character). Disabling Auto Complete -Auto complete can be disabled with the auto_complete setting. To disable it, add this line to Preferences/File Settings - User: +Auto complete can be disabled with the auto_complete setting. To disable it, add this line to the right-hand pane of Preferences/Settings: "auto_complete": false If auto complete is disabled, the completion popup can be shown manually, or tab can be used to insert the highest ranking completion without showing the popup. Manually Showing Completions -Pressing Ctrl+Space will show the completion popup if it's not currently showing. If it is showing, it'll select the next item. +Pressing ctrl+space will show the completion popup if it's not currently showing. If it is showing, it'll select the next item. Commit on Tab By default, the selected item in the completion popup will be committed when enter is pressed. This can create ambiguity between committing the completion, and inserting a newline. By setting the auto_complete_commit_on_tab setting to true, enter will insert a newline, and tab will commit the current completion. There are other benefits, too: because Sublime Text knows there is no ambiguity, it will show a more curated list of completions, with the one you want more likely to be in first place. Enabling Commit on Tab is recommended, but it will take a short time to get used to. diff --git a/www.sublimetext.com/docs/3/distraction_free.html b/www.sublimetext.com/docs/3/distraction_free.html index a9969a1..4fa80dd 100644 --- a/www.sublimetext.com/docs/3/distraction_free.html +++ b/www.sublimetext.com/docs/3/distraction_free.html @@ -13,5 +13,5 @@ "word_wrap": true, "scroll_past_end": true } -You can customize these via editing Packages/User/Distraction Free.sublime-settings, which is accessible via the Preferences/File Settings - More menu. +You can customize these via editing Packages/User/Distraction Free.sublime-settings, which is accessible via the Preferences/Settings – Distraction Free menu item. It's worth noting the wrap_width setting, above. The value of 80 causes wrapping to happen at 80 characters. You may want to set this to a higher value, or wrap to the window width, by setting it to 0. diff --git a/www.sublimetext.com/docs/3/font.html b/www.sublimetext.com/docs/3/font.html index 585d764..4a9f8a2 100644 --- a/www.sublimetext.com/docs/3/font.html +++ b/www.sublimetext.com/docs/3/font.html @@ -1,8 +1,8 @@ Font Settings -Changing the font can be done via adding these lines to Preferences/Settings - User: +Changing the font can be done via adding these lines to the right-hand pane of Preferences/Settings: "font_face": "Courier New", "font_size": 10 and then change as desired. The font will change when you save. -You can see other settings to change by browsing through Preferences/Settings - Default. There are many things that can be customized in Sublime Text. +You can see other settings to change by browsing through the left-hand pane of Preferences/Settings. There are many things that can be customized in Sublime Text. diff --git a/www.sublimetext.com/docs/3/indentation.html b/www.sublimetext.com/docs/3/indentation.html index ea9456e..34d3e4c 100644 --- a/www.sublimetext.com/docs/3/indentation.html +++ b/www.sublimetext.com/docs/3/indentation.html @@ -1,7 +1,7 @@ Indentation Settings -Indentation Settings determine the size of the tab stops, and control whether the tab key should insert tabs or spaces. In addition to the automatic detection, they can be customized globally, per-file type, or per-file. +Indentation settings determine the size of the tab stops, and control whether the tab key should insert tabs or spaces. In addition to the automatic detection, they can be customized globally, per-file type, or per-file. Settings tab_size Integer. The number of spaces a tab is considered equal to @@ -19,14 +19,8 @@ Packages/<syntax>/<syntax>.sublime-settings Packages/User/<syntax>.sublime-settings In general, you should place your settings in Packages/User/Preferences.sublime-settings. If you want to specify settings for a certain file type, for example, Python, you should place them in Packages/User/Python.sublime-settings. -Example Settings File -Try saving this as Packages/User/Preferences.sublime-settings -{ -"tab_size": 4, -"translate_tabs_to_spaces": false -} Per-syntax Settings -Settings may be specified on a per-syntax basis. You can edit the settings for the current syntax using the Preferences/Settings - More/Syntax Specific - User menu. +Settings may be specified on a per-syntax basis. You can edit the settings for the current syntax using the Preferences/Settings – Syntax Specific menu. Indentation Detection When a file is loaded, its contents are examined, and the tab_size and translate_tabs_to_spaces settings are set for that file. The status area will report when this happens. While this generally works well, you may want to disable it. You can do that with the detect_indentation setting. Indentation detection can be run manually via the View/Indentation/Guess Settings From Buffer menu, which runs the detect_indentation command. diff --git a/www.sublimetext.com/docs/3/index.html b/www.sublimetext.com/docs/3/index.html index 38f305f..1a950a4 100644 --- a/www.sublimetext.com/docs/3/index.html +++ b/www.sublimetext.com/docs/3/index.html @@ -1,8 +1,9 @@ Sublime Text 3 Documentation +Website +Forum Sublime Text 3 Documentation -General -Sublime Text Unofficial Documentation is an excellent resource, with a huge amount of information on Sublime Text. +The following pages contain the official documentation for Sublime Text 3. The Sublime Text Unofficial Documentation is an excellent supplementary resource, with a huge amount of information not covered in the official documentation. Usage Column Selection Multiple Selection with the Keyboard @@ -17,11 +18,13 @@ Indentation Spell Checking Packages -Syntax Miscellaneous Reverting to a Freshly Installed State OS X Command Line -API +Package Development API Reference +Syntax Definitions +Scope Naming +minihtml Reference Porting Guide How to Create a Sublime Text Plugin diff --git a/www.sublimetext.com/docs/3/minihtml.html b/www.sublimetext.com/docs/3/minihtml.html new file mode 100644 index 0000000..d11a5f6 --- /dev/null +++ b/www.sublimetext.com/docs/3/minihtml.html @@ -0,0 +1,173 @@ + + +minihtml Reference +Sublime Text contains a custom HTML and CSS engine, named +minihtml, for displaying stylized +content in editor panes. HTML content can be displayed in both +popup windows and phantoms. +minihtml provides a limited subset of +HTML and CSS features found in most web browsers. While only +certain CSS and HTML features may be implemented, they are designed +to be standards compliant. Any feature implemented should function +the same way in minihtml as in a +browser. +HTML +The following tags are styled by the default style sheet: +<html> +<head>, <style> +<body> +<h1>, +<h2>, +<h3>, +<h4>, +<h5>, +<h6> +<div> +<p> +<ul>, +<ol>, +<li> +<b>, <strong> +<i>, <em> +<u> +<big>, <small> +<a> +<code>, +<var>, +<tt> +Special behavior is implemented for a few tags: +<a> – a callback can be specified via the +API to handle clicks on anchor tags +<img> – supports PNG, JPG and GIF images +from http://, file://, +res:// and data: URLs +<ul> – bullets are displayed for +<li> tags +Other HTML tags with special behavior are not implemented. This +includes tags such as <input>, +<button>, <table>, etc. +Best Practices +To allow color scheme authors to tweak the look of popups and +phantoms, it is best to add a unique id="" +attribute to the <body> tag of your plugin's +HTML. +Within the <body> tag, add a +<style> tag containing selectors that do not +use the id. Leave that for selectors in color schemes +to be able to override the plugin. +<body id="my-plugin-feature"> +<style> +div.error { +background-color: red; +padding: 5px; +} +</style> +<div class="error"></div> +</body> +CSS +The following list provides an overview of supported properties and +values: +display: inline, +block, list-item, +none +margin: positive +units +margin-top: positive +units +margin-right: positive +units +margin-bottom: positive +units +margin-left: positive +units +position: static, +relative +top: positive and negative +units +right: positive and negative +units +bottom: positive and negative +units +left: positive and negative +units +background-color: colors +font-family: +comma-separated list of font families +font-size: positive +units +font-style: normal, +italic +font-weight: normal, +bold +line-height: positive +units +text-decoration: none, +underline +color: colors +padding: positive +units +padding-top: positive +units +padding-right: positive +units +padding-bottom: positive +units +padding-left: positive +units +border-radius: positive +units +border-top-left-radius: positive +units +border-top-right-radius: positive +units +border-bottom-right-radius: positive +units +border-bottom-left-radius: positive +units +Units +Supported units of measurement include: +rem +em +px +pt +rem units are recommended because they are based on the +user's font_size setting, and they will not cascade. +Colors +Colors may be specified via: +Named colors: white, tan, etc +Shorthand hex: #fff +Shorthand hex with alpha: #fff8 +Full hex: #ffffff +Full hex with alpha: #ffffff80 +RGB functional notation: rgb(255, 255, 255) +RGBA functional notation: rgba(255, 255, 255, 0.5) +HSL functional notation: hsl(0, 100%, 100%) +HSLA functional notation: hsla(0, 100%, 100%, 0.5) +transparent +Additionally, color values may be blended using the CSS Color Module Level 4 color-mod function with the blend() and blenda() adjusters. +.error { +background-color: color(var(--background) blend(red, 50%)); +} +The color-mod function will be most useful in combination with variables. +Variables +CSS variables are also supported using custom properties and the var() functional notation. Custom properties are those starting with --. +html { +--fg: #f00; +} +.error { +background-color: var(--fg); +} +The one limitation is that the var() notation can not be used for part of a multi-number value, such as padding or margin. With those aggregate properties, the var() notation must be used for the complete value. +Predefined Variables +When a color scheme is loaded, the background and foreground colors are set to CSS variables, along with the closest color found to a handful of basic colors. These are all set in an html { } rule set in the default CSS style sheet. +var(--background) +var(--foreground) +var(--redish) +var(--orangish) +var(--yellowish) +var(--greenish) +var(--bluish) +var(--purplish) +var(--pinkish) +The algorithm to pick the colors uses the HSL color space and uses several heuristics to try and pick colors that are suitable for foreground use. In the case that the automatic color selection is undesirable, color scheme authors may override the appropriate values with their own html { } rule set contained in the +popupCss or phantomCss settings. diff --git a/www.sublimetext.com/docs/3/packages.html b/www.sublimetext.com/docs/3/packages.html index e0f57a1..42e2c4c 100644 --- a/www.sublimetext.com/docs/3/packages.html +++ b/www.sublimetext.com/docs/3/packages.html @@ -1,7 +1,7 @@ Packages -Packages are a collection of resource files used by Sublime Text: plugins, syntax highlighting definitions, menus, snippets and more. Sublime Text ships with several packages, and more user created ones are available +Packages are a collection of resource files used by Sublime Text: plugins, syntax highlighting definitions, menus, snippets and more. Sublime Text ships with several packages, and more user created ones are available. Packages are stored in .sublime-package files, which are zip files with a different extension. Packages may also be stored unzipped within a directory, or a mix of the two: any loose files in the package directory will override files stored in the .sublime-package file. Locations Zipped packages may be stored in: diff --git a/www.sublimetext.com/docs/3/porting_guide.html b/www.sublimetext.com/docs/3/porting_guide.html index 1aaffe1..7bfb94d 100644 --- a/www.sublimetext.com/docs/3/porting_guide.html +++ b/www.sublimetext.com/docs/3/porting_guide.html @@ -13,25 +13,25 @@ Out of Process Plugins Plugins are now run in a separate process, plugin_host. From a plugin authors perspective, there should be no observable difference, except that a crash in the plugin host will no longer bring down the main application. Asynchronous Events -In Sublime Text 2, only the set_timeout method was thread-safe. In Sublime Text 3, every API method is thread-safe. Furthermore, there are now asynchronous event handlers, to make writing non-blocking code easier: -on_modified_async -on_selection_modified_async -on_pre_save_async -on_post_save_async -on_activated_async -on_deactivated_async -on_new_async -on_load_async -on_clone_async -set_timeout_async +In Sublime Text 2, only the set_timeout() method was thread-safe. In Sublime Text 3, every API method is thread-safe. Furthermore, there are now asynchronous event handlers, to make writing non-blocking code easier: +on_modified_async() +on_selection_modified_async() +on_pre_save_async() +on_post_save_async() +on_activated_async() +on_deactivated_async() +on_new_async() +on_load_async() +on_clone_async() +set_timeout_async() When writing threaded code, keep in mind that the buffer will be changing underneath you as your function runs. Restricted begin_edit() and end_edit() -begin_end() and end_edit() are no longer directly accessible, except in some special circumstances. The only way to get a valid instance of an Edit object is to place your code in a TextCommand subclass. In general, most code can be refactored by placing the code between begin_edit() and end_edit() in a TextCommand, and then calling run_command on that TextCommand. +begin_end() and end_edit() are no longer directly accessible, except in some special circumstances. The only way to get a valid instance of an Edit object is to place your code in a TextCommand subclass. In general, most code can be refactored by placing the code between begin_edit() and end_edit() in a TextCommand, and then running the command via run_command(). This approach removes the issue of dangling Edit objects, and ensures the repeat command and macros work as they should. Zipped Packages Packages in Sublime Text 3 are able to be run from .sublime-package (i.e., renamed .zip files) files directly, in contrast to Sublime Text 2, which unzipped them prior to running. While in most changes this should lead to no differences, it is important to keep this in mind if you are accessing files in your package. Importing Modules -Importing other Plugins is simpler and more robust in Sublime Text 3, and can be done with a regular import statement, e.g., import Default.comment will import Packages/Default/Comment.py +Importing other plugins is simpler and more robust in Sublime Text 3, and can be done with a regular import statement, e.g., import Default.comment will import Packages/Default/Comment.py. Restricted API Usage at Startup -Due to the plugin_host loading asynchronously, it is not possible to use the Sublime Text API at import time. This means that all top-level statements in your module must not call any functions from the sublime module. During startup, the API is in a dormant state, and will silently ignore any requests made. +Due to the plugin_host loading asynchronously, it is not possible to use the API at import time. This means that all top-level statements in your module must not call any functions from the sublime module. During startup, the API is in a dormant state, and will silently ignore any requests made. diff --git a/www.sublimetext.com/docs/3/projects.html b/www.sublimetext.com/docs/3/projects.html index 54c2887..c18fccf 100644 --- a/www.sublimetext.com/docs/3/projects.html +++ b/www.sublimetext.com/docs/3/projects.html @@ -1,10 +1,10 @@ Projects -Projects in Sublime Text are made up of two files: the sublime-project file, which contains the project definition, and the sublime-workspace file, which contains user specific data, such as the open files and the modifications to each. -As a general rule, the sublime-project file would be checked into version control, while the sublime-workspace file would not. +Projects in Sublime Text are made up of two files: the .sublime-project file, which contains the project definition, and the .sublime-workspace file, which contains user specific data, such as the open files and the modifications to each. +As a general rule, the .sublime-project file would be checked into version control, while the .sublime-workspace file would not. Project Format -sublime-project files are JSON, and support three top level sections: folders, for the included folders, settings, for file-setting overrides, and build_systems, for project specific build systems. An example: +.sublime-project files are JSON, and support three top level sections: folders, for the included folders, settings, for file-setting overrides, and build_systems, for project specific build systems. An example: { "folders": [ @@ -35,6 +35,6 @@ Each folder must have a path, and may optionally have settings file_exclude_patterns, file_include_patterns, folder_exclude_patterns, folder_include_patterns and follow_symlinks. The path may be relative to the project directory, or a fully qualified path. Folders may also be given a name setting, to set how they're displayed on the side bar. Converted projects from earlier versions may have a mount_points entry under folders. If you wish to use the exclude patterns, you'll need to change to the above format. Settings -Settings may be specified here using the settings key, and will override regular user settings. Note that they will not override syntax specific settings. +Settings may be specified here using the settings key, and will override regular user settings. Note that they will not override syntax-specific settings. Build Systems -Build Systems specifices an array of inline Build Systems definitions. In addition to the regular build system settings, a name must be specified for each one. Build Systems listed here will be available via the regular Tools/Build Systems menu. +build_systems specifices a list of inline Build Systems definitions. In addition to the regular build system settings, a name must be specified for each one. Build systems listed here will be available via the regular Tools/Build Systems menu. diff --git a/www.sublimetext.com/docs/3/revert.html b/www.sublimetext.com/docs/3/revert.html index 44280e4..fe1ffa4 100644 --- a/www.sublimetext.com/docs/3/revert.html +++ b/www.sublimetext.com/docs/3/revert.html @@ -7,10 +7,10 @@ Linux: ~/.config/sublime-text-3 To revert to a freshly installed state, you can: Exit Sublime Text -Delete (or move) the data folder, as listed above +Move the data folder to a backup location Start Sublime Text -When restarted, a fresh data folder will be created, just as it was the first time you ran Sublime Text. Keep in mind that this will also remove all of your settings and packages. -OS X Lion -In Lion, the ~/Library folder is hidden by default. To navigate there, select the Go/Go to Folder menu item in Finder, and type in ~/Library. +When restarted, a fresh data folder will be created, just as it was the first time you ran Sublime Text. Keep in mind that this will also remove all of your settings and packages. The backup copy of your data folder can be used to retrieve configuration, or custom packages that can not be reinstalled. +OS X +On OS X, the ~/Library folder is hidden by default. To navigate there, select the Go/Go to Folder menu item in Finder, and type in ~/Library. Windows In Windows, cache files are stored in a separate location, %LOCALAPPDATA%\Sublime Text 3, to improve performance with roaming profiles. diff --git a/www.sublimetext.com/docs/3/scope_naming.html b/www.sublimetext.com/docs/3/scope_naming.html new file mode 100644 index 0000000..bae9189 --- /dev/null +++ b/www.sublimetext.com/docs/3/scope_naming.html @@ -0,0 +1,273 @@ + + +Scope Naming +Syntax definitions and color schemes in Sublime Text interact through the use of scope names. Scopes are dotted strings, specified from least-to-most specific. For example, the if keyword in PHP could be specified via the scope name keyword.control.php. +Sublime Text supports TextMate language grammars, and inherited its default syntaxes from various open-source bundles. The TextMate language grammar documentation provided a base set of scope names that have been slowly expanded and changed by the community. +This is a living document that attempts to document best practices for using scope names in syntax definitions and color schemes. All of the Sublime Text default packages strive to adhere to these recommendations. +Usage in Syntax Definitions +The scopes documented below are a recommended base set of scope names to use when creating a syntax definition. +In this documentation, the syntax name is omitted from the end of the dotted scope name. When writing a syntax, unless otherwise noted, the syntax name should be the final segment of a dotted name. For example, a control keyword in Ruby would be keyword.control.ruby, whereas in Python it would be keyword.control.python. +It is an on-going process to improve and expand upon the default syntaxes that are shipped with Sublime Text. As of mid-2016, the following syntaxes have been recently re-worked, and may be used as a reference: +CSS +Go +HTML +PHP +Rust +Top-Level Scope Index +The following, top-level, list of scopes is sorted alphabetically. It is recommended to read through the entire list at least once before writing or modifying a syntax. +comment. +constant. +entity. +invalid. +keyword. +markup. +meta. +punctuation. +source. +storage. +string. +support. +text. +variable. +comment. +Single and multi-line comments should use, respectively: +comment.line +comment.block +Multi-line comments used as documentation, such as Javadoc or PhpDoc, should use: +comment.block.documentation +Symbols that delineate a comment, e.g. // or /*, should additionally use: +punctuation.definition.comment +Comments with special syntax that denote a section of code, should use the following scope on the text only. This will cause it to be shown in the symbol list. +meta.toc-list +constant. +Numeric literals, including integers, floats, etc. should use one of: +constant.numeric +constant.numeric.integer +constant.numeric.float +constant.numeric.hex +constant.numeric.octal +Constants that are built into the language, such as booleans and null values, should use: +constant.language +Character escapes in strings, e.g. \n and \x20, should use: +constant.character.escape +Formatting placeholders, such as those used for sprintf(), e.g. %s, should use: +constant.other.placeholder +Other language-specific constant values, such as symbols in Ruby, should use: +constant.other +entity. +The entity scopes are generally assigned to the names of data structures, types and other uniquely-identifiable constructs in code and markup. The notable exceptions are entity.name.tag and entity.other.attribute-name, which are used in HTML and XML tags. +The names of data structures will use one of the following scopes, or a new sub-scope of entity.name – this list is not exhaustive. To provide rich semantic information, use the specific terminology for a given language construct. +Avoid entity.name.type.class and entity.name.type.struct which unnecessarily nest scope labels under type. +entity.name.class +entity.name.struct +entity.name.enum +entity.name.union +entity.name.trait +entity.name.interface +entity.name.type +forward-decl variants of the above are used in languages such as C and C++. Such scopes can be used to exclude identifiers from the symbol list and indexing. +entity.name.class.forward-decl +Class, interface and trait names listed as an inherited class or implemented interface/trait should use: +entity.other.inherited-class +Function names receive one of the following scopes. These are included in the symbol list and index. +entity.name.function +entity.name.function.constructor +entity.name.function.destructor +Namespaces, packages and modules use the following scope. There are usually not multiple types of such constructs in a language, so this scope should suffice. +entity.name.namespace +Constants should use the following scope or variable.other.constant, depending on the language semantics. This scope is often included in the symbol list and index. +entity.name.constant +Labels for goto-like constructs should use: +entity.name.label +Heading names in markup languages, such as Markdown and Textile, should use: +entity.name.section +HTML and XML tags should use the following scope. This is the only entity.name scope that is applied to repeated constructs. +entity.name.tag +HTML, CSS and XML use the following for tag attribute names: +entity.other.attribute-name +invalid. +Elements that are illegal in a specific context should use the following scope. Overuse of this will likely lead to unpleasant highlighting for users as they edit code. +invalid.illegal +Deprecated elements should be scoped using the following scope. This should be very rarely used, as users may be working with older versions of a language. +invalid.deprecated +keyword. +Control keywords examples include if, try, end and while. Some syntaxes prefer to mark if and else with the conditional variant. The import variant is often used in appropriate situations. +keyword.control +keyword.control.conditional +keyword.control.import +Keywords that contain punctuation, such as the @ symbol in CSS, add the following scope to the symbols: +punctuation.definition.keyword +All remaining non-operator keywords fall under the other variant: +keyword.other +Operators are typically symbols, so the term keyword can seem somewhat contradictory. Specific variants are sometimes referenced based on the type of operator. +keyword.operator +keyword.operator.assignment +keyword.operator.arithmetic +keyword.operator.bitwise +keyword.operator.logical +When the operator is a word, such as and, or or not, the following variant is used: +keyword.operator.word +markup. +Markup scopes are used for content, as opposed to code. This includes syntaxes such as Markdown and Textile. +Section headings should use: +markup.heading +Lists should use one of: +markup.list.unnumbered +markup.list.numbered +Basic text styling should use one of: +markup.bold +markup.italic +markup.underline +Inserted and deleted content, such as with diff output, should use: +markup.inserted +markup.deleted +Links should use: +markup.underline.link +Blockquotes and other quote styles should use: +markup.quote +Inline and block literal quoting, often used for code, should use: +markup.raw.inline +markup.raw.block +Other markup, including constructs such as footnotes and tables, should use: +markup.other +meta. +Meta scopes are used to scope larger sections of code or markup, generally containing multiple, more specific scopes. These are not intended to be styled by a color scheme, but used by preferences and plugins. +The complete contents of data structures should be scoped using one of the following scopes. Similar to entity.name, they should be customized per language to provide rich semantic information. They should include all elements, such as the name, inheritance details and body. +meta.class +meta.struct +meta.enum +meta.union +meta.trait +meta.interface +meta.type +The entire scope of a function should be covered by one of the following scopes. Each variant should be applied to a specific part, and not stacked. For example, meta.function.php meta.function.parameters.php should never occur, but instead the scopes should alternate between meta.function.php then meta.function.parameters.php and back to meta.function.php. +meta.function +meta.function.parameters +meta.function.return-type +The entirety of a namespace, module or package should use: +meta.namespace +Preprocessor statements in language such as C should use: +meta.preprocessor +Complete identifiers, including namespace names, should use the following scope. Such identifiers are the fully-qualified forms of variable, function and class names. For example, in C++ a path may look like myns::myclass, whereas in PHP it would appears such as \MyNS\MyClass. +meta.path +Function names, including the full path, and all parameters should receive the following scope. The name of the function or method should be variable.function, unless the function is scoped with support.function. +meta.function-call +Sections of code delineated by curly braces should use one the following meta scopes, based on appropriate semantics. The { and } characters should additionally use the punctuation scopes. +meta.block +punctuation.section.block.begin +punctuation.section.block.end +meta.braces +punctuation.section.braces.begin +punctuation.section.braces.end +Sections of code delineated by parentheses should use one the following meta scopes, based on appropriate semantics. The ( and ) characters should additionally use the punctuation scopes. +meta.group +punctuation.section.group.begin +punctuation.section.group.end +meta.parens +punctuation.section.parens.begin +punctuation.section.parens.end +Sections of code delineated by square brackets should use the following scope. The [ and ] characters should additionally use the punctuation scopes. +meta.brackets +punctuation.section.brackets.begin +punctuation.section.brackets.end +Generic data type constructs should use the following scope. Any symbols that denote the beginning and end, such as < and >, should additionally use the punctuation scopes. +meta.generic +punctuation.definition.generic.begin +punctuation.definition.generic.end +HTML and XML tags, including punctuation, names and attributes should use the following: +meta.tag +Paragraphs in markup languages use: +meta.paragraph +punctuation. +The following scopes are punctuation scopes that are not embedded within other scopes. For instance, the string. section includes documentation about scopes for string punctuation. +Separators such as commas and colons should use: +punctuation.separator +Semicolons or other statement terminators should use: +punctuation.terminator +Line-continuation characters, such as in Python and R, should use: +punctuation.separator.continuation +Member access, scope resolution, or similar constructs should use the following scope. For Python or JavaScript this would be .. In PHP this would be applied to -> and ::. In C++, this would be applied to all three. +punctuation.accessor +source. +A language-specific variant of the following scope is typically applied to the entirety of a source code file: +source +storage. +Types and definition/declaration keywords should use the following scope. Examples include int, bool, char, func, function, class and def. Depending on the language and semantics, const may be this or storage.modifier. +storage.type +Keywords that affect the storage of a variable, function or data structure should use the following scope. Examples include static, inline, const, public and private. +storage.modifier +string. +Basic strings use the one of the following scopes, based on the type of quotes used: +string.quoted.single +string.quoted.double +string.quoted.triple +Strings that used unconventional quotes, such as < and > with C imports, should use: +string.quoted.other +Punctuation at the beginning and end of strings should use: +punctuation.definition.string.begin +punctuation.definition.string.end +Unquoted strings, such as in Shell and Batch File, should use: +string.unquoted +Regular expression literals should use: +string.regexp +support. +Elements provided by a base framework should use one of the following scopes. Examples include Cocoa within Objective-C, or the browser/Node within JavaScript. +support.constant +support.function +support.module +While also used for base frameworks, many syntaxes apply these to scopes unrecognized classes and types, effectively scoping all user constructs. +support.type +support.class +text. +Programming languages use source. as their base scope, whereas content uses text.. One of the biggest differences is the fact that many plugins and other dynamic functionality is disabled within text. scopes. markup. scopes are typically used within text. +HTML should use the following scope. Variants for this scope are different than other scopes, in that the variant is always added after the .html, such as text.html.basic or text.html.markdown. +text.html +XML should use: +text.xml +variable. +A generic variable should use the following scope. Some languages use the readwrite variant for contrast with the constant variant discussed below. +variable.other +variable.other.readwrite +Symbols that are part of the variable name, should additionally be applied the following scope. For example, the $ in PHP and Shell. +punctuation.definition.variable +Immutable variables, often via a const modifier, should receive the following scope. Depending on the language and semantics, entity.name.constant may be a better choice. +variable.other.constant +Reserved variable names that are specified by the language, such as this, self, super, etc. should use: +variable.language +Parameters to a function or methods should use the following scope. This may also be used for other parameter-like variables, such as receivers or named return values in Go. +variable.parameter +Fields, properties, members and attributes of a class or other data structure should use: +variable.other.member +Function and method names should be scoped using the following, but only when they are being invoked. When defined, they should use entity.name.function. +variable.function +Usage in Color Schemes +In general, when applying colors and styles to scopes in a color scheme, the most general form of a selector should be styled first. High-quality syntaxes utilizing the scopes outlined in the previous section should result is good user experience for end users. +Minimal Scope Coverage +The following is a recommended minimal set of scopes to highlight. Adding extra may result in a slightly improved experience, however being too specific will result in a color scheme that often only looks good for one or two syntaxes. +entity.name +entity.other.inherited-class +entity.name.section +entity.name.tag +entity.other.attribute-name +variable +variable.language +variable.parameter +variable.function +constant +constant.numeric +constant.language +constant.character.escape +storage.type +storage.modifier +support +keyword +keyword.control +keyword.operator +string +comment +invalid +meta. Colors +When styling scopes, resist the urge to directly style meta scopes. They are primarily intended to provide contextual information for preferences and plugins. +entity.name. Colors +Historically, many color schemes have provided one color for entity.name.function and entity.name.type, and often a different color for entity.name.tag. This leaves new entity.name.* scopes un-highlighted. +Color schemes should instead specify a color for entity.name that will be applied to classes, types, structs, interfaces and many other data structures. This color can be overridden for the two scopes entity.name.tag and entity.name.section, that are used for different types of constructs. diff --git a/www.sublimetext.com/docs/3/settings.html b/www.sublimetext.com/docs/3/settings.html index c857c56..361bc35 100644 --- a/www.sublimetext.com/docs/3/settings.html +++ b/www.sublimetext.com/docs/3/settings.html @@ -1,10 +1,9 @@ Settings -Sublime Text has many different settings to customize its behavior. Settings are changed by editing text files: while this is a little trickier than using a GUI, you're rewarded with aflexible system. +Sublime Text has many different settings to customize its behavior. Settings are changed by editing text files: while this is a little trickier than using a GUI, you're rewarded with a flexible system. Settings -To see what settings are available, and a description of each, take a look at Packages/Default/Preferences.sublime-settings. You can access this file from the Preferences/Settings - Default menu item. -When you've found some settings you'd like to change, add them to your User Settings (accessible from the Preferences/Settings - User menu), so they're preserved when upgrading. +Settings are accessed via the Preferences/Settings menu item. The left-hand pane contains all of the default settings, along with a description of each. The right-hand pane is where customization can be saved. Settings Files Settings files are consulted in this order: Packages/Default/Preferences.sublime-settings @@ -14,22 +13,16 @@ Packages/<syntax>/<syntax>.sublime-settings Packages/User/<syntax>.sublime-settings <Buffer Specific Settings> -In general, you should place your settings in Packages/User/Preferences.sublime-settings. If you want to specify settings for a certain file type, for example, Python, you should place them in Packages/User/Python.sublime-settings. -Example Settings File -Try saving this as Packages/User/Preferences.sublime-settings -{ -"tab_size": 4, -"translate_tabs_to_spaces": false -} +In general, you should place your settings in Packages/User/Preferences.sublime-settings, which is opened in the right-hand pane when selecting the menu item Preferences/Settings. If you want to specify settings for a certain file type, for example, Python, you should place them in Packages/User/Python.sublime-settings. This can be accessed via the right-hand pane when a Python file is open, and the menu item Preferences/Settings – Syntax Specific is selected. Per-syntax Settings Settings may be specified on a per-syntax basis. Common uses for this are to have different indentation settings or the color scheme vary by file type. -You can edit the settings for the current syntax using the Preferences/Settings - More/Syntax Specific - User menu. +You can edit the settings for the syntax of the current file by selecting the Preferences/Settings – Syntax Specific menu item. Per-project Settings -Settings can be set on a per-project basis, details are in the Project Documentation +Settings can be set on a per-project basis, details are in the Project Documentation. Distraction Free Settings -Distraction Free Mode has an additional settings file applied (Distraction Free.sublime-settings). You can place file settings in here to have them only apply when in Distraction Free Mode - access it from the Preferences/Settings - More/Distraction Free - User menu. +Distraction Free Mode has an additional settings file applied (Distraction Free.sublime-settings). You can place file settings in here to have them only apply when in Distraction Free Mode – access it from the Preferences/Settings – Distraction Free menu item. Changing Settings with a Key Binding -The toggle_setting command can be used to toggle a setting. For example, to make a key binding that toggles the word_wrap setting on the current file, you can use (in Preferences/Key Bindings - User): +The toggle_setting command can be used to toggle a setting. For example, to make a key binding that toggles the word_wrap setting on the current file, you can use (in Preferences/Key Bindings): { "keys": ["alt+w"], "command": "toggle_setting", diff --git a/www.sublimetext.com/docs/3/spell_checking.html b/www.sublimetext.com/docs/3/spell_checking.html index 501a5e8..bd3bf81 100644 --- a/www.sublimetext.com/docs/3/spell_checking.html +++ b/www.sublimetext.com/docs/3/spell_checking.html @@ -1,8 +1,8 @@ Spell Checking -Sublime Text uses Hunspell for its spell checking support. Additional dictionaries can be obtained from the OpenOffice.org Extension List -Dictionaries in a format ready to be used by Sublime Text are available at https://github.com/SublimeText/Dictionaries +Sublime Text uses Hunspell for its spell checking support. Additional dictionaries can be obtained from the OpenOffice.org Extension List. +Dictionaries in a format ready to be used by Sublime Text are available at https://github.com/titoBouzout/Dictionaries. Dictionaries Sublime Text currently only supports UTF-8 encoded dictionaries. Most dictionaries are not encoded in UTF-8, instead using a more compact encoding for the language in question. To use a dictionary with Sublime Text, it'll first need to be converted into UTF-8. Once you have a UTF-8 encoded dictionary, it can be installed by placing it in a package, for example, Packages/User, which you can access from the Preferences/Browse Packages menu item. Once the file is in place, you can select the dictionary from the View/Dictionary menu. diff --git a/www.sublimetext.com/docs/3/syntax.html b/www.sublimetext.com/docs/3/syntax.html index 28672c1..e9f5b4a 100644 --- a/www.sublimetext.com/docs/3/syntax.html +++ b/www.sublimetext.com/docs/3/syntax.html @@ -1,6 +1,6 @@ -Syntax +Syntax Definitions Sublime Text can use both .sublime-syntax and .tmLanguage files for syntax highlighting. This document describes .sublime-syntax files. Sublime Syntax files are YAML files with a small header, followed by a list of contexts. Each context has a list of patterns that describe how to highlight text in that context, and how to change the current text. Here's a small example of a syntax file designed to highlight C. @@ -43,19 +43,20 @@ scope: constant.character.escape.c - match: '"' pop: true -A second pattern has been added to the main context that matches a double quote character (note that '"' is used for this, as a standalone quote would be a YAML syntax error), and pushes a new context, string, onto the context stack. This means the rest of the file will be processing using the string context, and not the main context, until the string context is poped off the stack +A second pattern has been added to the main context that matches a double quote character (note that '"' is used for this, as a standalone quote would be a YAML syntax error), and pushes a new context, string, onto the context stack. This means the rest of the file will be processing using the string context, and not the main context, until the string context is popped off the stack. The string context introduces a new pattern: meta_scope. This will assign the string.quoted.double.c scope to all text while the string context is on the stack. While editing in Sublime Text, you can check what scopes have been applied to the text under the caret by pressing control+shift+p (OSX) or ctrl+alt+shift+p (Windows and Linux). -The string context has two patterns: the first matches a backslash character followed by any other, and the second matches a quote character. Note that the last pattern specifies an action: when as unescaped quote is encountered, the string context will be poped off the context stack, returning to assigning scopes using the main context. +The string context has two patterns: the first matches a backslash character followed by any other, and the second matches a quote character. Note that the last pattern specifies an action: when as unescaped quote is encountered, the string context will be popped off the context stack, returning to assigning scopes using the main context. When a context has multiple patterns, the leftmost one will be found. When multiple patterns match at the same position, the first defined pattern will be selected. Meta Patterns meta_scope. This assigns the given scope to all text within this context, including the patterns that push the context onto the stack and pop it off. meta_content_scope. As above, but does not apply to the text that triggers the context (e.g., in the above string example, the content scope would not get applied to the quote characters). meta_include_prototype. Used to stop the current context from automatically including the prototype context. +clear_scopes. This setting allows removing scope names from the current stack. It can be an integer, or the value true to remove all scope names. It is applied before meta_scope and meta_content_scope. This is typically only used when one syntax is embedding another. Meta patterns must be listed first in the context, before any match or include patterns. Match Patterns A match pattern can include the following keys: -match. The regex used to match against the text. YAML allows many strings to be written without quotes, which can help make the regex clearer, but it's important to understand when you need to quote the regex. If your regex includes the characters #, :, -, {, [ or > then you likely need to quote it. Regexes are only ever run against a single line of text at a time. +match. The regex used to match against the text. YAML allows many strings to be written without quotes, which can help make the regex clearer, but it's important to understand when you need to quote the regex. If your regex includes the characters #, :, -, {, [ or > then you likely need to quote it. Regexes are only ever run against a single line of text at a time. scope. The scope assigned to the matched text. captures. A mapping of numbers to scope, assigning scopes to captured portions of the match regex. See below for an example. push. The contexts to push onto the stack. This may be either a single context name, a list of context names, or an inline, anonymous context. @@ -98,7 +99,7 @@ - match: ">" scope: punctuation.definition.tag.end Note the first rule above. It indicates that when we encounter a <script> tag, the main context within JavaScript.sublime-syntax should be pushed onto the context stack. It also defines another key, with_prototype. This contains a list of patterns that will be inserted into every context defined within JavaScript.sublime-syntax. Note that with_prototype is conceptually similar to the prototype context, however it will be always be inserted into every referenced context irrespective of their meta_include_prototype setting. -In this case, the pattern that's inserted will pop off the current context while the next text is a </script> tag. Note that it doesn't actually match the </script> tag, it's just using a lookahead assertion, which plays two key roles here: It both allows the HTML rules to match against the end tag, highlighting it as-per normal, and it will ensure that all the JavaScript contexts will get poped off. The context stack may be in the middle of a JavaScript string, for example, but when the </script> is encoutered, both the JavaScript string and main contexts will get poped off. +In this case, the pattern that's inserted will pop off the current context while the next text is a </script> tag. Note that it doesn't actually match the </script> tag, it's just using a lookahead assertion, which plays two key roles here: It both allows the HTML rules to match against the end tag, highlighting it as-per normal, and it will ensure that all the JavaScript contexts will get popped off. The context stack may be in the middle of a JavaScript string, for example, but when the </script> is encountered, both the JavaScript string and main contexts will get popped off. Note that while Sublime Text supports both .sublime-syntax and .tmLanguage files, it's not possible to include a .tmLanguage file within a .sublime-syntax one. Another common scenario is a templating language including HTML. Here's an example of that, this time with a subset of Jinja: scope: text.jinja @@ -116,7 +117,7 @@ scope: keyword.control This is quite different from the HTML-embedding-JavaScript example, because templating languages tend to operate from the inside out: by default, it needs to act as HTML, only escaping to the underlying templating language on certain expressions. In the example above, we can see it operates in HTML mode by default: the main context includes a single pattern that always matches, consuming no text, just including the HTML syntax. -Where the HTML syntax is included, the Jinja syntax directives ("{{ ... }}" ) are included via the with_prototype key, and thus get injected into every context in the HTML syntax (and JavaScript, by transitivity). +Where the HTML syntax is included, the Jinja syntax directives ({{ ... }}) are included via the with_prototype key, and thus get injected into every context in the HTML syntax (and JavaScript, by transitivity). Variables It's not uncommon for several regexes to have parts in common. To avoid repetitious typing, you can use variables: variables: @@ -192,7 +193,7 @@ scope: entity.name.type pop: true In the above example, typename is a reusable context, that will read in a typename and pop itself off the stack when it's done. It can be used in any context where a type needs to be consumed, such as within a typedef, or as a function argument. -The main context uses a match pattern that pushes two contexts on the stack, with the rightmost context in the list becoming the topmost context on the stack. Once the typename context has poped itself off, the typedef_after_typename context will be at the top of the stack. +The main context uses a match pattern that pushes two contexts on the stack, with the rightmost context in the list becoming the topmost context on the stack. Once the typename context has popped itself off, the typedef_after_typename context will be at the top of the stack. Also note above the use of anonymous contexts for brevity within the typename context. PHP Heredocs This example shows how to match against Heredocs in PHP. The match pattern in the main context captures the heredoc identifier, and the corresponding pop pattern in the heredoc context refers to this captured text with the \1 symbol: @@ -235,7 +236,7 @@ // ^ string.quoted.double // ^ string.quoted.double - comment To make one, follow these rules -Ensure the file name starts with "syntax_test". +Ensure the file name starts with syntax_test_. Ensure the file is saved somewhere within the Packages directory: next to the corresponding .sublime-syntax file is a good choice. Ensure the first line of the file starts with: <comment_token> SYNTAX TEST "<syntax_file>". Note that the syntax file can either be a .sublime-syntax or .tmLanguage file. Once the above conditions are met, running the build command with a syntax test or syntax definition file selected will run all the Syntax Tests, and show the results in an output panel. Next Result (F4) can be used to navigate to the first failing test. diff --git a/www.sublimetext.com/docs/3/tab_completion.html b/www.sublimetext.com/docs/3/tab_completion.html index 2acfdd7..2044b1e 100644 --- a/www.sublimetext.com/docs/3/tab_completion.html +++ b/www.sublimetext.com/docs/3/tab_completion.html @@ -4,7 +4,7 @@ Tab Completion allows quickly completing words by pressing the tab key. When enabled, pressing tab will expand the text to the left of the cursor into the best match, using Sublime Text's fuzzy matching algorithm. Tab Completion is enabled by default. Disabling Tab Completion -Sometimes tab completion isn't desirable. To turn it off, add this line to Preferences/File Settings - User: +Sometimes tab completion isn't desirable. To turn it off, add this line to the right-hand pane of Preferences/Settings: "tab_completion": false Inserting Literal Tabs To insert a tab rather than a completion, press shift+tab. @@ -12,4 +12,4 @@ Sometimes the completed text isn't what's desired: to change to an alternative, press ctrl+space. This will roll back the completion, and display the standard auto complete list. Alternatively, tab can be pressed again to cycle to the next completion. Completion Sources -Information on completion sources, and creating your own completions, is available at sublimetext.info. +Information on completion sources, and creating your own completions, is available at docs.sublimetext.info. diff --git a/www.sublimetext.com/docs/3/vintage.html b/www.sublimetext.com/docs/3/vintage.html index e9580b1..adda89b 100644 --- a/www.sublimetext.com/docs/3/vintage.html +++ b/www.sublimetext.com/docs/3/vintage.html @@ -2,19 +2,18 @@ Vintage Mode Vintage is a vi mode editing package for Sublime Text. It allows you to combine vi's command mode with Sublime Text's features, including multiple selections. -Vintage mode is developed in the open, and patches are more than welcome. If you'd like to contribute, details are on the GitHub page. +Vintage mode is developed in the open, and patches are more than welcome. If you'd like to contribute, details are in the GitHub repo. Enabling Vintage Vintage is disabled by default, via the ignored_packages setting. If you remove "Vintage" from the list of ignored packages, you'll be able to edit with vi keys: -Select the Preferences/Settings - Default menu item +Select the Preferences/Settings menu item Edit the ignored_packages setting, changing it from: "ignored_packages": ["Vintage"] to: "ignored_packages": [] now save the file. -Vintage mode is now enabled - you'll see "INSERT MODE" listed in the status bar -Vintage starts in insert mode by default. This can be changed by adding: +Vintage mode is now enabled – you'll see "INSERT MODE" listed in the status bar +Vintage starts in insert mode by default. This can be changed by adding the following setting to your user settings: "vintage_start_in_command_mode": true -to your User Settings. What's Included Vintage includes most basic actions: d (delete), y (copy), c (change), gu (lower case), gU (upper case), g~ (swap case), g? (rot13), < (unindent), and > (indent). It also includes many motions, including l, h, j, k, W, w, e, E, b, B, alt+w (move by sub-words), alt+W (move backwards by sub-words), $, ^, %, 0, G, gg, f, F, t, T, ^f, ^b, H, M, and L. @@ -24,8 +23,10 @@ Insert mode is regular Sublime Text editing, with the usual Sublime Text key bindings: vi insert mode key bindings are not emulated. Ex commands are not implemented, apart from :w and :e, which work via the command palette. Under the Hood -Vintage mode is implemented entirely via key bindings and the plugin API - feel free to browse through the Vintage package and see how it's put together. As an example, if you'd like to bind "jj" to exit insert mode, you can add this key binding: -{ "keys": ["j", "j"], "command": "exit_insert_mode", +Vintage mode is implemented entirely via key bindings and the plugin API – feel free to browse through the Vintage package and see how it's put together. As an example, if you'd like to bind "jj" to exit insert mode, you can add this key binding: +{ +"keys": ["j", "j"], +"command": "exit_insert_mode", "context": [ { "key": "setting.command_mode", "operand": false },