.. include:: /include/substitutions.txt .. include:: /include/external_links.txt .. include:: /include/custom_roles.txt .. _glossary: ******** Glossary ******** .. glossary:: :sorted: action In the Sublime |nbsp| Text package/plug-in context, and action is a :term:`Command` that gets executed to do something within Sublime |nbsp| Text. Buffer ``sublime.Buffer`` class represents the data of a loaded file and additional metadata associated with 1 or more :term:`Views `. In documentation, sometimes the term Buffer and a :term:`View` are used interchangeably, though they are far from being the same. Build System Sublime |nbsp| Text comes with a beautiful and flexible subsystem to launch external programs. Because it is surrounded by information about the file you are currently editing, this framework is very convenient to use it to "do something" with the file you are editing -- typically: - running it, - testing it, or - translating it into something else. The whole concept of "building" is indeed the concept of translating something (considered source) into something else, whether it is a program or set of documentation, or whatever it is. Because this subsystem is normally used to compile (or otherwise translate) the files of the current source-code project, this subsystem is referred to as the "Build System". See :ref:`Build Systems` for details. cursor caret The insertion point, where keystrokes will change the file, a.k.a. "cursor". "caret" is the preferred term. Command A ``sublime.Command`` object represents an action to be executed and can be referenced in many types of resource files. It may accept JSON-serializable arguments and can be defined in user :term:`plugins `. See :ref:`Commands` for more details. TextCommand A TextCommand is a class that inherits from ``sublime.TextCommand``. It is the only type of command where: - you can edit or do things with the buffer, and - you get an :term:`Edit` object as an argument, enabling you to make calls on :term:`View` methods that require an :term:`Edit` object as an argument. Command Palette A pop-up for quick access to various Commands provided by Sublime |nbsp| Text's core or a :term:`package`. The Command Palette can be opened via ``ctrl+shift+p`` or via ``Tools > Command Palette...``. Completion Sublime |nbsp| Text Completions are yet another way to save typing and time by finishing words or inserting boilerplate text. Console Ctrl+\` (Ctrl+backtick) (or ``View > Show Console``) opens the console :term:`Overlay Panel` at the bottom of the Sublime |nbsp| Text window, with 2 child :term:`panels `: an output panel and below that, an input panel that allows you to send input directly into the Python interpreter that is executing plug-ins. 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. Context Menu 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.) The objects in Sublime |nbsp| Text that can host a Context Menu are (Context Menu names are in parentheses): - :term:`Sheets ` - Views (Context) - Images (Image Context) - Tabs (Tab Context) - :term:`Side Bar` - OPEN FILES list (Tab Sidebar Context) - FOLDERS - :term:`Mount Points ` (Side Bar Mount Point) - Folders and Files, possible multiple items selected (Side Bar) - :term:`Status Bar` - Encoding Status (Encoding) - Line Ending Status (Line Endings) - Indentation Status (Indentation) - Current Syntax Status (Syntax) - :term:`Overlay Panels ` - Console (Console Input Widget) - Find-in-Files Panel (Find in Files) - Other :term:`input panels ` (Widget Context) The Context Menu content can be found (and customized) in :term:`Package Resource` files in various Packages named ``.sublime-menu`` The default version of these are in the ``Default`` Package, and customizations of these can be found in various other Packages. See :ref:`menus` for more details. Core Package A :term:`shipped package` that provides core functionality for Sublime |nbsp| Text. data directory Core concept and storage for all of Sublime |nbsp| Text's customized resources. Refer to :ref:`data directory` for details. Edit A :term:`View's ` ``sublime.Edit`` object is a collection of changes on the View's :term:`Buffer` performed through that View. Users cannot create Edit objects. Sublime handles this for us. But we must receive them as arguments in ``TextCommand.run()`` methods and pass them to View methods as arguments when those methods change the :term:`Buffer`. Editing Panel The Editing Panel occupies the whole area to the right of the Side Bar (when the Side Bar 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. The Editing Panel can be made to display more than one Focus Group by invoking alternate :term:`Layouts `. To see examples of different 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 :term:`Focus Group`. See :ref:`Layouts` for more details. EOL end of line Event Listeners ``sublime_plugin.EventListener`` class and ``sublime_plugin.ViewEventListener`` class call user-specified callbacks when an event happens. The former is "global" (application wide) and the latter is targeted at one specific :term:`View` object. executable directory The directory in which Sublime |nbsp| Text executable was installed. If you used a Windows Installer, it is likely ``C:\Program Files\Sublime |nbsp| Text\``. file base name file stem The part of the file name before the extension. .. code-block:: text My_Language.sublime-build ^^^^^^^^^^^ | +-- file stem (or base name) file type In the context of Sublime |nbsp| Text, a file type refers to the type of file as determined by the applicable ``.sublime-syntax`` syntax definition. However, this is an ambiguous term and in some instances it could also be used with the broader meaning it has in technical texts. Focus Group 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 can only display one Sheet at a time. See :ref:`focus group panel` for more details. Gutter The area on either side of the text-editing area where line numbers, symbols, and colored markings can be drawn to convey certain meaning about the lines of text they are next to. GUI Graphical User Interface input handlers ``sublime_plugin.TextInputHandler`` class and ``sublime_plugin.CommandInputHandler`` class are used to get information from the user, from within the Command Palette. For example, the command "Rename File" uses an object instantiated from the former, and the command "View Package File" uses an object instantiated from the latter. The pop-up previews in these objects use :term:`miniHTML`. input panel An input area (a sublime.View object) allowing the user to free-form type. The path to the directory where Sublime |nbsp| Text was installed. installed Package A :term:`user package` inside the Installed Packages folder in the ``.sublime-package`` archive (.zip) format. Key Binding A Key Binding is a dictionary object that supplies Sublime |nbsp| Text with a possibly-conditional keyboard trigger that it should use to execute a command (with optional arguments) specified in the Key Binding's definition. Key Binding dictionary objects are found in ``.sublime-keymap`` files. See :doc:`key_bindings` for more details. Layout A Layout controls how the :term:`Editing Panel` divides its area among 1 or more :term:`Focus Groups `. Sublime |nbsp| Text's default :term:`Layout` simply shows 1 :term:`Focus Group`. That means the contents of only 1 file (Sheet) can be displayed at any given time. To display 2 or more Sheets simultaneously (e.g. side by side or one above the other), you need to invoke a :term:`Layout` that hosts more than one :term:`Focus Group` at a time. To see some examples, hold down the [alt+shift] keys and then type these numbers(in this sequence): 2, 3, 8, 9, and then 1 again to return to the normal Layout. Sublime |nbsp| Text's Layout engine is extremely flexible. See :ref:`Layouts` for more information about how to control it to your liking. miniHTML A subset of HTML and CSS that provides layout for things like pop-up windows that show information in a nice, readable format. Minimap A small, condensed version of your text file displayed along the right margin, providing a high-level view of the entire file. It helps users navigate large files more easily by allowing them to scroll quickly through the content. Main Menu Sublime |nbsp| Text's Main Menu is the row of click-able words just under each :term:`Window's ` Title Bar. See :ref:`menus` for more details. Mount Point A Mount Point is a top-level object in the :term:`Side Bar`'s Folder List. It represents the top-level directory of a Directory Tree, which represents the computer's file system below that directory, possibly filtered by the contents of the ``.sublime-project`` file. panel The term "panel" (lower case) refers to an independent area of a Window. This is a term used with almost any software application that interacts with the user using a :term:`GUI`. The various panels involved with most Windows applications are (in typical top-to-bottom order): - Title Bar Panel - Main Menu Panel - Client Area Panel (this is where the user spends most of his time) - Status Bar Panel (some applications don't have Status Bars) The Client Area Panel is often subdivided into sub-panels of its own, depending on the application. As you can see, these form a tree structure within the application. The "leaf" objects in this tree are normally referred to as "Controls" or ":term:`Widgets `", while "panels" are considered to be "containers" for other panels or Widgets. Overlay Overlay Panel "Overlay" is short for "Overlay Panel", which is an input/output :term:`Widget` that is Sublime |nbsp| Text's version of a :term:`GUI` dialog box. Overlay Panels use Widgets to interact with the user. Example Widgets: - Buttons, - TextBoxes (instances of the ``sublime.View`` class) - miniHTML pop-up windows (Widgets for presenting information more complex than a single line of text). Hit [alt+shift+ctrl+p] to see an example. Overlay Panel Examples: - At Bottom of Window - Find Overlay - Find-in-Files Overlay - Replace Overlay - Console Overlay - At Top of Window - Command Palette Overlay - Goto Anything Overlay - Overlays used by :term:`Packages ` to get user input - Custom user-created Overlays - Where Cursor Is - Current Scope Overlay ([alt+shift+ctrl+p] is an example of a miniHTML Widget) Override Package A special package that can override individual resource files of an :term:`installed Package` or `shipped Package`. See :ref:`overriding whole files` for more details. Package A Package is a collection of files grouped together and given a name, that are focused on augmenting Sublime |nbsp| Text is some fashion. The files are called :term:`Package Resource` files. Package URL syntax always uses forward slashes as directory separators. Key: - = :term:``. - = :term:`` :/Packages/: Shipped packages (loaded first, do not touch) :/Installed Packages/: ZIP files with extensions renamed to .sublime-package :/Packages//: Unpacked package directories (also where Packages are developed) :/Packages/User/: User overrides, loaded last, can apply to anything. Packages can be developed here as well in experimental stages. Can later be moved into %A%/Packages// later. Package Resource A Package Resource is simply a :term:`Resource File` that is part of a Package and therefore in a Package directory. See :ref:`Packages` for more details. PackageDev A package that: - Eases the creation of snippets, syntax definitions, etc. for Sublime |nbsp| Text. - Brings with it: - enhanced syntax highlighting to :term:`Package Resource` files - auto-completion in resource files - eases creation of package resources Phantoms ``sublime.Phantom`` class provides :term:`miniHTML` "balloon messages" on things while editing, containing information for the user that is not part of the buffer being edited. Plugin Plugins are augmentations to Sublime |nbsp| Text implemented in Python. See :ref:`Plugins` for details. Point ``sublime_types.Point`` is an alias for an Integer. A Point indicates a location within a :term:`buffer`. Specifically, it is an offset (in characters) from the start of a :term:`buffer`, regardless of the current file's encoding. To keep things simple, when Sublime |nbsp| Text loads a file, no matter what platform it is on, it normalizes the line endings to just a single ASCII line-feed (LF, 0x0A) character between each line, so you don't have to worry about how many characters are involved with line separation on any given platform. In other words, if Point ``a`` points to the last character on a line, Point ``a + 2`` will *always* point to the first character on the next line. Process This term is used in the sense of a Process being a running program under an Operating System (OS). Sublime |nbsp| Text is designed internally so that one process handles all Sublime |nbsp| Text :term:`Windows ` open. As an intentional side effect, this also allows all windows and code(including code you wrote to customize Sublime |nbsp| Text) can share the same resources. For example, you could write code that could iterate through all open Sublime |nbsp| Text windows and do something with them, as a service to the user. Project A Project in Sublime |nbsp| Text is merely a collection of 0 or more top-level folders to be displayed in the :term:`Side Bar` to make it easier for the user to open files and navigate within that directory structure. When a Project is stored on disk, it "remembers" that collection for the user. It's file name is meant to convey the meaning of the scope of the work that was being performed with that particular file structure. Project files always have ``.sublime-project`` and can be, but do not need to be within any of the top-level folders contained in the Project. When a project is saved to disk, a :term:`Workspace` with the same name is saved alongside it. See :ref:`Projects` for more details. Quick Panel An object used to get an item from a list of choices from a user (i.e. a filter-able drop-down list). The Command Palette [ctrl+shift+p] is such an object. reaction In the Sublime |nbsp| Text package/plug-in context, and reaction is a response to an event by an event handler. Region A ``sublime.Region`` object represents a contiguous "area" within a :term:`Buffer`. A Region object contains 2 :term:`Point` values ``a`` and ``b`` indicating the beginning and ending of the Region. In true Python style, the 2nd Point contains the :term:`Buffer` character offset of the character *just after* the last character in the Region. A Region can represent: - a single selection Region (where the ordering of ``a`` and ``b`` are important), or - simply an area of the text buffer, where ordering is generally ignored. If ``b`` == ``a``, the Region is empty. If ``b`` < ``a``, then the :term:`caret` is shown on the left side of the Region. This has an impact on changing the selection Region with up- and down-arrow keys. Regex Regular Expression A Regular Expression is a pattern describing a certain amount of text. The name comes from the mathematical theory on which they are based. The term is often abbreviated as "regex". Regular Expressions provide a powerful way to both: - find text as well as - determining if certain text strings match certain patterns. As such, Regexes are ubiquitous throughout the computer industry and many implementations have been implemented over the years. For example, Regular Expressions are instrumental and part of the core concepts in Compiler front-ends (the part that reads what the programmer wrote and translates it into an intermediate representations such as an Abstract Syntax Tree). Because they are so well-established and well-understood by most programmers, programmers' text editors almost always implement Regexes in their find and find-and-replace operations. Sublime |nbsp| Text is no exception to this, although Sublime |nbsp| Text notably implements two distinct implementations of Regexes: - `Boost Perl Regex Syntax`_ for its Find operations, `Boost Replace String Syntax`_ for its Replace operations (part of its find-and-replace operations), and both are used in the various ``view.find...()`` API functions. - `Oniguruma Regexes`_ for its syntax highlighting. Note that Oniguruma Regex Library is NOT an extension of the Boost Perl Regex library; it is a separate Regex library that supports various character encodings and is used in different programming languages and applications. While both libraries provide Regex functionality, they are distinct projects with different features and implementations. Resource File A Package Resource file is any special file the Sublime |nbsp| Text uses. Examples: .. code-block:: text - .sublime-settings Modifies default settings \ - .sublime-keymap Implements key actions >-- Behaviour and user input - .sublime-macro Stores replay-able key seq. / - .sublime-build Launches external programs - .sublime-snippet Custom static text snippets - .sublime-completions Autocomplete entries - .sublime-color-scheme \ - .tmTheme \ - .sublime-theme >- Visual appearance. - .hidden-color-scheme / - .hidden-tmTheme / - .sublime-commands Adds cmds to Command Palette \___ Operations and Menu - .sublime-menu Defines and modifies menus / items to trigger them - .sublime-syntax \ - .tmLanguage \__ Add syntax highlighting support. - .hidden-tmLanguage / - .tmPreferences / - .sublime-mousemap Map commands to mouse-button clicks. - .py Plugins add new :term:`Commands` and event handlers. - *.* Any other files needed. Examples: - documentation - configuration files - external scripts - tools - libraries 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 :ref:`scope selectors and context` for more details. Selection The term "selection" (lower case) in this documentation simply refers to a text selection in a :term:`View`. However, when it is capitalized as "Section" (capitalized), is the name of a class: ``sublime.Selection``. Each :term:`View` has exactly one Selection object, which is the LIST of selection :term:`Regions ` within a :term:`View`. In normal editing, there is only one :term:`Region` in this list, and it is normally empty: the :term:`caret`. However, Sublime |nbsp| Text supports any number of these in a :term:`View` at any given time for special types of editing. Once that special editing action is complete, you can hit [Esc] to go back to having one caret again (selection). 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. Settings The Sublime |nbsp| Text application has exactly one ``sublime.Settings`` object. That object is a representation of the current settings, and can be converted to a Python dictionary for viewing and use, though that dictionary is only a copy, so modifying it does not change the settings. There is, however, a way this can be done for individual :term:`Views `. Settings are stored in, and loaded from :term:`Sublime-relaxed-JSON format` files with the extension ``.sublime-settings.`` See :ref:`settings` for more information. Sheet ``sublime.Sheet`` class displays and manages contents shown within a tab. There are three types of Sheets in Sublime |nbsp| Text 4: - text sheet (contains a :term:`View` enabling user to view/edit a :term:`Buffer`) - image sheet (displays an image from a variety of image formats) - HTML sheet (displays "mini HTML") Side Bar In Sublime |nbsp| Text, the Side Bar in a possibly-hidden :term:`panel` on the left side that helps the user with opening and navigating among open files. shipped Package A :term:`Package` that is provided by Sublime |nbsp| Text on every installation. Shipped Packages can be "visible" as files in ``/Packages/`` or built into Sublime |nbsp| Text, in which case they are not visible. Snippet In Sublime |nbsp| Text, a Snippet is a "smart template", whose content is defined in a simplified XML file, at most one Snippet per file, with a ``.sublime-snippet`` extension. Snippets can optionally have any number of "fields" each with optional default and/or placeholder text in them. See :ref:`Snippets` for details. Status Bar The Status Bar is the bar at the bottom of any :term:`Window` that shows a variety of helpful information about the states of various parts of that window. See :ref:`status bar` for more details. Sublime-relaxed-JSON format Normal JSON except: - :term:`EOL` comments are allowed with ``//``, and - a trailing comma after last list item is allowed (like in Python) Target The term "target" has special meaning in the Sublime |nbsp| Text Build System. It means the *external program* that is to be launched -- not its output. In special cases, a Sublime |nbsp| Text Command can be the Target, in which case it executes fully within Sublime |nbsp| Text, not as an external process. Terminus A package that brings a real terminal to Sublime |nbsp| Text, with access to the Sublime |nbsp| Text Python API. It: - adds a terminal directly to Sublime |nbsp| Text, - works on Windows, Linux and MacOS, - can be used in Sublime-build files to execute builds. User Package A :term:`Package` installed or managed by the user. User Packages live in :term:``\ ``/Packages/User/``. See :ref:`data directory` for more details. View ``sublime.View`` class is the graphical display and editing interface of a :term:`Buffer`. Multiple Views can show (and allow editing on) the same buffer. In a :term:`Command`'s ``run()`` method, ``self.view`` is automatically populated with a reference to the View the command is attached to. In the Console input panel, ``view`` is automatically attached to the View that most recently had keyboard focus. Thus ``view.run_command('command_name')`` for example runs that command (which may be supplied by a :term:`Plugin`). The input :term:`Widgets ` in the "Find/Replace" dialogs are also View objects, as well as the console input and display panels, and the input area of the Command Palette. Widget An object within a :term:`GUI` that interacts with the user and is normally limited to one type of input or output. Examples: text display, clicks, free-form typing, selecting an item from a list. They are the "leaf" objects in the tree structure that makes up the GUI. Examples: - Labels (display text) - Buttons - TextBoxes - Drop-Down Lists - Menu Items Widgets can contain other Widgets, so they are not always "strictly" leaf objects in the tree. Most Widgets (except Labels) accept various kinds of user input (e.g. keyboard, mouse, etc.). Window ``sublime.Window`` class managing the container for the Sublime |nbsp| Text UI (opened document tabs, side bar, etc.), with minimize, maximize and close buttons on the right side of title bar. Each window always has exactly 1 project open at any given time. There can be any number of Windows open at the same time, though all of them are always controlled by at most a single Process. Workspace :term:`Projects ` in Sublime |nbsp| Text are made up of at least 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, the modifications to each, and various application states such as what files were open, cursor positions, tab ordering, etc.. It is possible to have more than one ``.sublime-workspace`` file per project, and either the workspace or the project file can be opened (``Project > Open Project...``) to return to your "last session" with that project, or to a particular session by opening the workspace file. You might want to have more than one workspace file if you regularly edit 2 or more different groups of files in that project and the tasks are logically separate, or that use different Window layouts, etc.. See :ref:`Projects` for more details