Library
Module
Module type
Parameter
Class
Class type
File operations.
val null : Fpath.t
null
is Fpath.v "/dev/null"
on POSIX and Fpath.v "NUL"
on Windows. It represents a file on the OS that discards all writes and returns end of file on reads.
val dash : Fpath.t
dash
is Fpath.v "-"
. This value is used by input and output functions to respectively denote stdin
and stdout
.
Note. Representing stdin
and stdout
by this path is a widespread command line tool convention. However it is perfectly possible to have files that bear this name in the file system. If you need to operate on such path from the current directory you can simply specify them as Fpath.(cur_dir / "-")
and so can your users on the command line by using "./-"
.
exists file
is true
if file
is a regular file in the file system and false
otherwise. Symbolic links are followed.
must_exist file
is Ok file
if file
is a regular file in the file system and an error otherwise. Symbolic links are followed.
delete ~must_exist file
deletes file file
. If must_exist
is true
(defaults to false
) an error is returned if file
doesn't exist.
val is_executable : Fpath.t -> bool
is_executable p
is true
iff file p
exists and is executable.
Stdin. In the following functions if the path is dash
, bytes are read from stdin
.
type input = unit -> (Bytes.t * int * int) option
The type for file inputs. The function is called by the client to input more bytes. It returns Some (b, pos, len)
if the bytes b
can be read in the range [pos
;pos+len
]; this byte range is immutable until the next function call. None
is returned at the end of input.
with_input ~bytes file f v
provides contents of file
with an input i
using bytes
to read the data and returns f i v
. After the function returns (normally or via an exception) a call to i
by the client raises Invalid_argument
.
val with_ic : Fpath.t -> (in_channel -> 'a -> 'b) -> 'a -> ('b, 'e) result
with_ic file f v
opens file
as a channel ic
and returns Ok (f ic v)
. After the function returns (normally or via an exception), ic
is ensured to be closed. If file
is dash
, ic
is Pervasives.stdin
and not closed when the function returns. End_of_file
exceptions raised by f
are turned it into an error message.
read_lines file
is file
's content, split at each '\n'
character.
fold_lines f acc file
is like List.fold_left f acc (read_lines p)
.
The following applies to every function in this section.
Stdout. If the path is dash
, bytes are written to stdout
.
Default permission mode. The optional mode
argument specifies the permissions of the created file. It defaults to 0o644
(readable by everyone writeable by the user).
Atomic writes. Files are written atomically by the functions. They create a temporary file t
in the directory of the file f
to write, write the contents to t
and renames it to f
on success. In case of error t
is deleted and f
left intact.
type output = (Bytes.t * int * int) option -> unit
The type for file outputs. The function is called by the client with Some (b, pos, len)
to output the bytes of b
in the range [pos
;pos+len
]. None
is called to denote end of output.
val with_output :
?mode:int ->
Fpath.t ->
(output -> 'a -> ('c, 'd) Result.result as 'b) ->
'a ->
('b, 'e) result
with_output file f v
writes the contents of file
using an output o
given to f
and returns Ok (f o v)
. file
is not written if f
returns an error. After the function returns (normally or via an exception) a call to o
by the client raises Invalid_argument
.
val with_oc :
?mode:int ->
Fpath.t ->
(out_channel -> 'a -> ('c, 'd) Result.result as 'b) ->
'a ->
('b, 'e) result
with_oc file f v
opens file
as a channel oc
and returns Ok (f oc v)
. After the function returns (normally or via an exception) oc
is closed. file
is not written if f
returns an error. If file
is dash
, oc
is Pervasives.stdout
and not closed when the function returns.
write file content
outputs content
to file
. If file
is dash
, writes to Pervasives.stdout
. If an error is returned file
is left untouched except if Pervasives.stdout
is written.
val writef :
?mode:int ->
Fpath.t ->
('a, Format.formatter, unit, (unit, 'e) result) format4 ->
'a
write file fmt ...
is like write file (Format.asprintf fmt ...)
.
write_lines file lines
is like write file (String.concat
~sep:"\n" lines)
.
type tmp_name_pat = (string -> string, Format.formatter, unit, string) format4
The type for temporary file name patterns. The string format is replaced by random characters.
val tmp : ?mode:int -> ?dir:Fpath.t -> tmp_name_pat -> (Fpath.t, 'e) result
tmp mode dir pat
is a new empty temporary file in dir
(defaults to Dir.default_tmp
) named according to pat
and created with permissions mode
(defaults to 0o600
only readable and writable by the user). The file is deleted at the end of program execution using a Pervasives.at_exit
handler.
Warning. If you want to write to the file, using with_tmp_output
or with_tmp_oc
is more secure as it ensures that noone replaces the file, e.g. by a symbolic link, between the time you create the file and open it.
val with_tmp_output :
?mode:int ->
?dir:Fpath.t ->
tmp_name_pat ->
(Fpath.t -> output -> 'a -> 'b) ->
'a ->
('b, 'e) result
with_tmp_output dir pat f v
is a new temporary file in dir
(defaults to Dir.default_tmp
) named according to pat
and atomically created and opened with permissions mode
(defaults to 0o600
only readable and writable by the user). Returns Ok (f file o v)
with file
the file path and o
an output to write the file. After the function returns (normally or via an exception), calls to o
raise Invalid_argument
and file
is deleted.
val with_tmp_oc :
?mode:int ->
?dir:Fpath.t ->
tmp_name_pat ->
(Fpath.t -> out_channel -> 'a -> 'b) ->
'a ->
('b, 'e) result
with_tmp_oc mode dir pat f v
is a new temporary file in dir
(defaults to Dir.default_tmp
) named according to pat
and atomically created and opened with permission mode
(defaults to 0o600
only readable and writable by the user). Returns Ok (f file oc v)
with file
the file path and oc
an output channel to write the file. After the function returns (normally or via an exception), oc
is closed and file
is deleted.