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 (both for 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.

Release Notes

[1.6.0] - 08-Aug-26

• Fixed syntax highlighting for the XOR, MAX, MOD, and EQV operators (never highlighted before) and USING (was highlighted with the wrong color, grouped in with I/O statement keywords) -- all five now highlight the same way as AND/OR/MIN, which were already correct.
• Added a new setting, ashell.promptOnExternalChange (default: on), to disable the Load Changes / Keep Editor Version prompt added in 1.5.0 for users who don't want it -- available in Extension Settings alongside ashell.miameIniPath.
• Completion after a DEFSTRUCT-typed variable's . (e.g. sum. where MAP1 sum, ST_TOTALS was declared) is now narrowed to just that struct's own fields, instead of the full catalog/declaration list. If the variable was declared with that struct type more than once (e.g. once per routine), fields from every associated struct are combined. Falls back to the normal full list when the variable isn't a known struct type.

[1.5.0] - 05-Aug-26

• Completion (and Tab-to-accept) now only offers items whose text literally starts with what you've typed, computed and filtered server-side on every keystroke -- fixes a real regression where, e.g., typing xxx.bsi and hitting Tab could replace it with xxx.BITOPS, because VS Code's own client-side fuzzy matcher treated "bsi" as a (non-contiguous) subsequence of "BITOPS". wordPattern/filterText behavior for existing sigils (++, $$, $, %, .-prefixed names) is unchanged.
• When an open A-Shell file is changed by another program (e.g. a compile, or an external editor), you're now always prompted to either load the change into the editor or keep what's currently open -- previously, a file with no unsaved changes was silently reloaded with no way to opt out.
• Added all XCALL MIAMEX, MX_xxx opcodes (~165) and XCALL AUI, AUI_xxx classes as recognized keywords, with hover and "Go to Documentation" support -- e.g. hovering MX_ROUND or right-clicking it now works exactly like any other built-in.
• Added the GDI Print Directives (//SETFONT, //RECTANGLE, //IMAGE, //SETPEN, and 36 others) as recognized keywords with hover, completion, and "Go to Documentation" -- these are unlike every other keyword in this extension in that they're processed by the print spooler at runtime, not the compiler, so they only ever appear inside a string literal (typically the entire argument of a PRINT to the print channel); recognized there accordingly, not as a bare source-level token. Not included this round (not corroborated as this same kind of directive): ORIENTATION (only found under the unrelated printer.ini directives) and the %#/Totpages page-count token (doesn't look like a //NAME directive).
• readme.md's Release Notes had fallen a full version behind changelog.md (missing 1.4.4) -- caught up, and both files should be kept in sync on every release going forward.

[1.4.4] - 02-Aug-26

• Added a "Go to Documentation" right-click context-menu command: for a built-in token under the cursor (function, statement, pragma, XCALL subroutine, tab10/AG_ function), opens the external browser to that token's page on the microsabio.net A-Shell manual (https://www.microsabio.net/dist/doc/conref/). Backed by a new "doc" field on every spec/catalog/*.json entry (see spec/catalog/SCHEMA.md), auto-populated by extension/scripts/build-doc-links.js from references/manual-index.md -- exact per-item manual pages where one exists (most XCALLs, many statements/pragmas/tab10 functions), a category-level manual page otherwise (most system functions land on a shared page like numericfunctions.htm, not one of their own). Individual entries can be hand-corrected directly in the catalog JSON.

[1.4.3] - 26-Jul-26

• Fixed a regression where a ! comment following a & line-continuation (e.g. Function fn'foo(arg1 as f6, & ! comment continuing on the next physical line) terminated the logical line early -- the comment now only affects the remainder of that one physical line, matching the compiler. This was most visible in Hover, which showed a declaration as having only the parameters that appeared before the comment.
• $COPY now defaults to a .CPY extension when the filespec has none ($COPY ABC behaves as $COPY ABC.CPY), matching the compiler.
• compil.exe 1.0.1086 update fixes a problem with mapping current directory to a DevPPN when %CurrentDirectory% used as a DEVICE definition.
• compil.exe now ships with the extension and installs/updates itself to %LOCALAPPDATA%\ashell\compil.exe on activation -- one shared copy per workstation, kept up to date automatically; compiler/compil.ps1's default $cmd points there. See the Compiler section above.
• Added an Outline view (Ctrl+Shift+O / breadcrumbs) listing FUNCTION and PROCEDURE declarations plus DEF* directives (DEFINE, DEFTYPE, DEFSTRUCT, DEFALIAS, DEFXCALL) for the currently open file (not files reached via ++include).

[1.4.2] - 21-Jul-26

• Added catalog entries (hover + syntax highlighting) for nearly all of the random-file, sequential-file, and ISAM-A file I/O statements that were previously unrecognized: READ, READL, READ'READ'ONLY, WRITEL/WRITEN/ WRITELN, the XREAD/XWRITE/XUNLOKR family, UNLOKR, ALLOCATE, ALLOCATE'INDEXED, SET'RECNO, FILEBASE, FIND/FIND'NEXT/FIND'PREV, the full GET/GET'NEXT/GET'PREV family (plus 'LOCKED/'READ'ONLY variants), UPDATE'RECORD, CREATE'RECORD, DELETE'RECORD, RELEASE'RECORD/RELEASE'ALL, INDEXED'STATS, and ISAM'PUSH/ISAM'POP -- along with the OPEN/XOPEN mode keywords (RANDOM, RANDOM'FORCED, INDEXED, INDEXED'EXCLUSIVE, ISAMP'INDEXED, ISAMP'INDEXED'EXCLUSIVE) and modifiers (WAIT'RECORD, WAIT'FILE, READ'ONLY, SPAN'BLOCKS, END'FILE). Also fixed a syntax-highlighting typo (xwritenl -> xwriteln) and added the missing XOPEN keyword.
• Fixed hover on the ISAM-A GET statement incorrectly showing the documentation for the unrelated XCALL GET subroutine (and the same latent confusion for INPUT/PRINT, which are also both a statement and an XCALL name) -- hover now tells them apart by whether the name is preceded by XCALL or starts its own statement.
• Fixed a performance/stability issue where editing a file with a large ++include closure could peg the CPU and eventually make the server unresponsive ("no instance" errors on Build): every keystroke re-read and re-indexed the entire include chain from disk with no debounce and no cache. Edits are now debounced (300ms) and serialized per document, and unchanged include targets are served from an in-memory cache instead of being re-read/re-tokenized on every reindex.

[1.4.1] - 18-Jul-26

• $COPY now finds a target sitting in the current directory (next to the file containing the directive, or next to the main program), matching the compiler.
• Complete syntax highlighting for the conditional compilation directives: ++IFLBL/++IFNLBL/++IFMAP etc. now highlight in full (no more half-blue "++IF" + white "LBL"), and ++ELIF/++ELIFDEF/++ELIFLBL/++ELIFMAP are recognized. ++INCLUDE'IF'EXISTS also highlights in full now.
• Ctrl+Right / Ctrl+Shift+Right in A-Shell files now stop at the start of the next word or punctuation run instead of its end — e.g. with the cursor at the end of the code in xxxxx ! comment, Ctrl+Shift+Right selects just the whitespace up to (but not including) the !.

[1.4.0] - 14-Jul-26

• Smart search (ctrl+alt+g) was only looking at the first folder in the workspace
• Allow for each folder in a multi-folder workspace to override the common miameIniPath.
• Pass the current miame.ini spec into the compil.ps1

[1.3.2] - 13-Jul-26

• Fix problem with ashell.miameIniPath not being recognized (when miame.ini not in the root directory of the workspace).

[1.3.1] - 13-Jul-26

• Fixed ++include/$COPY resolution when the target's DEVICE= entry points at a UNC share (e.g. DEVICE=DSK43: "\\JACKX1\vm\miame\dsk43\").

[1.3.0] - 10-Jul-26

• Fixed annoyance with treating literal file channel references as color a color decorator
• Support the $COPY directive
• Support ++INCLUDE'IF'EXISTS
• Hitting the build command (Ctrl+Shift+B) from the context of include file that was accessed via a Go To Definition operation should now revert to compiling the main program. (This is mainly a convenience to deal with the common scenario where you compil a program, it reports errors in an include file, which you then Go To, fix, and hit Ctrl+Shift+B to re-compile. Aside from saving you the hassle of having to first figure out what happened, then click back on the main program and re-execute the build command, it also eliminates the accumulation of useless RUN and LSX files for include files.)
• Add tracing improvement. To activate, open the Command Palette (Ctrl+Shift+P) and click on the A-Shell: Toggle Language Server Tracing, after which there'll be a lot more stuff output to the Output panel when you open a file.

[1.2.2] - 09-Jul-26

• Packaging-only update: picks up manual edits to readme.md,compiler/compil.ps1, and samples/demo.bas. No server/client code changes.

[1.2.1] - 08-Jul-26

• Fixed a bug in Signature Help

[1.2.0] - 07-Jul-26

• Go To Definition, Hover, Completion, Diagnostics, Folding, and Signature Help added on top of the original syntax-highlighting-only extension, via a real Language Server (vscode-languageserver).
• ++include resolution via A-Shell's DEVICE/ERSATZ file system (ashell.miameIniPath setting).
• Indexing scoped to the union of currently-open documents' own ++include closures, not a whole-workspace scan -- a same-named declaration in an unrelated file elsewhere in the workspace tree no longer shows up as a spurious extra match, and indexing cost no longer scales with workspace size. Check the "A-Shell Language Server" Output channel for <uri> reaches N file(s) via ++include to verify this per file opened.
• Signature Help is now aware of ASB's named-parameter calling convention (arguments in any order): typing name= highlights that exact parameter regardless of its declared position, and highlighting is suppressed (rather than guessing the wrong "next" parameter) once a named argument has already been used earlier in the same call.
• Toggle Marked Comment command (ctrl+shift+1).
• Auto-indent on Enter for block constructs.

1.2.1 [Release from MicroSabio] - 05-Jul-26

• Support function signature dynamic help
• Support Ctrl+Shift+1 to toggle/comment marked lines (using "!>!")

1.2.0 - 05-Jul-26

• Add dynamic scoping (based on file opening/closing)
• Support Go To Definition
• Support Hover

1.1.0 - [MicroSabio Fork] - 04-Jul-26

• Add an LSP to the 1.0.4 extension (several iterations assistance by Claude/Sonnet 5)
• Train it with ashref.md June 30, 2026 version

1.0.4 [Update from OmniLedger]

• unknown details

1.0.3 [Release]

• Fixed collapsible sections for routines (labels)
• Fixed highlighting for file channels
• Fixed file associations, the list under features should now trigger the A-Shell language correctly

1.0.2

• Compilation PS script compil.ps1
• Comments to compil.ps1
• compil.ps1 can now handle directory references with spaces

1.0.1

• Improvement to the Regex for all keywords
• More methods

1.0.0

• Created basic functionality for the Syntax Highlighter using Text Grammars
• A large selection of basic keywords, methods and functions

Compiler

compil.exe now ships with the extension. It's copied to %LOCALAPPDATA%\ashell\compil.exe the first time the extension activates, and re-copied there automatically whenever a newer extension version bundles a newer compiler -- one shared copy per workstation, kept up to date along with everything else, no separate download needed. compiler/compil.ps1's $cmd already points at that location by default; open compil.ps1 and edit $cmd yourself if you'd rather run a compil.exe of your own from somewhere else.

1. Open an A-Shell Project Workspace. If you don't have one, open the the highest level folder above your files (e.g. c:\vm\miame), then use Save Workspace As to save it (e.g. asb-code).
2. Create a folder aux-files beneath that folder.
3. Download compil.ps1 from A-Shell Extension Release or https://www.microsabio.net/dist/other/vscode.
4. Add to aux-files folder (e.g. c:\vm\miame\aux-files\compil.ps1**
5. Open compil.ps1 and read the comments for configuration
6. Download https://www.microsabio.net/dist/other/vscode/tasks.json and open it from a temp dir.
7. Open Tasks: Open User Tasks
8. Add the following object to tasks.json (copy and paste from step 6 if desired)

        {
            "label":   "A-Shell Compile",
            "type":    "shell",
            "command": "${workspaceFolder}\\aux-files\\compil.ps1",
            "args": [
                "${file}",
                "${workspaceFolder}",
                "${command:ashell.miameIni}"
            ],
            "options": {
                "cwd": ""
            },
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "presentation": {
                "reveal": "always",
                "revealProblems": "always",
                "focus": false,
                "echo": true,
                "showReuseMessage": false,
                "panel": "shared",
                "clear": true
            },
            "problemMatcher": {
                "owner": "ashell",
                "fileLocation": [
                    "autoDetect",
                    "${fileDirname}"
                ],
                "pattern": {
                    "regexp": "^(\\d+),(.+),(\\d+),(.+),(.+)$",
                    "file": 2,
                    "line": 3,
                    "column": 1,
                    "message": 4,
                    "code": 5
                }
            }
        }

For more information

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