JADE Plugin Instance Editor

Page Summary

On this page we cover the features and functionality of the JADE Plugin Instance Editor.

JADE Plugin Instance Editor

Often called simply “The Editor”, the editor used to edit configuration for plugin instances has several modern features, such as syntax highlighting, syntax error checking, hover help, and more.

As we saw in the Getting Started, the editor is opened from the Application Manager by either double-clicking on a plugin instance, or right-clicking on a plugin instance and choosing Edit.... Below we see an example of a plugin instance editor.


There are several features to take note of above.

JSON Format

The format of all plugin instance configurations is JSON (JavaScript Object Notation), which is human-readable and fully expressive in that it can represent booleans, strings, numbers, arrays, and objects - all composable with arbitrarily deep hierarchy.

Syntax Highlighting

Syntax highlighting helps guide the eye to key syntax elements in configuration. In general, distinct JSON data types and delimiting syntax will hightlight in their own colors. Matching sets of curly braces will also change colors at different levels to help distinguish the layers. Comments are also allowed as shown in green.

{
    // this is a comment
    "boolean": true,
    "string": "something",
    "number": 12.5,
    "array": [1, 2, 3],
    "object": {
        "anotherString": "something else" 
    }
}

In addition to JSON syntax highlighting (with comments), JADE expression and variable syntax are also highlighted. Notably, JADE expressiona and variables are always within a string so that the underlying JSON syntax remains vaild.

{
    "sampleExpressionSyntax": "Float:( Sqrt(19/4095) * @VAR{submatch[0]} + 1 )"
}

Details of the JADE expression language and variables are in the Expression Language Syntax Reference.

Toolbar

Notice the toolbar at the top of the window. Here we find the ability to zoom in/out, fold/unfold object layers, rename the plugin instance, select a plugin version, visit documentation

Regex Helper

A regular expression, or regex for short, is a string syntax which describes how to parse another string. Regular expressions are used ubiquitously in software development, and some JADE plugins support them, for example, to handle instrument responses.

However, regular expressions themselves have a particular syntax which sometimes conflates with JSON syntax (ex. escaping or “slashing” characters with the \ character). This can always be handled correctly in a JSON string, but sometimes requires “double slashing” making it more difficult on the eyes

For this reason, the editor provides an in-context regex helper which can be opened by clicking the little regular expression icon (.*) next to the line number for configuration options which support or require regular expressions. Below we show the icon before being clicked.


Clicking the icon opens the regex helper as shown below.


There are several key things to note about the Regex Helper inlay.

Regex Helper Fields

There are 4 primary sections to the regex helper: SUBJECT STRING, REGULAR EXPRESSION, MATCH, and SUBMATCHES. We discuss each in detail below.

SUBJECT STRING

First, observe that the content of the SUBJECT STRING field (at the top left of the regex helper inlay) is equivalent to the simulationResponse on line 22. Note the highlights here which correspond to submatches captured by the regular expression.

2345 +052 +048\n

REGULAR EXPRESSION

The REGULAR EXPRESSION field (contents shown below) holds a regular expression which corresponds to the responseRegex on line 28. Notice the syntax highlighting which makes the regular expression easier on the eyes.

\+?((?&number))\s+\+?((?&number))\s+\+?((?&number))\s*

However, we observe that it doesn’t have the “double-slashing” which we see on line 28. Instead, the REGULAR EXPRESSION field allows us to compose the regular expression without concern over the additional escaping / slashing required by for JSON.

MATCH

The MATCH field shows the full portion of SUBJECT STRING which is matched by the REGULAR EXPRESSION. In this case it’s the full string:

2345 +052 +048\n

SUBMATCHES

The SUBMATCHES fields display variables and matched values corresponding to the capture groups or submatches of REGULAR EXPRESSION. Submatches are enumerated in the order in which they appear in the regular expression.

To make submatches available for use elsewhere in the instance configuration (in this case the plublishDataFormat), they are placed into an array named submatches within a VAR variable container (see the JADE Expression Language syntax reference for more details on variable syntax). Notice that lines 35-37 have the same variable syntax as shown in the SUBMATCHES area, such as @VAR{submatch[0]}. Also note that the colors in the SUBMATCHES area match the corresponding highlights in the SUBJECT STRING:

"waterLevelRaw": "Integer:(@VAR{submatch[0]})",
"airTemperatureRaw": "Integer:(@VAR{submatch[1]})",
"waterTemperatureRaw": "Integer:(@VAR{submatch[2]})",

As an aside, on lines 35-37 we also see the wrapping “return type” syntax Integer, but we again defer that detail to the JADE Expression Language syntax reference.

PCRE Regex

The regular expression engine underneath the REGULAR EXPRESSION field is PCRE (the “Pearl Compatible Regular Expression” engine). Given the flags applied to regular expressions in JADE (supported by PCRE), this allows for some additional features not shown above such as the inclusion of whitespace characters (ex. literal spaces and line breaks) which are not interpreted as part of the matching syntax. This is helpful when regular expressions become larger and otherwise harder to read. One can also include comments in the regex using the # key. This again can help when regular expressions become more arcane and otherwise difficult to understand. Further details are in the Regular Expression syntax reference.

How did the simulationResponse and responseRegex content get pulled into the Regex Helper automatically?

The reason the regex helper knows to use the simulationResponse and responseRegex is that those JSON elements were specified in an underlying JSON Schema defined for the VISA Publisher. Generally, plugins allow for specifying the configuration elements which should be used to seed the Regex Helper. We discuss this further in the JADE DEVKIT documentation, where such a schema is created as part of developing a plugin. Notably, this is also where we can supply hover help text for each field.