A Sublime Text 3 Plugin for Sublime Text's Internal Console
Branch | ||
---|---|---|
release | ||
master (develop) |
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.7 (
python
command) - Run as Python 3 (
python3
command)
- Run as Python 2.7 (
- 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.
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.
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.
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...
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 ...
}
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 ...
}
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 menuslocation
[macros string] A location path to run the commandrequired
[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 towindow_command
orview_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
andarch
are from Sublime Text'ssublime.platform()
andsublime.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": {}
}
- Every macro name (except inside
required
) should have$
prefix. - Each action must contains only one of
command
,window_command
andview_command
(other can be omitted) location
,no_echo
,read_only
andclose_on_exit
only works withcommand
onlyargs
only works withwindow_command
orview_command
only
See example inside Terminality's user settings file (and also in Terminality's .sublime-project file itself!).
file
: Path to current working file
file_relative
: Relative path offile
file_name
: Name offile
working
: This will useworking_project
but if not found it will useproject
and if still not found it will useparent
working_relative
: Relative path ofworking
working_name
: Name ofworking
working_project
: Project folder contains current working file
working_project_relative
: Relative path ofworking_project
working_project_name
: Name ofworking_project
project
: First project folder
project_relative
: Relative path ofproject
project_name
: Name ofproject
parent
: Parent folder contains current working file
parent_relative
: Relative path ofparent
parent_name
: Name ofparent
packages_path
: Path to Sublime Text's packages folderraw_selection
: Raw text of last selectionselection
: Striped text of last selectionarguments
: A text which passed via arguments inputsep
: Path separator (/
or\
depends on your operating system)$
:$
symbol
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) fromstart
toend
["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 fromstart
toend
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
]
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.