## `ftextinput` -- read a text file

#### Introduction

`ftextinput(`filename, x`)` reads a line from a text file, interprets the line as a string and assigns this string to the identifier `x`.

`ftextinput(`n, x`)` reads from the file associated with the file descriptor `n`.

#### Call(s)

`ftextinput(filename)`
`ftextinput(filename, x1, x2...)`
`ftextinput(n)`
`ftextinput(n, x1, x2...)`

#### Parameters

`filename` | - | the name of a file: a character string
`n` | - | a file descriptor provided by `fopen`: a positive integer
`x1, x2...` | - | identifiers

#### Returns

the last line that was read from the file: a character string.

#### Related Functions

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

#### Details

- `ftextinput(`filename`)` reads the first line of the text file and returns it as a string to the MuPAD session.
- `ftextinput(`filename, x1, x2, ...`)` reads the file line by line. The i-th line is converted to a character string and assigned to the identifier x.i. The identifiers are not evaluated while executing `ftextinput`; previously assigned values are overwritten.
- Instead of a file name, also a file descriptor `n` of a file opened via `fopen` can be used. The functionality is as described above. However, there is one difference: With a file name, the file is closed automatically after the data were read. A subsequent call to `ftextinput` starts at the beginning of the file. With a file descriptor, the file remains open (use `fclose` to close the file). The next time data are read from this file, the reading continues at the current position. Consequently, a file descriptor should be used, if the individual lines in the file are to be read via several subsequent calls of `ftextinput`. Cf. example 2.
- If the number of identifiers specified in the `ftextinput` call is larger than the number of lines in the file, the exceeding identifiers are not assigned any values. In such a case, `ftextinput` returns the void object of type `DOM_NULL`.
- `ftextinput` 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.

  Also absolute path names are processed by `ftextinput`.

- Expression sequences are not flattened by `ftextinput` and cannot be used to pass several identifiers to `ftextinput`. Cf. example 3.
- `ftextinput` is a function of the system kernel.

#### Example 1

First, we use `fprint` to create a text file with three lines:

    >> fprint(Unquoted, Text, "test", "x + 1\n2nd line\n3rd line"):

We read the first two lines of the file and assign the corresponding strings to the identifiers `x1` and `x2`:

    >> ftextinput("test", x1, x2): x1, x2

                                "x + 1", "2nd line"

If we try to read beyond the last line of the file, `ftextinput` returns the void object of type `DOM_NULL`:

    >> ftextinput("test", x1, x2, x3, x4); domtype(%)

                                     DOM_NULL

    >> x1, x2, x3, x4

                        "x + 1", "2nd line", "3rd line", x4

    >> delete x1, x2, x3:

#### Example 2

We read some lines from a file using several calls of `ftextinput`. We have to use a file descriptor for reading from the file. The file is opened for reading with `fopen`:

    >> fprint(Unquoted, Text, "test",
              "x + 1\nx + 2\n3rd line\n4th line"):

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

The file descriptor returned by `fopen` can be passed to `ftextinput` for reading the data:

    >> ftextinput(n, x1, x2): x1, x2

                                 "x + 1", "x + 2"

    >> ftextinput(n, x3, x4): x3, x4

                              "3rd line", "4th line"

Finally, we close the file and delete the identifiers:

    >> fclose(n): delete n, x1, x2, x3, x4:

Alternatively, the contents of a file can be read into a MuPAD session in the following way:

    >> n := fopen("test"):
       for i from 1 to 4 do
          x.i := ftextinput(n)
       end_for:
       x1, x2, x3, x4

                     "x + 1", "x + 2", "3rd line", "4th line"

    >> fclose(n): delete n, i, x1, x2, x3, x4:

#### Example 3

Expression sequences are not flattened by `ftextinput` and cannot be used to pass identifiers to `ftextinput`:

    >> fprint(Unquoted, Text, "test", "1st line\n2nd line\n3rd line"):
       ftextinput("test", (x1, x2), x3)

          Error: Illegal argument [ftextinput]

The following call does not lead to an error because the identifier `x12` is not evaluated. Consequently, only one line is read from the file and assigned to `x12:`

    >> x12 := x1, x2: ftextinput("test", x12): x1, x2, x12

                                x1, x2, "1st line"

    >> delete x12:

#### Changes

- no changes

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