Making Console Applications: Prompts, Input Options, and Menus

Output:

Output:

Three lessons in one run: the short form appended ? to 'Your name: ', the prompt form did not, and a line input with no prompt shows nothing at all. Use the prompt form whenever the exact text matters.

Output:

key input returns as soon as one key is pressed; the value is that single character. It is the statement for "press any key" pauses and single-letter choices.

Words and keys that are not an answer

Output:

Test _help first, then _back and _exit: more than one can be set by a single answer (when EXIT is the default and the person asks for help, both _help and _exit are true). The usual shape is a loop that leaves on _exit:

That loop also shows a habit worth keeping: read into an ordinary variable, check it, and only then store it in a table field — never input straight into client(last_name).

Enter alone

Pressing Enter with nothing typed gives a numeric variable 0 and a string variable the empty string:

Output:

Quoted answers

An unquoted answer to input loses its leading and trailing spaces and cannot hold a comma. An answer typed in quotes keeps its spaces and its commas; the quotes themselves are removed:

Output:

Several variables in one statement

input fills a list of variables from comma-separated answers. They can all be typed on one line, or one per line with a comma at the end of each line that has more to come:

Output:

More answers than variables is the exception toomanyinp (8003, Too many input items); too few, when the input has run out, is toofewinp (8002, Too few input items).

line input takes a list too, but never splits an answer: it asks once for each variable, and a comma is just part of the text.

Output:

Editing keys while typing

Ctrl+A, Ctrl+C and Ctrl+T belong to the console: Select All, Copy and Copy All Text. They work on the text of the screen, so the answer never sees them. Escape, the Up arrow and Ctrl+Z end the input too (see the table of words and keys that are not an answer, above).

More about key input

key input does not echo the key and does not start a new line — the print after it does that. It takes the same options as input, and it sets _exit, _back and _help the same way. The key that ended an input is in _terminator$: RETURN for Enter, and a control key as CTRL/G.

Output:

The options a program most often reaches for are timeout with elapsed, and eof:

Output:

Output:

Without eof, reading past the end of input is an error; with it, the variable comes back empty and the flag says why. That is the idiom for a program that reads until its input runs out.

at places the prompt anywhere on the screen. This is the screen image captured while the program waited, with the prompt at row 5, column 10:

Output:

• length 20 limits the answer to twenty characters and draws the field as twenty underscores after the prompt, so the person can see how much room there is.
• default 'CA' puts CA in the field; Enter accepts it, typing replaces it.
• attributes takes a list in a string — bold, blink, reverse, separated by commas.
• erase clears the input line before the prompt appears and clears it again once the answer is in, so a prompt placed with at leaves nothing behind: input 'Enter a 2nd name', at 4, 1, erase: name_2$.

valid

The rules are the ones the valid() function takes, so a rule list can be tried out on its own. Several rules are separated by semicolons, and the answer must pass them all:

Output:

timeout

When the time runs out the statement raises the exception inptmo (8401, Timeout on input). The number may carry a fraction — timeout 4.5. Catch it to carry on with a default:

area

line input area top, left, bottom, right: text$ turns a rectangle of the screen into a small text editor: the text wraps from line to line as it is typed, the four arrow keys move through it, characters can be inserted and deleted, and a bell sounds at the edge of the area or when the text is full. Escape in the top-left position abandons the input; the Help button leaves it with _help set. Trailing spaces and line breaks are removed from the result, and wrap$() re-wraps it to any width:

Output:

Items

• Items are comma-separated. An unquoted item is shown in upper case (apples becomes APPLES); a quoted item keeps its case exactly — "Apples".
• text = value shows the text and returns the value:

Output:

• text = { items } is a submenu, nested as deeply as you like. A submenu with no %title of its own is titled with the item's text, as TROPICAL was above.

• A value keeps its case when it is quoted, like an item: "Control Panel" = "ctrl" returns ctrl, while "Notepad" = notepad returns NOTEPAD.
• A description that holds spaces or special characters must be quoted.
• A menu can hold up to 5,000 items.
• %bar "*" draws the rule with the text you give instead of dashes, and %heading with no text draws a blank line and a dashed rule:

That last capture is what a menu looks like when the program runs with /headless and its answers come from a file: the items are numbered, and the answer is the number (or the item's text). It is how a console application is tested unattended.

What the program gets back

• The variable receives the chosen item's value, or its text when it has no value.
• _string$ receives the path of the choice through the levels: #3;#2 means the third item of the top menu, then the second item of its submenu. Rules and headings are not counted.
• Escape (or the Back item of a submenu) leaves the menu with an empty result. Ctrl+Z leaves it too and sets _exit to true — a console application should test that before trusting the result:

Pre-selecting an item, and the other options

• The default option names the item to highlight when the menu opens, by its path — the same form _string$ returns: default '#2' highlights the second choosable item, default '#3;#2' opens the third item's submenu on its second item. Keeping the last _string$ and passing it back as the default reopens a menu on the person's previous choice. A default that is not a path raises the illnum exception.
• timeout and elapsed work with a menu exactly as with a prompt.
• input menu spec$: choice$ is the same statement as line input menu.

The keys a person uses

• Up and Down move the highlight; Delete jumps to the first item.
• Enter, Space, Right arrow, or a click chooses the item, or opens its submenu.
• Escape or Left arrow goes back to the calling menu; from the top menu, Escape leaves with an empty result.
• Ctrl+Z leaves the whole menu and sets _exit.

Layout

Content

Behaviour

Each picture is the screen captured while the menu waited, with the part of the menu string that made the difference. Six directives have no picture because they change behaviour rather than appearance: %message (a status line while the menu is up), %autodisplay, %lockstep, %nomouseover, %inactive and %attached. %title is on every picture, and %heading, %invalid and %split are in the Layout example above.

%at center, center

%size 3 — three rows visible, the rest scroll

%columns 2 — the items split evenly

%items 3 — a new column every three items

%maxwidth 40 — the whole menu capped, the last column cut

%autovbar off — no bars between columns

%vbar — a bar after this column only

%border off — no frame, and so no title

Output:

%bar 'text' — a rule that carries a label

%replace — the submenu takes the parent's place

The parent, then the screen after choosing reports: the submenu is where the parent was, not beside it. Its Back item returns.

%menubar — a horizontal bar with pull-downs

%multi — a checklist

%width 40 — a column at least 40 wide

%left — no indent in front of the items

The checked items come back separated by line breaks, so pieces() counts them and piece$() takes them one at a time. The rule: a %multi menu cannot contain submenus. The menu string is refused when it is parsed, and the exception says why:

Output:

Format characters

Format options

Options come first, separated by commas, and end with a colon: <aj, digits: ###-####>.

elapsed and timeout are the statement's options, as for a prompt: input screen scr$, timeout 30, elapsed took: a$.

Running without a screen

Under /headless (see A Guide for an AI when Vibe Coding) a form is printed instead of drawn — the text before the first field on its own line, then one line a field with the format characters shown as underscores and a default in brackets — and each answer is read from the input, one line a field; an empty line keeps the default. A field's valid rules, req and its call routine apply there too: a refused answer prints (not valid -- try again), (required -- try again) or the routine's own message, (zip 00000 is not a place -- try again), and the field's line again. That is how a program with fill-in fields is tested unattended.

Testing in the window: typeahead

Under /headless the answers come from the input; in the window they can come from the program itself. set window: typeahead text$ puts keystrokes into the window's type-ahead buffer, and the next input, input screen, menu or dialog box takes them as if a person had typed them — chr$(9) is Tab to the next field, chr$(13) is Enter. ask window: typeahead left$ reads what is still waiting, and set window: typeahead '' empties the buffer. That is how every kind of input statement is tested without a person at the keyboard.

An error clears the buffer. When an answer is refused — a valid rule fails, a required field is left empty, a call routine says message error: — whatever was typed behind it is thrown away, on purpose: a canned stream of keys must not cascade through an error into the wrong field. The prompt then waits for a person (or its timeout), so a test types one accepted answer per field, and pins a refusal through a short timeout, as below.

A check of your own on a field: call

When a rule word cannot say it — a zip code looked up in a table, an end date that must follow a start date — put call routine_name on the field. The routine runs the moment the field is left, before the person moves on, with the field's text in _string$; to refuse the answer it says message error, and the field is asked again with the message shown. No loop around the statement, and the check stays next to the field it checks:

The Age field's valid "integer" runs before check_age, so the routine never sees abc. A call that names no routine raises nodispatch when the field is left.

A form: several fields in one statement

Put several <...> fields in the string and list a variable for each. Tab moves to the next field, Escape goes back to the previous one, and Enter — pressed in the last field — completes the form; until then every answer can still be changed. A default for a form is one value per field, separated by line feeds.

A %text block holds a form one field a line (see String handling); every field carries its own at, so the line ends between them are never drawn. A default for the same form is one value a field, joined with line feeds:

For anything larger than this — labels, checkboxes, dropdowns, buttons — use a dialog box (Dialog Boxes: Forms, Fields, and Native File Pickers).

message

message writes in the status bar at the bottom of the window, in dark blue, where the window's mode (Running, REPL) is usually shown, and the mode comes back when the message's time is up (the window keeps a scrollable history of messages, and the title bar shows the latest). Nothing the program has printed is touched and nothing pops up. It takes a list like print, with one difference: a comma puts a single space between two items and a semicolon puts nothing.

shows number is 123456789. A message stays for at least three seconds. Two options change how it is delivered:

• message error: 'Is this really your age?' — an error: shown in red in the status bar with a low tone (for anyone who may not see the red), and anything the person had typed ahead is thrown away, so a stray Enter cannot answer the next question.
• message delay: text$ — the program waits while the message is read: about three seconds, and a little longer for a longer message.

With nobody at a window a message is a line of text: a program run with /headless writes -- text (?? text for an error) on its error output, and a compile (/validate, /build) writes %message text into its build report as $info | -- text.

delay

delay 4.5 pauses for that many seconds (fractions allowed, to about a tenth of a second). delay with no number shows Press the ENTER key to continue and waits for Enter or a mouse click; Ctrl+Z, Escape and Help are answered there too, and set _exit, _back and _help. Under /headless a delay does not wait at all.

clear and clear area

clear wipes the whole console, messages included. clear area wipes one rectangle, given as two opposite corners — top row, left column, bottom row, right column — on a screen that is 30 rows by 100 columns unless you have changed it. Attributes (bold, blink, reverse, separated by commas) go before a colon, and box draws a frame around the area:

This is the screen while that program waited, and under it the part of the screen's attribute map that holds the box (# marks the frame):

clear area reverse: 5, 10, 11, 60 fills the same rectangle in reverse video instead; text printed into it afterwards shows in the normal way.

Output:

In a mask, ~ makes the next character literal — that is how the space and the dash got into 800 555-2527.