Introduction to the REPL and Interrupting a Running Program

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$, …

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.

The built-in shorthand:

You do not have to remember them: a lone . and Enter (or TAB) pops up an Abbreviations menu of every one (your own first, then these); pick one and it lands on the line. o. and TAB narrows the menu to the ones starting with o, and when only one fits it simply expands. keys prints every keystroke and console word on this page, in colour.

A starred abbreviation is listed first in the .-TAB menu, 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.

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.

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.

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 sheerpower:sp4gl_cmds.txt (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.

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.

The file has two sections, 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'

• [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.

The console writes the file whenever you star something, 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 other one are kept as they are.

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.

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

• edit — hands the program you have built to the Sheerpower IDE for full, free-form editing, validated as you go. When you leave the IDE, 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;
• 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).

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.

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

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

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

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:

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

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.

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

• 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:

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.

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: