.. include:: /include/substitutions.txt .. include:: /include/external_links.txt .. include:: /include/custom_roles.txt .. _introduction: ************ Introduction ************ Sublime |nbsp| Text is a fast and thoroughly-customizable text editor, adept at everything from editing source code to prose. It is designed with the ethos that "everything is customizable". You can both add your own features to the editor, as well as add your own programming languages if yours are not already supported. Sublime |nbsp| Text exposes its internals via an Application Programming Interface (API) that programmers can interact with by creating :term:`Plugins ` using the Python programming language. Getting Sublime |nbsp| Text *************************** - Stable Build: https://www.sublimetext.com/ - Cutting-Edge Build: https://www.sublimetext.com/dev (requires license) The cutting-edge build can be useful for things like `when you report a bug `__ and then they fix it and release a new build right away (happened to me on build 4199). .. _basics: Sublime Basics ************** Starting Sublime |nbsp| Text ============================ Starting Sublime |nbsp| Text is as easy as launching ``sublime_text.exe`` from its installation directory. Normally this is done by opening the Sublime |nbsp| Text icon that was installed with it. ``subl.exe`` is a command-line helper designed to make it easier on Windows to deal with certain things. It launches ``sublime_text.exe``. There are a few command-line options that may be of interest. Here is the output of ``subl --help``: .. code-block:: text Sublime Text build 4192 Usage: subl [arguments] [files] Edit the given files or: subl [arguments] [directories] Open the given directories or: subl [arguments] -- [files] Edit files that may start with '-' or: subl [arguments] - Edit stdin or: subl [arguments] - >out Edit stdin and write the edit to stdout Arguments: --project : Load the given project --command : Run the given command -n or --new-window: Open a new window --launch-or-new-window: Only open a new window if the application is open -a or --add: Add folders to the current window -w or --wait: Wait for the files to be closed before returning -b or --background: Don't activate the application -s or --stay: Keep the application activated after closing the file --safe-mode: Launch using a sandboxed (clean) environment -h or --help: Show help (this message) and exit -v or --version: Show version and exit Filenames may be given a :line or :line:column suffix to open at a specific location. See official documentation here: https://www.sublimetext.com/docs/command_line.html Major Concepts ************** Sublime |nbsp| Text is built up from a number of simple-but-powerful concepts. It is this fact that makes it---once you get to know it---a joy to work with, and easy to customize for the type of editing you engage in most. These concepts are summarized here with links to more detailed information. :Application: A :term:`Process` in the Operating System sense of the word (``sublime_text.exe`` on Windows), is a "singleton-type" application, meaning there can be at most one running on any given computer, but it can host any number of open Sublime |nbsp| Text Windows simultaneously, each potentially having a different Project open. :Window: A Window is a single unit of the UI with title bar, and minimize, maximize and close buttons in the upper right. Each :term:`Window` has (in top-to-bottom order): - one Title Bar - one Main Menu - one Client-Area :term:`panel` - one :term:`Status Bar` The Client-Area panel has (in left-to-right order): - one :term:`Side Bar` (may be hidden) - one :term:`Editing Panel` (always visible) - several :term:`Overlay Panels `, though only one is ever visible at a time. .. figure:: _static/images/window_screenshot.png :align: center :scale: 40% :alt: Screenshot of a Sublime |nbsp| Text Window Screenshot of a Sublime |nbsp| Text Window .. _side bar: :Side Bar: The display area on the left (when visible) that permits navigating the directory structure of the current project, opening files, and viewing and sorting the list of open files. Each Side Bar has (in top-to-bottom order): - one Open Files list (hidden by default) - one or more top-level Folders (a.k.a. :term:`Mount Points `) list (shows the contents of the current :term:`Project`) Each top-level Folder has a Directory Tree, representing the file system below its top-level directory. This tree can be filtered via ``Project > Edit Project``. See :doc:`projects` for details. .. figure:: _static/images/side_bar_screenshot.png :align: center :scale: 40% :alt: Screenshot showing Side Bar Side Bar :Editing Panel: The :term:`Editing Panel` occupies the whole area to the right of the Side Bar (when it is visible) and is where the Sublime |nbsp| Text user spends most of his time. The Editing Panel contains 1 or more :term:`Focus Group` Panels. .. figure:: _static/images/editing_panel_screenshot.png :align: center :scale: 40% :alt: Screenshot showing Editing Panel Editing Panel .. _focus group panel: :Focus Group Panel: A Focus Group Panel is a single sub-panel of the :term:`Editing Panel` that contains 1 or more :term:`Sheets `. While a Focus Group can host any number of :term:`Sheets `, it normally only displays one Sheet at a time. To display 2 or more Sheets simultaneously (e.g. side by side or one above the other), you invoke a :term:`Layout` that hosts more than one Focus Group Panel at a time. To see examples of different Focus-Group-Panel Layouts, hold down the [alt+shift] keys and hit the following numbers in this sequence: 2, 3, 8, 9, and finally 1 to return to the original Layout. Each of those "areas" is called a Focus Group Panel (or just "Focus Group"). .. figure:: _static/images/focus_group_panel_screenshot.png :align: center :scale: 40% :alt: Screenshot showing Focus Group Panel Focus Group Panel :Layout: A :term:`Layout` controls how the :term:`Editing Panel` divides its area among 1 or more :term:`Focus Group ` Panels. See :ref:`Layouts` for more details. :Sheet: A Sheet represents 1 file (or display output, such as the "Find Results" display resulting from a Find-in-Files operation), each having a Tab at the top and a display/editing area below it. Sheets come in one of 3 types: - Text - Image - miniHTML .. figure:: _static/images/sheet_screenshot.png :align: center :scale: 40% :alt: Screenshot showing Sheet Sheet When the area below the Tab contains text, the text display and editing functions (assuming it is not in read-only mode) are carried out by a :term:`View`. If you single click a file containing text in the Side Bar, the contents appear in the :term:`View` in "peek" mode. (File name is in italics in the Tab.) If you open the file by one of these methods: - ``File > Open File...`` from the menu, - double-click the filename in the Side Bar, - double-click the Tab (when it is already showing in "peek" mode), or - start editing it, then the file is considered "officially" open, the filename will no longer be in italics in the Tab, and then its name will also appear in the OPEN FILES list at the top of the :ref:`Side Bar`. You can drag these names in the OPEN FILES list, or drag the Tabs at the top of the :ref:`Focus Group `, to reorder them. :View: A View is the tremendously-capable editing interface of the Sublime |nbsp| Text UI, accepting user keystrokes, displaying its contents, and has vast capabilities. Views are used for a large number of purposes, and can be read-only when appropriate. Not every View is connected with a file on disk. Examples: - displaying report output (e.g. Find-in-Files Results titled "Find Results"), - displaying (read-only) :term:`Package Resource` files stored in ``.sublime-package`` (zip) format, - new files (``File > New File``) before they are saved to disk. Once such content is displayed, it can be saved, if desired, by using ``File > Save As...``. Each View is attached to exactly one :term:`Buffer` (though multiple Text Views can be attached to the same Buffer). Views are also used as input "TextBoxes" inside :term:`Panels `. Examples: - Find/Replace/Find-in-Files Panels, - Console input and output, and - Input field in Command Palette and other input-gathering panels. The beauty of this is that they have many features (like Undo/Redo), and :term:`Plugins ` can get access to their contents in Text :term:`Commands ` in the same way as they do for regular text being edited. .. figure:: _static/images/view_screenshot.png :align: center :scale: 40% :alt: Screenshot showing View View :Buffer: The container for the edited content, representing that content as a contiguous sequence of possibly-multi-byte characters. Line separators within the Buffer are always a single newline ('\\n', 0x0A) character. For platforms that use different line separators for text stored in files, this translation occurs during loading and saving, but the line separators in Buffers are consistent across all platforms. :Overlay Panel: An Overlay Panel is Sublime |nbsp| Text's version of a :term:`GUI` Dialog Box. It is called an Overlay Panel because it is anchored to, and overlays part of the Sublime |nbsp| Text Window, usually at the top of the :term:`Editing Panel`, or at the bottom of the :term:`Window` above the :term:`Status Bar`. Overlay Panels are used to gather user input and/or perform certain types of actions that sometimes require more than a single key-stroke to complete. .. figure:: _static/images/overlay_panel_screenshot.png :align: center :scale: 40% :alt: Screenshot showing Overlay Panel Overlay Panel :Menu: A tree-structured display, normally collapsed to the top level, allowing the user to select actions to take by topic. The Main Menu is located at the top of the window, just under the Title Bar. .. figure:: _static/images/main_menu_screenshot.png :align: center :scale: 40% :alt: Screenshot showing Main Menu Main Menu .. _status bar: :Status Bar: The Status Bar is the bar at the bottom of the window that shows a variety of helpful information about a number of things you occasionally need to know about (in left-to-right order): - current row and column of the caret (cursor) in current :term:`View` - how many Selection Regions (carets) are active in current View - state of current Git repository (if any, click to launch Sublime Merge if installed) - number of misspelled words (when :ref:`spell checking` is turned on) - information about the file being displayed in the current View: - current encoding (click to change) - type of line endings being used (click to change) - indentation settings (click to change) - current language syntax being used (for highlighting and other behaviors; click to change) - When one of the Find Overlay Panels is being displayed, the current row and column are replaced by the number of Find results there are, and which is being highlighted (if any). .. figure:: _static/images/status_bar_screenshot.png :align: center :scale: 40% :alt: Screenshot showing Status Bar Status Bar .. note:: *line-ending* and *current-encoding* status display are turned off by default, but can be turned on by including these two entries in your custom settings: .. code-block:: json { "show_encoding": true, "show_line_endings": true, } Current language syntax controls: - syntax highlighting - :term:`Build Systems ` that are available - some :term:`Package` functionality that is only available for certain file types .. _run-time object model: :Run-Time Object Model: All of the above concepts (Application, Window, Side Bar, Editing Panel, Focus Group Panel, Sheet, View, Buffer, Overlay Panel, Menu and Status Bar) have the relationship shown below. This relationship is helpful to understand so you know what you are working with in the Python code you create to make customizations. In an Entity-Relationship Diagram (ERD), this Run-Time Object Model would look like this: .. code-block:: text +-------------------------+ |Key: | | | | | | | + | | | /|\ /|\ | | Exactly Zero One | | One or or | | More More| +-------------------------+ Sublime Text Process | + /|\ Window -------------------------------------------------- | | | Side Bar Editing +-- Title Bar / \ Panel +-- Main Menu Folders Open | +-- Status Bar List Files + +-- Zero or One Visible Overlay Panel | List /|\ (Sublime Text's version /|\ Focus Group of a dialog box) Mount Panel Point | | | Directory | Tree + /|\ Sheet (flavors: text [View], Image, HTML) ---------------------------------------------------------------------------- | | Tab View --------------------------------------------------------------------- | | | | | (possible | | + | | other Views) Regions | /|\ | | /----- View Dictionary | Selection | Buffer ----- View | | \----- View Settings Edit Dictionary (Change-History Stack) .. _context menus: :Context Menus: A :term:`Context Menu` is a pop-up menu that opens as a result of right-clicking any of several objects in the Sublime |nbsp| Text :term:`GUI`. (Some keyboards also have the ability to open Context Menus.) Note that :term:`Context Menus ` were not shown in the above diagram to reduce clutter. But for reference, the following types of objects (shown above) can pop up Context Menus: - :term:`Sheets ` - Tabs - Views - Images - :term:`Side Bar` - :term:`Mount Points ` (top-level folders) - files and folders - open files (in Open Files list) - :term:`Status Bar` - Encoding Status - Line Ending Status - Indentation Status - Current Syntax Status - :term:`Overlay Panels ` - Console - Find-in-Files Panel - Other :term:`input panels ` See :ref:`Menus` for more details. .. figure:: _static/images/context_menu_screenshot.png :align: center :scale: 40% :alt: Screenshot showing Context Menu Context Menu :Viewport: .. TODO:: Viewport, and its relationship to these View functions: - viewport_position(self) -> Vector: """ :returns: The offset of the viewport in layout coordinates. """ - set_viewport_position(self, xy: Vector, animate=True): """ Scrolls the viewport to the given layout position. """ - viewport_extent(self) -> Vector: """ :returns: The width and height of the viewport. """ - layout_extent(self) -> Vector: """ :returns: The width and height of the layout. """ - text_to_layout(self, tp: Point) -> Vector: """ Convert a text point to a layout position. """ - text_to_window(self, tp: Point) -> Vector: """ Convert a text point to a window position. """ - layout_to_text(self, xy: Vector) -> Point: """ Convert a layout position to a text point. """ - layout_to_window(self, xy: Vector) -> Vector: """ Convert a layout position to a window position. """ - window_to_layout(self, xy: Vector) -> Vector: """ Convert a window position to a layout position. """ - window_to_text(self, xy: Vector) -> Point: """ Convert a window position to a text point. """ - line_height(self) -> DIP: """ :returns: The light height used in the layout. """ :Key Bindings: Key Bindings connect key combinations with the actions they perform. See :doc:`key_bindings` for more details. :Scope: Scope is the "characteristics of the caret's location in a text file". Syntax definitions make Sublime |nbsp| Text aware of the Scope for any given position in a file. They do so by generating *scope names* to provide metadata about language tokens. This metadata is updated on-the-fly every time the caret moves in any kind of document, but it is especially applicable in source code where the metadata reveals the nature of the area that the caret is currently sitting in (e.g. keyword, keyword category, number, symbol, comment, etc.). See :term:`Scope` for more details. :Selector: A Selector is a string that is evaluated against the current Scope, and triggers a ``True`` or ``False`` result based on that evaluation. Its use is to determine whether a particular 'thing' is applicable based on the nature of the current :term:`caret` location, i.e. its Scope. If you're familiar with CSS, Sublime |nbsp| Text Selectors behave like selectors in a CSS file: they are a very efficient method of determining whether something "applies" or not. See :ref:`scope selectors and context` for more details. :Context: A Context is an optional element of a Key Binding, that uses the key "context" in the Key Binding dictionary object. When present, it provides a possibly-complex condition under which that key combination can be applied. See :ref:`key binding definitions` for full details. :Commands: Commands are how Sublime |nbsp| Text carries out actions that are beyond handling individual printable keystroke. They are ubiquitous: key bindings, menu items, macros and many other types of actions are implement through the command system. Some commands are implemented in the editor's core, but the remainder are provided through :term:`Plugins `, which means you can view and customize their source code and behavior. Every command (including built-in ones) can be called from a Plugin. See :doc:`commands` for details. .. _settings: :Settings: Settings (Preferences) are stored in :term:`Sublime-relaxed-JSON format`. The global defaults for these are accessed (read-only) by: ``Preferences > Settings`` (left side since Sublime |nbsp| Text 4) The major sections of that file are: - Editor settings (the top 2/3 of the file) - UI settings - Application Note that the comments in this file describe each setting key and its possible values and what they mean---which is a great place for this documentation: where and when you need it. The right side (as of Sublime |nbsp| Text 4) are editable user overrides created by copying the key/value pairs from the left side and pasting them on the right and modifying (and saving) their default values. .. note:: If you have the PackageDev Package installed, this copy/pasting can be done by a single mouse click, among many other things. There are also :term:`Package` settings, which apply to specific package behavior, which are accessed by: ``Preferences > Package Settings > ...`` These preferences are applied in layers like CSS, where lower (more specific) preferences override higher-level preferences of the same name. The "path" of the "layer cascade" is guided by scopes that apply to the that currently shown in the editing area. .. container:: tighter-table-6 +--------------------------------------------------+-----------------------------------------------------------------+---------------------------------------------------------------+ | Layer | Access | Notes | +==================================================+=================================================================+===============================================================+ | global defaults | ``Pref > Settings`` (left side) | Preferences.sublime-settings | +--------------------------------------------------+-----------------------------------------------------------------+---------------------------------------------------------------+ | platform defaults | ``Tools > View Package File`` > Default/Preferences ()| Preferences (Windows).sublime-settings | +--------------------------------------------------+-----------------------------------------------------------------+---------------------------------------------------------------+ | user-scope overrides | ``Pref > Settings`` (right side) | Packages/User/Preferences.sublime-settings | +--------------------------------------------------+-----------------------------------------------------------------+---------------------------------------------------------------+ | project-scope overrides | ``Project > Edit Project`` > "settings": { ... } entry | Editor preferences only, not UI or APP BEHAVIOR preferences. | +--------------------------------------------------+-----------------------------------------------------------------+---------------------------------------------------------------+ | file-extension-scope (syntax-specific) defaults | ``Pref > Settings - Syntax Specific`` (left) | C.sublime-settings | +--------------------------------------------------+-----------------------------------------------------------------+---------------------------------------------------------------+ | file-extension-scope (syntax-specific) overrides | ``Pref > Settings - Syntax Specific`` (right) | Packages/User/C.sublime-settings | +--------------------------------------------------+-----------------------------------------------------------------+---------------------------------------------------------------+ :Project: A Project is how Sublime |nbsp| Text enables the user to rapidly access and open a set of related files from the :term:`Side Bar` Folders tree. See :doc:`projects` for details. :Snippet: A Snippet is an external XML file that enables one to call up static text that you use frequently, and can optionally perform like an HTML form, giving you the opportunity to manually fill out "fields". Snippets can also be used programmatically by plugins. See :doc:`snippets` for details. :Completions: The concept of Completions is an "umbrella" topic that covers different ways Sublime |nbsp| Text saves typing and time by finishing words or inserting boilerplate text. See :doc:`completions` for details. :Plugins: Plugins are Python modules that are stored in the root of a Package directory, and serve to provide additional (or modified) functionality for Sublime |nbsp| Text. See :doc:`plugins` for details. :Packages: A Package is a group of :term:`Package Resource` files grouped under one directory name, which name indicates the nature of the additional functionality it provides to Sublime |nbsp| Text. See :ref:`Packages` for more information. .. _data directory: :Data Directory: Once installed, all customizations of Sublime |nbsp| Text go into its data directory. It has a different path depending on the platform: :Windows: ``%APPDATA%/Sublime Text/`` :Windows Portable Version: ``path/to/application/Data/`` :Linux: ``~/.config/sublime-text/`` :MacOS: ``~/Library/Application Support/Sublime Text/`` This also makes it easy to revert Sublime |nbsp| Text to its freshly-installed state by - closing Sublime |nbsp| Text, - renaming that directory to a backup directory, - re-starting Sublime |nbsp| Text. From here on in the documentation, we will refer to the Data Directory as simply :term:``. :Console: Sublime |nbsp| Text and Plugins can push debug information to the :term:`Console` by using the Python ``print()`` function. To open the Console, press ``Ctrl+``` or select ``View > Show Console`` from the main menu. .. figure:: _static/images/console_screenshot.png :align: center :scale: 40% :alt: Screenshot showing Console Console Panel The upper panel is a read-only :term:`View` and at this writing cannot be searched. The lower panel sends its input to the built-in Python interpreter, giving you direct access to the Sublime |nbsp| Text API. Entering ``sublime.log_commands(True)`` and/or ``sublime.log_input(True)`` is a great way to see what's going on inside, as well as debug, if something isn't going as you expected. Using ``sublime.log_commands(True)`` is also the only way currently known by this author to discover the names of internal commands that are built into the Sublime |nbsp| Text core, and therefore not exposed to being gathered and reported by Plugins like `generate_cmd_list.py `__. Path Syntax =========== Sublime |nbsp| Text uses forward slashes as directory separators on all platforms. While on Windows systems, native Windows path syntax (using backslashes) is supported in the "Where" field (path(s) + filters) of the "Find-in-Files" Panel, and in the ``path`` element of Sublime Project files, and possibly in other places where paths are used, forward slashes are fully supported everywhere, including in those places. Sublime Python ============== Sublime |nbsp| Text has its own internal Python engine. It does not interact with, impact, or use Python in your system PATH variable in any way, unless directed to do so by a :term:`Build System`. Sublime API =========== The Sublime |nbsp| Text Python API is contained in: - :term:``\ ``/Lib/python38/*.py`` and - :term:``\ ``/Lib/python33/*.py``. If you are a Python developer and want to customize Sublime |nbsp| Text, this is a great place to look to better understand the facilities that are available. The above :ref:`Run-Time Object Model` should help you better understand where objects of each class are (e.g. Window, View, Buffer, etc.), and their relation to the whole. JSON ==== Most types of settings in Sublime |nbsp| Text are stored (or represented) in :term:`Sublime-relaxed-JSON format`. Additional Information Resources ******************************** Documentation ============= - Official documentation: https://www.sublimetext.com/docs/index.html - Unofficial documentation: https://docs.sublimetext.io/ In-Application References ========================= - ``Tools > Command Palette... > View Package File``: lets you see all the default "things" you might want to customize, such as default settings, menus, commands available to the Command Palette, etc., and where they have overrides in place from installed packages. Example: type in "sublime-menu". ``Main.sublime-menu`` contains all the default menu bar items starting at the top level and showing all their children. See :doc:`menus` for more details. - Comments in default settings that document each individual setting value: ``Preferences > Settings`` Training Videos =============== - https://www.youtube.com/@OdatNurd Sublime |nbsp| Text Community ============================= - https://forum.sublimetext.com/ 3rd-Party Contributions, Examples, Etc. ======================================= - https://github.com/STealthy-and-haSTy - https://github.com/Sublime-Instincts There are literally dozens if not hundreds of of GitHub accounts and other sites that host repositories for publicly-released 3rd-Party Packages. These often show great example Plugins and Packages for Sublime |nbsp| Text that you can both install and learn from.