Popup YouTube Video
Sheerpower Logo

Introduction to the REPL and Interrupting a Running Program


Everything in this section assumes that you have already installed Sheerpower. The install typically takes less than three minutes. Installing Sheerpower on Windows Step-by-Step

To use these post-install tutorials on Windows, you will use the SPDEV IDE that was installed on your desktop, or, on both Windows and Linux, you will use Visual Studio Code with the Sheerpower extensions installed. If you need help getting started, see Writing and Running Sheerpower Programs.

Note: The online Sheerpower tutorials restrict interactive use of certain features, since misuse could cause the server to become unresponsive for other users. This section is intended for developers who have installed Sheerpower locally, where they can safely explore and use all features without such restrictions.

The Sheerpower REPL — Read—Eval—Print Loop

You write Sheerpower programs in SPDEV or Visual Studio Code. This tutorial covers the other half of the development loop: the Sheerpower console you use when you run a program, test a line of code, or press ALT+B to interrupt a program that is already running and then examine its variables, etc.

The console is a REPL — type a Sheerpower statement, variable, or expression, and it is evaluated immediately, with the result displayed at once.

But the console goes beyond simple one-line testing. Using [], you can build new Sheerpower source directly from the console.

When your work grows large enough to need a full editor, simply type edit: the program opens in VS Code, or in the Sheerpower IDE when VS Code is not installed (on Linux, VS Code or the editor you choose).

What follows shows the Sheerpower console at full strength.

You can open the Sheerpower console in several ways: by starting SPDEV, using Visual Studio Code, or typing sp4gl at the Windows command prompt. This launches the Sheerpower console, which functions like a REPL (Read—Eval—Print Loop) found in many other programming languages. A REPL is an interactive programming environment where you enter code, have it evaluated immediately, and see the results printed right away. In Sheerpower, you can also enter multiple statements on a single line by separating them with a backslash (\).


C:> sp4gl ───────────────────────────────────────────────────────────────── SHEERPOWER V011.0nn.nn │ 🎓 Skill 3 · Regular │ KEYS · HELP ───────────────────────────────────────────────────────────────── File 📁 %APPDATA%\Sheerpower\sp4gl_cmds.txt Saved ⭐ 1 Starred 🕘 0 History 🔤 42 Abbreviations >>> a=355 >>> b=113 >>> print a/b 3.1415929203539823 >>> >>> a=355\b=113\print a/b 3.1415929203539823 >>>

Each section below opens with the idea; click a Show me line for the keystrokes and examples, or Expand all.

Printing and Inspecting a Value

There are three ways to see a value at the prompt. print expr is the full statement; as a shorthand, a line that begins with = prints the expression, and so does simply typing the expression on its own line:

>>> a = 355 >>> =a / 113 3.1415929203539823 >>> a / 113 3.1415929203539823 >>>

To inspect a variable — its type and its value — begin the line with ?. Sheerpower prints the variable's typeof$ description, then its value:

>>> a = 355 >>> ?a Name:A, Dtype:Real, *Narrow* 355 >>> >>> dim scores(*) >>> fill scores with 90, 85, 77 >>> ?scores Name:SCORES, Dtype:Real, *Array*, Dims:1, Bounds:1:3, Size:3, *Expandable* 90, 85, 77 >>>

? works on any variable: a scalar, an array (you see its bounds and size, then the elements), or a cluster (you see *Cluster* and its row count).

Tab Completion

Press TAB and Sheerpower completes what you are typing, aware of the grammar at that point in the statement. When one completion fits it is filled in for you; when several fit, the Choices list opens over the bottom of the screen — every choice, narrowed as you type more of the word; Enter or TAB (or a click on one) puts the highlighted choice on the line. A misspelling is corrected to the closest match.

Show me: what TAB completes, and an example

It completes:

  • statement keywords and the options a statement takes (after print you are offered at, using, the screen colors, then the functions);
  • built-in function names;
  • your own variables, arrays, and cluster names;
  • a cluster's members after -> — type cities-> then TAB to list city$, country$, …
>>> cluster cities: city$, country$, population >>> print cit ← press TAB → print cities >>> print cities-> ← press TAB → Choices (3) population country$ > city$ > Filter the choices... Up/Down to move Enter or Tab to use Esc to cancel

F1 — Help for the Word at the Cursor

Press F1 and a help window opens on the word the cursor is on: a statement, a built-in function, a % directive, or a system variable such as _extracted. When the word is part of a statement of several words, the help is for the whole statement: F1 on input in a cluster input line opens cluster input, and F1 on case in select case opens select case. The list shows every entry that matches, the best match at the bottom next to the search line, and the box beside the highlighted entry holds its help — the form to write, what it does, a Watch out note when there is a trap, and an example that ran together with what it printed. Up and Down move through the list and the help follows; type to search for something else; Enter or ESC closes the window and leaves your line exactly as it was.

The last line of the box, See tutorial, is a link: click it and the tutorial page that teaches the highlighted name opens in your browser. The help stays open, so you can go on to the next name.

The mouse works here too: click an entry to show its help, and the wheel moves through the list. To copy an example, drag across it in the help box and press Ctrl/C — the selection stays inside the box, and a line the box had to wrap is copied as the one line it is — then close the help and paste it at the prompt. A one-line example runs when you press Enter; one that spans several lines (a for … next loop, a routine) goes in through [], as Writing a Program in the REPL below shows.

Show me: F1 on len, and what else the help finds
  • The order: the name itself first, then names that start with what you typed, then names that contain it (for a symbol alone, such as --, only the first two). In each group statements and built-in functions come first, then directives and system variables, then other languages' names.
  • When the cursor is on no name, the search starts from the statement the line begins with — open table for an open table line — else from the symbol at the cursor: F1 on -= opens -=, and == says No help matches ==. On an empty line it lists everything.
  • Each key you type narrows the list; BACKSPACE or Ctrl/U widens it again.
  • Type what you want to do instead of a name: find text finds the task cut, find and compare text, whose help lists the functions that do it, each with its form.
  • Names from other languages are there too: F1 on strlen says it is not Sheerpower and that the Sheerpower name is len().
  • While a program is halted, F1 keeps its job of stepping over a line.
>>> total = len(name$) ← cursor on len, press F1 → Help (8) len(str_expr) Returns the length of a string as an integer. Watch out: strings are BYTES: len() counts bytes, so one UTF-8 accented letter counts 2 Example: dim names$(*) fill names$ with "cy", "Ann", "bob" print ucase$(names$) ! CY ANN BOB print len(names$) ! 2 3 3 print filter(names$, len(names$) > 2) ! Ann bob dim clean$(*) clean$ = ucase$(trim$(names$)) ! maps nest other lang strlen() print stats$sum(len(names$)) ! 8 function urlencode$() prints: statement input length CY ANN BOB function htmlencode$() 2 3 3 statement ask table, field: length Ann bob other lang length() 8 other lang len$() > function len() See tutorial > len Up/Down to move type to search Enter or Esc to close

Keys — For a list of special keystrokes available to you

Type keys at the prompt and the console prints a one-screen reference of every special keystroke it understands, grouped by purpose — Editing the line, Completing, Remembering, Running, and the Console words themselves. Everything covered on this page is listed there — TAB completion, F1 help, your abbreviations, Ctrl/R history search, Ctrl/S starring, Ctrl/+ and Ctrl/- for the text size, skill for your skill level, ALT/B to halt a running program — so it is the quickest reminder when you forget a key, without leaving what you are doing.

Show me: the full keys reference
>>> keys The console's keys (the prompt is >>> ; <enter> runs the command) Editing the line - <left> <right> move along the line -- a long line wraps onto the rows below, and the arrows go across them - <end> move to the end of the line - a click put the cursor on that character of the line - <backspace> <del> erase the character before / under the cursor - ctrl/j delete the word before the cursor - ctrl/u clear to the start of the line - ctrl/a toggle insert / overwrite - ctrl/c copy the selected text - ctrl/w redraw the screen - ctrl/+ ctrl/- the window and its text larger / smaller (remembered) - ctrl/0 the window back to its normal size Completing - <tab> complete the word: a keyword, option, function, variable, cluster, or a cluster's member after -> - f1 help for the word at the cursor: the statements and functions that match, the selected one's form, use and an example that ran beside them; type to search, <esc> closes it (a halted program: f1 = step over) - ctrl/e pick an emoji: the starred first, then the last 20 used, then the most used; type to search, <enter> inserts it, ctrl/s stars it, <esc> closes the list - name.<enter> your abbreviation: its text appears on the next line -- <enter> runs it, <ctrl/u> erases it, or edit it first - .<enter> the Abbreviations menu: pick one, its text appears - {table} holes in an abbreviation: <tab> jumps to the next hole, <shift/tab> back; {rate: 0.12} = a default; {nl} lands as \ so the whole block is one runnable line; a {name} value fills every later {name} Remembering - <up> <down> walk back and forth through earlier commands; <down> past the newest: the line you were typing - <home> recall the earlier command that starts as typed - ctrl/r search the history: a list over the screen, starred first, then newest, each with its age; what you type is found anywhere in a command -- type more to narrow it, <up> <down> to move, <enter> puts the command on the line, <esc> leaves, ctrl/s stars; after a ~ the letters need not be contiguous: ~gneve finds Genevieve - ctrl/s star / un-star the command on the line, or the abbreviation whose name is on the line - <pgup> <pgdn> walk the recall list from where you last left it Running - <enter> run the line - alt/b halt a running program and enter the console there - <esc> f1 f2 f3 when halted: step, step over, step, step out - ctrl/z leave the console Console words - help open the getting-started page - help <words> the help f1 gives for those words - edit edit this source code - [] start adding lines to the program; <esc> stops - keys this list - skill the five skill levels, yours marked - skill n set your skill level, 1 to 5 (remembered) - ?name inspect a variable, array or cluster - ?expr its type and value - name. = text define an abbreviation; name. = (nothing) removes it - *name. = text a starred abbreviation; *name. toggles the star

Help — For access to this tutorial

Type help at the prompt to open the getting-started page — this tutorial — in your browser, so the language reference and the worked examples are always one word away. Both keys and help are named in the console's opening banner (KEYS · HELP), so you never have to remember where to find them.

>>> help

Followed by a word or two, help opens the help box that F1 opens for those words — help cluster input shows the form, use and example of cluster input — without leaving the console. The line goes into the history, so Up or Ctrl/R brings it back.

Your Skill Level — skill n

The first time the console starts, it lists five skill levels, from 1 — Beginner (new to programming) to 5 — Expert, and asks you to choose the one that fits. Type skill and the number:

C:> sp4gl ──────────────────────────────────────── SHEERPOWER V011.0nn.nn │ KEYS · HELP ──────────────────────────────────────── File 📁 %APPDATA%\Sheerpower\sp4gl_cmds.txt Saved ⭐ 0 Starred 🕘 0 History 🔤 40 Abbreviations Skill levels 1 - Beginner new to programming 2 - Newcomer new to Sheerpower, not to programming 3 - Regular writes Sheerpower often 4 - Fluent tables, web handlers and arrays every day 5 - Expert knows the language well skill n chooses yours (1 to 5) and remembers it >>> skill 3 Skill 3 - Regular >>>

The console remembers your level in sp4gl_cmds.txt (below) and, from then on, names it in the banner (Skill 3 · Regular) instead of showing the list. Until you choose one, the list appears every time the console starts. skill on its own lists the five levels again, your own marked with >, and skill with another number changes it.

───────────────────────────────────────────────────────────────── SHEERPOWER V011.0nn.nn │ 🎓 Skill 3 · Regular │ KEYS · HELP ───────────────────────────────────────────────────────────────── File 📁 %APPDATA%\Sheerpower\sp4gl_cmds.txt Saved ⭐ 0 Starred 🕘 0 History 🔤 40 Abbreviations >>> skill Skill levels 1 - Beginner new to programming 2 - Newcomer new to Sheerpower, not to programming > 3 - Regular writes Sheerpower often 4 - Fluent tables, web handlers and arrays every day 5 - Expert knows the language well skill n changes yours (1 to 5) and remembers it >>>

What Your Skill Level Changes — the Error Messages

Your skill level decides how much an error message explains. At skill 3, a mistake is reported in a few words for someone who knows the language. At skill 1, the same mistake is explained in plain words for someone new to programming, and the Help>> lines end with the line to write, on a line of its own, using your program's own names. The message, the line number and the Detail>> facts are the same at every level. Suppose c:\work\loop.spsrc forgets the next that ends its loop:

Show me: a compile error and a runtime error, at skill 3 and at skill 1
total = 0 for i = 1 to 3 total = total + i print total end

At skill 3:

>>> run 'c:\work\loop' | ?? FOR without matching NEXT | --> line 2 | 2 | for i = 1 to 3 | Help>> every FOR needs a next index line (a FOR EACH ends with next cluster_name) 1 error, first at line 2 -- correct them to RUN

At skill 1, the same program:

>>> run 'c:\work\loop' | ?? FOR without matching NEXT | --> line 2 | 2 | for i = 1 to 3 | Help>> this for loop has no end -- after the lines it repeats, add this line: | Help>> next i 1 error, first at line 2 -- correct them to RUN

A runtime error works the same way. At every level the Detail>> line gives the facts; at skill 1 the Help>> lines say what they mean and what to change. Suppose c:\work\scores.spsrc fills one place more than its array has:

dim scores(5) for i = 1 to 6 scores(i) = i * 10 next i print scores(5) end

At skill 3:

>>> run 'c:\work\scores' c:\work\scores.spsrc -- | ?? Subscript out of bounds | --> MAIN, line 3 | 3 | scores(i) = i * 10 | Detail>> Index 6 is higher than 5

At skill 1, the same program:

>>> run 'c:\work\scores' c:\work\scores.spsrc -- | ?? Subscript out of bounds | --> MAIN, line 3 | 3 | scores(i) = i * 10 | Detail>> Index 6 is higher than 5 | | Help>> scores has places 1 to 5, so scores(6) is past its end -- make it bigger: | Help>> dim scores(6)

Messages that have no beginner wording yet show the same text at every level. When the plain words start to feel long, skill 3 keeps the messages short; you can change your level at any time.

Shorthand — Type an Abbreviation, Press Enter

Type an abbreviation with its dot and press Enter: its expansion appears on the next line, already typed, with the cursor at the end. Press Enter again to run it — the same keystroke twice — or edit it first, or press Ctrl/U to erase it and walk away.

Show me: expanding abbreviations, and the built-in shorthand table
>>> t. ← Enter >>> run 'sptests:sptest' ← the expansion, ready: Enter runs it

TAB expands an abbreviation too — in place, so it works in the middle of a line as well, and pressing TAB after each one lets you expand several abbreviations into a single line as you type it.

>>> ot. ← TAB → >>> open table >>> cc. ← TAB → >>> collect cluster >>> if done? then xr. ← TAB mid-line → if done? then exit routine

The built-in shorthand:

ot. open tablein. includer. routine
of. open fileex. excludeer. end routine
et. extract tablesb. sort bypr. private routine
ee. end extractsd. sort descending bywe. when exception in
st. set tablep. printu. use
cc. collect clusterpc. print #ew. end when
ec. end collectpa. print atsc. select case
ac. add clusterpe. print _extractedce. case else
ea. end addli. line inputes. end select
fe. for eachlm. line input menuei. end if   ed. end do
ne. nextls. line input screenxd. xf. xr. exit do / for / routine
e. editl. list

You do not have to remember them: a lone . and Enter (or TAB) opens the Abbreviations list over the bottom of the screen — every one, each name beside its text, the starred ones and your own first, then these. Type to narrow it: the names that start with what you type come first, then those whose text holds it (table finds ot., et. and st.). Enter or a click puts the highlighted one on the line, and Ctrl/S stars it. o. and TAB opens the list already narrowed to o, and when only one fits it simply expands. keys prints every keystroke and console word on this page, in colour.

Your Own Abbreviations

Define an abbreviation right at the prompt — a name ending in a dot, an equals sign, and what it stands for. Nothing is echoed; it is in effect at once and kept for good.

Show me: defining, removing, and starring your own
>>> pt. = print typeof$(x) >>> t. = run 'sptests:sptest' >>> t. ← Enter: the expansion lands, ready >>> run 'sptests:sptest' >>> pt. = ← removes it pt. removed

A starred abbreviation is listed first in the .-TAB list, marked with a *: define it as *t. = run 'sptests:sptest', or star an existing one with *t. (the same again un-stars it), or press Ctrl/S with just t. on the line. Your own abbreviations take precedence over the built-in ones, so ot. can be made to mean whatever you like.

Fill-in Abbreviations — Holes

An abbreviation can leave holes to fill in. Write a hole as {name}. When you expand the abbreviation, the first hole is selected — shown in reverse video — and whatever you type replaces it. Tab moves to the next hole, Shift/Tab back, and Enter moves to the next hole until none are left, then runs the line. Ctrl/U erases the whole thing if you change your mind.

Show me: holes, same-name fill, defaults, and block skeletons
>>> x. = for {var} = 1 to 10\print {var}\next {var} >>> x. ← Enter (or TAB): expands, cursor waiting in the first hole >>> for idx = 1 to 10\print idx\next idx ← type idx once

Two touches make this fast. A hole's name matters: every hole with the same name fills together, live, as you type — type idx once and all three {var} become idx. And a hole may carry a default, written like a named option, {name: value}: tab past it to accept the default, or type to replace it.

>>> of. = open file {ch}: name '@{file}', access {access: input} >>> of. ← fill ch and file ; tab past access to accept input

The built-in block abbreviations already use holes, so et., cc., fe., sc., we., do. and fo. drop in a ready-to-fill skeleton. Because the console runs one line at a time, a multi-line skeleton lands as a single line joined by \ (Sheerpower's statement separator) — it runs exactly as the block would.

Holes are only for abbreviations. Braces you type yourself — in a definition, or JSON inside a string — are ordinary text; the fill-in behaviour happens only when an abbreviation expands to holes.

Editing and Organizing Your Abbreviations

To change an abbreviation, just define it again with the same name — the new expansion replaces the old one. There is no separate edit step, and no need to remove it first.

Show me: redefining, and bulk-editing in sp4gl_cmds.txt
>>> g. = print 'hello' >>> g. = print 'hello, ' + name$ ← same name: this is now what g. means >>> g. ← removes it g. removed

Defining one at a time at the prompt is convenient for a quick abbreviation. Once you have a handful you care about — and especially the complex, hole-filled ones you do not want to retype — edit them in bulk in the file where they live: the [abbreviations] section of sp4gl_cmds.txt in your own folder (see The Console's Memory, below). Each abbreviation is one line, name. what it expands to, exactly as you would type the definition; a hole is just {name} in that line, so a whole block skeleton is one editable line. A // line is a comment — use them to group and label your abbreviations.

[abbreviations] // --- my project shortcuts --- t. run 'sptests:sptest' * rp. run 'reports:monthly' // --- editing skeletons (holes) --- nr. add table {tbl}\{tbl}(id) = _gid$\{tbl}({field}) = {value}\end add

The console rewrites that file for you whenever you star something or run a console command, so your hand edits and your prompt-defined ones live together, survive between sessions, and travel with the file if you copy it to another machine.

Long Lines

A command is not limited to the width of the window. Type past the right margin and the line wraps onto the row below and keeps going — for as many rows as the console window holds. Left, Right and Backspace move across the rows, End goes to the end of the whole line, and Enter runs all of it. Recalled later with Up, it comes back wrapped the same way.

A click on the line puts the cursor on that character, on any of its rows. A click past the end of a row goes to the end of that row, a click below the line goes to the end of the line, and a click on the >>> prompt goes to the start. A click on the output above the line leaves the cursor where it is.

Fixing a Typo — f

When a line has one mistake and Sheerpower can name the fix, the help ends with (f = fix it). Press f at the empty prompt and the corrected line appears, ready to run with Enter or to edit first. Any other key carries on as usual.

>>> prnt "hi" | ?? Unrecognized statement | --> line 1, col 1 | 1 | prnt "hi" | ^ | Help>> 'prnt' is not a statement -- did you mean print? (f = fix it) 1 error, first at line 1 -- correct them to RUN >>> print "hi" ← press f and this line appears; Enter runs it hi

Text Size — Ctrl/+ and Ctrl/-

Ctrl/+ (Ctrl with the = key, or with the + on the keypad) makes the console's text one point larger, and the window grows with it so every row and column still fits. Ctrl/- makes it one point smaller, and Ctrl/0 brings back the normal size. Everything already on the screen changes size too.

The console remembers the size you choose: every console window opens at it, until Ctrl/0 puts it back. Dragging the edge of the window changes the size of the text as well, but only for that window. The window never grows past the edge of the screen or shrinks below 6 points; at either end the key just beeps.

Recalling Earlier Commands

The Up and Down arrow keys walk back and forth through the commands you have already typed, so you can rerun or edit one without retyping it. The console keeps the last 500, and carries them all over to your next session, so tomorrow starts with today's commands already there.

An Up pressed by accident costs nothing: the line you were typing is kept, and Down past the newest command brings it back just as you left it. Down on the line you are typing leaves it alone.

Searching the History — Ctrl/R

When the command you want is further back, type a few characters of it and press Ctrl/R. A list opens over the screen with every earlier command that contains what you typed, anywhere in it (case does not matter), each with its age. It reads upward from the search line: the starred commands first, marked with a *, then the rest, newest first, and in each the commands that start with what you typed come first. With nothing typed it lists them all. Keep typing to narrow it; Up and Down move, and so does the mouse wheel. Enter — or a click on a command — puts it on the line, ready to run or edit; it does not run it. ESC leaves the line as it was. A command too long for its row is cut short, ending in ...; while it is highlighted, the box beside it shows the whole command, and picking it brings back all of it.

Show me: the Ctrl/R history list
>>> pr ← Ctrl/R, then Up twice → History (5) 44m ago print 5 + 10 29m ago print 'hi' > 9m ago print 'The quick brown fox jumps over the lazy ... print 'The quick brown fox jumps 6m ago print sprintf$('%m', 1234567) over the lazy dog -- a line too * 1h ago print cities->city$ long for its row' > pr Up/Down to move Enter to use Esc to cancel Ctrl/S to star or un-star

What you type is found anywhere in a command, not just at its start, so a word from the middle is enough. Typing logical finds the command that set a logical name, wherever the word sits in it:

Show me: a word from the middle finds the command
>>> logical ← Ctrl/R → History (1) > 50m ago set system, logical 'gnvdata': value 'd:/reports' > logical

When You Remember Only Part of It — the Tilde

Sometimes you remember a word of the command but not how the rest was spelled. Put a tilde (~) in what you type before pressing Ctrl/R. What comes before the tilde is found just as you typed it, anywhere in the line. What comes after it is the part you are unsure of: its letters must appear in order, but they need not be contiguous, and they must come after the part before the tilde. So set~gnv keeps only the line where something like gnv follows the word set:

Show me: set~gnv narrows it to one
>>> set~gnv ← Ctrl/R → History (1) > 50m ago set system, logical 'gnvdata': value 'd:/reports' > set~gnv

With nothing before the tilde, the whole line is searched that loose way. This is the one for a name you cannot spell: ~gneve finds Genevieve.

Show me: ~gneve finds a word you cannot spell
>>> ~gneve ← Ctrl/R → History (1) > 2h ago print 'Genevieve' > ~gneve

The rule in one sentence: what you type is found anywhere in the command, and the letters after a tilde need not be contiguous. Case never matters, before or after the tilde.

The loose part forgives letters you left out, and nothing else. ~gneve finds Genevieve because every letter of what you typed is there, in that order. ~genivieve does not, because the i you added is not in the name. If you are unsure, type less: the fewer letters you give, the more it finds.

Because a search can match a great many commands, the list is ordered to put the likeliest first: commands that start with what you typed (the part before the tilde, when there is one), then those that contain what you typed all in one piece, then the rest. Within each group the newest comes first, as always.

A command with a real tilde in it is still findable: type ~~ where you want a literal one. Only the first single tilde splits what you typed; any after it are literal.

When nothing matches, the list says so and suggests the tilde:

>>> zzz ← Ctrl/R → History (0) no match -- try ~zzz: the letters after a ~ need not be contiguous > zzz

Starring a Command — Ctrl/S

A command you use all the time can be starred: with it on the line, press Ctrl/S and the console answers Starred. From then on it heads the Ctrl/R list, in this session and every later one. To un-star it, recall it onto the line and press Ctrl/S again: Un-starred — it drops back into the plain history where its age puts it. Up to twenty commands can be starred. Inside the Ctrl/R list, Ctrl/S stars or un-stars the highlighted command, and the list's title line says so.

Emoji and Accented Letters

The console shows text as it is written. A program that prints an emoji, a Chinese character or an accented letter written in UTF-8 shows it as itself — an emoji in colour, taking the two columns it needs:

>>> print "Thanks 👍 café 中文" Thanks 👍 café 中文

Text you paste at the prompt (Ctrl/V) arrives the same way: copy a line holding emoji from your editor or a web page, paste it, and each character comes in whole. Copying from the console (select, then Ctrl/C) keeps them too, so a line copied out pastes back exactly. Accented letters typed on the keyboard — é, ö, Ç, £ — go in as the letters they are.

On the line an emoji is one character: Left and Right step over it, Backspace deletes it whole, and a long line wraps before it rather than through it. The Ctrl/R list and TAB completion show emoji as themselves, and a name may hold one: after Gabby❤️$ = 'hi', typing print gab and TAB completes the whole name, heart and all.

Emoji — Ctrl/E

Ctrl/E at the console's prompt opens a list of the 50 most used emoji over the bottom of the screen, as the Ctrl/R list opens: each with its name, and the box beside the highlighted one showing the words it is found by and its code point. Type to narrow it — a name or a word such as heart, smile or thumbs, found anywhere, as in the history search — and press Enter, or click one, to put it on the line at the cursor. ESC leaves the line as it was.

The ones you use come back first: the last 20 you chose are listed under the starred ones, each with how long ago you used it. Ctrl/S in the list stars the highlighted emoji, or un-stars it; a starred emoji heads the list, marked with a *, in this session and every later one.

Show me: the emoji list
>>> print 'Thanks ' ← Ctrl/E → Emoji (50) smileys 🤣 rolling on the floor laughing face with tears of joy hearts ❤️ red heart laugh, lol, funny, joy, tears, haha > smileys 😂 face with tears of joy U+1F602 > Search the emoji... a name or a word: heart, smile, thumbs Up/Down to move Enter to insert Esc to cancel Ctrl/S to star or un-star

The Console's Memory — sp4gl_cmds.txt

Everything above lives in one plain-text file in your own Windows user folder: %APPDATA%\Sheerpower\sp4gl_cmds.txt — for a user named pat, C:\Users\pat\AppData\Roaming\Sheerpower\sp4gl_cmds.txt. That is the folder where programs keep each user's own settings (VS Code and PowerShell's command history live there too), so everyone who signs in to the machine has their own history, abbreviations and skill level, and the folder sp4gl.exe is installed in never has to be writable. The console makes the Sheerpower folder the first time it needs it, and the file the first time it writes it. To open the folder, type %APPDATA%\Sheerpower in File Explorer's address bar. The console's banner names the file (its folder as %APPDATA%) and what it holds:

Show me: the file's sections and how it is kept
───────────────────────────────────────────────────────────────── SHEERPOWER V011.0nn.nn │ 🎓 Skill 3 · Regular │ KEYS · HELP ───────────────────────────────────────────────────────────────── File 📁 %APPDATA%\Sheerpower\sp4gl_cmds.txt Saved ⭐ 2 Starred 🕘 100 History 🔤 43 Abbreviations >>>

The file has a section for each thing it remembers, and you may edit it by hand:

// sp4gl_cmds.txt -- the console's memory.  [history] is the last 500 commands, oldest
// first; a line starting "* " is a starred command (Ctrl/S) and is kept for good.
// [abbreviations] is yours to edit.
[abbreviations]
// name. what it expands to   (the dot is optional; TAB adds a space after the expansion;
//  a * in front = starred: listed first)
* t. run 'sptests:sptest'
pt. print typeof$(x)

[history]
* print cities->city$
print 5+10
print 'hi'

[settings]
skill 3
  • [abbreviations] (an older file's [shortcuts] header is still read, and the next save renames it): one per line as name. what it expands to — the dot is assumed if you leave it out, a leading * stars it, a line starting // is a comment. The expansion is taken as written; TAB puts one space after it when it ends in a letter or digit.
  • [history]: the commands, oldest first, newest at the bottom; a * prefix marks a starred one.
  • [settings]: skill n, your skill level — the skill command writes it, at the end of the file the first time.
  • [emoji]: the emoji list's stars, as * and the emoji, then the last 20 you chose, newest first, each after the time it was chosen.

The console writes the file whenever you star something, choose a skill level or pick an emoji, whenever you type a console command such as run, save, edit, build, new, old, exit or stop, and when it exits — so it is never more than one real action behind, even if a session ends badly. Only the section being written is touched; your comments and ordering in the others are kept as they are.

Scripted sessions: set the environment variable SHEERPOWER_CMDS to a file's full path and the console uses that file instead of yours — a test's own memory, so a script never changes your history or level. Under sp4gl /headless < transcript.txt every menu — the Ctrl/R list, the Ctrl/E emoji list, the Abbreviations list, a program's line input menu — comes out as numbered text and reads its pick from the next line of the transcript, and a raw Ctrl/R, Ctrl/S or Ctrl/E byte in a transcript line means that keystroke at that point. So everything on this page can be exercised, and pinned in a regression test, without a window.

Writing a Program in the REPL

You do not have to leave the console to write a whole program. Type [] on its own and press Enter: the console switches into source-entry mode, the prompt changes to [] , and now every line you type is added to the program instead of run — a print goes in as source and shows only when you run it. That includes whole multi-line, multi-statement constructs: a for loop, an if block, or a routine all go in with their structure intact. Press <esc> to leave source-entry mode and return to the >>> prompt; then a bare run runs what you built:

Show me: building a program with [], appending, and its life cycle
>>> [] Enter source code. <esc> when done. [] for i = 1 to 10 [] print i [] next i [] ← press <esc> here to finish >>> run C:\Sheerpower\MyProgram.spsrc 1 2 3 4 5 6 7 8 9 10 >>>

And it appends as you go. Run it, try a few things at the prompt, then open [] again — the new block is added to the end of the program, not put in place of what was there. So a program grows a piece at a time, in whatever order the pieces occur to you, and edit is there when you want to reorder or remove one.

>>> [] Enter source code. <esc> when done. [] print 'first' [] ← press <esc> on the empty line >>> run C:\Sheerpower\MyProgram.spsrc first >>> [] ← open [] again to add a second block Enter source code. <esc> when done. [] print 'second' [] ← <esc> >>> run C:\Sheerpower\MyProgram.spsrc first ← both blocks now run, in order second >>>

What you have built this way is a real, editable program, and the console gives you its whole life cycle:

  • edit — opens the program you have built in VS Code for full, free-form editing, validated as you go when the Sheerpower extension is installed (see Sheerpower and Visual Studio Code (VS Code)). The console waits while you edit: save the program and close its tab, and the edited program is reloaded into the console — usually in under half a second, even for large programs — and you are back at the >>> prompt, right where you left off, ready to run it or keep working. Close the tab without saving, and the program stays as it was. Without VS Code, the Sheerpower IDE opens instead, and leaving it does the same (on Linux, an editor takes the IDE's place: see below);
  • save 'name' — writes it out to a file;
  • build 'name' — compiles and deploys it as a .sprun image;
  • run — runs what you have written; run 'name' runs a saved program (see the next section).

On Linux, edit opens the program in VS Code when it is installed and you are at a desktop — an Ubuntu or Chromebook desktop, or a terminal inside VS Code itself. The console waits while you edit: save the program and close its tab, and it is reloaded, just as when you leave the IDE. Without VS Code or a desktop (over SSH, for example), the program opens right in the terminal, in nano or vi: save it and leave the editor to come back. An editor named by the VISUAL or EDITOR environment variable always comes first — for example, export EDITOR=vim in your ~/.bashrc. A program you leave unchanged stays as it was.

In many interactive prompts, what builds up as you type is a playground of live values and definitions — handy for trying an idea out, but you cannot really see it as a program, and it cannot become a finished application; you experiment at the prompt and write the real code somewhere else. Here, what you build up is real source: you can look at it and rearrange it (edit), keep it (save 'name'), and turn it into a deployable application (build 'name'). So the session is not a throwaway scratchpad — it is the start of a real program, and edit takes it into the full IDE when it outgrows the prompt.

Worth knowing: where the console really stands out is debugging a running program: halt it, inspect and change values, single-step, then continue. That live, in-place debugging is more integrated than the tooling most languages give you out of the box.

Running a Saved Program from the Console

A program you have saved in a file is run from the console with run followed by the file's path in quotes. The .spsrc file type is the default, so it can be left off; a logical name that points at a folder works too (run 'sptests:hello'). The program is compiled first and then run; its output appears in the console, and when it ends you are back at the >>> prompt with every variable still available for inspection.

Show me: running a saved program and inspecting its variables after

Say c:\work\hello.spsrc holds this small, correct program:

greeting$ = "Hello, world!" print greeting$ end

Because it compiles cleanly, it runs: the console names the file, the program prints its output, and you are left at the prompt — where its variables are still set, so you can inspect them:

>>> run 'c:\work\hello' c:\work\hello.spsrc Hello, world! >>> print greeting$ Hello, world! >>>

Running a Deployed (.sprun) Program

The run command runs your saved source (a .spsrc file). When a program is ready to hand to other people, you deploy it: sp4gl myprog /build (or Deploy in SPDEV, Ctrl+F6 in Visual Studio Code) compiles it and writes a .sprun file — a portable, encrypted image that runs exactly the same but keeps your source code hidden. You run a .sprun the same way; just include the .sprun on the name, since .spsrc is what run assumes:

Show me: running a .sprun, and shipping without Sheerpower installed
>>> run 'c:\work\hello.sprun' c:\work\hello.sprun Hello, world! >>>

Note: Deploying is covered in full in its own section. To ship a program to someone with no Sheerpower installed, put the .sprun beside a renamed copy of sp4gl.exe (for example MyProg.exe) — running that .exe runs the deployed program. See Building and Deploying.

When a saved program has mistakes, the same run reports them and does not run — that is the next section.

How Compile-Time Errors Are Reported

If the program has mistakes, it does not run. Each mistake is shown as a block: the message, an arrow to the line and column, the source line with its line number in the gutter, a caret under the offending token, and a labelled explanation — Help>> for what went wrong, Format>> for the statement's correct shape and Fix>> for what to do. The blocks are listed in line order. Suppose c:\work\broken.spsrc holds:

Show me: an error listing, the ENTER-to-edit offer, and cascades
dim grid(2 3), other(4) print other(1) prnt "hello" select cse x end

>>> run 'c:\work\broken' | ?? Syntax error | --> line 1, col 12 | 1 | dim grid(2 3), other(4) | ^ | Help>> DIM name() expects a closing ')' | also: other undeclared at line 2 -- follows the error at line 1 | ?? Unrecognized statement | --> line 3, col 1 | 3 | prnt "hello" | ^ | Help>> 'prnt' is not a statement -- did you mean print? | ?? Unrecognized keyword | --> line 4, col 8 | 4 | select cse x | ^ | Format>> select case expr | | Fix>> SELECT must be followed by CASE 3 errors, first at line 1, plus 1 that follows from them -- correct them to RUN Press ENTER to edit the program. >>>

Because the program did not run, the console offers to fix it: after the errors it prints Press ENTER to edit the program. and waits at the prompt. You read the errors, press ENTER, and Sheerpower opens the program in the editor, ready for you to correct the lines it named. The pause matters — it lets you read the error messages first, so you are never thrown straight into the editor before you can see what was wrong. This offer appears only at the interactive console — a batch or /headless run simply reports the errors and stops.

Two things in that listing are worth knowing. The one-line also: entry is a cascade: other(4) was never declared because its dim line failed, so the later complaint about it is reported as a consequence of the first error rather than as a separate block — fix the dim line and both go away. And the count line at the end tells you where to start: with more than a few errors it says fix the first error first; later ones often follow from it. After ten blocks the rest are only counted; run sp4gl broken /allerrors from the Windows command prompt to see every one.

Some mistakes can only be found once every statement compiles: a variable that is used but never given a value, a routine called with parameters it does not have, and a block that is never closed — an if without its end if, a for without its next. Those checks look at the program as a whole, so they wait until the statements themselves are right. After you fix the first batch of errors, the next run can report new ones. Suppose c:\work\report.spsrc holds:

total = 12 if total > 10 then prnt 'big' end

>>> run 'c:\work\report' | ?? Unrecognized statement | --> line 3, col 3 | 3 | prnt 'big' | ^ | Help>> 'prnt' is not a statement -- did you mean print? 1 error, first at line 3 -- correct them to RUN

Correct prnt to print and run it again: now that every statement compiles, the missing end if is found.

>>> run 'c:\work\report' | ?? IF without matching END IF | --> line 2 | 2 | if total > 10 then | Help>> every block IF (a line that ends with THEN) needs an END IF -- and ELSEIF is one | word 1 error, first at line 2 -- correct them to RUN

How an Uncaught Runtime Exception Is Reported

A program that compiles cleanly can still fail while running — a file that is not there, a division by zero, an argument out of range. If nothing in the program catches the exception (see Exception Handling tutorial for when exception in ... use ... end when), the console shows a block of the same shape: the message, the routine and line where it happened, the failing statement, a Detail>> line with the specifics, and a Called>> line for each level of the call stack, innermost first. Suppose c:\work\oops.spsrc holds:

Show me: a runtime-error block and the _error_ file
option abort code = 300 show_it end routine show_it c$ = chr$(code) end routine

>>> run 'c:\work\oops' c:\work\oops.spsrc -- | ?? Illegal argument to CHR$() | --> SHOW_IT, line 1 | 1 | c$ = chr$(code) | Detail>> chr$(300): the code must be 0..255 | | Called>> from MAIN, line 3: show_it Writing all debug information to... c:\work\oops_error_20261012_063344.txt Done.

The line number is counted within the routine (SHOW_IT, line 1 is the first statement of show_it), and the Called>> line shows the statement in MAIN that called it. Because the program says option abort, it ends and writes an _error_ file that opens with this same block and goes on to list every variable, the open files and the call stack — everything you need to see what the program was doing. Without option abort the block is shown and you are left at the >>> prompt inside the stopped program, exactly as after ALT+B below, where print code would show the 300 that caused it.

Mistakes Typed at the Console

A line typed at the prompt is compiled and run on the spot, so a mistake in it is reported the same way, as a block. There is no file: the line number counts the lines you have typed at the prompt.

Show me: a mistyped console line reported as a block
>>> prnt a/b | ?? Unrecognized statement | --> line 1, col 1 | 1 | prnt a/b | ^ | Help>> 'prnt' is not a statement -- did you mean print? 1 error, first at line 1 -- correct them to RUN >>>

Nothing is lost: the variables you set earlier are untouched, and the corrected line can be typed straight away.

Each line typed at the prompt runs on its own, so a statement whose partner comes on a later line — a for without its next, for instance — is reported as soon as you press Enter, with the two ways in: type [] to enter the lines as a program, or join a short block on one line with \:

>>> for i = 1 to 3 | ?? FOR without matching NEXT | --> line 1 | 1 | for i = 1 to 3 | Fix>> at the console each line runs on its own -- type [] and Enter, paste or type the | lines, press <esc>, then run (a short block can go on one line, joined with \: | for i = 1 to 3 \ print i \ next i) 1 error, first at line 1 -- correct them to RUN >>> for i = 1 to 3 \ print i \ next i 1 2 3

Interrupting a Running Program

When a Sheerpower program is running in its console window, you might encounter a situation where the program is taking too long to complete, or you suspect it's stuck in an infinite loop. For these moments, Sheerpower provides a powerful built-in debugging feature.

By clicking anywhere in the console window to give it focus and then pressing ALT+B, you can immediately halt the program's execution.

This action does more than just stop the program—it drops you directly into the Sheerpower REPL (Read—Eval—Print Loop) at the exact point where the program was interrupted. The console will display the source file and line number where the halt occurred, giving you immediate context.

From within this interactive state, you can:

Show me: inspect, change, step, resume, and read a routine's variables
  • Inspect a variable: type print variable_name, or the shorthand = variable_name, to see its current value.
  • Evaluate an expression: test a condition or do a calculation with the live data — = balance * rate.
  • Change a variable: assign a new value with variable_name = value, then go — the program runs on with the value you set, so you can try a fix without editing and restarting.
  • See everything: type show all to dump every variable, array, table, and cluster, the open files, and the calling stack, all at once.
  • Step one statement at a time: type step to run the next statement and stop again, or step 5 to run five. The Esc key is a one-tap step; F1 steps over a routine call, and F3 steps out of the current routine. Stepping opens a Program Trace window that logs each statement as it runs; trace off stops it as does closing the trace window.
  • Trace only the routines: trace routine: on logs one line per routine entered — the routine's header, indented two spaces for each level of call — instead of every statement. Every way of calling reaches it: a statement call, a function-form call, a pipe, a routine map, a local routine. It is the quickest way to see an application's higher-level logic: which routines run, in what order, and what calls what. trace routine: off (or trace off) stops it, and trace on switches back to tracing every statement.
  • Resume execution: type go to let the program proceed from where it left off.
  • Stop execution: type stop to end the program completely, or simply close the window.

The names you reach this way are the program's module variables. To read a routine's parameters or its private variables, prefix the name with the routine's own name and a $. Given routine do_taxes with rate, the parameter rate is do_taxes$rate at the halted console — you can print it and change it just like any other variable:

BREAK at DO_TAXES.4 >>> = do_taxes$rate ← a routine parameter: routine-name $ variable 0.0275 >>> do_taxes$rate = 0.03 ← change it >>> go ← continue, now with rate = 0.03

Instead of running straight on with go, you can walk the program one statement at a time. Type step to run the next statement and stop again, or step 5 to run five in a row; tapping Esc is the same as step then Enter, so you can rest a finger on it and watch the program advance. When the next statement is a routine call, two function keys refine the step: F1 steps over the call — it runs the whole routine at full speed and stops on the line after — and F3 steps out of the routine you are in, running to its return and stopping back in the caller. Stepping opens a Program Trace window that lists each statement as it runs — the time, its MAIN.line label, and the source text — so you see exactly the path the program takes. Type trace off when you are done to close it.

BREAK at MAIN.4 >>> step ← run the next statement, stop again (Esc does the same) >>> step >>> step 5 ← three statements on, the loop printed 5 >>> step 3 ← run three at once 6 >>> trace off ← close the Program Trace window >>> go ← run on normally

To see the shape of a program rather than every step of it, trace the routines alone: with the program already loaded, trace routine: on then a bare run. (run 'myprogram' loads a program and starts it clean, with tracing off, so give the switch after the program is loaded.) The trace window logs one line per routine entered, indented by call depth, so a run reads like an outline of the application:

>>> trace routine: on >>> run routine load_config routine process_orders routine price_order with order_id$, returning total routine apply_discount with amount, code$, returning amount routine price_order with order_id$, returning total routine apply_discount with amount, code$, returning amount routine print_report >>> trace routine: off

Tip: This feature is an invaluable tool for live debugging. It allows you to pause a running application and diagnose its state instantly, without needing to stop and restart it under a separate debugger.
(Show/Hide Sheerpower REPL & ALT+B Debugging Takeaways)
Hide Description

    

       


      

Enter or modify the code below, and then click on RUN

Looking for the full power of Sheerpower?
Check out the Sheerpower website. Free to download. Free to use.