Compiling JSS Files with SCompile.exe

Set Up For Visual Studio Code/VSCodium

Why

I typically code outside of the Script Manager. I do my JAWS Script writing using VSCode, Positron, Theia, or Zed, which is comonly used by coders and programmers for python, R, Java, C#, TypeScript, JavaScript, and other development respectively[^1]¹. I also prefer NVDA as my daily screenreader, so I want to make sure that I can compile my scripts in a way that is maximally accessible to me.

To accomplish this, I use a round-about way to control my terminal outputs to increase screenreader accessibility and ease of browsing Errors.

I create a task in VSCode using a .JSON file². This will call a powershell .ps1 script or else a Command Prompt Batch (.bat) file that contains my actual commands. VSCode submits to the shell script the path of the file I currently have open, which is the one targeted to be compiled.

For this chapter, if you prefer Powershell in your terminal, follow the relavant instructions. If you prefer Command Prompt, follow the instructions for that.

Setup

To set up using SCompile, the following information is needed:

• File path to scompile.exe (typically C:\Program Files\Freedom Scientific\JAWS[year]\scompile.exe).

• VSCode, VSCodium, Code OSS, Positron, Theia, Mr. Code, or another compatible editor.

• Administrator Rights for running VSCode (Otherwise VSCode cannot run scompile.exe in an Elevated (Admin) terminal)

  OR

• A win-sudo or gsudo installation to allow Elevated Terminal Privileges (preferred)

To run scompile as administrator, one of the following need to be performed. One can also do both, but it is redundant.

1. To Open VSCode with Admin rights

   • When on the icon for VSCode, press ALT + ENTER to open Propertie

   • Navigate to "Compatibility" tab

   • Select "Run this Program as Administrator"

   Now when you open the program, and Administrator prompt will appear and all actions in the terminal will be run with Admin rights.

2. To install gsudo or win-sudo

   • In command prompt or powershell, type "winget install gsudo" or "winget install win-sudo" and follow the prompts

   Now when you open the program, you can type "gsudo" or "win-sudo" in the terminal before the command you want to run with Admin rights.

The steps to setting up a Task to run the necessary commands, the following steps need to be followed in order:

1. Press ALT, then T for Terminal

2. Press C for Configure Task

3. Press DOWN ARROW to "Create tasks.json file from template"

4. Press DOWN ARROW to "Others" and press ENTER

The resulting .JSON file looks like this³:

{
    "version": "2.0.0",
        "tasks": [
            {
            "label" : "echo",
            "type": "shell",
            "command": "echo Hello"
            }
        ]
}

Copy and paste the appropriate data into the appropriate sections and add an "args" section so the tasks.json looks like this if you open VSCode:

1. Use with Powershell

   {
       "version": "2.0.0",
       "tasks": [
           {
               "label": "compile",
               "type": "shell",
               "command": "pwsh",
               "args": [
                   "-File",
                   "workspaceFolder/compile.ps1",
                   "file"
               ],
               "group": {
                   "kind": "build",
                   "isDefault": True
               },
               "problemMatcher": {
               "owner": "custom",
               "fileLocation": ["absolute"],
               "pattern": {
                   "regexp": "^file (.*), line (\d + ), column (\d + ): Error: (.*)\$",
                   "file": 1,
                   "line": 2,
                   "column": 3,
                   "message": 4
                   }
               },
               "presentation": {
                   "reveal": "always",
                   "clear": True,
                   "showReuseMessage": False,
                   "echoCommand": False
               }
           }
       ]
   }
   

   Now create the following file in your User scripts directory (typically "C:\Users\AppData\Roaming\Freedom Scientific\JAWS[year]\Settings\enu"):

   Name the file "compile.ps1".

   The full path for the file is now "C:\Users[user]\AppData\Roaming\Freedom Scientific\JAWS[year]\Settings\enu\compile.ps1"

   • Option 1: VSCode launches with Admin rights.

     param (
         [String]\$filePath
     )
     If (-Not filePath) {
         Write-Error "No file path provided."
         exit 1
     }
     # Run the compiler and capture the output
     \$output = & "`C:\Program` Files\Freedom Scientific\JAWS\2024\scompile.exe" \$filePath 2>&1
     # Print the compiler output
     \$output
     # Check the exit status of the compiler
     If (\$LASTEXITCODE -eq 0) {
         Write-Output "\$filePath Compiled Successfully"
     } else {
         # Print the exit message
         Write-Output "The terminal process terminated with exit code: 1."
     
         # Print the error message again
         \$output -match "Error.*" | ForEach-Object { Write-Output \$_ }
     }
     

   • Option 2 (preferred): Run in an elevated Terminal prompt

     param (
         [String]\$filePath
     )
     If (-Not filePath) {
         Write-Error "No file path provided."
         exit 1
     }
     # Run the compiler and capture the output
     \$output = & sudo "C:\Program Files\Freedom Scientific\JAWS\2024\scompile.exe" \$filePath 2>&1
     # Print the compiler output
     \$output
     # Check the exit status of the compiler
     If (\$LASTEXITCODE -eq 0) {
         Write-Output "\$filePath Compiled Successfully"
     } else {
         # Print the exit message
         Write-Output "The terminal process terminated with exit code: 1."
     
         # Print the error message again
         \$output -match "Error.*" | ForEach-Object { Write-Output \$_ }
     }
     

2. Use with Command Prompt

   Create the following file in your User scripts directory (typically "C:\Users\AppData\Roaming\Freedom Scientific\JAWS[year]\Settings\enu"):

   Name the file "compile.bat".

   The full path for the file is now "C:\Users[user]\AppData\Roaming\Freedom Scientific\JAWS[year]\Settings\enu\compile.bat"

   {
       "version": "2.0.0",
       "tasks": [
           {
               "label": "compile",
               "type": "shell",
               "command": "pwsh",
               "args": [
                   "-File",
                   "\${workspaceFolder"/compile.ps1},
                   "\${file"}
               ],
               "group": {
                   "kind": "build",
                   "isDefault": True
               },
               "problemMatcher": {
               "owner": "custom",
               "fileLocation": ["absolute"],
               "pattern": {
                   "regexp": "^file (.*), line (\d + ), column (\d + ): Error: (.*)\$",
                   "file": 1,
                   "line": 2,
                   "column": 3,
                   "message": 4
                   }
               },
               "presentation": {
                   "reveal": "always",
                   "clear": True,
                   "showReuseMessage": False,
                   "echoCommand": False
               }
           }
       ]
   }
   

   • Option 1: VSCode launches with Admin rights.

     @echo Off
     setlocal
     set "filePath=%~1"
     If "%filePath%"==" " (
         echo No file path provided.
         exit /b 1
     )
     rem Run the compiler and capture the output
     "`C:\Program` Files\Freedom Scientific\JAWS\2024\scompile.exe" "%filePath%" 2>&1
     rem Check the exit status of the compiler
     If %errorlevel% equ 0 (
         echo %filePath% Compiled Successfully
     ) else (
         rem Print the exit message
         echo The terminal process terminated with exit code: %errorlevel%.
         rem Print the error message again
         For /f "tokens=* delims=" %%i in ('"`C:\Program` Files\Freedom Scientific\JAWS\2024\scompile.exe" "%filePath%" 2^>^&1 ^| findstr /r "Error.*"') do echo %%i
         )
     

   • Option 2 (preferred): Run in an elevated Command Prompt

     @echo Off
     setlocal
     set "filePath=%~1"
     If "%filePath%"==" " (
         echo No file path provided.
         exit /b 1
     )
     rem Run the compiler and capture the output
     sudo "C:\Program Files\Freedom Scientific\JAWS\2024\scompile.exe" "%filePath%" 2>&1
     rem Check the exit status of the compiler
     If %errorlevel% equ 0 (
         echo %filePath% Compiled Successfully
     ) else (
         rem Print the exit message
         echo The terminal process terminated with exit code: %errorlevel%.
         rem Print the error message again
         For /f "tokens=* delims=" %%i in ('"C:\Program Files\Freedom Scientific\JAWS\2024\scompile.exe" "%filePath%" 2^>^&1 ^| findstr /r "Error.*"') do echo %%i
     )
     

To speed up the keystrokes necessary to get to the Run Task dialog (currently 4 keystrokes at least), we can assign a keystroke to the Run Task command directly.

• Press CONTROL + K,release the K while keeping the CONTROL button down, and press K again

• "Tasks: Run Task" into the form field and press \

• Press DOWN ARROW to Run Task, it is the second one down. You are now placed in a form field labelled "Press desired key combination and then press ENTER"

• Press the desired shortcut combination and press ENTER. The program tells you if you are using a repeated keystroke. I used CONTROL + ALT + ; since it was not already being used.

Now you can press CONTROL + ALT + ; (semicolon) then just hit ENTER since scompile is the top run task available. It will bring up a drop down with output scanning options.

This will open a terminal on the bottom of the screen --either Powershell or Command Prompt depending upon your selected preferences -- and run the task of compiling the .jss file. If successful, the terminal output states

::: leftbar C:\ProgramData\Freedom Scientific\JAWS[year]\Scripts\enu[script.jss] Compiled Successfully :::

If there is an error, the following will be output to the terminal:

::: leftbar Compiling C:\ProgramData\Freedom Scientific\JAWS[year]\Scripts\enu[script.jss]

file C:\Users[user]\AppData\Roaming\Freedom Scientific\JAWS[year]\Settings\enu[script.jss], line XX, column XX: Error: Unexpected word XX

The terminal process terminated with exit code 1

file C:\Users[user]\AppData\Roaming\Freedom Scientific\JAWS[year]\Settings\enu[script.jss], line XX, column XX: Error: Unexpected word XX :::

If you press CONTROL + SHIFT + M and access the Problems tab, the top entry will be this:

::: leftbar Unexpected word XX [Ln XX, Col XX] :::

When you highlight the Error, the cursor for the editor moves to the line with the error and highlights it. Pressing F6 a few times moves the editing cusor there. Or else you can just use the line and column of the error to get to it

VS Code-Based Code Editors Summary

Given the popularity of Visual Studio Code and its open-source core Code-OSS, many editors and IDEs have been built on top of, or are compatible with, the VS Code base. The table below summarizes some of the notable editors and IDEs in this ecosystem, highlighting their relationship to VS Code, form factors, and key notes. My focus on these editors over others is the fact that accessibility tools work out of the box with them, making them suitable for JAWS scripting without a large amount of additional configuration. I am providing this list and diagram as a resource to alllow you to choose your preferred editor while still being able to follow along with the instructions in this book.

graph TD
    subgraph core["🔵 Core"]
        codeoss["Code-OSS<br/>(VS Code Open Source core)"]
        rawbuild["Code-OSS<br/>(raw builds)"]
    end
    
    subgraph forks["🟢 Forks / Distributions"]
        vscode["Visual Studio Code"]
        vscodium["VSCodium"]
        cursor["Cursor"]
        positron["Positron"]
        mrcode["MrCode"]
    end
    
    subgraph servers["🟠 Server / Browser"]
        openvscode["OpenVSCode Server"]
        codeserver["code-server"]
    end
    
    subgraph clouds["🟡 Cloud / Web IDEs"]
        codespaces["GitHub Codespaces"]
        vscodeweb["VS Code for the Web<br/>(vscode.dev)"]
        gitlabide["GitLab Web IDE"]
        gwork["Google Cloud<br/>Workstations"]
        gitpod["Gitpod"]
        sapbas["SAP Business<br/>Application Studio"]
        awsce["AWS SageMaker<br/>Code Editor"]
        coder["Coder platform"]
    end
    
    subgraph theia["🟣 VS Code-compatible"]
        theia_fw["Eclipse Theia<br/>Framework"]
        theiaide["Theia IDE"]
        theia_gen["Theia Yeoman<br/>Generator<br/>(custom IDEs,<br/>Embedded, IoT,<br/>Enterprise, Cloud,<br/>Education)"]
        che["Eclipse Che"]
        codeeditor["Code Editor<br/>(Oracle)"]
        smartface["SmartFace"]
        css["Code Composer<br/>Studio"]
        arduino["Arduino IDE 2.0"]
    end
    
    %% Forks from Code-OSS (solid arrows)
    codeoss --> vscode
    codeoss --> vscodium
    codeoss --> cursor
    codeoss --> mrcode
    codeoss --> rawbuild
    codeoss --> positron
    
    %% Servers from Code-OSS (solid arrows)
    codeoss --> openvscode
    codeoss --> codeserver
    
    %% Cloud services from Code-OSS (solid arrows)
    codeoss --> codespaces
    codeoss --> vscodeweb
    codeoss --> gitlabide
    codeoss --> gwork
    
    %% Cloud services from OpenVSCode Server (solid arrows)
    openvscode --> gitpod
    openvscode --> sapbas
    openvscode --> awsce
    
    %% Cloud services from code-server (solid arrows)
    codeserver --> coder
    
    %% Connection to Theia ecosystem (dashed for compatibility)
    codeoss -.->|compatibility| theia_fw
    
    %% Theia relationships (solid arrows)
    theia_fw --> che
    theia_fw --> theiaide
    theia_fw --> theia_gen
    theia_fw --> codeeditor
    
    theia_gen --> css
    theia_gen --> arduino
    theia_gen --> smartface
    
    %% Styling
    classDef coreStyle fill:#ADD8E6,stroke:#000,stroke-width:2px
    classDef forkStyle fill:#90EE90,stroke:#000,stroke-width:2px
    classDef serverStyle fill:#FFB347,stroke:#000,stroke-width:2px
    classDef cloudStyle fill:#FFFF99,stroke:#000,stroke-width:2px
    classDef compatStyle fill:#DDA0DD,stroke:#000,stroke-width:2px
    
    class codeoss,rawbuild coreStyle
    class vscode,vscodium,cursor,positron,mrcode forkStyle
    class openvscode,codeserver serverStyle
    class codespaces,vscodeweb,gitlabide,gwork,gitpod,sapbas,awsce,coder cloudStyle
    class theia_fw,theiaide,theia_gen,che,codeeditor,smartface,css,arduino compatStyle

The above information is from these sources:

{{#cite ms-code-oss-github}}

{{#cite ms-vscode-site}}

{{#cite vscodium-site}}

{{#cite archwiki-vscode}}

{{#cite positron-migrate-vscode}}

{{#cite posit-blog-positron-guides}}

{{#cite codecademy-cursor-guide}}

{{#cite vibe-coding-cursor}}

{{#cite gitpod-openvscode-github}}

{{#cite devclass-openvscode}}

{{#cite coder-code-server-github}}

{{#cite coder-code-server-docs}}

{{#cite stackblitz-webcontainers-post}}

{{#cite maiertech-codeflow}}

{{#cite eclipsesource-theia-vs-vscode}}

{{#cite theia-language-support}}

{{#cite che-theia-github}}

{{#cite eclipsesource-che-vs-codespaces}}