Streams and LowLevel Input and Output

Files and pipes are both examples of general Wolfram System objects known as streams. A stream in the Wolfram System is a source of input or output. There are many operations that you can perform on streams.

You can think of >> and << as "highlevel" Wolfram System inputoutput functions. They are based on a set of lowerlevel inputoutput primitives that work directly with streams. By using these primitives, you can exercise more control over exactly how the Wolfram System does input and output. You will often need to do this, for example, if you write Wolfram System programs which store and retrieve intermediate data from files or pipes.

The basic lowlevel scheme for writing output to a stream in the Wolfram System is as follows. First, you call OpenWrite or OpenAppend to "open the stream", telling the Wolfram System that you want to write output to a particular file or external program, and in what form the output should be written. Having opened a stream, you can then call Write or WriteString to write a sequence of expressions or strings to the stream. When you have finished, you call Close to "close the stream".

"name"a file, specified by name
"!name"a command, specified by name
InputStream["name",n]an input stream
OutputStream["name",n]an output stream

Streams in the Wolfram System.

When you open a file or a pipe, the Wolfram System creates a "stream object" that specifies the open stream associated with the file or pipe. In general, the stream object contains the name of the file or the external command used in a pipe, together with a unique number.

The reason that the stream object needs to include a unique number is that in general you can have several streams connected to the same file or external program at the same time. For example, you may start several different instances of the same external program, each connected to a different stream.

Nevertheless, when you have opened a stream, you can still refer to it using a simple file name or external command name so long as there is only one stream associated with this object.

This opens an output stream to the file tmp:
Click for copyable input
This writes a sequence of expressions to the file:
Click for copyable input
Since you only have one stream associated with file tmp, you can refer to it simply by giving the name of the file:
Click for copyable input
This closes the stream:
Click for copyable input
Here is what was written to the file:
Click for copyable input
OpenWrite["file"]open an output stream to a file, wiping out the previous contents of the file
OpenWrite[]open an output stream to a new temporary file
OpenAppend["file"]open an output stream to a file, appending to what was already in the file
OpenWrite["!command"]open an output stream to an external command
Write[stream,expr1,expr2,]write a sequence of expressions to a stream, ending the output with a newline (line feed)
WriteString[stream,str1,str2,]write a sequence of character strings to a stream, with no extra newlines
Close[stream]tell the Wolfram System that you are finished with a stream

Lowlevel output functions.

When you call Write[stream,expr], it writes an expression to the specified stream. The default is to write the expression in Wolfram System input form. If you call Write with a sequence of expressions, it will write these expressions one after another to the stream. In general, it leaves no space between the successive expressions. However, when it has finished writing all the expressions, Write always ends its output with a newline.

This reopens the file tmp:
Click for copyable input
This writes a sequence of expressions to the file, then closes the file:
Click for copyable input
All the expressions are written in input form. The expressions from a single Write are put on the same line:
Click for copyable input

Write provides a way of writing out complete Wolfram Language expressions. Sometimes, however, you may want to write out less structured data. WriteString allows you to write out any character string. Unlike Write, WriteString adds no newlines or other characters.

This opens the stream:
Click for copyable input
This writes two strings to the stream:
Click for copyable input
This writes another string, then closes the stream:
Click for copyable input
Here are the contents of the file. The strings were written exactly as specified, including only the newlines that were explicitly given:
Click for copyable input
Write[{stream1,stream2},expr1,]write expressions to a list of streams
WriteString[{stream1,stream2},str1,]write strings to a list of streams

Writing output to lists of streams.

An important feature of the functions Write and WriteString is that they allow you to write output not just to a single stream, but also to a list of streams.

In using the Wolfram System, it is often convenient to define a channel which consists of a list of streams. You can then simply tell the Wolfram System to write to the channel, and have it automatically write the same object to several streams.

In a standard interactive Wolfram System session, there are several output channels that are usually defined. These specify where particular kinds of output should be sent. Thus, for example, $Output specifies where standard output should go, while $Messages specifies where messages should go. The function Print then works essentially by calling Write with the $Output channel. Message works in the same way by calling Write with the $Messages channel. "The Main Loop" lists the channels used in a typical Wolfram System session.

Note that when you run the Wolfram System through the Wolfram Symbolic Transfer Protocol (WSTP), a different approach is usually used. All output is typically written to a single WSTP link, but each piece of output appears in a "packet" which indicates what type it is.

In most cases, the names of files or external commands that you use in the Wolfram System correspond exactly with those used by your computers operating system. On some systems, however, the Wolfram System supports various streams with special names.

"stdout"standard output
"stderr"standard error

Special streams used on some computer systems.

The special stream "stdout" allows you to give output to the "standard output" provided by the operating system. Note however that you can use this stream only with simple textbased interfaces to the Wolfram System. If your interaction with the Wolfram System is more complicated, then this stream will not work, and trying to use it may cause considerable trouble.

option name
default value
FormatTypeInputFormthe default output format to use
PageWidth78the width of the page in characters
NumberMarks$NumberMarkswhether to include ` marks in approximate numbers
CharacterEncoding$CharacterEncodingencoding to be used for special characters

Some options for output streams.

You can associate a number of options with output streams. You can specify these options when you first open a stream using OpenWrite or OpenAppend.

This opens a stream, specifying that the default output format used should be OutputForm:
Click for copyable input
This writes expressions to the stream, then closes the stream:
Click for copyable input
The expressions were written to the stream in OutputForm:
Click for copyable input

Note that you can always override the output format specified for a particular stream by wrapping a particular expression you write to the stream with an explicit Wolfram System format directive, such as OutputForm or TeXForm.

The option PageWidth gives the width of the page available for textual output from the Wolfram System. All lines of output are broken so that they fit in this width. If you do not want any lines to be broken, you can set PageWidth->Infinity. Usually, however, you will want to set PageWidth to the value appropriate for your particular output device. On many systems, you will have to run an external program to find out what this value is. Using SetOptions, you can make the default rule for PageWidth be, for example, PageWidth:><<"!devicewidth", so that an external program is run automatically to find the value of the option.

This opens a stream, specifying that the page width is 20 characters:
Click for copyable input
This writes out an expression, then closes the stream:
Click for copyable input
The lines in the expression written out are all broken so as to be at most 20 characters long:
Click for copyable input

The option CharacterEncoding allows you to specify a character encoding that will be used for all strings which are sent to a particular output stream, whether by Write or WriteString. You will typically need to use CharacterEncoding if you want to modify an international character set, or prevent a particular output device from receiving characters that it cannot handle.

Options[stream]find the options that have been set for a stream
SetOptions[stream,opt1->val1,]reset options for an open stream

Manipulating options of streams.

This opens a stream with the default settings for options:
Click for copyable input
This changes the FormatType option for the open stream:
Click for copyable input
Options shows the options you have set for the open stream:
Click for copyable input
This closes the stream again:
Click for copyable input
Options[$Output]find the options set for all streams in the channel $Output
SetOptions[$Output,opt1->val1,]set options for all streams in the channel $Output

Manipulating options for the standard output channel.

At every point in your session, the Wolfram System maintains a list Streams[] of all the input and output streams that are currently open, together with their options. In some cases, you may find it useful to look at this list directly. The Wolfram System will not, however, allow you to modify the list, except indirectly through OpenRead and so on.