5.19.6 Input

For ways of storing character strings in memory see String Formats.

key       – char         core       “key”

Receive (but do not display) one character, char.

key?       – flag         facility       “key-question”

Determine whether a character is available. If a character is available, flag is true; the next call to key will yield the character. Once key? returns true, subsequent calls to key? before calling key or ekey will also return true.

ekey       – u         facility-ext       “e-key”

Receive a keyboard event u (encoding implementation-defined).

ekey>char       u – u false | c true         facility-ext       “e-key-to-char”

Convert keyboard event u into character c if possible.

ekey?       – flag         facility-ext       “e-key-question”

True if a keyboard event is available.

Gforth recognizes various keys available on ANSI terminals (in MS-DOS you need the ANSI.SYS driver to get that behaviour). These are the keyboard events produced by various common keys:

k-left       – u         gforth       “k-left”

k-right       – u         gforth       “k-right”

doc-k-up doc-k-down doc-k-home doc-k-end

k-prior       – u         gforth       “k-prior”

aka PgUp

k-next       – u         gforth       “k-next”

aka PgDn

k-insert       – u         gforth       “k-insert”

k-delete       – u         gforth       “k-delete”

The function keys (aka keypad keys) are:

k1       – u         gforth       “k1”

k2       – u         gforth       “k2”

k3       – u         gforth       “k3”

k4       – u         gforth       “k4”

k5       – u         gforth       “k5”

k6       – u         gforth       “k6”

k7       – u         gforth       “k7”

k8       – u         gforth       “k8”

k9       – u         gforth       “k9”

k10       – u         gforth       “k10”

k11       – u         gforth       “k11”

k12       – u         gforth       “k12”

Note that K11 and K12 are not as widely available. The shifted function keys are also not very widely available:

s-k1       – u         gforth       “s-k1”

s-k2       – u         gforth       “s-k2”

s-k3       – u         gforth       “s-k3”

s-k4       – u         gforth       “s-k4”

s-k5       – u         gforth       “s-k5”

s-k6       – u         gforth       “s-k6”

s-k7       – u         gforth       “s-k7”

s-k8       – u         gforth       “s-k8”

s-k9       – u         gforth       “s-k9”

s-k10       – u         gforth       “s-k10”

s-k11       – u         gforth       “s-k11”

s-k12       – u         gforth       “s-k12”

Words for inputting one line from the keyboard:

accept       c-addr +n1 – +n2         core       “accept”

Get a string of up to n1 characters from the user input device and store it at c-addr. n2 is the length of the received string. The user indicates the end by pressing <RET>. Gforth supports all the editing functions available on the Forth command line (including history and word completion) in accept.

edit-line       c-addr n1 n2 – n3         gforth       “edit-line”

edit the string with length n2 in the buffer c-addr n1, like accept.

Conversion words:

s>number?       addr u – d f         gforth       “s>number?”

converts string addr u into d, flag indicates success

s>unumber?       addr u – ud flag         gforth       “s>unumber?”

converts string addr u into ud, flag indicates success

>number       ud1 c-addr1 u1 – ud2 c-addr2 u2         core       “to-number”

Attempt to convert the character string c-addr1 u1 to an unsigned number in the current number base. The double ud1 accumulates the result of the conversion to form ud2. Conversion continues, left-to-right, until the whole string is converted or a character that is not convertable in the current number base is encountered (including + or -). For each convertable character, ud1 is first multiplied by the value in BASE and then incremented by the value represented by the character. c-addr2 is the location of the first unconverted character (past the end of the string if the whole string was converted). u2 is the number of unconverted characters in the string. Overflow is not detected.

>float       c-addr u – f:... flag        float       “to-float”

Actual stack effect: ( c_addr u – r t | f ). Attempt to convert the character string c-addr u to internal floating-point representation. If the string represents a valid floating-point number r is placed on the floating-point stack and flag is true. Otherwise, flag is false. A string of blanks is a special case and represents the floating-point number 0.

Obsolescent input and conversion words:

convert       ud1 c-addr1 – ud2 c-addr2         core-ext       “convert”

OBSOLESCENT: superseded by >number.

expect       c-addr +n –         core-ext       “expect”

Receive a string of at most +n characters, and store it in memory starting at c-addr. The string is displayed. Input terminates when the <return> key is pressed or +n characters have been received. The normal Gforth line editing capabilites are available. The length of the string is stored in span; it does not include the <return> character. OBSOLESCENT: superceeded by accept.

span       – c-addr         core-ext       “span”

Variable – c-addr is the address of a cell that stores the length of the last string received by expect. OBSOLESCENT.