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.

Commands¶

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.

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.
The "Reload Base Information" command below has additional details regarding the availability of the lrauv-application code on your system .

Linting¶

TethysL: Lint this .tl mission

This command performs a basic linting of the script, and reports any issues or associated suggestions.

Checks initially implemented include:

Consistency of ID of mission or aggregate with filename;
Possible use of array syntax extension in arguments and output sections;
Possible use of macro syntax extension in embedded aggregates;
Recursively, the above checks for each embedded aggregate.

Here's a lint operation report example:

Science/altitudeServo_approach_backseat_poweronly_blockisland.tl
================================================================

In arguments section
--------------------

Possible use of 'array' extension:

  These 50 definitions: Lon1, Lon2, ..., Lon50
  could probably be replaced with: Lon[1..50]

  These 50 definitions: Lat1, Lat2, ..., Lat50
  could probably be replaced with: Lat[1..50]



Under aggregate `Lap`
---------------------

    Possible use of 'macro' extension
    ---------------------------------

      These 50 aggregates:

        aggregate Wpt1 { ... }
        ...
        aggregate Wpt50 { ... }

      could probably be replaced with:

        macro $k = 1..50 {
          aggregate Wpt$k {
            ...
          }
        }

Reload Base Information¶

TethysL: Reload Base Information

This command reloads all information of relevant LRAUV definitions (behaviors, units, universals, etc.) used by the TethysL compiler in your VSCode session.

The following describes the three possible cases for the source of such information. The first two depend on settings in VSCode, while the third is the default.

Tip

In the VSCode Settings window, filter by "tethysl" to quickly find the TethysL settings.

Source: lrauv‑application revision¶

The name of the setting in VSCode is LRAUV revision.

If this setting is given (but with the LRAUV path empty, see below), then the reload command will use information published by MBARI for the given revision. You need internet access for this to work. The revision can be a git branch name (e.g., "master"), a tag, or a commit hash. Depending on your situation, you may get advice from the LRAUV team on which revision to use.

The following screenshot shows master as the value for the setting.

Source: lrauv‑application path¶

The name of the setting in VSCode is LRAUV path.

If available, you can explicitly indicate the location of the lrauv-application clone on your system. In this case, the reload command will parse that codebase for the needed information.

Note

If what you are opening as workspace in VSCode is one of the following:

lrauv-application clone directory
lrauv-application/Missions subdirectory
Some directory that has lrauv-application as sibling

then you can leave the LRAUV path setting empty; TethysL should be able to automatically "discover" the corresponding lrauv-application location for purposes of reloading the information.

Run this command when there are changes in your lrauv-application clone that should be reflected for proper mission validation (e.g., upon merging or changing branches).

Source: Embedded resources¶

When none of the above settings are used, and when TethysL cannot "discover" an lrauv-application codebase location depending on the workspace being opened, then the extension will use LRAUV information that was embedded in the system at time of creating the TethysL software distribution. Of course, this embedded information may get outdated.

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
}

Regression Testing¶

TethysL: Test mission using runTest.py

Note

For this command to be functional, the following is required on your machine:

A clone of the lrauv-application codebase
python on your PATH

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.

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.

Why not .tx generation enabled by default?

The .tx is basically an internal representation used in the vehicle at time of execution. In general, this is not intended to be used directly by users when editing a script. The .tl is the primary source of truth for the mission script. The toggle here is mainly intended for users with experience with (or curious about) the XML format to facilitate inspection and migration from XML.

Here's a screencast demonstrating some features initially implemented.