11.3.201 seeing/1

Synopsis

seeing(-FileOrStream)

Unifies FileOrStream with the current input stream or file.

Arguments

FileOrStream

file_spec or stream_object

Description

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

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

% nonvar(FileNameOrStream),
see(FileNameOrStream),
…
seeing(FileNameOrStream)

If the current input 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 see/1 (since only filename access to streams opened by see/1 is supported). This includes the stream object user_input (since the standard input stream is assumed to be opened by see/1, and so seeing/1 would return user in this case).

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

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

% var(OldFileNameOrStream),
seeing(OldFileNameOrStream),
…
see(OldFileNameOrStream)

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

% var(OldStream),
current_input(OldStream),
…
set_input(OldStream)

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

Exceptions

None.

See Also

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