STOS Visual Studio Code Extension Alpha Program

Thank you for joining the Visual Studio Code extension for STOS Basic alpha program.

The following page details all the information you will need in order to participate in the alpha, beta and release testing & refinements of this extension.

Important Stuff

The extension was conceived, created and developed by Neil Halliday from STOS Coders. All source code contained within this extension and repository are (C)2020 Neil Halliday/STOS Coders. By signing up to the alpha program and having the following, you accept the following:

  • No part of the source code can be copied, reproduced, or used outside of this extension.
  • You will not create your own VS Code STOS extension as a result of joining this program – I’m not spending my personal time creating this project for it to be ripped off and other extensions created by it’s participants – I’m sure you understand.
  • You may clone the repository and create branches should you wish, however the master branch is the version I will always be working with, and I cannot guarantee that things I do may not break any of your branches.

OK, so now that all the boring stuff is out of the way, let’s get on with the fun stuff.

The GitHub Repository

You can find all the source code for this extension on my GitHub repository at the following address. Please clone the repository onto your PC or MAC using the the Code button on the repository main page.

Once you have cloned the repository, you will need to unzip the node_modules.zip file that you can find in the root directory of the extension. This should save you from having to install “yo  code” and running “npm install”. However, you may find that a more preferable way of installing. Please make sure that the files are located in the node_modules folder, otherwise your extension will not compile. DO NOT DELETE THE ZIP FILE from your cloned repository.

Once you have everything cloned and unzipped, simply open the root folder of the extension in Visual Studio Code to access the uncompiled extension.

OK, you are good to go! Press F5 to compile and test the extension. If you get any compilation errors, you’re on your own sorry! There are plenty of tutorials online helping with installation errors for VS Code, so I suggest start reading there. Unfortunately I don’t have time to help out with these kinds of errors.

The Extension

There are many file making up the extension, so I will try and document as many of them as I can, however for the time being, there are a few key ones of note.

./src/extension.ts is the heart of the Intellisense functionality and command helper. In this file there are calls to the VS Code engine to register an Intellisense command, and it’s associated text. I’m using the MarkDown option in order to give the user command help/hints and tips. These are taken directly from the STOS (or extension manual) and are all formatted in the same way, along with example code where possible. I would like to keep this format consistent throughout the extension.

  • const Completion_<CommandNoSpaces> = new vscode.CompletionItem(‘<Command>’); activates a new Intellisense command. <CommandNoSpaces> is the variable name, and I am prefixing all these with Completion_ to keep everything neat. All variable names should use, as the example suggests, the command name but with the space removed. For example “screen copy” would become screencopy. All commands should be written in lower case. <Command> represents the command as it is shown in STOS Basic. Working with the same example, this would be “screen copy”.  The full line of code would look like the following: const Completion_screencopy = new vscode.CompletionItem(‘screen copy’);
  • Completion_inc.documentation = new vscode.MarkdownString(‘MarkdownString>’); is used to add a command helper to the Intellisense, so we can offer the user instructions and examples on how the command works. These should be taken from the manual of the program/extension and need to be consistent throughout the VS Code extension. I’m not going to explain the Markdown functionality, but tell you the format of the command helper. This should take the form of…
    • (line1)Command syntax with the command written in bold and parameters written in italics.
    • (line2)blank
    • (line3)Instructions for the use of the command, with the command word written in bold.
    • (line4)blank
    • (line5)”Example:” written in bold & italics
    • (line6)blank
    • (line7 onwards) the different examples

Always make sure that the the variables being passed  make sense as it will make it easier for the user.

  • Completion_autoback.kind = vscode.CompletionItemKind.Keyword; tells Visual Studio Code what kind of icon to show next to the Intellisense dropdown whilst on the screen. There are two “kinds” that are used in the extension. These are .Keyword, where the STOS command does not return a value (for example “screen copy”) and .Function, where the STOS command calculates something and returns it for later use (for example “upper$”). This methodology must be maintained in order to keep the extension consistent.

./syntaxes/stos.tmLanguage.json defines the syntaxes that are highlighted. I have put support in for all the standard STOS commands and my own GBP extension, however it is this file where additional extension commands would be put. Any new extension commands you want to add need to be added in their own element within the support section. They should be called “support.other.<extensionname>.stos”, with <extensionname> being all lowercase, and no spaces. You can copy the match section of the “support.other.gbpextension.stos” and simply replace the keywords within the brackets with those of the extension you are adding support for. The | character separates the keywords.

./themes/stos-color-theme.json defines the colour templates that are used within the theme. I’m pretty sure I have captured everything, so there will probably be no need to alter this file.

Testing Your Changes

If you make any changes to the files, please make sure you test them. You can do this by simply pressing the F5 key whilst editing the extension. This will launch a new VS Code window that is empty on it’s first use. Please load any STOS basic file that has been saved as ascii text (save “myfile.asc” from STOS). Once you have done this, VS Code will remember this file the next time you compile and run the extension. You must make sure to stop the extension from running before making any other changes. Do this by switching back to the extension source and clicking on the stop button that is now on the screen. This will close the other VS Code window. Make sure you save the files before running the extension, otherwise it may not pick up your last changes.

 

Ok, that is all I can think about for the moment, so please let me know if you have any problems, and report any errors or omissions back to me so I can correct.

Happy STOSing