IdrisDoc: Effect.File

# Effect.File

Effectful file operations.

A : Type

  A file can only be appended to.

APlus : Type

  A file will read from the beginning and write at the end.

FILE : (ty : Type) -> EFFECT

  Effectful operations for interacting with files.

  The `FILE` effect is parameterised by a file handle once a handle has been acquired, and Unit (`()`) if the file handle is expected to be released once the function has returned.

data FileE : Effect

  An effect to describe operations on a file.

  Open : (fname : String) -> (m : Mode) -> sig FileE FileOpSuccess () (\res => calcResourceTy m res)
  OpenX : (fname : String) -> (m : Mode) -> sig FileE FileOpSuccess () (\res => calcResourceTy m res)
  Close : sig FileE () (FileHandle m) ()
  FGetC : {auto prf : ValidModeRead m} -> sig FileE (FileOpResult Char) (FileHandle m) (FileHandle m)
  FGetLine : {auto prf : ValidModeRead m} -> sig FileE (FileOpResult String) (FileHandle m) (FileHandle m)
  FReadFile : (fname : String) -> sig FileE (FileOpResult String) () ()
  FPutStr : (str : String) -> {auto prf : ValidModeWrite m} -> sig FileE FileOpSuccess (FileHandle m) (FileHandle m)
  FPutStrLn : (str : String) -> {auto prf : ValidModeWrite m} -> sig FileE FileOpSuccess (FileHandle m) (FileHandle m)
  FWriteFile : (fname : String) -> (contents : String) -> sig FileE FileOpSuccess ()
  FFlush : sig FileE () (FileHandle m) (FileHandle m)
  FEOF : {auto prf : ValidModeRead m} -> sig FileE Bool (FileHandle m)
data FileHandle : (m : Mode) -> Type

  The file handle associated with the effect.

  m

    The `Mode` that the handle was generated under.

  FH : File -> FileHandle m
R : Type

  A file has been opened for reading.

RW : Type

  A file can be read and written to.

RWPlus : Type

  A file opened for reading and writing and has been truncated to
  zero if it previously existed.

data ValidModeRead : Mode -> Type

  A record of the file modes that can read from a file.

  VMRRead : ValidModeRead Read
  VMRReadW : ValidModeRead ReadWrite
  VMRReadWT : ValidModeRead ReadWriteTruncate
  VMRReadA : ValidModeRead ReadAppend
data ValidModeWrite : Mode -> Type

  A record of the file modes that can write from a file.

  VMWWrite : ValidModeWrite WriteTruncate
  VMWAppend : ValidModeWrite Append
  VMWReadW : ValidModeWrite ReadWrite
  VMWReadWT : ValidModeWrite ReadWriteTruncate
W : Type

  A file has been opened for writing.

calcResourceTy : (m : Mode) -> (ty : FileOpReturnTy fOpTy retTy) -> Type

  Calculates the type for the resource being computed over. `Unit`
  to describe pre-and-post file handle acquisition, and `FileHandle m` when a file handle has been acquired.

  m

    The mode the file handle was generated under.

  ty

    The functions return type.

close : Eff () [ FILE (FileHandle m)] [ FILE ()]

  Close a file.

eof : {auto prf : ValidModeRead m} -> Eff Bool [ FILE (FileHandle m)]

  Have we reached the end of the file.

flush : Eff () [ FILE (FileHandle m)]
open : (fname : String) -> (m : Mode) -> Eff FileOpSuccess [ FILE ()] (\res => [ FILE (calcResourceTy m res)])

  Open a file.

  fname

    the filename.

  m

    the mode; either Read, WriteTruncate, Append, ReadWrite,
    ReadWriteTruncate, or ReadAppend

openX : (fname : String) -> (m : Mode) -> Eff FileOpSuccess [ FILE ()] (\res => [ FILE (calcResourceTy m res)])

  Open a file using C11 extended modes.

  fname

    the filename

  m

    the mode; either Read, WriteTruncate, Append, ReadWrite,
    ReadWriteTruncate, or ReadAppend

readChar : {auto prf : ValidModeRead m} -> Eff (FileOpResult Char) [ FILE (FileHandle m)]

  Read a `Char`.

readFile : (fname : String) -> Eff (FileOpResult String) [ FILE ()]

  Read the contents of a file into a string.

  This checks the size of
  the file before beginning to read, and only reads that many bytes,
  to ensure that it remains a total function if the file is appended
  to while being read.

  Returns an error if fname is not a normal file.

readLine : {auto prf : ValidModeRead m} -> Eff (FileOpResult String) [ FILE (FileHandle m)]

  Read a complete line.

writeFile : (fname : String) -> (contents : String) -> Eff FileOpSuccess [ FILE ()]

  Create a file and write contents to the file.

writeLine : (str : String) -> {auto prf : ValidModeWrite m} -> Eff FileOpSuccess [ FILE (FileHandle m)]

  Write a complete line to the file.

writeString : (str : String) -> {auto prf : ValidModeWrite m} -> Eff FileOpSuccess [ FILE (FileHandle m)]

  Write a string to the file.