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.

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) or Cmd+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) or Cmd+Space (Mac) to trigger autocompletion
Press Ctrl+Click (Linux/Windows) or Cmd+Click (Mac) to navigate to the definition of an element
Press Ctrl+Shift+Click (Linux/Windows) or Cmd+Shift+Click (Mac) to navigate to the references of an element
Press Ctrl+Shift+F (Linux/Windows) or Cmd+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 and lrauv-application repositories. If the two associated directories are siblings, you can open the lrauv-mission directory in VS Code and TethysL will be able to "discover" and navigate to the lrauv-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 the lrauv-application base directory directly, or its Missions 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.