VSCode A-Shell Extension
Skip to Installation Guide to avoid my ramblings.



Updates
[Fix] compil.ps1 - Jorge pointed out that compil.ps1 cannot handle directory references with spaces, this should now not be an issue. See the $cmd_args variable declaration for more details.

Progress

We've made a little progress but it still doesn't have a language server, which would be required to make it really powerful. However, I do use it every day for all of my development work now. This is partly due to the extension, and partly due to the power of VSCode. I won't yammer on about VSCode, it needs to be experienced to fully understand its useful qualities. However, I'll add a few notes about how I use it.

You guys bringing this up has reinvigorated me and as such I've fixed a few bugs in the latest build. When our workload calms down, I'll get the project up and running properly again.

I've added the image of the Hermosa Pier to a) inspire me and b) because it makes this post feel like a 90's software manual .

What can it do?

1. Highlight syntax.
2. Show/hide sections of code, it correctly recognises routines and functions for the most part. It still has a few issues in this area but functions are pretty solid now.
3. Compile with a single command. When running compile locally, it is as fast as APN.
4. List compilation errors with links that snap you to the location of the error when clicked. This should work fine across files/includes.

What can't it do?

1. It won't scan code for errors live although APN doesn't do this either.
2. Go to Definition. Although VSCode's search is very powerful which does circumvent this somewhat.
3. AutoComplete. It can partially do this, however this is using VSCode's built in attempt which can be a little flakey.

All of these issues would be solved by implementing a Language Server, which would really improve things. It would allow for modern code monitoring as seen in languages like Javascript, which would allow you to see errors pop up live as you are typing. This however would take considerable effort to implement.

Useful VSCode Functionality

1. Command Palette (Ctrl + Shift + P) - used to execute many special commands within the IDE
2. File Search (Ctrl + P) - as it sounds, great for your workflow if your workspace is setup correctly
3. Find in Folder (Shift + Alt + F or right-click folder) - similar to a GUI based grep/find in linux, a decent replacement for Go to Definition in APN
4. Tasks: Run Build Task (Ctrl + Shift + B) - run a task, we use this for Compile

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Installation Guide
See each Step below for more detail

1. Download latest Version
2. Install VSCode and Create a Workspace
3. Install VSCode Extension using .vsix file (e.g. ashell-1.0.2.vsix)
4. Add a new Compiler Task in VSCode
5. Customise compil.ps1 Script

Step 1: Download latest Version

1. Go to A-Shell Extension bitbucket
2. Download ashell-1.0.2.vsix (or latest version)
3. Download comil.ps1

Step 2: Install VSCode and Create a Workspace

1. Install VSCode
2. Open VSCode
3. Click File
4. Click Open Folder...
5. Open the highest level folder that contains your A-Shell Files
6. Create a new Folder called aux-files at the top level of this workspace, this needs to be here as it is used by the Compiler Task (see Step 4: Add a new Compiler Task in VSCode)
7. Move compil.ps1 file downloaded in Step 1 in to aux-files

VSCode Workspaces are a little like Projects in APN. There are many reasons to use them, the most important of which is File Search (Ctrl + P) which will search across your open Workspace for files. This is a powerful way to access files without having to use the explorer manually. Another feature I use regularly is Find in Folder (Shift + Alt + F or right-click a folder in the Explorer), which I use in lieu of Go to Definition.

Step 3: Install VSCode Extension

1. Open VSCode
2. Click Extensions (left sidebar)
3. Click the ellipsis (top right of left sidebar)
4. Click "Install from VSIX..."
5. Select the .vsix file downloaded in Step 1
6. Reload your VSCode instance

You should now see A-Shell Language Module in the Extensions list. At this point you are ready to use the Syntax Highlighter but not the compiler!

Step 4: Add a new Compiler Task in VSCode

1. Use the Command Palette (Ctrl+Shift+P) and type "Tasks"
2. Click "Tasks: Open User Tasks"
3. Add the following object to the "tasks": [ ] array;



Step 5: Customise compil.ps1 Script

1. Open up compil.ps1
2. Read the comments in the file
3. You likely will have to change the location of ashed.ini and compil.exe on lines 18 and 19. We have our ashed.ini at the top level of our A-Shell directory and compil.exe is in our local c:/.
4. You may also want to change the compiler arguments but I'll leave that up to you. I've left in what we use, I expect they will work for you. If you don't use certain flags then you may get weird results if you've structured your files in a certain way.

Step X: Stuff that I may have missed but I can't be sure... You can skip this (maybe)!

1. You may need to install and/or update PowerShell on Windows
2. You may want to change your VSCode User Settings to recognise different word separators. Command Palette > Preferences: Open User Settings and add this line after "editor.wordSeparators";

"[ashell]": { "editor.wordSeparators": "`~!@#%^&*()-=+[{]}\\|;:\",.<>/?" },

We use this REGEX because we use apostrophes in our variable/routine/function names e.g. PRINT'ALL'TENANTS. If you didn't have the above set, then when you double-clicked PRINT'ALL'TENANTS it would treat PRINT, ALL and TENANTS as separate words. A minor annoyance.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
General Information

Now when you run the Command Palette > Tasks: Run Build Task (Ctrl + Shift + B) VSCode will attempt to run compil via the compil.ps1 script on any file you have focused in VSCode! If everything is setup correctly, then this should result in a short "Building..." loading spinner followed by the Problems tab being populated (or not, if there are no errors in the file).

The extension should automatically switch VSCode's Language to A-Shell when opening the following list of file extensions. If it doesn't then you can manually assign a language to a file by clicking the far bottom right toolbar and selecting A-Shell or use Command Palette > Change Language Mode.

.bp .bas .bsi .map .max .bav .mav .r10 .r11

The Compiler

The file compil.ps1 is a wrapper script for the compil operation, it passes the run command with the required arguments to compil.exe. It then outputs a temporary file which is parsed by VSCode, the result is shown in the Problems panel. The compil.ps1 script is only required to re-order this data and if compil.exe were able to output the format we require, then we could cut this step out.

tasks.json allows this format to be customised however after some experimentation it does appear to require certain elements (such as Column #). For this reason the first part of each line in the problems file is 1 (a fake column number). An example line would be as follows;

column, filename, line #, error, code

1, dsk11\077251\tenjson.bas, 429, Unmapped variable: COMPNY'NO, 123
1, dsk11\077251\tenjson.bas, 430, Your code is terrible, 123

Future Development

Let me know in a reply below if I've missed any commonly used A-Shell file extensions, or if there are keywords/functions/compiler statements I've missed. I've been adding to the syntax highlighter as I've been doing day to day work, so I have no doubt that I am missing a bunch of these.

At some point soon™ I'll open source the main BitBucket Repo so that you guys can pull down the source and add/change whatever you want. I'll also get the documentation on the extension sorted, as it is a mess at the moment.

Once this is done, I'll happily hand-over the project to Microsabio, if you guys want it. Otherwise it can remain a community project!

Publishing the Extension

If MicroSabio have a Microsoft corporation account, then feel free to publish it. I am not sure if there is any reason to until the extension is a little more fleshed out. I was going to do this under the OmniLedger umbrella but we use our corporation account fairly heavily.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

P.S. I realise I've stolen MicroSabio's company logo for use in this extension, please let me know and I'll remove it. However, I consider the extension to be the property of the MicroSabio community and withhold no rights (outside of bragging) for myself or for OmniLedger.

I'm speechless. (But when I do regain that faculty, I'll call off the trademark lawyers. :D)

Now I just need to find a deserted beach where I can be alone with this for awhile. If you don't get any immediate feedback, it's because the satellite link has gone down.

Many, many thanks!

Hi Matt,
This is absolutely awesome and excelent documentated.
I'm just afraid that you're not aware about how we are picky with the things we like and this looks absolutely yummy :-)

Anyone knows how can I workaround my OneDrive path which has spaces in the middle?
I confess that didn't investigate deeper because it was so easy to reach the compilation point.

Many, many thanks hopefully this project will find a lot of fans and chances to get improved a lot.

Jack, maybe you can join me here, there are a lot of hidden beaches without internet access

I was able to compil without errors after:
1. move compil.exe and miame.ini to c:\temp
2. assign c:\temp to $workingDirectory and $cmd in compil.ps1

But, besides I see the "building" message after pressing CTRL+SHIFT+B inside of a .bas file and no message is displayed in the Problems panel, it doesn't generate any RUN file, also, if I force any error in the code, no error message show up in the Problems panel.
Any tip about what's missing or where to look for?

Anyway, the code looks great!

Thanks for the offer Jorge, it's pretty tempting. The only problem I can envision is that with the amount of partying down there, there might not be enough time in the day to code. (Not that that's a bad thing! And not that I got much done here today either, with all of the phone and internet interruptions!)

But I may have a tip for you on the compil. You may need to switch to the TERMINAL panel to see errors related to the compil.ps1 script. (I had edited the $cmd_args line but had a missing quote that was causing the script to abort.) For the record, here's what I changed it to...

Another obstacle was this security warning (also appearing only in the TERMINAL panel) ...

If I answer R, then it compiles, showing something like the following in the TERMINAL panel...

I entered the following (also in the TERMINAL panel to unblock the script...

One other tip: It appears that Ctrl+Shift+B does not automatically save the file, so if you're trying to deliberately introduce a syntax error to see how the compiler handles it, make sure to save the file after the change. On the other hand, VSCode appears to not only detect changes to the file made outside the editor (such as if you are running APN and VSCode side-by-side with the same files), but instead of warning you about the change, it automatically reloads the updated file into the editor.

Beyond that I haven't had time yet to really dig into it.

Hi Jack,
Well, the offer is open.
Correct, I also had to execute the unblock-file to avoid the need to confirm on each execution and, yes, was saving the file to apply changes and, yes, I checked in all panels for output messages, anyway thanks for mention that.

Doubts:
1. in the compil.ps1, is this correct?

I'm using the arguments copied from my APN compile command.

2. To apply the changes in compil.ps1, do I have to save, exit VSC and reenter?

3. I had to switch the Encoding of my sources to get my portuguese accented sentences displaying correctly, to do it globally for A-Shell I've adjusted settings.json to:

The default encoding was UTF-8, do you know if the right one is Windows 1252?
It displays fine using it, but there are other encodings that also produces the same result.

4. If I change the "c:\temp" path to "C:\Users\User\OneDrive - Umzero\desenvolvimento\soft\dsv" in $workingDirectory and $cmd , it complains truncating the path to "C:\Users\User\OneDrive ".
I tried to enclose the path in apostrophe inside the quotation marks w/o success, no surprise :-)

Apparently, my compile is breaking in some place but without echoing the problem.

Don't feel any pressure to reply this, probably, neither me will get back on this today and I believe that my doubts above are generic for VSC to which I should be able to find answers with some searches.

Have a nice day

You're very welcome gents! I'll happily come join you guys on the beach... the weather in the UK is bonkers even by UK standards .

I should have documented our journey from inception really as I've found it a little tricky remembering the bits that we've jury rigged along the way. Hence Step X above! I'll keep sifting through my notes and see if I can find any other nuggets. Documenting all of your fixes and tweaks on the forum will help a lot!

It'd be great to get the syntax and compil bundled up in to the same Extension, which I think maybe doable. It is only really tricky because we all potentially use different settings.

It is interesting to note that if compil.exe were able to spit out the column (rather than the 1 we are using as a placeholder), then the little red underline would be able to point the user directly to the error, rather than just the line number.

@Jorge

1. This looks right to me, however see my answer to 4 below.
2. No, no need to restart VSC. If there is a little white circle next to the filename in the top tab then it means the file is unsaved. Every time you press Compile, it will go and get the most recent compil.ps1.
3. I won't answer this one, don't know I am afraid .
4. The spaces in the longer directory reference are causing parsing errors in the the final command, you should be able to just do this change;

From:


To:


In essence, this just wraps the directory references in double quotes, which makes the shell treat it as a string (and stops the spaces from breaking things).

EDIT: After re-reading your first problem, I think the issue is that assigning the $cmd="C:\temp\compil.exe" will only solve one of your problems. The reason you aren't getting a compiled file out the end is both strings are getting messed up as I am assuming your .bas files are in the same "C:\Users\User\OneDrive - Umzero\desenvolvimento\soft\dsv" location.

If you do Fix 4 above, it should resolve all of your issues (hopefully). Also this fix should allow you to use directory references to wherever you want.

Now Compiling with success ... Thank you very much

Excellent! No problem, happy to help.

It seems we've come a long way from dreaming about growing up to rescue people from burning buildings or drive race cars to figuring out how to embed spaces inside of nested single and double quotes! But I'm glad that problem is solved.

As for your comment Matt about the compiler identifying the column number where an error occurs, I gave some thought to it awhile ago, but set it aside because by that time, the compiler was already doing a fair amount of reformatting of input lines before it started syntax checking. (Concatenating continuation lines, remove the embedded comments, replacing defined symbols, etc.) Which makes it (at least seem to be) difficult to work backwards from the location of the error in the massaged buffer to the location in the original source line. Or change the order of processing so that the syntax checking occurs before the reformatting. I took the easy way out, rationalizing that in most cases the location of the error could be identified by the variable name or other symbolic clue. But in the context of VSC maybe it's time to revisit that.

I have nightmares about poorly nested code , forget burning buildings!

Indeed! I agree, Jack. It is very much just a "nice to have" and I don't think it's really required for A-Shell as the culture around the code has been to keep files lanky (tall and thin) rather than some other languages that can get wider.

I think the row being labelled as having an error is more than enough.