/usr/lib/swi-prolog/doc/Manual/chario.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

<HTML>
<HEAD>
<TITLE>SWI-Prolog 5.11.18 Reference Manual: Section 4.17</TITLE><LINK REL=home HREF="index.html">
<LINK REL=contents HREF="Contents.html">
<LINK REL=index HREF="DocIndex.html">
<LINK REL=summary HREF="summary.html">
<LINK REL=previous HREF="streamstat.html">
<LINK REL=next HREF="termrw.html">
<STYLE type="text/css">
/* Style sheet for SWI-Prolog latex2html
*/

dd.defbody
{ margin-bottom: 1em;
}

dt.pubdef
{ background-color: #c5e1ff;
}

dt.multidef
{ background-color: #c8ffc7;
}

.bib dd
{ margin-bottom: 1em;
}

.bib dt
{ float: left;
margin-right: 1.3ex;
}

pre.code
{ margin-left: 1.5em;
margin-right: 1.5em;
border: 1px dotted;
padding-top: 5px;
padding-left: 5px;
padding-bottom: 5px;
background-color: #f8f8f8;
}

div.navigate
{ text-align: center;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
}

div.title
{ text-align: center;
padding-bottom: 1em;
font-size: 200%;
font-weight: bold;
}

div.author
{ text-align: center;
font-style: italic;
}

div.abstract
{ margin-top: 2em;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
margin-left: 10%; margin-right:10%;
}

div.abstract-title
{ text-align: center;
padding: 5px;
font-size: 120%;
font-weight: bold;
}

div.toc-h1
{ font-size: 200%;
font-weight: bold;
}

div.toc-h2
{ font-size: 120%;
font-weight: bold;
margin-left: 2em;
}

div.toc-h3
{ font-size: 100%;
font-weight: bold;
margin-left: 4em;
}

div.toc-h4
{ font-size: 100%;
margin-left: 6em;
}

span.sec-nr
{
}

span.sec-title
{
}

span.pred-ext
{ font-weight: bold;
}

span.pred-tag
{ float: right;
padding-top: 0.2em;
font-size: 80%;
font-style: italic;
color: #202020;
}

/* Footnotes */

sup.fn { color: blue; text-decoration: underline; }
span.fn-text { display: none; }
sup.fn span {display: none;}
sup:hover span
{ display: block !important;
position: absolute; top: auto; left: auto; width: 80%;
color: #000; background: white;
border: 2px solid;
padding: 5px; margin: 10px; z-index: 100;
font-size: smaller;
}
</STYLE>
</HEAD>
<BODY BGCOLOR="white">
<DIV class="navigate"><A class="nav" href="index.html"><IMG SRC="home.gif" BORDER=0 ALT="Home"></A>
<A class="nav" href="Contents.html"><IMG SRC="index.gif" BORDER=0 ALT="Contents"></A>
<A class="nav" href="DocIndex.html"><IMG SRC="yellow_pages.gif" BORDER=0 ALT="Index"></A>
<A class="nav" href="summary.html"><IMG SRC="info.gif" BORDER=0 ALT="Summary"></A>
<A class="nav" href="streamstat.html"><IMG SRC="prev.gif" BORDER=0 ALT="Previous"></A>
<A class="nav" href="termrw.html"><IMG SRC="next.gif" BORDER=0 ALT="Next"></A>
</DIV>

<H2><A NAME="sec:4.17"><SPAN class="sec-nr">4.17</SPAN> <SPAN class="sec-title">Primitive 
character I/O</SPAN></A></H2>

<A NAME="sec:chario"></A>

<P>See <A class="sec" href="chars.html">section 4.2</A> for an overview 
of supported character representations.

<DL class="latex">
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="nl/0"><STRONG>nl</STRONG></A></DT>
<DD class="defbody">
Write a newline character to the current output stream. On Unix systems
<A NAME="idx:nl0:814"></A><A class="pred" href="chario.html#nl/0">nl/0</A> 
is equivalent to <CODE>put(10)</CODE>.</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="nl/1"><STRONG>nl</STRONG>(<VAR>+Stream</VAR>)</A></DT>
<DD class="defbody">
Write a newline to <VAR>Stream</VAR>.</DD>
<DT class="pubdef"><A NAME="put/1"><STRONG>put</STRONG>(<VAR>+Char</VAR>)</A></DT>
<DD class="defbody">
Write <VAR>Char</VAR> to the current output stream, <VAR>Char</VAR> is 
either an integer-expression evaluating to a character code or an atom 
of one character. Depreciated. New code should use <A NAME="idx:putchar1:815"></A><A class="pred" href="chario.html#put_char/1">put_char/1</A> 
or <A NAME="idx:putcode1:816"></A><A class="pred" href="chario.html#put_code/1">put_code/1</A>.</DD>
<DT class="pubdef"><A NAME="put/2"><STRONG>put</STRONG>(<VAR>+Stream, 
+Char</VAR>)</A></DT>
<DD class="defbody">
Write <VAR>Char</VAR> to <VAR>Stream</VAR>. See <A NAME="idx:put1:817"></A><A class="pred" href="chario.html#put/1">put/1</A> 
for details.</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="put_byte/1"><STRONG>put_byte</STRONG>(<VAR>+Byte</VAR>)</A></DT>
<DD class="defbody">
Write a single byte to the output. <VAR>Byte</VAR> must be an integer 
between 0 and 255.</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="put_byte/2"><STRONG>put_byte</STRONG>(<VAR>+Stream, 
+Byte</VAR>)</A></DT>
<DD class="defbody">
Write a single byte to a stream. <VAR>Byte</VAR> must be an integer 
between 0 and 255.</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="put_char/1"><STRONG>put_char</STRONG>(<VAR>+Char</VAR>)</A></DT>
<DD class="defbody">
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 <VAR>Stream</VAR> cannot represent <VAR>Char</VAR>.</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="put_char/2"><STRONG>put_char</STRONG>(<VAR>+Stream, 
+Char</VAR>)</A></DT>
<DD class="defbody">
Write a character to <VAR>Stream</VAR>, obeying the encoding defined for
<VAR>Stream</VAR>. Note that this may raise an exception if the encoding 
of <VAR>Stream</VAR> cannot represent <VAR>Char</VAR>.</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="put_code/1"><STRONG>put_code</STRONG>(<VAR>+Code</VAR>)</A></DT>
<DD class="defbody">
Similar to <A NAME="idx:putchar1:818"></A><A class="pred" href="chario.html#put_char/1">put_char/1</A>, 
but using a <EM>character code</EM>. <VAR>Code</VAR> is a non-negative 
integer. Note that this may raise an exception if the encoding of <VAR>Stream</VAR> 
cannot represent <VAR>Code</VAR>.</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="put_code/2"><STRONG>put_code</STRONG>(<VAR>+Stream, 
+Code</VAR>)</A></DT>
<DD class="defbody">
Same as <A NAME="idx:putcode1:819"></A><A class="pred" href="chario.html#put_code/1">put_code/1</A> 
but directing <VAR>Code</VAR> to <VAR>Stream</VAR>.</DD>
<DT class="pubdef"><A NAME="tab/1"><STRONG>tab</STRONG>(<VAR>+Amount</VAR>)</A></DT>
<DD class="defbody">
Writes <VAR>Amount</VAR> spaces on the current output stream. <VAR>Amount</VAR> 
should be an expression that evaluates to a positive integer (see
<A class="sec" href="arith.html">section 4.25</A>).</DD>
<DT class="pubdef"><A NAME="tab/2"><STRONG>tab</STRONG>(<VAR>+Stream, 
+Amount</VAR>)</A></DT>
<DD class="defbody">
Writes <VAR>Amount</VAR> spaces to <VAR>Stream</VAR>.</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="flush_output/0"><STRONG>flush_output</STRONG></A></DT>
<DD class="defbody">
Flush pending output on current output stream. <A NAME="idx:flushoutput0:820"></A><A class="pred" href="chario.html#flush_output/0">flush_output/0</A> 
is automatically generated by <A NAME="idx:read1:821"></A><A class="pred" href="termrw.html#read/1">read/1</A> 
and derivatives if the current input stream is <CODE>user</CODE> and the 
cursor is not at the left margin.</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="flush_output/1"><STRONG>flush_output</STRONG>(<VAR>+Stream</VAR>)</A></DT>
<DD class="defbody">
Flush output on the specified stream. The stream must be open for 
writing.</DD>
<DT class="pubdef"><A NAME="ttyflush/0"><STRONG>ttyflush</STRONG></A></DT>
<DD class="defbody">
Flush pending output on stream <VAR>user</VAR>. See also <A NAME="idx:flushoutput01:822"></A><A class="pred" href="chario.html#flush_output/0">flush_output/[0,1]</A>.
</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="get_byte/1"><STRONG>get_byte</STRONG>(<VAR>-Byte</VAR>)</A></DT>
<DD class="defbody">
Read the current input stream and unify the next byte with <VAR>Byte</VAR> 
(an integer between 0 and 255. <VAR>Byte</VAR> is unified with -1 on end 
of file.</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="get_byte/2"><STRONG>get_byte</STRONG>(<VAR>+Stream, 
-Byte</VAR>)</A></DT>
<DD class="defbody">
Read the next byte from <VAR>Stream</VAR>, returning an integer between 
0 and 255.</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="get_code/1"><STRONG>get_code</STRONG>(<VAR>-Code</VAR>)</A></DT>
<DD class="defbody">
Read the current input stream and unify <VAR>Code</VAR> with the 
character code of the next character. <VAR>Code</VAR> is unified with -1 
on end of file. See also <A NAME="idx:getchar1:823"></A><A class="pred" href="chario.html#get_char/1">get_char/1</A>.</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="get_code/2"><STRONG>get_code</STRONG>(<VAR>+Stream, 
-Code</VAR>)</A></DT>
<DD class="defbody">
Read the next character-code from <VAR>Stream</VAR>.</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="get_char/1"><STRONG>get_char</STRONG>(<VAR>-Char</VAR>)</A></DT>
<DD class="defbody">
Read the current input stream and unify <VAR>Char</VAR> with the next 
character as a one-character-atom. See also <A NAME="idx:atomchars2:824"></A><A class="pred" href="manipatom.html#atom_chars/2">atom_chars/2</A>. 
On end-of-file, <VAR>Char</VAR> is unified to the atom <CODE>end_of_file</CODE>.</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="get_char/2"><STRONG>get_char</STRONG>(<VAR>+Stream, 
-Char</VAR>)</A></DT>
<DD class="defbody">
Unify <VAR>Char</VAR> with the next character from <VAR>Stream</VAR> as 
a one-character-atom. See also <A NAME="idx:getchar2:825"></A><A class="pred" href="chario.html#get_char/2">get_char/2</A>, <A NAME="idx:getbyte2:826"></A><A class="pred" href="chario.html#get_byte/2">get_byte/2</A> 
and <A NAME="idx:getcode2:827"></A><A class="pred" href="chario.html#get_code/2">get_code/2</A>.</DD>
<DT class="pubdef"><A NAME="get0/1"><STRONG>get0</STRONG>(<VAR>-Char</VAR>)</A></DT>
<DD class="defbody">
Edinburgh version of the ISO <A NAME="idx:getcode1:828"></A><A class="pred" href="chario.html#get_code/1">get_code/1</A> 
predicate. Note that Edinburgh prolog didn't support wide characters and 
therefore technically speaking
<A NAME="idx:get01:829"></A><A class="pred" href="chario.html#get0/1">get0/1</A> 
should have been mapped to <A NAME="idx:getbyte1:830"></A><A class="pred" href="chario.html#get_byte/1">get_byte/1</A>. 
The intention of <A NAME="idx:get01:831"></A><A class="pred" href="chario.html#get0/1">get0/1</A> 
however is to read character codes.</DD>
<DT class="pubdef"><A NAME="get0/2"><STRONG>get0</STRONG>(<VAR>+Stream, 
-Char</VAR>)</A></DT>
<DD class="defbody">
Edinburgh version of the ISO <A NAME="idx:getcode2:832"></A><A class="pred" href="chario.html#get_code/2">get_code/2</A> 
predicate. See also <A NAME="idx:get01:833"></A><A class="pred" href="chario.html#get0/1">get0/1</A>.</DD>
<DT class="pubdef"><A NAME="get/1"><STRONG>get</STRONG>(<VAR>-Char</VAR>)</A></DT>
<DD class="defbody">
Read the current input stream and unify the next non-blank character 
with <VAR>Char</VAR>. <VAR>Char</VAR> is unified with -1 on end of file.</DD>
<DT class="pubdef"><A NAME="get/2"><STRONG>get</STRONG>(<VAR>+Stream, 
-Char</VAR>)</A></DT>
<DD class="defbody">
Read the next non-blank character from <VAR>Stream</VAR>.</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="peek_byte/1"><STRONG>peek_byte</STRONG>(<VAR>-Byte</VAR>)</A></DT>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="peek_byte/2"><STRONG>peek_byte</STRONG>(<VAR>+Stream, 
-Byte</VAR>)</A></DT>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="peek_code/1"><STRONG>peek_code</STRONG>(<VAR>-Code</VAR>)</A></DT>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="peek_code/2"><STRONG>peek_code</STRONG>(<VAR>+Stream, 
-Code</VAR>)</A></DT>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="peek_char/1"><STRONG>peek_char</STRONG>(<VAR>-Char</VAR>)</A></DT>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="peek_char/2"><STRONG>peek_char</STRONG>(<VAR>+Stream, 
-Char</VAR>)</A></DT>
<DD class="defbody">
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 <A NAME="idx:setstream2:834"></A><A class="pred" href="IO.html#set_stream/2">set_stream/2</A>) 
and raise a permission_error if the stream is unbuffered or the buffer 
is too small to hold the longest multibyte sequence that might need to 
be buffered.</DD>
<DT class="pubdef"><A NAME="skip/1"><STRONG>skip</STRONG>(<VAR>+Code</VAR>)</A></DT>
<DD class="defbody">
Read the input until <VAR>Char</VAR> or the end of the file is 
encountered. A subsequent call to <A NAME="idx:getcode1:835"></A><A class="pred" href="chario.html#get_code/1">get_code/1</A> 
will read the first character after
<VAR>Code</VAR>.</DD>
<DT class="pubdef"><A NAME="skip/2"><STRONG>skip</STRONG>(<VAR>+Stream, 
+Code</VAR>)</A></DT>
<DD class="defbody">
Skip input (as <A NAME="idx:skip1:836"></A><A class="pred" href="chario.html#skip/1">skip/1</A>) 
on <VAR>Stream</VAR>.</DD>
<DT class="pubdef"><A NAME="get_single_char/1"><STRONG>get_single_char</STRONG>(<VAR>-Code</VAR>)</A></DT>
<DD class="defbody">
Get a single character from input stream `user' (regardless of the 
current input stream). Unlike <A NAME="idx:getcode1:837"></A><A class="pred" href="chario.html#get_code/1">get_code/1</A> 
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 <STRONG>-tty</STRONG> 
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.</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="at_end_of_stream/0"><STRONG>at_end_of_stream</STRONG></A></DT>
<DD class="defbody">
Succeeds after the last character of the current input stream has been 
read. Also succeeds if there is no valid current input stream.</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="at_end_of_stream/1"><STRONG>at_end_of_stream</STRONG>(<VAR>+Stream</VAR>)</A></DT>
<DD class="defbody">
Succeeds after the last character of the named stream is read, or
<VAR>Stream</VAR> 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 <A NAME="idx:open4:838"></A><A class="pred" href="IO.html#open/4">open/4</A>).</DD>
<DT class="pubdef"><A NAME="set_end_of_stream/1"><STRONG>set_end_of_stream</STRONG>(<VAR>+Stream</VAR>)</A></DT>
<DD class="defbody">
Sets the size of the file opened as <VAR>Stream</VAR> to the current 
file-position. This is typically used in combination with the open-mode <CODE>update</CODE>.</DD>
<DT class="pubdef"><A NAME="copy_stream_data/3"><STRONG>copy_stream_data</STRONG>(<VAR>+StreamIn, 
+StreamOut, +Len</VAR>)</A></DT>
<DD class="defbody">
Copy <VAR>Len</VAR> codes from stream <VAR>StreamIn</VAR> to <VAR>StreamOut</VAR>. 
Note that the copy is done using the semantics of <A NAME="idx:getcode2:839"></A><A class="pred" href="chario.html#get_code/2">get_code/2</A> 
and
<A NAME="idx:putcode2:840"></A><A class="pred" href="chario.html#put_code/2">put_code/2</A>, 
taking care of possibly recoding that needs take place between two text 
files. See <A class="sec" href="widechars.html">section 2.17.1</A>.</DD>
<DT class="pubdef"><A NAME="copy_stream_data/2"><STRONG>copy_stream_data</STRONG>(<VAR>+StreamIn, 
+StreamOut</VAR>)</A></DT>
<DD class="defbody">
Copy data all (remaining) data from stream <VAR>StreamIn</VAR> to
<VAR>StreamOut</VAR>.</DD>
<DT class="pubdef"><A NAME="read_pending_input/3"><STRONG>read_pending_input</STRONG>(<VAR>+StreamIn, 
-Codes, ?Tail</VAR>)</A></DT>
<DD class="defbody">
Read input pending in the input buffer of <VAR>StreamIn</VAR> and return 
it in the difference list <VAR>Codes</VAR>-<VAR>Tail</VAR>. I.e. the 
available characters codes are used to create the list <VAR>Codes</VAR> 
ending in the tail <VAR>Tail</VAR>. This predicate is intended for 
efficient unbuffered copying and filtering of input coming from network 
connections or devices.

<P>The following code fragment realises efficient non-blocking copy of 
data from an input- to an output stream. The <A NAME="idx:atendofstream1:841"></A><A class="pred" href="chario.html#at_end_of_stream/1">at_end_of_stream/1</A> 
call checks for end-of-stream and fills the input buffer. Note that the 
use of a <A NAME="idx:getcode2:842"></A><A class="pred" href="chario.html#get_code/2">get_code/2</A> 
and <A NAME="idx:putcode2:843"></A><A class="pred" href="chario.html#put_code/2">put_code/2</A> 
based loop requires a <A NAME="idx:flushoutput1:844"></A><A class="pred" href="chario.html#flush_output/1">flush_output/1</A> 
call after <EM>each</EM> <A NAME="idx:putcode2:845"></A><A class="pred" href="chario.html#put_code/2">put_code/2</A>. 
The <A NAME="idx:copystreamdata2:846"></A><A class="pred" href="chario.html#copy_stream_data/2">copy_stream_data/2</A> 
does not allow for inspection of the copied data and suffers from the 
same buffering issues.

<PRE class="code">
copy(In, Out) :-
        repeat,
            (   at_end_of_stream(In)
            -&gt;  !
            ;   read_pending_input(In, Chars, []),
                format(Out, '~s', [Chars]),
                flush_output(Out),
                fail
            ).
</PRE>

<P></DD>
</DL>

<P></BODY></HTML>
swi-prolog-nox 5.10.4-3ubuntu1 / usr / lib / swi-prolog / doc / Manual / chario.html
