A-Shell Language Extension README

A-Shell Language Mode Extension for VSCode.

Features

• Language mode for A-Shell
• Syntax highlighting
• Collapsible code sections
• Go To Definition (for variables, function calls and ++include)
• Dynamic scoping as files opened / closed; supports DevPPN & ersatz with ++include
• Hover cursor over token (keyword, variable, function, ...) to see definition
• Function signature help (pops up as parameters entered)
• Outline view (Ctrl+Shift+O / breadcrumbs): lists FUNCTION/PROCEDURE declarations and DEF* directives (DEFINE, DEFTYPE, DEFSTRUCT, DEFALIAS, DEFXCALL) in the current file

The language mode is automatically swapped to A-Shell for the following file extensions;

• .bas
• .bp
• .bpi
• .bsi
• .stru
• .map
• .max
• .bav
• .mav
• .r11
• .r10
• .lsx
• .lst

If a file extension is not covered in the above list, then you can manually enable the A-Shell language by clicking the Select Language Mode in the bottom of the screen. Or by using Command Palette > Change Language Mode.

Known Issues

• Conditional compilation directives aren't being recognized/processed during editing.

Compiler

The compiler and its build task ship with the extension. Press Ctrl+Shift+B in an A-Shell file (or run A-Shell: Compile from the Command Palette) to compile it. Errors appear in the PROBLEMS tab, where clicking one takes you to the offending source line. There's nothing to add to tasks.json.

On activation the extension installs, and keeps up to date, these files in a per-user folder:

• Windows: %LOCALAPPDATA%\ashell\ (e.g. C:\Users\<you>\AppData\Local\ashell\) -- compil.exe and its task wrapper, compil.ps1
• Linux / WSL: ~/.local/share/ashell/ (or $XDG_DATA_HOME/ashell/) -- compil (with its executable bit set) and its task wrapper, compil.sh

(Both wrappers are installed on either platform.) The extension's compile task, A-Shell: compile, runs the wrapper from there; the wrapper runs the compiler and passes its error lines on to the PROBLEMS tab. Don't edit the installed wrapper -- the next extension update replaces it. See Customizing the build below instead.

Compiler switches: the switches the VS Code / compiler interface depends on (-ini, -n, -l, -b, -so, -z) are fixed inside the wrappers. The optional ones that vary from one developer or workspace to another (-a, -x:2, -px, ...) come from the ashell.compilerSwitches setting (user, workspace, or folder level).

miame.ini: the compile uses the same miame.ini as the rest of the extension -- the ashell.miameIniPath setting, or miame.ini in the file's workspace folder if that's empty.

Include files: building while an include-only module is active -- one whose extension is listed in the ashell.includeFileExtensions setting (default .bsi, .inc, .bpi, .map, .def, .sdf, .sub, .stru) -- compiles the most recently compiled program of the session instead, if it's still open; otherwise the build is cancelled with an "include files aren't directly compilable" message. Likewise, building an include file you reached from a program you've already compiled (e.g. via Go To Definition from an error) recompiles that program.

WSL / Linux MIAME: compil's ++include device: / ersatz: resolution only activates when the MIAME environment variable is set (a full A-Shell login sets it; a bare compil does not). compil.sh defaults MIAME to the folder containing the miame.ini it was handed, which is right when your miame.ini sits at the MIAME root. If it lives elsewhere and uses %MIAME%, export MIAME from your shell profile (~/.profile).

How to set up a workspace for A-Shell development

1. Open an A-Shell project workspace. If you don't have one, open the highest-level folder above your files (e.g. c:\vm\miame), then use File > Save Workspace As to save it (e.g. asb-code).
2. If your miame.ini isn't in that folder, set ashell.miameIniPath to its full path (File > Preferences > Settings, search for "ashell").
3. Set your compiler switches in the ashell.compilerSwitches setting.
4. Open an A-Shell program and press Ctrl+Shift+B.

Customizing the build

• Hooks (recommended): to add steps before or after the compile, create a folder named aux-files in the workspace folder and put a pre-compil.ps1 / post-compil.ps1 (Windows) or pre-compil.sh / post-compil.sh (Linux / WSL) in it. They're called just before and just after the compiler with the wrapper's four arguments (file to compile, workspace folder, miame.ini, optional switches); the post-compile hook also gets the compiler's exit code as a fifth. A pre-compile hook that exits non-zero skips the compile. Hooks live in your workspace, so extension updates never touch them.

• PROBLEMS tab: when a compile finds errors, the extension brings the PROBLEMS tab forward (keeping focus in the editor) -- the equivalent of the task option "revealProblems": "onProblem", which VS Code doesn't let an extension set on its own task. Turn this off with the ashell.revealProblemsOnErrors setting if you'd rather control it through the task properties below.

• Task properties: to change how the task's terminal behaves (e.g. its presentation options), run Tasks: Configure Task and pick A-Shell: compile. That adds an entry like the following to the workspace's .vscode/tasks.json, holding only the properties you change -- VS Code applies them on top of the extension's own task, so they survive extension updates. (Each workspace has its own tasks.json -- including a WSL workspace, separately from its Windows counterpart.)

  {
      "type": "ashell",
      "task": "compile",
      "problemMatcher": ["$ashell-compil"],
      "presentation": {
          "reveal": "always",
          "revealProblems": "onProblem",
          "focus": false,
          "echo": true,
          "showReuseMessage": false,
          "panel": "shared",
          "clear": true
      },
  }
  

• Your own wrapper: to change the wrapper itself (e.g. to run a compiler of your own), copy the installed compil.ps1 / compil.sh somewhere else, edit the copy, and point the ashell.compileWrapperPath setting at it. You then own that copy: when an extension update changes the task <-> wrapper interface, the extension warns you after a build, and you'll need to merge your changes into a fresh copy.

Updating to 1.8.0

Before 1.8.0, setting up the compiler meant copying compil.ps1 / compil.sh into your workspace's aux-files folder and adding an "A-Shell Compile" task to tasks.json by hand. The extension now provides both, so:

1. Remove the old task: run Tasks: Open User Tasks (and/or open your workspace's .vscode/tasks.json) and delete the "A-Shell Compile" object from the tasks array. If you'd customized any of its presentation settings, re-apply them as described under Customizing the build above. (If the old task is still run, the extension warns you.)
2. Move your compiler switches into the settings: take the optional switches from the old wrapper's $cmd_args line -- everything except -ini, -n, -l, -b, -so / -s, -z and the file name -- and put them in the ashell.compilerSwitches setting (e.g. -i -w:5000 -x:2 -px -a -m -lf).
3. Move any other wrapper customizations into hooks (see above). If that's not possible, use ashell.compileWrapperPath with an edited copy of the new wrapper instead.
4. Retire the old wrapper: back up and remove aux-files\compil.ps1 / aux-files/compil.sh (nothing runs them any more). Keep the aux-files folder if it holds your hooks.
5. Check your presentation options: the PROBLEMS tab is now brought forward on compile errors by the extension itself (the ashell.revealProblemsOnErrors setting), so revealProblems no longer needs to be set anywhere. If your old task had other presentation settings you want to keep, re-apply them as described under Customizing the build > Task properties above.

For more information

• Visual Studio Code's Markdown Support
• Markdown Syntax Reference