11.3.225 telling/1

Synopsis

telling(-FileOrStream)

Unifies FileOrStream with the current output stream or file.

Arguments

FileOrStream

file_spec or stream_object

Description

Exactly the same as current_output(FileOrStream), except that FileOrStream will be unified with a filename if the current output stream was opened by tell/1 (ref-iou-sfh).

Can be used to verify that FileNameOrStream is still the current output stream as follows:

% nonvar(FileNameOrStream),
tell(FileNameOrStream),
…
telling(FileNameOrStream)

If the current output stream has not been changed (or if changed, then restored), then the above sequence will succeed for all file names and all stream objects opened by open/[3,4]. However, it will fail for all stream objects opened by tell/1 (since only filename access to streams opened by tell/1 is supported). This includes the stream object user_output (since the standard output stream is assumed to be opened by tell/1, and so telling/1 would return user in this case).

If FileOrStream is instantiated to a value that is not the identifier of the current output stream, then telling(FileOrStream) simply fails.

Can be followed by tell/1 to ensure that a section of code leaves the current output unchanged:

% var(OldFileNameOrStream),
telling(OldFileNameOrStream),
…
tell(OldFileNameOrStream)

The above is analogous to its stream-object-based counterpart,

% var(OldStream),
current_output(OldStream),
…
set_output(OldStream)

Both of these sequences will always succeed regardless of whether the current output stream was opened by tell/1 or open/[3,4].

Exceptions

None.

See Also

tell/1, open/[3,4], current_input/1, ref-iou-sfh.