8.1.4 Character Input/Output

Most of character I/O predicates have several variants:

bytes vs. characters

There are separate predicates for binary I/O, which work on bytes, and for text I/O, which work on characters. The former have the suffix `_byte', e.g. put_byte.

character codes vs. one-char atoms

The text I/O predicates come in two variants, those that use character codes (suffix `_code', e.g. put_code), and those using one-char atoms (suffix `_char', e.g. put_char).

SICStus compatibility predicates

The SICStus compatibility predicates work on both binary and text streams and use character codes or bytes, depending on the stream type. They normally have no suffix (e.g. put), with the exception of peek_char.

explicit vs. implicit stream

Each of the above predicates comes in two variants: with an explicit first argument, which is the stream or alias to which the predicate applies (e.g. put_byte(Stream, Byte)), or without the stream argument, in which case the current input or output stream is used, depending on the context (e.g. put_byte(Byte)).

I/O on standard streams

These are variants of SICStus compatibility predicates that always work on the standard input or output. These predicates have the prefix tty, e.g. ttyput(Code).

nl ISO

nl(+Stream) ISO

A new line is started on the text stream Stream by printing a <LFD>. If Stream is connected to the terminal, its buffer is flushed.

get_code(?Code) ISO

get_code(+Stream,?Code) ISO

Code is the character code of the next character read from text stream Stream. If all characters of Stream have been read, Code is -1, and further calls to get_code/2 for the same stream will normally raise an exception, unless the stream is connected to the terminal (but see the eof_action option of open/4; see Stream Pred).

get_char(?Char) ISO

get_char(+Stream,?Char) ISO

Char is the one-char atom naming the next character read from text stream Stream. If all characters of Stream have been read, Char is end_of_file, and further calls to get_char/2 for the same stream will normally raise an exception, unless the stream is connected to the terminal (but see the eof_action option of open/4; see Stream Pred).

get_byte(?Byte) ISO

get_byte(+Stream,?Byte) ISO

Byte is the next byte read from the binary stream Stream. It has the same behavior at the end of stream as get_code.

get0(?Code) obsolescent

get0(+Stream,?Code) obsolescent

A combination of get_code and get_byte: Code is the next character code or byte read from the arbitrary stream Stream.

get(?N) obsolescent

get(+Stream,?N) obsolescent

Same as get0/2, except N is the character code of the next character that is not a layout-char (see Token String) read from Stream.

peek_code(?Code) ISO

peek_code(+Stream,?Code) ISO

Code is the character code of the next character from text stream Stream, or -1, if all characters of Stream have been read. The character is not actually read; it is only looked at and is still available for subsequent input.

peek_char(?Char) ISO only

peek_char(+Stream,?Char) ISO only

Char is the one-char atom naming the next character from text stream Stream, or end_of_file, if all characters of Stream have been read. The character is not actually read.

peek_char(?Code) SICStus only

peek_char(+Stream,?Code) SICStus only

Identical to peek_code.

peek_byte(?Byte) ISO

peek_byte(+Stream,?Byte) ISO

Byte is the next byte from binary stream Stream, or -1, if all bytes of Stream have been read. The byte is not actually read.

skip(+Code) obsolescent

skip(+Stream,+Code) obsolescent

Skips just past the next character code Code from Stream. Code may be an arithmetic expression.

skip_line

skip_line(+Stream)

Skips just past the next <LFD> from the text stream Stream.

read_line(-Line)

read_line(+Stream, -Line)

Reads one line of input from Stream, and returns the code-list Line. When the end of file is reached, Line is the atom end_of_file, and on subsequent calls an exception is raised.

put_code(+Code) ISO

put_code(+Stream,+Code) ISO

Character code Code is output onto text stream Stream.

put_char(+Char) ISO

put_char(+Stream,+Char) ISO

The character named by the one-char atom Char is output onto text stream Stream.

put_byte(+Byte) ISO

put_byte(+Stream,+Byte) ISO

Byte Byte is output onto binary stream Stream.

put(+Code) obsolescent

put(+Stream,+Code) obsolescent

A combination of put_code and put_byte: Code is output onto (an arbitrary stream) Stream. Code may be an arithmetic expression.

tab(+N) obsolescent

tab(+Stream,+N) obsolescent

N spaces are output onto text stream Stream. N may be an arithmetic expression.

The above predicates are the ones that are the most commonly used, as they can refer to any streams. The predicates listed below always refer to the standard input and output streams. They are provided for compatibility with DEC-10 character I/O, and are actually redundant and easily recoded in terms of the above predicates.

ttynl obsolescent

Same as nl(user_output).

ttyflush obsolescent

Same as flush_output(user_output).

ttyget0(?N) obsolescent

Same as get0(user_input, N).

ttyget(?N) obsolescent

Same as get(user_input, N).

ttyput(+N) obsolescent

Same as put(user_output, N).

ttyskip(+N) obsolescent

Same as skip(user_input, N).

ttytab(+N) obsolescent

Same as tab(user_output, N).