Run Goal as once/1,
while characters written to the current output are sent to Output.
The predicate is SWI-Prolog-specific, inspired by various posts to the
mailinglist. It provides a flexible replacement for predicates such as
sformat/3 , swritef/3,
term_to_atom/2, atom_number/2
converting numbers to atoms, etc. The predicate format/3
accepts the same terms as output argument.
For capturing other streams, see with_output_to/3.
Applications should generally avoid creating atoms by breaking and
concatenating other atoms, as the creation of large numbers of
intermediate atoms generally leads to poor performance, even more so in
multithreaded applications. This predicate supports creating difference
lists from character data efficiently. The example below defines the DCG
rule term//1 to insert a term in the output:
term(Term, In, Tail) :-
with_output_to(codes(In, Tail), write(Term)).
?- phrase(term(hello), X).
X = [104, 101, 108, 108, 111]
Output takes one of the shapes below. Except for the
first, the system creates a temporary stream using the wchar_t
internal encoding that points at a memory buffer. The encoding cannot be
changed and an attempt to call set_stream/2
using encoding(Encoding) results in a permission_error
exception.
- A Stream handle or alias
- Temporarily switch current output to the given stream. Redirection using
with_output_to/2
guarantees the original output is restored, also if
Goal fails or raises an exception. See also call_cleanup/2.
- atom(-Atom)
- Create an atom from the emitted characters. Please note the remark
above.
- string(-String)
- Create a string object as defined in section
5.2.
- codes(-Codes)
- Create a list of character codes from the emitted characters, similar to
atom_codes/2.
- codes(-Codes, -Tail)
- Create a list of character codes as a difference list.
- chars(-Chars)
- Create a list of one-character atoms from the emitted characters,
similar to atom_chars/2.
- chars(-Chars, -Tail)
- Create a list of one-character atoms as a difference list.