read

Search, read, and execute file

MuPAD® notebooks will be removed in a future release. Use MATLAB® live scripts instead.

MATLAB live scripts support most MuPAD functionality, though there are some differences. For more information, see Convert MuPAD Notebooks to MATLAB Live Scripts.

Syntax

read(filename | n, <Quiet>, <Plain>, <Encoding = "encodingValue">)

Description

read(filename) searches for the file in various folders:

  • First, filename is concatenated to each folder given by the environment variable READPATH.

  • Then the file name is interpreted as an absolute path name.

  • Then the file name is interpreted as a relative pathname, i.e., relative to the “working folder.”

  • Last, the file name is concatenated to the library path.

If a file can be opened with one of these names, then the file is read and executed with fread.

read(filename, Encoding = "encodingValue") uses the specified encoding for text files. For supported encodings, see Options.

If the file is in gzip-compressed format and its name ends in “.gz”, it will be transparently uncompressed upon reading.

Note that the meaning of “working folder” depends on the operating system. On Microsoft® Windows® systems and on Mac OS X systems, the “working folder” is the folder where MATLAB® is installed. On UNIX® systems, it is the current working folder in which MATLAB was started. When started from a menu or desktop item, this is typically the user's home folder.

A path separator (“/”) is inserted as necessary when concatenating a given path and filename.

read(n) with a file descriptor n as returned by fopen is equivalent to the call fread(n). When called with a file description, read does not automatically open and close the file. Use fopen and fclose to open and close the file. The Encoding option does not work with this syntax.

When you use the read command to read a file, the command evaluates all the statements in that file with the maximal substitution depth defined by LEVEL. The default value of LEVEL for interactive computations is 100. See Example 3.

See the function fread for details about reading and executing the file's content and for a detailed description of the options Plain and Quiet.

When a file is read with read, the variable FILEPATH contains the path of the file.

Examples

Example 1

Create a new file in the system's temporary folder. The name of the temporary folder varies for different platforms. The fopen command with the TempFile option creates a file in any system's temporary folder (if such folder exists):

a := 3:
b := 5:
fid := fopen(TempFile, Write, Text):

Use the write command to store values a and b in the temporary file:

write(fid, a, b):

Use fname to return the name of the temporary file you created:

file := fname(fid):

After reading the file, the values of a and b are restored:

delete a, b:
read(file):
a, b

Alternatively, use fopen to open the file and read its content:

delete a, b:
n := fopen(file):
read(n):
fclose(n):
a, b

delete a, b, READPATH, n:

Example 2

You can explicitly specify the folder and file names. The following example only works on systems like UNIX. To make it work on other operating systems, change the path names accordingly. First, use write to store values in the file “testfile.mb” in the “/tmp” folder:

a := 3:
b := 5:
write("/tmp/testfile.mb", a, b):

Now, define “/tmp” as the search folder and provide a path name relative to it. Note that the path separator “/” is inserted by read:

delete a, b:
READPATH := "/tmp":
read("testfile.mb"):
a, b

Example 3

The read command evaluates all the statements in a file it reads with the maximal substitution depth defined by LEVEL. For example, create and read a file that specifies the value of the variable a by using another variable b. Use the fopen command with the TempFile option to create a new file in the system's temporary folder:

fid := fopen(TempFile, Write, Text):

Write the following statements to the file:

fprint(Unquoted, fid, "a := b^2:  b := 5: c := a/3: delete a, b:"):

Use fname to return the name of the temporary file you created. Use fclose to close the file:

file := fname(fid):
fclose(fid)

Read the file. The read command evaluates the statements in the file recursively:

read(file):
c

To supress recursive evaluations, change the maximal substitution depth to 1:

delete c:
LEVEL := 1:
read(file):
c

Restore the default value of LEVEL for further computations:

delete LEVEL

Example 4

To specify the encoding to read data, use Encoding. The Encoding option applies only to text files that are opened using a file name and not a file descriptor. Open a file and write the statement "str = abcäöü" in the encoding "UTF-8":

fprint(Unquoted, Text, Encoding="UTF-8",
                       "read_test",
                       "str := \"abcäöü\"")

Specify the encoding to read the file. read returns the correct output:

read("read_test",Encoding="UTF-8"):
"abcäöü"

If you do not specify an encoding, the default system encoding is used. Thus, your output might vary from that shown next. Characters unrecognized by the default system encoding are replaced by the default substitution character for that encoding:

read("read_test"):
"abc������"

Parameters

filename

The name of a file: a character string

n

A file descriptor provided by fopen: a positive integer

Options

Plain

Makes read use its own parser context

Quiet

Suppresses output during execution of read

Encoding

This option lets you specify the character encoding to use. The allowed encodings are:

"Big5"

"ISO-8859-1"

"windows-932"

"EUC-JP"

"ISO-8859-2"

"windows-936"

"GBK"

"ISO-8859-3"

"windows-949"

"KSC_5601"

"ISO-8859-4"

"windows-950"

"Macintosh"

"ISO-8859-9"

"windows-1250"

"Shift_JIS"

"ISO-8859-13"

"windows-1251"

"US-ASCII"

"ISO-8859-15"

"windows-1252"

"UTF-8"

 

"windows-1253"

  

"windows-1254"

  

"windows-1257"

The default encoding is system dependent. If you specify the encoding incorrectly, characters might read incorrectly. Characters unrecognized by the encoding are replaced by the default substitution character for the specified encoding.

Encodings not listed here can be specified but might not produce correct results.

Return Values

Return value of the last statement of the file.