====================================================================
Text File
====================================================================

The domain TextFile allows FriCAS to read and write character data and
exchange text with other programs.  This type behaves in FriCAS much
like a File of strings, with additional operations to cause new lines.
We give an example of how to produce an upper case copy of a file.

This is the file from which we read the text. ::

  f1: TextFile := open("/etc/group", "input")
    "/etc/group"
                               Type: TextFile

This is the file to which we write the text. ::

  f2: TextFile := open("/tmp/MOTD", "output")
    "MOTD"
                               Type: TextFile

Entire lines are handled using the readLine and writeLine operations. ::

  l := readLine! f1
    "root:x:0:root"
                               Type: String

  writeLine!(f2, upperCase l)
    "ROOT:X:0:ROOT"
                               Type: String

Use the endOfFile? operation to check if you have reached the end of the file. ::

  while not endOfFile? f1 repeat
    s := readLine! f1
    writeLine!(f2, upperCase s)
                               Type: Void

The file f1 is exhausted and should be closed. ::

  close! f1
    "/etc/group"
                               Type: TextFile

It is sometimes useful to write lines a bit at a time.  The write operation 
allows this. ::

  write!(f2, "-The-")
    "-The-"
                               Type: String

  write!(f2, "-End-")
    "-End-"
                               Type: String

This ends the line.  This is done in a machine-dependent manner. ::

  writeLine! f2
    ""
                               Type: String

  close! f2
    "MOTD"
                               Type: TextFile

Finally, clean up. ::

  )system rm /tmp/MOTD

See Also:

* )help File
* )help KeyedAccessFile
* )help Library
* )show TextFile