Reading Textual Data

With <<, you can read files that contain Wolfram Language expressions given in input form. Sometimes, however, you may instead need to read files of data in other formats. For example, you may have data generated by an external program which consists of a sequence of numbers separated by spaces. This data cannot be read directly as Wolfram Language input. However, the function (RefLink[ReadList, paclet:ref/ReadList]) can take such data from a file or input stream, and convert it to a Wolfram Language list.

Reading numbers from a file.

Here is a file of numbers:

FilePrint["ExampleData/numbers"]

This reads all the numbers in the file, and returns a list of them:

ReadList["ExampleData/numbers",Number]

Reading blocks of numbers.

This puts each successive pair of numbers from the file into a separate list:

ReadList["ExampleData/numbers",{Number,Number}]

This makes each line in the file into a separate list:

ReadList["ExampleData/numbers",Number,RecordLists->True]

(RefLink[ReadList, paclet:ref/ReadList]) can handle numbers that are given in Fortran-like "(RefLink[E, paclet:ref/E])" notation. Thus, for example, (RefLink[ReadList, paclet:ref/ReadList]) will read 2.5(RefLink[E, paclet:ref/E])+5 as 2.5×(10^5). Note that (RefLink[ReadList, paclet:ref/ReadList]) can handle numbers with any number of digits of precision.

Here is a file containing numbers in Fortran-like "(RefLink[E, paclet:ref/E])" notation:

FilePrint["ExampleData/bignum"]

(RefLink[ReadList, paclet:ref/ReadList]) can handle numbers in this form:

ReadList["ExampleData/bignum",Number]

Reading objects of various types.

(RefLink[ReadList, paclet:ref/ReadList]) can read not only numbers, but also a variety of other types of object. Each type of object is specified by a symbol such as (RefLink[Number, paclet:ref/Number]).

Here is a file containing text:

FilePrint["ExampleData/strings"]

This produces a list of the characters in the file, each given as a one-character string:

ReadList["ExampleData/strings",Character]

Here are the integer codes corresponding to each of the bytes in the file:

ReadList["ExampleData/strings",Byte]

This puts the data from each line in the file into a separate list:

ReadList["ExampleData/strings",Byte,RecordLists->True]

Types of objects to read.

This returns a list of the "words" in the file strings:

ReadList["ExampleData/strings",Word]

(RefLink[ReadList, paclet:ref/ReadList]) allows you to read "words" from a file. It considers a "word" to be any sequence of characters delimited by word separators. You can set the option (RefLink[WordSeparators, paclet:ref/WordSeparators]) to specify the strings you want to treat as word separators. The default is to include spaces and tabs, but not to include, for example, standard punctuation characters. Note that in all cases successive words can be separated by any number of word separators. These separators are never taken to be part of the actual words returned by (RefLink[ReadList, paclet:ref/ReadList]).

Options for (RefLink[ReadList, paclet:ref/ReadList]).

This reads the text in the file strings as a sequence of words, using the letter e and . as word separators:

ReadList["ExampleData/strings",Word,WordSeparators->{"e","."}]

The Wolfram Language considers any data file to consist of a sequence of records. By default, each line is considered to be a separate record. In general, you can set the option (RefLink[RecordSeparators, paclet:ref/RecordSeparators]) to give a list of separators for records. Note that words can never cross record separators. As with word separators, any number of record separators can exist between successive records, and these separators are not considered to be part of the records themselves.

By default, each line of the file is considered to be a record:

ReadList["ExampleData/strings",Record]//InputForm

Here is a file containing three "sentences" ending with periods:

FilePrint["ExampleData/sentences"]

This allows both periods and newlines as record separators:

ReadList["ExampleData/sentences",Record,RecordSeparators->{".","\n"}]

This puts the words in each "sentence" into a separate list:

ReadList["ExampleData/sentences",Word,RecordLists->True,RecordSeparators->{".","\n"}]

Settings for the (RefLink[RecordSeparators, paclet:ref/RecordSeparators]) option.

Here is a file containing some text:

FilePrint["ExampleData/source"]

This reads all the text in the file source and returns it as a single string:

InputForm[ReadList["ExampleData/source",Record,RecordSeparators->{}]]

This gives a list of the parts of the file that lie between (: and :) separators:

ReadList["ExampleData/source",Record,RecordSeparators->{{"(: "},{" :)"}}]

By choosing appropriate separators, you can pick out specific parts of files:

ReadList["ExampleData/source",Record,RecordSeparators->{{"(: function ","["},{" :)","]"}}]

The Wolfram Language usually allows any number of appropriate separators to appear between successive records or words. Sometimes, however, when several separators are present, you may want to assume that a "null record" or "null word" appears between each pair of adjacent separators. You can do this by setting the options (RefLink[NullRecords, paclet:ref/NullRecords])->(RefLink[True, paclet:ref/True]) or (RefLink[NullWords, paclet:ref/NullWords])->(RefLink[True, paclet:ref/True]).

Here is a file containing "words" separated by colons:

FilePrint["ExampleData/words"]

Here the repeated colons are treated as single separators:

ReadList["ExampleData/words",Word,WordSeparators->{":"}]

Now repeated colons are taken to have null words in between:

ReadList["ExampleData/words",Word,WordSeparators->{":"},NullWords->True]

In most cases, you want words to be delimited by separators that are not themselves considered as words. Sometimes, however, it is convenient to allow words to be delimited by special "token words", which are themselves words. You can give a list of such token words as a setting for the option (RefLink[TokenWords, paclet:ref/TokenWords]).

Here is some text:

FilePrint["ExampleData/language"]

This reads the text, using the specified token words to delimit words in the text:

ReadList["ExampleData/language",Word,TokenWords->{"+","*"}]

You can use (RefLink[ReadList, paclet:ref/ReadList]) to read Wolfram Language expressions from files. In general, each expression must end with a newline, although a single expression may go on for several lines.

Here is a file containing text that can be used as Wolfram Language input:

FilePrint["ExampleData/exprs"]

This reads the text in exprs as Wolfram Language expressions:

ReadList["ExampleData/exprs",Expression]

This prevents the expressions from being evaluated:

ReadList["ExampleData/exprs",Hold[Expression]]

(RefLink[ReadList, paclet:ref/ReadList]) can insert the objects it reads into any Wolfram Language expression. The second argument to (RefLink[ReadList, paclet:ref/ReadList]) can consist of any expression containing symbols such as (RefLink[Number, paclet:ref/Number]) and (RefLink[Word, paclet:ref/Word]) specifying objects to read. Thus, for example, (RefLink[ReadList, paclet:ref/ReadList])["file",{(RefLink[Number, paclet:ref/Number]),(RefLink[Number, paclet:ref/Number])}] inserts successive pairs of numbers that it reads into lists. Similarly, (RefLink[ReadList, paclet:ref/ReadList])["file",(RefLink[Hold, paclet:ref/Hold])[(RefLink[Expression, paclet:ref/Expression])]] puts expressions that it reads inside (RefLink[Hold, paclet:ref/Hold]).

If (RefLink[ReadList, paclet:ref/ReadList]) reaches the end of your file before it has finished reading a particular set of objects you have asked for, then it inserts the special symbol (RefLink[EndOfFile, paclet:ref/EndOfFile]) in place of the objects it has not yet read.

Here is a file of numbers:

FilePrint["ExampleData/numbers"]

The symbol (RefLink[EndOfFile, paclet:ref/EndOfFile]) appears in place of numbers that were needed after the end of the file was reached:

ReadList["ExampleData/numbers",{Number,Number,Number,Number}]

Reading from commands and streams.

This executes the Unix command date, and reads its output as a string:

ReadList["!date",String]

Functions for reading from input streams.

(RefLink[ReadList, paclet:ref/ReadList]) allows you to read all the data in a particular file or input stream. Sometimes, however, you want to get data a piece at a time, perhaps doing tests to find out what kind of data to expect next.

When you read individual pieces of data from a file, the Wolfram Language always remembers the "current point" that you are at in the file. When you call (RefLink[OpenRead, paclet:ref/OpenRead]), the Wolfram Language sets up an input stream from a file, and makes your current point the beginning of the file. Every time you read an object from the file using (RefLink[Read, paclet:ref/Read]), the Wolfram Language sets your current point to be just after the object you have read. Using (RefLink[Skip, paclet:ref/Skip]), you can advance the current point past a sequence of objects without actually reading the objects.

Here is a file of numbers:

FilePrint["ExampleData/numbers"]

This opens an input stream from the file:

snum=OpenRead["ExampleData/numbers"]

This reads the first number from the file:

Read[snum,Number]

This reads the second pair of numbers:

Read[snum,{Number,Number}]

This skips the next number:

Skip[snum,Number]

This reads the remaining numbers:

ReadList[snum,Number]

This closes the input stream:

Close[snum]

You can use the options (RefLink[WordSeparators, paclet:ref/WordSeparators]) and (RefLink[RecordSeparators, paclet:ref/RecordSeparators]) in (RefLink[Read, paclet:ref/Read]) and (RefLink[Skip, paclet:ref/Skip]) just as you do in (RefLink[ReadList, paclet:ref/ReadList]).

Note that if you try to read past the end of file, (RefLink[Read, paclet:ref/Read]) returns the symbol (RefLink[EndOfFile, paclet:ref/EndOfFile]).