## `fprint` -- write data to a file

#### Introduction

`fprint(`filename, objects`)` writes MuPAD objects to the file `filename`.

`fprint(`n, objects`)` writes to the file associated with the file descriptor `n`.

#### Call(s)

`fprint( <style,> <format,> filename, object1, object2...)`
`fprint( <style,> n, object1, object2...)`

#### Parameters

`filename` | - | the name of a file: a character string
`object1, object2...` | - | arbitrary MuPAD objects
`n` | - | a file descriptor provided by `fopen`: a nonnegative integer

#### Options

`style` | - | either Unquoted or NoNL. These options are relevant for text files only. Both options make `fprint` store character strings without quotation marks. All objects are stored without separating colons in the text file. With Unquoted, a newline character is appended to the line generated by `fprint`. With NoNL, no newline character is appended to the line.
`format` | - | the write format: either Bin or Text. With Bin, the data are stored in MuPAD's binary format. With Text, standard ASCII format is used. The default is Bin.

#### Returns

the void object of type `DOM_NULL`.

#### Side Effects

The function is sensitive to the environment variable `WRITEPATH`. If this variable has a value, the file is created in the corresponding directory. Otherwise, the file is created in the ``working directory''.

#### Related Functions

`expr2text`, `fclose`, `finput`, `fopen`, `fread`, `ftextinput`, `pathname`, `print`, `protocol`, `read`, `READPATH`, `write`, `WRITEPATH`

#### Details

- `fprint` is used to write MuPAD objects to a file. The objects are evaluated, the results are stored in the file. These data can be read into another MuPAD session via the functions `finput` and `ftextinput`, respectively.
- The file may be specified directly by its name. In this case, `fprint` creates a new file or overwrites an existing file. `fprint` opens and closes the file automatically.

  If `WRITEPATH` does not have a value, `fprint` interprets the file name as a pathname 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 `fprint`.

- Instead of a file name, also a file descriptor of a file opened via `fopen` can be used. Cf. example 2. In this case, the data written by `fprint` are appended to the corresponding file. The file is not closed automatically by `fprint` and must be closed by a subsequent call to `fclose`.

  Note that `fopen``(filename)` opens the file in read-only mode. A subsequent `fprint` command to this file causes an error. Use the Write or Append option of `fopen` to open the file for writing.

  The file descriptor `0` represents the screen.

- Text output occurs without the Pretty-Printer. A call to `fprint` writes all specified objects into a single line of the text file. A newline character is appended to this line, unless the option NoNL is used. By default, the written objects are separated by colons without any further white space. The resulting text data consists of syntactically correct MuPAD code and can be read again using `finput`. With the options Unquoted and NoNL, neither white space no colons are inserted to separate the objects. The resulting text data cannot be read again using `finput`. Cf. example 3.

  Note that the text version of a MuPAD object does not necessarily reflect its data structure. A domain element stored in text mode may be read as an element of a different type by `finput`. Use the binary mode if stored data are to be read in their original form into another MuPAD session. Cf. example 4.

- MuPAD statements such as assignments etc. must be bracketed as in `fprint(`"test", (a := 2)`)`.
- `fprint` is a function of the system kernel.

#### Option: Unquoted

- This option is useful for writing user-formated text files. Data written with this option cannot be read again via `finput`.
- With this option, character strings are written without quotation marks. Additionally, the control characters `'`\n`'` and `'`\t`'` in strings are expanded. Furthermore, no colons are inserted between the objects. A newline character is appended to the line written by `fprint`.

#### Option: NoNL

- This option has the same functionality as `Unquoted`, with the only difference that no newline character is appended to the line written by `fprint`.

#### Example 1

We write some data to the file `test`. By default, this file is created as a binary file. For syntactical reasons, the assignment `d := 5` must be enclosed in additional brackets:

    >> fprint("test", (d := 5), d*3):

The file is read into the MuPAD session. The assignment `d := 5` is executed, its return value is assigned to the identifier `e`. The value `d*3` is assigned to the identifier `f`:

    >> finput("test", e, f): d, e, f;

                                     5, 5, 15

    >> delete d, e, f:

#### Example 2

We use a file descriptor to access the file `test`. Several calls to `fprint` append data to the file:

    >> n := fopen("test", Write):
       fprint(n, (d := 5), d*3):
       fprint(n, "more data"):

Using a file descriptor, we have to call `fclose` to close the file:

    >> fclose(n):

The file is read into the MuPAD session, assigning the stored values to the identifiers `e`, `f`, and `g`:

    >> finput("test", e, f, g ): e, f, g;

                                5, 15, "more data"

    >> delete n, d, e, f, g:

#### Example 3

With the option `Unquoted`, character strings are written without quotation marks:

    >> fprint(Text, "test1", "Hello World!", MuPAD + 1):
       fprint(Unquoted, Text, "test2", "Hello World!", MuPAD + 1):

Now, the files `test1` and `test2` have the following content:

          test1:
          "Hello World!":MuPAD + 1:

          test2:
          Hello World!MuPAD + 1

We can use `finput` or `ftextinput` to read the data from the file:

    >> finput("test1", a, b): a, b;

                             "Hello World!", MuPAD + 1

    >> ftextinput("test2", c): c

                              "Hello World!MuPAD + 1"

    >> delete a, b, c:

#### Example 4

The text version of a MuPAD object does not necessarily reflect its data structure. E.g., the function `matrix` creates matrices of domain type `Dom::Matrix()`. The text version, however, is an array:

    >> fprint(Text, "test", matrix([1, 2])):
       finput("test")

                     array(1..2, 1..1, (1, 1) = 1, (2, 1) = 2)

Use the binary mode to guarantee that stored objects can be read in their original form:

    >> fprint("test", matrix([1, 2])):
       finput("test"); domtype(%)

                                      +-   -+
                                      |  1  |
                                      |     |
                                      |  2  |
                                      +-   -+

                                   Dom::Matrix()

#### Changes

- no changes

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