LIBCOURSE-UTILS(3)

NAME
out.repeat, out.ch, out.string, out.byte, out.int, out.hex, out.bool, out.yes.no, in.skip, in.digit, in.string, in.bool, in.byte, in.int, ask.string, ask.bool, ask.byte, ask.int, cursor.x.y, cursor.up, cursor.down, cursor.right, cursor.left, cursor.visible, cursor.invisible, erase.eol, erase.bol, erase.line, erase.eos, erase.screen, black.hole, flush, pos.int, pos.yes.no - KRoC course library functions

SYNOPSIS
#USE "course.lib"
kroc -lcourse

PROC out.repeat (VAL BYTE ch, VAL INT n, CHAN BYTE out!)
PROC out.ch (VAL BYTE ch, VAL INT field, CHAN BYTE out!)
PROC out.string (VAL []BYTE s, VAL INT field, CHAN BYTE out!)
PROC out.byte (VAL BYTE b, VAL INT field, CHAN BYTE out!)
PROC out.int (VAL INT n, VAL INT field, CHAN BYTE out!)
PROC out.hex (VAL INT n, VAL INT field, CHAN BYTE out!)
PROC out.bool (VAL BOOL b, VAL INT field, CHAN BYTE out!)
PROC out.yes.no (VAL BOOL b, VAL INT field, CHAN BYTE out!)

PROC in.skip (BYTE ch, CHAN BYTE in?)
PROC in.digit (BYTE d, CHAN BYTE in?, out!)
PROC in.string ([]BYTE s, INT length, VAL INT max, CHAN BYTE in?, out!)
PROC in.bool (BOOL b, CHAN BYTE in?, out!)
PROC in.byte (BYTE b, VAL INT max, CHAN BYTE in?, out!)
PROC in.int (INT n, VAL INT max, CHAN BYTE in?, out!)

PROC ask.string (VAL []BYTE prompt, []BYTE s, INT length, VAL INT max, CHAN BYTE in?, out!)
PROC ask.bool (VAL []BYTE prompt, BOOL b, CHAN BYTE in?, out!)
PROC ask.byte (VAL []BYTE prompt, BYTE b, VAL INT max, CHAN BYTE in?, out!)
PROC ask.int (VAL []BYTE prompt, INT n, VAL INT max, CHAN BYTE in?, out!)

PROC cursor.x.y (VAL BYTE x, y, CHAN BYTE out!)
PROC cursor.up (VAL BYTE n, CHAN BYTE out!)
PROC cursor.down (VAL BYTE n, CHAN BYTE out!)
PROC cursor.right (VAL BYTE n, CHAN BYTE out!)
PROC cursor.left (VAL BYTE n, CHAN BYTE out!)
PROC cursor.visible (CHAN BYTE out!)
PROC cursor.invisible (CHAN BYTE out!)

PROC erase.eol (CHAN BYTE out!)
PROC erase.bol (CHAN BYTE out!)
PROC erase.line (CHAN BYTE out!)
PROC erase.eos (CHAN BYTE out!)
PROC erase.bos (CHAN BYTE out!)
PROC erase.screen (CHAN BYTE out!)

PROC black.hole (CHAN BYTE in?)
PROC flush (CHAN BYTE out!)
PROC pos.int (VAL INT col, row, n, field, CHAN BYTE out!)
PROC pos.yes.no (VAL INT col, row, VAL BOOL b, VAL INT field, CHAN BYTE out!)

DESCRIPTION

These PROCs provide basic input and output, interactive input, cursor positioning (for VT220 compatible terminals), and miscellaneous input/ouput.

SIMPLE OUTPUT

out.repeat outputs the BYTE ch down the channel out, n times.

out.ch outputs ch in a fieldwidth field down out. If the fieldwidth is too wide for ch, it right-justifies ch with spaces on the left. If the field is not wide enough, it prints the ch anyway. These rules for fieldwidth are the same as those used by the Pascal write procedure.

out.string outputs the BYTE array (string) s in fieldwidth field down the channel out. See out.ch for a description of field.

out.byte outputs the decimal value of b in fieldwidth field down the channel out. out.int outputs the decimal value of n in fieldwidth field down the channel out.

out.hex outputs the hexidecimal value of n in fieldwidth field down the channel out. At least 9 characters are always sent, including the leading `#'.

out.bool and out.yes.no output the value of b (as either "TRUE"/"FALSE" or "yes"/"no" respectively), in fieldwidth field down the channel out.

SIMPLE INPUT

in.skip inputs BYTE values from the in channel until a non-space character is input. The non-space character is returned in ch.

in.digit inputs a digit (BYTE) from the in channel and stores it in d. If a non-digit character is input, a BEL character is output to the out channel.

in.string inputs a string of up to max characters inputted from the in channel and stores them in s. Input is terminated with a new-line or carriage-return, that is not included in s. The number of characters input is stored in length, any remaining characters in s are set to NUL. All characters are echoed on the out channel. Backspace is handled sensibly.

in.bool waits for a "y" or "n" character from the in channel, sending a BEL character to out for other characters. "Y" and "N" are also accepted. The BOOL value is returned in b and also output on the out channel as either "yes" or "no" respectively.

in.byte inputs a BYTE expressed as decimal digits. Up to max characters are input from in and echoed on out, with backspace handled sensibly. Input is terminated with a carriage-return, new-line or space. Values greater than 255 are ignored.

in.int inputs an INT expressed as decimal digits. Up to max characters are input from in and echoed on out, with backspace handled sensibly. Input is terminated with a carriage-return, new-line or space. The first character may be "+" or "-". in.int will guard against overflow.

INTERACTIVE INPUT

ask.string outputs the prompt string and waits for input from in of up to max characters (terminated by a carriage-return or new-line) echoing down out as necessary. The input string is returned in s with its length in length, padded on the right with NUL characters if needed.

ask.bool outputs the prompt string and waits for input from in of either a "y" or "n" character (other characters cause BEL to be output to out). The boolean b is set TRUE or FALSE depending on whether "y" or "n" was received, echoing "yes" or "no" down out respectively. "Y" and "N" are accepted as "y" and "n".

ask.byte outputs the prompt string and waits for input from in of a properly formatted (decimal) byte. Up to max input characters are allowed, terminated by a carriage-return, new-line or space. The value of the byte is computed and returned in b. Characters are echoed to the out channel.

ask.int outputs the prompt string and waits for input from in of a properly formatted integer. Up to max input characters are allowed, terminated by a carriage-return, new-line or space. The value of the integer is computed and returned in n. Characters are echoed to the out channel.

VT220 CURSOR CONTROL

cursor.x.y outputs a VT220 control sequence down channel out to place the cursor at screen coordinates (x, y).

cursor.up outputs a VT220 control sequence down channel out to move the cursor up n lines.

cursor.down outputs a VT220 control sequence down channel out to move the cursor down n lines.

cursor.left outputs a VT220 control sequence down channel out to move the cursor left n columns.

cursor.right outputs a VT220 control sequence down channel out to move the cursor right n columns.

cursor.visible outputs a VT220 control sequence down channel out to make the cursor visible.

cursor.invisible outputs a VT220 control sequence down channel out to make the cursor invisible. Note: not all terminals support this.

VT220 SCREEN ERASING

erase.eol outputs a VT220 control sequence down channel out to erase characters from the current cursor position to the end of the screen line.

erase.bol outputs a VT220 control sequence down channel out to erase characters from the current cursor position backwards to the start of the line.

erase.line outputs a VT220 control sequence down channel out to erase all characters on the current line.

erase.eos outputs a VT220 control sequence down channel out to erase characters from the current cursor position to the end of the screen.

erase.bos outputs a VT220 control sequence down channel out to erase characters from the current cursor position backwards to the start of the screen.

erase.screen outputs a VT220 control sequence down channel out to erase all characters from the screen.

MISCELLANEOUS

black.hole inputs characters from in forever. It is used to mask off unwanted BYTE streams.

flush is used to flush screen output. If out is (ultimately) connected to the external "screen" channel (standard-output of the occam program), this flushes all characters in the screen output buffer, ensuring that they are written to the underlying file-descriptor.

pos.int outputs a VT220 control sequence down channel out to place the cursor at screen coordinates (col, row) and output n in a fieldwidth of field.

pos.yes.no outputs a VT220 control sequence down channel out to place the cursor at screen coordinates (col, row) and output b (as either "yes" or "no") in a fieldwidth of field.

AUTHOR
This manual page is maintained by Fred Barnes <frmb@kent.ac.uk>. The documentation itself was largely extracted from the library sources.

SEE ALSO
kroc(1)
course/examples/test_utils.occ in the KRoC distribution

REPORTING BUGS
Please report bugs to <ofa-bugs@kent.ac.uk>

COPYRIGHT
Copyright © 1997 P.H.Welch

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA