====================================================================
File
====================================================================

The ``File(S)`` domain provides a basic interface to read and write values
of type S in files.

Before working with a file, it must be made accessible to FriCAS with
the open operation. ::

  ifile:File List Integer:=open("/tmp/jazz1","output") 
    "jazz1"
                         Type: File List Integer

The open function arguments are a FileNam} and a String specifying the
mode.  If a full pathname is not specified, the current default
directory is assumed.  The mode must be one of "input" or "output".
If it is not specified, "input" is assumed.  Once the file has been
opened, you can read or write data.

The operations read and write are provided. ::

  write!(ifile, [-1,2,3])
    [- 1,2,3]
                         Type: List Integer

  write!(ifile, [10,-10,0,111])
    [10,- 10,0,111]
                         Type: List Integer

  write!(ifile, [7])
    [7]
                         Type: List Integer

You can change from writing to reading (or vice versa) by reopening a file. ::

  reopen!(ifile, "input")
    "jazz1"
                         Type: File List Integer

  read! ifile
    [- 1,2,3]
                         Type: List Integer

  read! ifile
    [10,- 10,0,111]
                         Type: List Integer

The read operation can cause an error if one tries to read more data
than is in the file.  To guard against this possibility the readIfCan
operation should be used. ::

  readIfCan! ifile 
    [7]
                         Type: Union(List Integer,...)

  readIfCan! ifile
    "failed"
                         Type: Union("failed",...)

You can find the current mode of the file, and the file's name. ::

  iomode ifile
    "input"
                         Type: String

  name ifile
    "jazz1"
                         Type: FileName

When you are finished with a file, you should close it. ::

  close! ifile
    "jazz1"
                         Type: File List Integer

  )system rm /tmp/jazz1

A limitation of the underlying ``LISP`` system is that not all values can
be represented in a file.  In particular, delayed values containing
compiled functions cannot be saved.

See Also:

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