Sheerpower

Write, build, run and debug Sheerpower programs (.spsrc, .spinc) in Visual Studio Code. From Touch Technologies, Inc.

It brings together the features of Sheerpower Scripting (the language server), Sheerpower Scripting Debug (the debugger) and Smart Copy. The older Sheerpower extensions stay available, unchanged, for installations that keep them. On a machine with both, choose this one for Sheerpower files:

"files.associations": { "*.spsrc": "sheerpower", "*.spinc": "sheerpower" }

What it does

• Language server -- reads your program and its %include files, starting from the root .spsrc: hover shows a routine's header comment, completion offers routine calls, F12 goes to a routine, and the Explorer gets Routines and Included Files views. A file is parsed again 3 seconds after you stop typing.
• Validate, run, deploy with sp4gl.exe (in c:\sheerpower, or the folder the setting sheerpower.debugger.sp4glOverridePath names): errors, warnings and %todo lines go to the Problems panel, each error with its Help>> lines. Saving a Sheerpower file validates it (the setting sheerpower.validateOnSave), and an edited line drops its error at once. Validate, Run, Deploy and a debug launch first save every changed file the program reads -- the program and each file its %include lines reach, whatever the extension -- and a validate on save saves them too. Other changed files, another program's among them, are left as they are. A clean build plays a light "ta-da", a build with errors a soft "uh-oh" (the setting sheerpower.sounds).
• On Linux: sp4gl from the sheerpower package (/usr/bin/sp4gl); Run (F5) runs the program in a VS Code terminal. Debug (Ctrl+F5) runs it in a terminal too, the debugger connected.
• Debugger -- breakpoints, stepping, variables (global, local, routine parameters) that can be changed, the program's console output in the Debug Console.
• Snippets for a new file, a routine and a control block; the Sheerpower Default dark theme.
• Smart Copy and Paste (any file) -- see below.

The root .spsrc that includes the other files must be open for the symbols of every file to be found. @ in an include name is the root .spsrc file's folder, as in Sheerpower.

F1 help and abbreviations, as in the console

• F1 in a Sheerpower file opens the console's help for the word or phrase at the cursor (cluster input, end if, len(): a list of the matching entries -- type to search -- and a pane beside the editor with the form, what it does, what to watch out for, an example with what it prints, and a link to its tutorial page. The Command Palette stays on Ctrl+Shift+P. Hovering over a built-in function or system variable shows its help, short (the setting sheerpower.hoverHelp: functions, everything or off).
• Abbreviations: type one with its dot and press Tab -- fo. Tab gives a for loop, its holes the next Tabs. Typing . lists them. Yours, from the console's command file (sp4gl_cmds.txt), come first and replace a built-in one of the same name; one you define at the console works here at once.

Keys

| Ctrl+K B | Read a build log into the Problems panel |

During a debug session F5, Shift+F5 and F6 are VS Code's own: Continue, Stop and Pause; Ctrl+F5 says a session is running.

The Sheerpower meta-key: Ctrl+M

In a Sheerpower file, Ctrl+M -- M for meta -- is the Sheerpower meta-key, a prefix key: press Ctrl+M, let go, then press a letter (with or without Ctrl held). Ctrl+M M -- meta, menu -- lists the commands; choosing one runs it.

| Ctrl+M C | A new Sheerpower console -- the REPL -- in the folder of the file being edited (its own window; on Linux a terminal) | | Ctrl+M F | Go to a routine, or routine.line (path_combine.10) as Sheerpower reports a location |

| Ctrl+M L | Go to a line of the current routine | | Ctrl+M M | The list of these keys, in this order | | Ctrl+M O | Organize the routines in calling order | | Ctrl+M R | A new routine with its header at the cursor; with lines selected, they become the new routine | | Ctrl+M S | Smart Copy and Paste |

• Organize (O): the main code stays first; the routines follow in the order they are called -- the main code's calls in order, and right after each routine its local routines, then the other routines it calls. A routine always comes below every routine that calls it: one called from several routines goes below the last of them. Routines nothing calls stay at the end, in their order. Each routine takes the comment block above it along; a handler or a module moves as one block. Between the end of one routine and the comment header of the next, and after the main code, there are always three blank lines -- Ctrl+M O spaces them so even when the order is already right; what follows the last routine is left as it is. If code sits between or after the routines, nothing is moved. One Ctrl+Z puts everything back.
• Align (A): each paragraph is aligned on its own (a blank line or an empty ! line ends one), and comment lines and code lines are aligned apart, so a whole routine header can be selected at once.
• Routine (R): asks for the name (it must contain an underscore) and the parameters (amount, rate = 0.1, returning total, or nothing). The new routine never goes inside another routine or into the middle of the main code: then it goes after that routine, or after the main code. It gets three blank lines above it and below it, as Ctrl+M O spaces routines. Tab moves through the header's four sections. With lines of a routine selected, they become a local routine of it: no parameters -- it shares the routine's variables, a private routine's own ones too -- the call local name takes their place, and it goes right after the routine (and the local routines already there). Lines of the main code become a plain routine after the main code, called with its parameters named (calc_part with amount, rate, returning total), so the variables of those names are passed. Watch for exit routine in the selected lines. In the routine it left the routine; in the new local routine it leaves only the local routine, and the routine carries on after the local name call -- quietly: the compiler finds nothing wrong. Rework such lines first, for example by setting a flag in the local routine and testing it after the call: if done? then exit routine.

Outside Sheerpower files Ctrl+M keeps VS Code's own meaning (Toggle Tab Key Moves Focus). In a Sheerpower file that toggle -- which, hit by accident, stops Tab from expanding abbreviations -- is still in the Command Palette.

Smart Copy and Paste

Copies the paragraph above the cursor once for each value in a list, replacing a placeholder word with the value in the placeholder's case. Put the cursor below the paragraph, run Smart Copy and Paste from the Command Palette, give the placeholder (placeholder) and the values (east, west):

total_placeholder = 0  ! the Placeholder total

becomes, below the cursor,

total_east = 0  ! the East total

total_west = 0  ! the West total

Settings

All under sheerpower.: the language server's (maxNumberOfProblems, maxCodeCompletionItems, recursiveSearchForRoutinesByRootSpsrc, recursiveSearchForRoutines, recursiveParseFiles, defaultIncludesExtensionsAsSpinc, skipFirstTwoLinesOfCommentBlock, maxFileSizeToParse, trace.server) and the debugger's (debugger.trace, debugger.stopOnEntry, debugger.sp4glOverridePath, program.arguments, mirrorOutput, exceptions.*). The older extensions' names (sheerpowerBasic.*, sheerpower-debug.*) are not read: CHANGELOG.md lists the new names.

Building it

npm install          (installs client\ and server\ as well)
npm run compile

F5 in this folder ("Launch Client") opens VS Code with the extension loaded; vsce package makes the .vsix.

Thanks

Thanks to Chris Turner for his hard work.