TethysL VS Code Extension¶
Visual Studio Code (VS Code) is currently our primary target for enabling enhanced features on TethysL scripts, including validation, autocompletion, navigation, and mission regression testing.
Once you have VS Code installed on your machine,
you can install the TethysL VS Code extension from within VS Code itself.
More details here, but, in short, you can use the Marketplace option in VS Code,
search for tethysl
, and then install the extension.
Features¶
- Complete mission validation, with error highlighting
- Autocompletions, covering a good part of the language
- Element information on mouse hover and with links to documentation
- Mission script outline
- Go-to-definition/references navigation:
- From the use of an argument or output variable to its definition
- From an argument definition to its usages
- If the lrauv-application codebase is also available on the system, you can also quickly navigate to the C++ definition of behaviors and settings, units, and universals.
- Source reformatting
- Mission regression test execution (with support from the lrauv-application)
- Advanced:
- Optionally, you can enable the automatic generation of XML (
.tx
extension) upon any successful compilation of the TethysL script. This, in particular, intended to facilitate inspection by users familiar with the XML format. - You can also generate TethysL from existing XML files. This is intended to facilitate the migration of existing mission scripts to the TethysL format.
- Optionally, you can enable the automatic generation of XML (
Using the extension¶
Open a directory containing TethysL mission files (*.tl
) in VS Code.
Typically, such directory will be a clone of the
lrauv-mission
or the lrauv-application
repository.
Commands¶
For the specific list of TethysL-related commands:
- Press
Ctrl+Shift+P
(Linux/Windows) orCmd+Shift+P
(Mac) to open the command palette - Type
tethysl
to filter the list of available commands - Select the desired command
- Press
Enter
to execute the command - Press
Esc
to cancel the command
General VS Code commands (see VS Code "Basics" documentation) are also available for tethysL scripts, such as:
- Press
Ctrl+Space
(Linux/Windows) orCmd+Space
(Mac) to trigger autocompletion - Press
Ctrl+Click
(Linux/Windows) orCmd+Click
(Mac) to navigate to the definition of an element - Press
Ctrl+Shift+Click
(Linux/Windows) orCmd+Shift+Click
(Mac) to navigate to the references of an element - Press
Ctrl+Shift+F
(Linux/Windows) orCmd+Shift+F
(Mac) to reformat the script
Pro Tip
With the lrauv-application
codebase available on your machine, you will
also enjoy the associated navigation features provided by TethysL, for example,
from the settings of an invoked behavior in a mission to the corresponding C++ definitions.
Two common scenarios:
- You have clones of both the
lrauv-mission
andlrauv-application
repositories. If the two associated directories are siblings, you can open thelrauv-mission
directory in VS Code and TethysL will be able to "discover" and navigate to thelrauv-application
codebase. - If you only have a clone of the
lrauv-application
repository, TethysL will recognize the overall structure for appropriate navigation whether you open thelrauv-application
base directory directly, or itsMissions
subdirectory.
Regression Testing¶
TethysL: Test mission using runTest.py
Note
This command requires the lrauv-application
codebase available on your machine to be functional.
With the lrauv-application codebase available on the system,
the extension allows to directly
run Tools/regression/runTest.py
on your mission from within VS Code.
The command is enabled for .tl
, .tx
, and .xml
files.
Once complete, the output of the test is shown in a VS Code panel for your inspection.
Note
Recall that mission test execution may take significant time,
especially if valgrind
is set in the mission script.
More details about mission testing can be found
here.
Reload Base Information¶
TethysL: Reload Base Information
Note
This command requires the lrauv-application
codebase available on your machine to be functional.
This command will reload the base LRAUV information used by the TethysL compiler (behaviors, units, universals, etc.) from the lrauv-application codebase. Run this command when there are changes in your lrauv-application clone that should be reflected (e.g., upon merging or changing branches). For details, see this section.
Simplifying behavior settings¶
TethysL: Toggle simplifying behavior settings when reformatting
Simplification of behavior setting IDs during reformatting is enabled by default. Simplifying a behavior setting ID means removing the redundant prefix corresponding to the behavior itself.
As an example, with the flag enabled, this behavior invocation block:
behavior Trigger:PeakDetectVsDepth {
run in sequence
set Trigger:PeakDetectVsDepth.detect = Universal:mass_concentration_of_chlorophyll_in_sea_water
set Trigger:PeakDetectVsDepth.timeWindowPeakReport = TimeWindowPeakReport
outputArg PeakChl = Trigger:PeakDetectVsDepth.peakDetect
outputArg PeakChlDepth = Trigger:PeakDetectVsDepth.peakDepth
}
will get reformatted to the semantically equivalent but more legible:
behavior Trigger:PeakDetectVsDepth {
run in sequence
set detect = Universal:mass_concentration_of_chlorophyll_in_sea_water
set timeWindowPeakReport = TimeWindowPeakReport
outputArg PeakChl = peakDetect
outputArg PeakChlDepth = peakDepth
}
Generate XML (.tx)¶
TethysL: Toggle flag to generate XML (.tx)
Upon every successful compilation of a .tl
script, a corresponding "compiled XML" version
(with file extension .tx
) can be generated, but this is not enabled by default.
Use this command to toggle the corresponding flag.
Here's a screencast demonstrating some features initially implemented.