PROMPT
                                    ======


PROMPT is a function to simplify the evaluation of single-key press user
input.

Syntax:
=======

   optno% = PROMPT([#chan, ]<prompt> [, <option1> [, <option2>..]..])


Example:
========

    answer% = PROMPT("Continue? ", 'Yy' & CHR$(10), 'Nn' & CHR$(27))

The example above displays Continue? at the current cursor position in
channel #1, (and in current paper and ink colours) and waits for a user
key press. It will only return on 'Y', 'y' or <ENTER> being pressed, in
which case it returns 1, for option number 1, or on 'N', 'n' or <ESC>, in
which case it returns 2, for option number 2.


Features:
=========

You can have as many options as you like, and each option can contain
whatever characters you like. The routine will return on the character
press that first matches one of the characters in one of the option
strings.

The /first/ character of an option string will be printed to the channel if
any of the characters in that option matches, provided it is a printable
character, otherwise a '?' will be printed instead.


If only one option string is present then, if a key press matches any
character in the string, the character (if printable) is printed and the
function returns with the character code:

        drvno% = PROMPT("Enter drive number (1..8) ", 12345678)

Note: The option is fetched as a string, so remember to account for
S*BASIC's coercion and conversion conventions, ie:

        number% = PROMPT("Enter a number (0..9) ", 1234567890)

may not do what you expect! Rather do:

        number% = PROMPT("Enter a number (0..9) ", '0123456789')

in a case like that.

Note: When options are present, but no ESC is specified in any option,
as above, pressing <ESC> will return -1


You can also omit options altogether:

        chr% = PROMPT("Press any key to continue.. ")

In this form the function returns the key code of any key pressed, Again:
Unprintable characters will be represented by a '?', but whatever the
character, its code will be returned.

Note: If the input character is in the last position on the line, the
cursor moves to the next line (SMSQ/E). This is automatic and cant be helped.


Programming:
============

This started off as a general purpose subroutine for any old S*BASIC
command that needed a prompt function, but I thought it might be useful
to have it as a free-standing function, as it could potentially save a lot
of S*BASIC code and faffing around. It turns out it wasnt so
straightforward to convert.

The original function could have fixed strings and codes as part of the
code in memory, while the free-standing version has to rely on strings on
the stack, so things got a little messy.. a bit like an old house
conversion.

Anyway, its done now, and seems to work ok. On its own it takes about
350 bytes, but as part of a toolkit with other commands that need to decode
a channel number and fetch parameters it doesnt add that much to the
total.

This free-standing version was assembled with a more compact gtchan; in a
larger toolkit Id remove the lines

* AOB
input sbu_chn_chan_rel

in the link file and replace it with

* AOB
library lib_uti_sbu_lib


Program Status:
===============

V0.01, pjw, 2022 Feb 23

Conditions and DISCLAIMER as per Knoware.no