bos 0.2.1 · OCaml Package

File operations.

Famous file paths

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 "./-".

Existence, deletion and properties

val exists : Fpath.t -> (bool, 'e) result

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

val must_exist : Fpath.t -> (Fpath.t, 'e) result

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

val delete : ?must_exist:bool -> Fpath.t -> (unit, 'e) 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.

val truncate : Fpath.t -> int -> (unit, 'e) result

truncate p size truncates p to s.

val is_executable : Fpath.t -> bool

is_executable p is true iff file p exists and is executable.

Input

Stdin. In the following functions if the path is dash, bytes are read from stdin.

type input = unit -> (Stdlib.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.

val with_input : 
  ?bytes:Stdlib.Bytes.t ->
  Fpath.t ->
  (input -> 'a -> 'b) ->
  'a ->
  ('b, 'e) result

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.

raises Invalid_argument
if the length of bytes is 0.

val with_ic : 
  Fpath.t ->
  (Stdlib.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 Stdlib.stdin and not closed when the function returns. End_of_file exceptions raised by f are turned it into an error message.

val read : Fpath.t -> (string, 'e) result

read file is file's content as a string.

val read_lines : Fpath.t -> (string list, 'e) result

read_lines file is file's content, split at each '\n' character.

val fold_lines : ('a -> string -> 'a) -> 'a -> Fpath.t -> ('a, 'e) result

fold_lines f acc file is like List.fold_left f acc (read_lines p).

Output

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 = (Stdlib.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 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 ->
  (Stdlib.out_channel -> 'a -> ('c, 'd) 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 Stdlib.stdout and not closed when the function returns.

val write : ?mode:int -> Fpath.t -> string -> (unit, 'e) result

write file content outputs content to file. If file is dash, writes to Stdlib.stdout. If an error is returned file is left untouched except if Stdlib.stdout is written.

val writef : 
  ?mode:int ->
  Fpath.t ->
  ('a, Stdlib.Format.formatter, unit, (unit, 'e) result) Stdlib.format4 ->
  'a

write file fmt ... is like write file (Format.asprintf fmt ...).

val write_lines : ?mode:int -> Fpath.t -> string list -> (unit, 'e) result

write_lines file lines is like write file (String.concat ~sep:"\n" lines).

Temporary files

type tmp_name_pat =
  (string -> string, Stdlib.Format.formatter, unit, string) Stdlib.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 Stdlib.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 -> Stdlib.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.

package bos

Famous file paths

Existence, deletion and properties

Input

Output

Temporary files