# Module Topkg.OS.File

    module File: sig .. end

File operations.

## Famous file paths

    val null : Topkg.fpath

`null` represents a file on the OS that discards all writes and returns end of file on reads.

    val dash : Topkg.fpath

`dash` is `"-"`. This value is is used by `Topkg.OS.File.read` and `Topkg.OS.File.write` to respectively denote `stdin` and `stdout`.

## Existence and deletion

    val exists : Topkg.fpath -> bool Topkg.result

`exists file` is `true` if `file` is a regular in the file system and false otherwise. Symbolic links are followed.

    val must_exist : Topkg.fpath -> Topkg.fpath Topkg.result

`must_exist file` is `file` if `file` is a regular file in the file system and an error otherwise. Symbolic links are followed.

    val delete : ?must_exist:bool -> Topkg.fpath -> unit Topkg.result

`delete ~must_exist file` deletes file `file`. If `must_exist` is `true` (defaults to `false`) an error is returned if `file` doesn't exist.

## Folding over file hierarchies

    val fold : ?skip:(Topkg.fpath -> bool) ->
           (Topkg.fpath -> 'a -> 'a) -> 'a -> Topkg.fpath list -> 'a Topkg.result

`fold_files skip f acc paths` folds `f` over the files found in the file hierarchies starting at `paths`. Files and directories `p` for which `skip p` is `true` are skipped. `skip` defaults to `(fun _ -> false)`.

## Reading and writing

    val read : Topkg.fpath -> string Topkg.result

`read file` is `file`'s contents. If `file` is `Topkg.OS.File.dash` reads from `stdin` and the channel is not closed when the function returns.

    val write : Topkg.fpath -> string -> unit Topkg.result

`write file content` writes `content` to `file`. If `file` is `Topkg.OS.File.dash` writes to `stdout` and flushes but doesn't close the channel when the function returns.

    val write_subst : Topkg.fpath -> (string * string) list -> string -> unit Topkg.result

`write_subst file vars content` is like `Topkg.OS.File.write` except any occurence of a string of the form `"%%ID%%"` in `content` is replaced by the value of `List.assoc "ID" vars`, if any.

## Temporary files

    val tmp : unit -> Topkg.fpath Topkg.result

`tmp ()` creates a temporary file and returns its name. The file is destroyed at the end of program execution.