4.18 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. Depreciated. 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 a 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 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 Stream cannot represent Code.

[ISO]put_code(+Stream, +Code)

Same as put_code/1 but directing Code to Stream.

tab(+Amount)

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

tab(+Stream, +Amount)

Writes 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, returning 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.

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.

get0(+Stream, -Char)

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

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.

get(+Stream, -Char)

Read the next non-blank character from Stream.

[ISO]peek_byte(-Byte)

Reads the next input byte like get_byte/1, but does not remove it from the input stream.

[ISO]peek_byte(+Stream, -Byte)

Reads the next input byte like get_byte/2, but does not remove it from the stream.

[ISO]peek_code(-Code)

Reads the next input code like get_code/1, but does not remove it from the input stream.

[ISO]peek_code(+Stream, -Code)

Reads the next input code like get_code/2, but does not remove it from the stream.

[ISO]peek_char(-Char)

Reads the next input character like get_char/1, but does not remove it from the input stream.

[ISO]peek_char(+Stream, -Char)

Reads the next input character like get_char/2, but does not remove it from the stream.

skip(+Code)

Read the input until Char 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 -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.

[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 stream (unbuffered input streams are rarely used, see open/4).

copy_stream_data(+StreamIn, +StreamOut, +Len)

Copy Len codes from stream 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 take place between two text files. See section 2.17.1.

copy_stream_data(+StreamIn, +StreamOut)

Copy data all (remaining) data from stream StreamIn to StreamOut.

read_pending_input(+StreamIn, -Codes, ?Tail)

Read input pending in the input buffer of StreamIn and return it in the difference list Codes-Tail. I.e. the available characters codes are used to create the list Codes ending in the tail Tail. This predicate is intended for efficient unbuffered copying and filtering of input coming from network connections or devices.

The following code fragment realises efficient non-blocking copy 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,
            (   at_end_of_stream(In)
            ->  !
            ;   read_pending_input(In, Chars, []),
                format(Out, '~s', [Chars]),
                flush_output(Out),
                fail
            ).