## `fread` -- read and execute a file

#### Introduction

`fread``(filename)` reads and executes the MuPAD file `filename`.

`fread``(n)` reads and executes the file associated with the file descriptor `n`.

#### Call(s)

`fread(filename <, Quiet> <, Plain>)`
`fread(n <, Quiet> <, Plain>)`

#### Parameters

`filename` | - | the name of a file: a character string
`n` | - | a file descriptor provided by `fopen`: a positive integer

#### Options

`Plain` | - | makes `fread` use its own parser context
`Quiet` | - | suppresses output during execution of `fread`

#### Returns

the return value of the last statement of the file.

#### Related Functions

`fclose`, `finput`, `fopen`, `fprint`, `ftextinput`, `input`, `loadproc`, `pathname`, `print`, `protocol`, `read`, `READPATH`, `textinput`, `write`, `WRITEPATH`

#### Details

- `fread(`filename`)` reads the file and evaluates each MuPAD statement in the file.
- `fread` is similar to `read`. The only difference is that `fread` does not search for files in the directories given by `READPATH` and `LIBPATH`; `fread` only searches for the file relative to the ``working directory''.

  Note that the meaning of ``working directory'' depends on the operating system. On Windows systems, the ``working directory'' is the folder where MuPAD is installed. On UNIX or Linux systems, it is the current working directory in which MuPAD was started.

  On the Macintosh, an empty file name may be given. In this case, a dialogue box is opened in which the user can choose a file. Further, on the interactive level, MacMuPAD warns the user, if an existing file is about to be overwritten.

  Also absolute path names are processed by `fread`.

- `fread` can read MuPAD binary files (created via `fprint` or `write`) as well as ASCII text files. `fread` recognizes the format of the file automatically.
- Instead of a file name, also a file descriptor of a file opened via `fopen` can be used. Cf. example 3.
- `fread` is a function of the system kernel.

#### Option: Quiet

- With this option, output is suppressed while reading and executing the file. However, warnings, error messages as well as the output of `print` commands are still visible.

#### Option: Plain

- With this option, the file is read in a new parser context. This means that the `history` is not modified by the statements in the file. Further, abbreviations set outside the file via `alias` or user defined operators are ignored during the execution of the file. This option is useful for reading initialization files in a clean environment.

#### Example 1

The following example is only functional under UNIX and Linux; on other operating systems one must change the path names accordingly. First, we use `fprint` to create a file containing three MuPAD statements:

    >> fprint(Unquoted, Text, "/tmp/test", "a := 3; b := 5; a + b;"):

When reading the file, the statements are executed. Each produces a print output. The second `8` below is the return value of `fread`:

    >> delete a, b: fread("/tmp/test")

                                         3

                                         5

                                         8

                                         8

Now, the variables `a` and `b` have the values assigned inside the file :

    >> a, b

                                       3, 5

With the option Quiet, only the return value of `fread` is printed:

    >> delete a, b: fread("/tmp/test", Quiet)

                                         8

    >> delete a, b:

#### Example 2

The next example demonstrates the option Plain. First, an appropriate input file is created:

    >> fprint(Unquoted, Text, "/tmp/test",
              "f := proc(x) begin x^2 end_proc:",
              "a := f(3): b := f(4):"):

We define an `alias` for `f`:

    >> alias(f = ßome text"):

An error occurs if we try to read the file without the option Plain. In the parser context of the MuPAD session, the alias replaces `f` by the corresponding string in the assignment `f := ...`. However, strings cannot be assigned a value:

    >> fread("/tmp/test"):

          Error: Invalid left-hand side [_assign];
          while reading file '/tmp/test'

With the option Plain, no such error arises: the alias for `f` is ignored by `fread`:

    >> fread("/tmp/test", Plain): a, b

                                       9, 16

    >> unalias(f): delete f, a, b:

#### Example 3

We use `write` to save the value of the identifier `a` in the file ```/tmp/test`'':

    >> a := PI + 1: write("/tmp/test", a): delete a:

This file is opened for reading with `fopen`:

    >> n := fopen("/tmp/test")

                                        17

The file descriptor returned by `fopen` can be passed to `fread`. Reading the file restores the value of `a`:

    >> fread(n): a

                                      PI + 1

    >> fclose(n): delete a:

#### Changes

- The new option Plain was introduced.

Do you have questions or comments?
Copyright © SciFace Software GmbH & Co. KG 2000