Table of Contents

Theory

ADOxx Development Languages: Syntax Support in Microsoft Visual Studio Code

AdoScriptExtension.png  

Syntax support is now available for AdoScript within Microsoft's Visual Studio Code (VSC) editor!
A great big thank you to Patrik Burzynski for creating this solution.
 
Microsoft Visual Studio Code (VSC) is an editor and development environment for mutiple programming languages. 
Syntax support for various different languages is provided through extensions, and now there is a functional extention available for AdoScript. The solution focuses on recognizing the right concepts and displaying them according to the used theme.
Additionally, it tries to identify illegal code where possible and mark it accordingly, like the use of variables where they aren't allowed or having lower-case characters in a procedure name.
 

Features 

Code highlighting and snippets
 
  • Highlighting of both AdoScript code and LEO programs, with some help for noticing errors: if something isn't highlighted properly or even marked as illegal then there's probably some syntax error, like missing closing brackets or unintentional escaping of double quotes. Note: the debug modifier is marked as illegal.deprecated so it can be quickly identified in the code.
  • Any LEO-program (e.g. GRAPHREP, ATTRREP, EXPRESSION-type attributes etc.) now has basic code highlighting as long as it doesn't deviate from the LEO grammar.
  • Additionally AdoScript specific code highlighting is provided for its additional keywords and API-commands.
  • Code snippets for typical LEO and AdoScript patterns, like conditional or loop statements and the AdoScript message port calls. All snippets in alphabetical order:
  1. AdoScript - ccacq, ccado, ccana, ccapp, ccaql, cccore, cccui, ccdb, ccdoc, ccdraw, cceval, ccexp, ccimp, ccmod, ccsim, ccuser, fornum, fortok, else, elsif, if, while
  2. LEO - cond, fornum, fortok, while
  • Support for other common features like bracket matching / autoclosing, comment toggling, folding etc.
 

Installation

The Installation of the extension can be done directly within Microsoft's Visual Studio Code editor!
 
InstallAdoxxAdoScriptExtension.gif
 
 
The Microsoft Visual Studio Code (VSC) editor can be downloaded here.
The AdoScript Syntax Extension can also be downloaded here.
 
 

Recommendations

The syntax highlighting assigns scopes to the different parts of the code, which are then colored and styled according to the selected theme.
While the syntax highlighting mostly relies on scopes commonly found in the available themes, it is possible to further fine-tune some of the formatting to better visualize some of the special AdoScript cases.
It is not necessary to directly edit the used themes, since own customizations can be provided through the settings JSON file (settings.json accessible through the command palette, F1 or CTRL+SHIFT+P on Windows).
There the editor.tokenColorCustomizations key can be used to specify text colors and styles for the different scopes which are then applied on top of the used theme. See below for a recommended code snippet that formats built-in functions, procedures and the debug modifier in italics and the TODO in comments in bold.
More information on what scopes are made available by the syntax highlighting and for which parts of code can be found under "Used Syntax Highlighting Scopes" on the following README page.
 
{ // Copy into settings.json
    "editor.tokenColorCustomizations": {
        "textMateRules": [
            {
                "name": "built-in LEO functions",
                "scope": [
                    "support.function",
                    "keyword.operator.new"
                ],
                "settings": { "fontStyle": "italic" }
            }, {
                "name": "API-commands in AdoScript",
                "scope": "support.function.api-command",
                "settings": { "fontStyle": "italic" }
            }, {
                "name": "the debug modifier",
                "scope": "invalid.deprecated.debug",
                "settings": { "fontStyle": "italic" }
            }, {
                "name": "the TODO in comments",
                "scope": "comment.todo",
                "settings": { "fontStyle": "bold" }
            }
        ]
    }
}
While the style for support.function applies to both the built-in LEO functions and the API-commands, the more specific support.function.api-command scope is also added to allow applying a different style for API-commands.
 
 

Restrictions

(Don't worry, there's a lot of text, but it's just 4 easy steps to follow restrictions)
 
The syntax highlighting can't cover everything that is technically allowed as valid code in AdoScript, due to how the two systems work. However, some of the cases that can't be covered by this extension could be regarded as bad practices and should be avoided. To ensure that everything works fine please consider the following list as a set of best practices when writing AdoScript code using this extension:
 
  1. Only the new style of IF-ELSIF-ELSE using curly brackets is supported (IF (...) { ... } ELSE { ... }).
  2. Don't use any of the data type names (like integer, reference, map etc.) or built-in function names (aappend, array, map, abs, cond, lower, etc.) as the exact identifier for your variable or function (lower-case identifiers). Also try to avoid using variable names that are used as parameters or return values (objid, objids, attrid, return, result etc.). While the code might work in some or even most cases, there is the danger that your variable will be overwritten by a command (for example a CC). For procedures avoid any exact matches with names used by an available API-command (upper-case identifiers, INFOBOX, GET_ATTR_VAL, EVAL_AQL_EXPRESSION etc.). Consider using meaningful prefixes in the names / identifiers you assign.

    Good Example:
    SETL int_count:(10)
    SETL map_message:({"header": {"Content-Type": "text/plain"}, "body": "..."})
    SETL i:0
    SETL str_name:"AdoScript"
    FUNCTION my_token:global src:string tok:integer return:(...)
    FUNCTION array_init_zeroes return:(...)
    PROCEDURE BEEUP_INFOBOX ...
    Bad Example:
    SETL reference:(3)
    SETL abs:("absolutely")
    SETL type:("AB+")
    FUNCTION token:global src:string tok:integer return:(...)
    FUNCTION array return:(...)
    PROCEDURE INFOBOX ...
  3. Definition of or value assignment to a parameter (for procedures, functions, basic commands like SEND and CALL etc.) should not be split into several lines. Basically this means that definitions like name:type or type:name or for example the LEO parameters like get-str-value:fname:"firstname" should be in the same line. Putting different parameter definitions / assignments in separate lines or spreading a bracketed LEO expressions among several lines is however fine. 

    Good Example:
    PROCEDURE MY_PROCEDURE integer:int_main str_separator:string {
        ...
    }
    PROCEDURE MY_OTHER_PROCEDURE string:str_main
                                 int_from:integer
                                 int_to:integer
    {
        ...
    }
    Bad Example:
    PROCEDURE MY_OTHER_PROCEDURE string:
                                    str_main
                                 int_increment:
                                    integer
    {
        ...
    }
  4. When using CC "Application" EXIT write the API-command in the same line as the CC if you want it to highlight properly. This is necessary, because AdoScript uses EXIT both as an API-command (exit the application) and a normal command (exit a code block / script). Putting the API-command in the same line allows to distinguish the two from one another.

    Good Example:
    CC "Application" EXIT
    CC "Application" debug EXIT
    Bad Example:
    CC "Application"
        EXIT
    CC
        "Application"
        EXIT
 
 
Want to contribute to the development of this application? Have a look at our repository here.
Want to report an issue with this application? Have a look at our issue tracking page here.
Want to learn more about this application? More information is available here.
 
If you need help with the AdoScript extension or VSC, or have questions please don't hesitate to contact us under info@adoxx.org!
Average (0 Votes)
The average rating is 0.0 stars out of 5.

Hands On

Community

There are no results.

Scenario

There are no results.

Development Tools