194 lines
7.0 KiB
HTML
194 lines
7.0 KiB
HTML
<html>
|
|
<head>
|
|
<!-- This file has been generated by unroff 1.0, 03/21/96 19:29:45. -->
|
|
<!-- Do not edit! -->
|
|
<link rev="made" href="mailto:net@informatik.uni-bremen.de">
|
|
<title>unroff Programmer's Manual, section 9.</title>
|
|
</head><body>
|
|
<h2><a name="section9">9.</a> <tt> </tt>Streams
|
|
</h2>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt>Input, output, and storage of text lines in
|
|
<i>unroff
|
|
</i>are centered around a new Scheme data type named
|
|
<i>stream
|
|
</i>and a set of primitives that work on streams.<tt> </tt>
|
|
A stream can act as a source (input stream) or as a sink (output
|
|
stream) for lines of text.<tt> </tt>
|
|
Streams not only serve as the basis for input and output operations
|
|
and for the exchange of text with shell commands, but can also be used
|
|
to temporarily buffer lines of text (e.g. footnotes or tables of
|
|
contents) and to implement user-defined macros in a simple way.<tt> </tt>
|
|
Each input or output stream can be connected to one of the
|
|
following three types of
|
|
<i>targets</i>:
|
|
<ul>
|
|
<li>
|
|
a file, or the program's standard input or standard output
|
|
<li>
|
|
a UNIX pipe connected to a shell running a shell command
|
|
<li>
|
|
an internal
|
|
<i>buffer
|
|
</i>whose lifetime is limited to that of the current invocation of
|
|
<i>unroff</i>.<tt> </tt>
|
|
</ul>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt>Buffers act similar to (initially empty) files, except that
|
|
they are not visible from the outside and that they are destroyed
|
|
automatically on exit of the program.<tt> </tt>
|
|
Once a buffer has been filled with text through an output stream,
|
|
it can be reopened and read through an input stream multiple times.<tt> </tt>
|
|
However, if a buffer is currently written through an output stream,
|
|
no more streams may refer to the same buffer.<tt> </tt>
|
|
As the contents of buffers kept in memory, input and output operations
|
|
on buffers are fast.<tt> </tt>
|
|
The sample implementation of user-defined macros utilizes buffers
|
|
to store the macro bodies; a macro can then be expanded simply
|
|
by redirecting the current input source to the corresponding buffer
|
|
temporarily.<tt> </tt>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt>Both the parser and all input and output primitives operate on a
|
|
<i>current input stream
|
|
</i>and a
|
|
<i>current output stream</i>;
|
|
input and output is always performed using these two streams.<tt> </tt>
|
|
On startup,
|
|
<i>unroff
|
|
</i>initializes the current output stream to either point to
|
|
standard output or to a newly created output file (usually depending on
|
|
the value of the
|
|
<b>document
|
|
</b>option).<tt> </tt>
|
|
If the current output stream is assigned the literal #f,
|
|
output is sent to standard output<a href="m-notes.html#footnote2">[note 2]</a>
|
|
.<tt> </tt>
|
|
Likewise, for each input file mentioned in the command line,
|
|
a stream pointing to that file is created and assigned to
|
|
the current input stream before the parser starts processing
|
|
the file.<tt> </tt>
|
|
The rest of this section lists the Scheme primitives operating
|
|
on streams.<tt> </tt>
|
|
<h2>
|
|
(stream? <i>obj</i>)
|
|
</h2>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt>The type predicate for the new data type.<tt> </tt>
|
|
It returns #t if
|
|
<i>obj
|
|
</i>is a member of the type
|
|
<i>stream</i>,
|
|
otherwise #f.<tt> </tt>
|
|
<h2>
|
|
(input-stream)
|
|
<br>
|
|
(output-stream)
|
|
</h2>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt>Returns the current input stream, or output stream respectively.<tt> </tt>
|
|
<h2>
|
|
(open-input-stream <i>target</i>)
|
|
<br>
|
|
(open-output-stream <i>target</i>)
|
|
<br>
|
|
(append-output-stream <i>target</i>)
|
|
</h2>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt>These primitives create a new input stream or output stream pointing
|
|
to the specified target.<tt> </tt>
|
|
The argument
|
|
<i>target
|
|
</i>is a string or a symbol.<tt> </tt>
|
|
If the target is enclosed in square brackets, it names a buffer;
|
|
if it begins with the pipe symbol `|', a pipe to a shell running
|
|
the rest of the target as a shell command is established; otherwise
|
|
<i>target
|
|
</i>is interpreted as a file name.<tt> </tt>
|
|
<i>append-output-stream
|
|
</i>rewinds to the end of the specified output buffer or file before
|
|
the first output operation; it acts like
|
|
<i>open-output-stream
|
|
</i>in case of a pipe.<tt> </tt>
|
|
Examples:
|
|
<dl><dt><dd>
|
|
<pre>
|
|
(let* ((buffer (open-output-stream '[temp]))
|
|
(pipe (open-input-stream "|ls -l /usr/lib/tmac"))
|
|
(file (open-input-stream "/etc/passwd")))
|
|
...)
|
|
</pre>
|
|
</dl>
|
|
<h2>
|
|
(set-input-stream! <i>stream</i>)
|
|
<br>
|
|
(set-output-stream! <i>stream</i>)
|
|
</h2>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt>These primitives make the specified stream the
|
|
<i>current
|
|
</i>input stream (or output stream respectively).<tt> </tt>
|
|
<i>stream
|
|
</i>must be the result of a call to one of the three primitives that
|
|
open a stream, or #f.<tt> </tt>
|
|
An error is signaled if
|
|
<i>set-input-stream!
|
|
</i>is applied to an output stream or vice versa, or if the stream
|
|
has been closed in the meantime.<tt> </tt>
|
|
<h2>
|
|
(close-stream <i>stream</i>)
|
|
</h2>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt>Closes the specified stream.<tt> </tt>
|
|
An error is signaled if the stream is still the current input
|
|
stream or current output stream.<tt> </tt>
|
|
Once an output stream pointing to a buffer has been closed, the
|
|
buffer can be reopened for reading.<tt> </tt>
|
|
A stream that is no longer reachable is closed automatically
|
|
during the next run of the garbage collector.<tt> </tt>
|
|
<h2>
|
|
(stream-buffer? <i>stream</i>)
|
|
<br>
|
|
(stream-file? <i>stream</i>)
|
|
<br>
|
|
(stream-pipe? <i>stream</i>)
|
|
</h2>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt>These predicates return #t if the specified stream points to a
|
|
buffer, a file, or a pipe respectively, otherwise #f.<tt> </tt>
|
|
<h2>
|
|
(stream-target <i>stream</i>)
|
|
</h2>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt>This primitive returns the target to which the specified stream
|
|
points.<tt> </tt>
|
|
The return value is a string.<tt> </tt>
|
|
In case of a pipe, the target is truncated at the first space,
|
|
that is, only the command name is included.<tt> </tt>
|
|
The target of the current input stream (together with the current
|
|
line number) is displayed as a prefix of error messages and
|
|
can also be obtained through the primitive
|
|
<a href="m-11.html#.substitute"><i>substitute</i></a>
|
|
described below.<tt> </tt>
|
|
<h2>
|
|
(stream-position <i>stream</i>)
|
|
</h2>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt>Returns the current character position of the specified output stream,
|
|
that is, the offset at which the next character will be written.<tt> </tt>
|
|
The return value for input streams is currently always zero.<tt> </tt>
|
|
This primitive is useful in conjunction with
|
|
<a href="m-14.html#.file-insertions"><i>file-insertions</i></a>
|
|
(described below).<tt> </tt>
|
|
<h2>
|
|
(stream-string <i>target</i>)
|
|
</h2>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt>This primitive opens an input string to the specified target,
|
|
reads from the stream until end-of-stream is reached, closes
|
|
the stream, and returns the concatenation of all the lines that
|
|
have been read as a string<a href="m-notes.html#footnote3">[note 3]</a>
|
|
.<tt> </tt>
|
|
<p><hr>
|
|
Markup created by <em>unroff</em> 1.0, <tt> </tt> <tt> </tt>March 21, 1996, <tt> </tt> <tt> </tt>net@informatik.uni-bremen.de</body>
|
|
</html>
|