
ftextinput - line-by-line read-in of text from a file

Calling sequence:
ftextinput(integer [ , identifier ... ])
ftextinput(string [ , identifier ... ])

Parameter:
integer      --  positive integer
identifier   --  identifier
string       --  character string

Summary:

ftextinput reads-in character stringsline-by-line from a text file. The first
argument specifies the file.  The other parameters of ftextinput must be
identifiers.  Individual text lines are read-in from the file in sequence and
assigned to these identifiers.  The result of ftextinput is the final read-in
text line.

If a line cannot be read-in then the corresponding identifier and those following
are not assigned any lines. In this case the result of ftextinput has the type
DOM_NULL    .

If ftextinput is called without identifiers as arguments then only one line is

read-in. This is then the return value of the function. If the line cannot be
read-in then the return value has the type DOM_NULL.

The file is specified as follows:

  o  If the first argument is a positive integer integer then this is considered
     a file descriptor. The relevant text file must have already been opened
     with fopen .

     After the text lines have been read-in the file remains open. The next
     reading from the file with this descriptor begins at the current position.

  o  If a character string is given as the argument string then the file with
     this name is newly opened.  The file is searched for in the current
     directory.

     The text lines are read-in starting at the beginning of the file. After the
     data have been read the file is closed.

  o  In MacMuPAD, if an empty character string is given as the argument
     string then a dialogue is opened in which the user can choose a file.

When a file name is given then only the lines at the beginning of a file can
be read. If successive text lines are to be read from a file with several calls
of ftextinput then a file descriptor must be used.

In contrast to most other functions, arguments which are expression sequences,
are not flattened. ftextinput is a kernel function.

>>  fprint(Unquoted, Text, "test", "AA\nBB\nCC\nDD\n"):
    ftextinput("test", z1, z2): z1, z2;

      "AA", "BB"

>>  fp:= fopen("test"): ftextinput(fp, z1, z2):
    ftextinput(fp, z1, z2): z1, z2;

      "CC", "DD"

See also:  fclose , fopen , finput , fread , read, textinput

