Terminality

Terminality

A Sublime Text 3 Plugin for Sublime Text's Internal Console

Branch
release
master (develop)

What is Terminality

Terminality is a plugin to allows Sublime Text to be used as Terminal. This included input and output from/to Sublime Text's buffer. Although Terminality can run many commands, it is not gurranteed that it can be used for all commands.

The command is language-based. Current version support the following languages…

• C
  • Compile and Run
• C++
  • Compile and Run
• Lua
  • Run
• Python
  • Run as Python 2 (python command)
  • Run as Python 3 (python3 command)
• Rust (thanks to @divinites)
  • Run
• Ruby
  • Run
• Swift (OS X only)
  • Run

Is that it? No, Terminality allows you to add your own commands to be used inside Sublime Text. Please see the section belows for more informations.

How to use it?

Just pressing Ctrl+Key+R and the menu will show up, let's you select which command to run.

If you want to pass arguments to command (depends on how each command use the arguments), pressing Ctrl+Key+Shift+R instead. This will let's you select the command first, then ask you for arguments input.

Key is Alt in Windows, Linux, Cmd in OS X

Note! This key binding is conflicted with SFTP. You might have to override it yourself.

Settings

Terminality is using a very complex settings system in which you can control how settings affect the whole Sublime Text or each project you want.

As you might already know, you can override default settings by set the desire settings inside user's settings file (can be access via Preferences > Packages Settings > Terminality > Settings - User).

But if you want to override the settings for particular project, you can add the terminality dictionary to the .sublime-project file. Under this dictionary, it works like a user's settings file but for that project instead.

To summarize, Terminality will look for any settings in your project settings file first, then user's settings file, and finally, the default package settings.

How Terminality can helps my current workflow?

Good question! You might think Terminality is just a plugin that showing a list of commands which you already know how to use it. Sure, that what it is under the hood but Terminality does not stop there. Here are the list of somethings that Terminality can do for you…

• Run tests on your project
• Exclusively build and run your project without affecting another project
• Dynamically run Sublime Text's commands based on your project or current file
• One keystroke project deployment
• And much more…

How can I created my own command to be used with Terminality?

You can create your own command to be used with Terminality by override the commands in which using only execution_units key in the settings.

Or if you want to create and share some of your Terminality commands, use the Collections (See Collections section belows).

In v0.3.7 or earlier, you must set it in additional_execution_units instead.
In v0.3.8 or later, additional_execution_units is deprecated and will be removed in v0.4.0

// Settings file
{
    // ... Your other settings ...
    "execution_units": {
        // ... See Language Scopes section belows ...
    },
    // ... Your other settings ...
}

Language Scopes

Terminality use Sublime Text's syntax language scope in which you can look it up at the status bar when pressing Ctrl+Alt+Shift+P (Windows and Linux) and Ctrl+Shift+P (OSX).

Language Scope section is a dictionary contains commands which will available for specified language scope.

The key of the language scope is simply a scope name you want to specified. If you want the command to be available to all language just simply use the * as a language scope.

You cannot override the default language scope. However, you can remove the default commands for that language scope by set the value to non-dictionary type (such as 0).

"<Language Scope>": {
    // ... See Commands section belows ...
}

Commands

Command section is a dictionary contains informations about how to run the command.

The key of the command is simply a command name you want to use as a command reference (this will also be used as command name if you did not specified the name key).

You can override the command by use the exactly same command reference name of the command you want to override (included default one). And you can also remove the commands by set the value to non-dictionary type (such as 0).

Each key is optional (exceptions in the Limitations/Rules section belows) and has the following meaning…

• name [macros string] A name of the command (which showing in the menu).
• description [macros string] A description of the command (which show as subtitle in the menu).
• order [string] A string which used for sorting menus
• location [macros string] A location path to run the command
• required [list] A list of macro name (without $) that have to be set before run the command (if any of the macro is not set, command will not run).
• arguments [string] A text to show when ask for arguments input.
• command [macros string] A macros string define the command that will be run.
• window_command [macros string] A macros string define the Sublime Text's window command (included any plugin you installed) that will be run.
• view_command [macros string] A macros string define the Sublime Text's view command (command in which only run within a view) that will be run.
• args [dict] A dictionary that will be passed to window_command or view_command. Each macro inside the dictionary's value will be parsed recursively.
• platforms [list] A list of supported platforms. In <os>-<arch>, <os> or <arch> format (os and arch are from Sublime Text's sublime.platform() and sublime.arch() command).
• no_echo [bool] Specify whether input will be echo (false) or not (true).
• read_only [bool] Specify whether running view can receives input from user (false) or not (true).
• close_on_exit [bool] Specify whether running view will be closed when command is terminated (true) or not (false).
• macros [dict] A dictionary contains custom macro definitions. See Custom Macros section belows.

"<Command Reference>": {
    "name": "<Command Reference>",
    "description": "<Command Name> command",
    "order": "<Command Name>"
    "location": "$working",
    "required": [],
    "arguments": "Arguments",
    // You can use only one of "command", "window_command" or "view_command"
    "command": "<No default value>",
    "window_command": "<No default value>",
    "view_command": "<No default value>",
    // "args" will only use with "window_command" and "view_command"
    "args": {},
    "platforms": [<No default value>],
    "no_echo": false,
    "read_only": false,
    "close_on_exit": false,
    "macros": {}
}

Limitations/Rules

• Every macro name (except inside required) should have $ prefix.
• Each action must contains only one of command, window_command and view_command (other can be omitted)
• location, no_echo, read_only and close_on_exit only works with command only
• args only works with window_command or view_command only

See example inside Terminality's user settings file (and also in Terminality's .sublime-project file itself!).

Predefined Macros

• file: Path to current working file
  file_relative: Relative path of file
• file_name: Name of file
• working: This will use working_project but if not found it will use project and if still not found it will use parent
working_relative: Relative path of working
• working_name: Name of working
• working_project: Project folder contains current working file
  working_project_relative: Relative path of working_project
• working_project_name: Name of working_project
• project: First project folder
  project_relative: Relative path of project
• project_name: Name of project
• parent: Parent folder contains current working file
  parent_relative: Relative path of parent
• parent_name: Name of parent
• packages_path: Path to Sublime Text's packages folder
• raw_selection: Raw text of last selection
• selection: Striped text of last selection
• arguments: A text which passed via arguments input
• sep: Path separator (/ or \ depends on your operating system)
• $: $ symbol

Custom Macros

You can create your own macro to be used with custom command by adding each macro to macros section in your execution unit (See Commands aboves). Each macro is a key-value pairs in which key indicated macro name (a-zA-Z0-9_ without prefixed $) and value is a list of any combination of the following values…

• "String and/or $macro" This will be a parsed string (which must not contains self-recursion) if previous value is not found
• ["Start:End"] This will substring the previous value (if any) from start to end
• ["RegEx Pattern", <Optional Capture Group>] This will return a specified group (or default match if not specified) from previous value matching
• ["String and/or $macro", "Start:End"] This will substring the specified string/macro from start to end if previous value is not found
• ["String and/or $macro", "RegEx Pattern", <Optional Capture Group>] This will return a specified group (or default match if not specified) from specified string/macro matching if previous value is not found

Substring works just like Python's substring. You can omitted start or end as you like.

Macro works as a sequence, if current macro is not found it will look at the next macro.

Example:

"CustomMacro": [
    "$file_name", // Get the file name from predefined macro
    [":-4"], // Remove the last 4 characters (if value is found)
    ["$file", "\\w+"], // Get the result from parsing "$file" with RegEx if previous value is not found
    "" // If nothing can be used, use empty string
]

Collections

Implemented in v0.3.8 and later

Collections is a package contains Terminality commands which can be install by place in the User directory.

The structure of Collections file is simply a JSON file with .terminality-collections extension. Inside the file contains the following format…

{
    "execution_units": {
        // ... See Language Scopes section aboves ...
    }
}

Please note that Collections is not a settings file (although it contains the same key name). Any other key will be ignored completely.

Contributors

• @utensil
• @zmLGBBM
• @divinites