4.19 Primitive character I/O

See section 4.2 for an overview of supported character representations.

[ISO]nl

Write a newline character to the current output stream. On Unix systems nl/0 is equivalent to put(10).

[ISO]nl(+Stream)

Write a newline to Stream.

put(+Char)

Write Char to the current output stream. Char is either an integer expression evaluating to a character code or an atom of one character. Deprecated. New code should use put_char/1 or put_code/1.

put(+Stream, +Char)

Write Char to Stream. See put/1 for details.

[ISO]put_byte(+Byte)

Write a single byte to the output. Byte must be an integer between 0 and 255.

[ISO]put_byte(+Stream, +Byte)

Write a single byte to Stream. Byte must be an integer between 0 and 255.

[ISO]put_char(+Char)

Write a character to the current output, obeying the encoding defined for the current output stream. Note that this may raise an exception if the encoding of the output stream cannot represent Char.

[ISO]put_char(+Stream, +Char)

Write a character to Stream, obeying the encoding defined for Stream. Note that this may raise an exception if the encoding of Stream cannot represent Char.

[ISO]put_code(+Code)

Similar to put_char/1, but using a character code. Code is a non-negative integer. Note that this may raise an exception if the encoding of the output stream cannot represent Code.

[ISO]put_code(+Stream, +Code)

Same as put_code/1 but directing Code to Stream.

tab(+Amount)

Write Amount spaces on the current output stream. Amount should be an expression that evaluates to a positive integer (see section 4.27).

tab(+Stream, +Amount)

Write Amount spaces to Stream.

[ISO]flush_output

Flush pending output on current output stream. flush_output/0 is automatically generated by read/1 and derivatives if the current input stream is user and the cursor is not at the left margin.

[ISO]flush_output(+Stream)

Flush output on the specified stream. The stream must be open for writing.

ttyflush

Flush pending output on stream user. See also flush_output/[0,1].

[ISO]get_byte(-Byte)

Read the current input stream and unify the next byte with Byte (an integer between 0 and 255). Byte is unified with -1 on end of file.

[ISO]get_byte(+Stream, -Byte)

Read the next byte from Stream and unify Byte with an integer between 0 and 255.

[ISO]get_code(-Code)

Read the current input stream and unify Code with the character code of the next character. Code is unified with -1 on end of file. See also get_char/1.

[ISO]get_code(+Stream, -Code)

Read the next character code from Stream.

[ISO]get_char(-Char)

Read the current input stream and unify Char with the next character as a one-character atom. See also atom_chars/2. On end-of-file, Char is unified to the atom end_of_file.

[ISO]get_char(+Stream, -Char)

Unify Char with the next character from Stream as a one-character atom. See also get_char/2, get_byte/2 and get_code/2.

[deprecated]get0(-Char)

Edinburgh version of the ISO get_code/1 predicate. Note that Edinburgh Prolog didn't support wide characters and therefore technically speaking get0/1 should have been mapped to get_byte/1. The intention of get0/1, however, is to read character codes.

[deprecated]get0(+Stream, -Char)

Edinburgh version of the ISO get_code/2 predicate. See also get0/1.

[deprecated]get(-Char)

Read the current input stream and unify the next non-blank character with Char. Char is unified with -1 on end of file. The predicate get/1 operates on character codes. See also get0/1.

[deprecated]get(+Stream, -Char)

Read the next non-blank character from Stream. See also get/1, get0/1 and get0/2.

[ISO]peek_byte(-Byte)

[ISO]peek_byte(+Stream, -Byte)

[ISO]peek_code(-Code)

[ISO]peek_code(+Stream, -Code)

[ISO]peek_char(-Char)

[ISO]peek_char(+Stream, -Char)

Read the next byte/code/char from the input without removing it. These predicates do not modify the stream's position or end-of-file status. These predicates require a buffered stream (see set_stream/2) and raise a permission error if the stream is unbuffered or the buffer is too small to hold the longest multi-byte sequence that might need to be buffered.

peek_string(+Stream, +Len, -String)

Read the next Len characters (if the stream is a text stream) or bytes (if the stream is binary) from Stream without removing the data. If Len is larger that the stream buffer size, the buffer size is increased to Len. String can be shorter than Len if the stream contains less data. This predicate is intended to guess the content type of data read from non-repositionable streams.

skip(+Code)

Read the input until Code or the end of the file is encountered. A subsequent call to get_code/1 will read the first character after Code.

skip(+Stream, +Code)

Skip input (as skip/1) on Stream.

get_single_char(-Code)

Get a single character from input stream‘user' (regardless of the current input stream). Unlike get_code/1, this predicate does not wait for a return. The character is not echoed to the user's terminal. This predicate is meant for keyboard menu selection, etc. If SWI-Prolog was started with the --no-tty option this predicate reads an entire line of input and returns the first non-blank character on this line, or the character code of the newline (10) if the entire line consisted of blank characters. See also with_tty_raw/1.

with_tty_raw(:Goal)

Run goal with the user input and output streams set in raw mode, which implies the terminal makes the input available immediately instead of line-by-line and input that is read is not echoed. As a consequence, line editing does not work. See also get_single_char/1.

[ISO]at_end_of_stream

Succeeds after the last character of the current input stream has been read. Also succeeds if there is no valid current input stream.

[ISO]at_end_of_stream(+Stream)

Succeeds after the last character of the named stream is read, or Stream is not a valid input stream. The end-of-stream test is only available on buffered input streams (unbuffered input streams are rarely used; see open/4).

set_end_of_stream(+Stream)

Set the size of the file opened as Stream to the current file position. This is typically used in combination with the open-mode update.

copy_stream_data(+StreamIn, +StreamOut, +Len)

Copy Len codes from StreamIn to StreamOut. Note that the copy is done using the semantics of get_code/2 and put_code/2, taking care of possibly recoding that needs to take place between two text files. See section 2.19.1.

copy_stream_data(+StreamIn, +StreamOut)

Copy all (remaining) data from StreamIn to StreamOut.

[det]fill_buffer(+Stream)

Fill the Stream’s input buffer. Subsequent calls try to read more input until the buffer is completely filled. This predicate is used together with read_pending_codes/3 to process input with minimal buffering.

read_pending_codes(+StreamIn, -Codes, ?Tail)

Read input pending in the input buffer of StreamIn and return it in the difference list Codes-Tail. That is, the available characters codes are used to create the list Codes ending in the tail Tail. On encountering end-of-file, both Codes and Tail are unified with the empty list ([]).

This predicate is intended for efficient unbuffered copying and filtering of input coming from network connections or devices. It also enables the library library(pure_input), which processes input from files and streams using a DCG.

The following code fragment realises efficient non-blocking copying of data from an input to an output stream. The at_end_of_stream/1 call checks for end-of-stream and fills the input buffer. Note that the use of a get_code/2 and put_code/2 based loop requires a flush_output/1 call after each put_code/2. The copy_stream_data/2 does not allow for inspection of the copied data and suffers from the same buffering issues.

copy(In, Out) :-
        repeat,
            fill_buffer(In),
            read_pending_codes(In, Chars, Tail),
            \+ \+ ( Tail = [],
                    format(Out, '~s', [Chars]),
                    flush_output(Out)
                  ),
            (   Tail == []
            ->  !
            ;   fail
            ).

read_pending_chars(+StreamIn, -Chars, ?Tail)

As read_pending_codes/3, but returns a difference list of one-character atoms.