OpenTerm
OpenTerm allows you to run arbitrary commands from Independent Terminal Emulators of target OS's and to see the output. It also provides configurable function which will automatically determine Terminal to run command from, depending on Target OS.
pkg Usage
You can use OpenTerm with npm pkg. For more details see the example.
Package Key Aspects
- The most important thing is the ability of seeing output, because in general terminals adhere to behavior of closing after command finished execution, which not allow client to see the final output(s).
- Terminal must be opened in a separate window, or at least in a new Tab of initial terminal, so that the output does not interfer with another process of working with terminal.
Table of Contest
Usage
This package consists of 2 parts.
- Part 1 - VT : Virtual Terminal runners list.
- Part 2 - VTexec - Configurable function which automatically determines Terminal and runs.
Part 1: VT
Table of Contest
First Part exported as "VT" consists of distributed by platforms functions for running different Terminals. You can use them to run command in a separate Terminal:
- Use Linux Terminals. e.g.const VT =VTlinux // Runs "ls -l" command in xterm.VTlinux // Runs "ls -l" command in guake.
- Use Win32 Terminals. e.g.const VT =VTwin32 // Runs "help" command in cmd.
Be Sure you have appropriate terminal in your PATH or consider to use VTexec whch will automatically determinal terminal to use.
When calling VT functions, as a result you getting ChildProcess instance representing spawned terminal. If you want you can unref it to allow current nodejs process to exit independently of the spawned terminal.
VT Function Signiture
All VT functions has same signiture named TerminalExecutor:
- command - Defines command string to execute in opened terminal.
- terminalSpawnOptions - Options to spawn terminal process with 3 defaults:
- detached -
true
- stdio -
'ignore'
- shell - platform ===
'win32'
?true
:false
For more details see SpawnOptions.
- detached -
- terminalArgs - Defines arguments to start terminal with. By default all terminals runed with 3 types of arguments each responsible for key behaviour of our package:
For more details See VT key args and Package Key Aspects
If you provide any number of terminalArgs which not contain execArg ( See VT key args ) for terminal, then all default arguments will be disabled except execArg, and provided list will be used. If you want to disable all default arguments including execArg, you must specify execArg.
VT key args
By default terminals will be triggered with arguments ( if needed ) that are responable for key aspects of the package. Therefore, We distinguish 3 types of arguments to avoid confusions:
- execArg:Static Argument responsible for command execution on terminal startup, which takes provided command, e.g
-e command
for "guake" - holdArg:Optional: Argument which force terminal to not be closed after command finished execution. e.g.
-hold
for "xterm".NOTE: Although this argument defines required behaviour for our package, "terminals must not be closed after command executed" - but in some cases, the terminal not provide arguments to control this behaviour, at the same time it behaves exactly as desired, so we stick with static and at same time desired behaviour. Good example is "guake".
Important: Terminals that cannot achieve this behavior are not supported by package.
- PopupArgs:Optional: This argument(s) force to open terminal in a new window, or at least in a new tab and show it immediately, e.g.
--show -n .
for "guake".NOTE: If there is a way, terminal will be opened in a new window. If not, it will be opened in a new tab and shown. Good example is " guake", when theres no way to open a new window, but we can open a new tab, and show "guake" at startup.
"arg:Static" - means that this argument will be allways provided by package.
"arg:Optional" - means that this argument is not necesserily will be presented depending on terminal existing opportunities.
You can find information about available arguments for particular terminal on its man page or in help.
Supported Terminals
Currently supported Terminal Emulators listed by Platforms:
- linux
- xterm -
VT.linux.xterm
- guake -
VT.linux.guake
- konsole -
VT.linux.konsole
- xfce4-terminal -
VT.linux.xfce
- xterm -
- windows
- cmd -
VT.win32.cmd
- cmd -
For more terminals and platforms support, consider to open an issue.
Part 2: VTexec
Table of Contest
This function automatically determine terminal to use, open it, and execute provided command in it. Algorithm which define's how to find terminal, follow the configuration provided with second argument to VTexec function. If It's not provided, then,
- For supported platforms ( See PlatformsList ) default {{Platform}}SearchConfig will be used.
- For not supported platforms, VTexec will iterate through PlatformsList and for each platform look in {{Platform}}TerminalsList for terminal until found.
Well, example below will success both on win32 and linux, and additionally in any OS, if env.PATH
contains at least one terminal from supported ones regardless of platform i.e. if your os platform is blablabla, but you have in your $PATH
guake, then we will run it.
const VTexec = // Runs "help" command.
You can force VTexec to not support particular platform by providing appropriate property on VTexecConfig with value null
.
const VTexec = // Force to throw an error: 'NotSupported' for 'win32' and 'openbsd'.
Or, you can change default searchConfig values for supported platforms. For more ditails see SearchConfig.
Configs for not supported platforms, if provided, will be ignored.
const VTexec =
Here, as any VT Terminal function, it return's ChildProcess instance. To be precise, it uses the same VT functions under the hood.
VTexec Function Signiture
-
command - Defines command string to execute in found terminal.
-
VTexecConfig:Optional - Is a
{ [key: {{platform}}]?:{{searchConfig | null}}, default?: Platform[] | null }
map with one reserved key - "default", which cant be used as platform name.SearchConfig if provided, will be considered only for supported platforms. Every supported platform has it's default searchConfig ( see {{Platform}}SearchConfig ). Platform's support can be manually disabled by setting appropriate platform property to
null
.Property "default", instead of searchConfig, takes Array of platform names from PlatformsList, as fallbacks list to search terminal for not supported platforms unless that platform is not explicitly excluded. Fallbacks can be disabled by setting this property to
null
. If "default" is not provided, PlatformsList will be used.VTexecConfig - default is empty object, i.e. Any internal properties will take their defaults.
SearchConfig
SearchConfig determines the behaviour of the terminal selection algorithm for a specific supported platform ( See PlatformsList ). It will be processed by VTexec and transformed to Terminals ordered list, which then will be iterate to find valid terminal.
- terms - Terminals list which will be looked, when searching terminal to use. By default it takes {{Platform}}TerminalsList for appropriate platform.
- excludeTerms - Terminals to exclude from SearchConfig.terms. By default is empty Array:
[]
. - priorityTerms - Priority Terminals to look for first in same order as specified in the list. By default it takes {{Platform}}TerminalsList.
NOTE: See default searchConfigs for supported platforms: {{Platform}}SearchConfig.
Terminal Search Algorithm
When searching terminal to use, VTexec first of all look for your platform in VTexecConfig map,
- If it exists in the map, then:
- If provided value is
null
it will end with error: NotSupported. - If searchConfig provided
- If your platform is supported then it will deduce from provided config a list of terminals, and iterate through until terminal found. If no valid terminal found, it will end with error: NotSupported
- If your platform is not supported ( See PlatformsList ) it will fall to "default".
See "default" below.
- If provided value is
- If it not exist:
- If your platform is supported, then {{Platform}}SearchConfig, which is default, will be used.
- If your platform is not supported, the algorithm will look for "default" in provided VTexecConfig.
- If default is null, then it will end with error: NotSupported
- If default is list of platforms, then it will iterate through and watch for all terminals of each provided platform which is supported, until one is found. If no valid terminal found, it will end with error: NotSupported
- If default is not specified it will take as default PlatformsList.
Package Defaults
PlatformsList
'linux' 'win32'
{{Platform}}SearchConfig
- linuxSearchConfig:priorityTerms: 'xterm' 'guake' 'konsole' 'xfce'terms: 'xterm' 'guake' 'konsole' 'xfce'excludeTerms:
- win32SearchConfig:priorityTerms: 'cmd'terms: 'cmd'excludeTerms:
{{Platform}}TerminalsList
- linuxTerminalsList:'xterm' 'guake' 'konsole' 'xfce'
- win32TerminalsList:'cmd'
Thats it.