bos 0.2.1 · OCaml Package

Directory operations.

Existence, creation, deletion and contents

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

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

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

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

val create : ?path:bool -> ?mode:int -> Fpath.t -> (bool, 'e) result

create ~path ~mode dir creates, if needed, the directory dir with file permission mode (defaults 0o755 readable and traversable by everyone, writeable by the user). If path is true (default) intermediate directories are created with the same mode, otherwise missing intermediate directories lead to an error. The result is:

Ok true if dir did not exist and was created.
Ok false if dir did exist as (possibly a symlink to) a directory. In this case the mode of dir and any other directory is kept unchanged.
Error _ otherwise and in particular if dir exists as a non-directory

val delete : ?must_exist:bool -> ?recurse:bool -> Fpath.t -> (unit, 'e) result

delete ~must_exist ~recurse dir deletes the directory dir. If must_exist is true (defaults to false) an error is returned if dir doesn't exist. If recurse is true (default to false) no error occurs if the directory is non-empty: its contents is recursively deleted first.

val contents : 
  ?dotfiles:bool ->
  ?rel:bool ->
  Fpath.t ->
  (Fpath.t list, 'e) result

contents ~dotfiles ~rel dir is the list of directories and files in dir. If rel is true (defaults to false) the resulting paths are relative to dir, otherwise they have dir prepended. See also fold_contents. If dotfiles is false (default) elements that start with a . are omitted.

val fold_contents : 
  ?err:'b Path.fold_error ->
  ?dotfiles:bool ->
  ?elements:Path.elements ->
  ?traverse:Path.traverse ->
  (Fpath.t -> 'a -> 'a) ->
  'a ->
  Fpath.t ->
  ('a, 'e) result

fold_contents err dotfiles elements traverse f acc d is:

contents d >>= Path.fold err dotfiles elements traverse f acc

For more details see fold.

User and current working directory

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

user () is the home directory of the user executing the process. Determined by consulting the passwd database with the user id of the process. If this fails or on Windows falls back to parse a path from the HOME environment variable.

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

current () is the current working directory. The resulting path is guaranteed to be absolute.

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

set_current dir sets the current working directory to dir.

val with_current : Fpath.t -> ('a -> 'b) -> 'a -> ('b, 'e) result

with_current dir f v is f v with the current working directory bound to dir. After the function returns the current working directory is back to its initial value.

Temporary directories

type tmp_name_pat =
  (string -> string, Stdlib.Format.formatter, unit, string) Stdlib.format4

The type for temporary directory 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 directory in dir (defaults to Dir.default_tmp) named according to pat and created with permissions mode (defaults to 0o700 only readable and writable by the user). The directory path and its content is deleted at the end of program execution using a Stdlib.at_exit handler.

val with_tmp : 
  ?mode:int ->
  ?dir:Fpath.t ->
  tmp_name_pat ->
  (Fpath.t -> 'a -> 'b) ->
  'a ->
  ('b, 'e) result

with_tmp mode dir pat f v is a new empty directory in dir (defaults to Dir.default_tmp) named according to pat and created with permissions mode (defaults to 0o700 only readable and writable by the user). Returns the value of f tmpdir v with tmpdir the directory path. After the function returns the directory path tmpdir and its content is deleted.

Default temporary directory

val default_tmp : unit -> Fpath.t

default_tmp () is the directory used as a default value for creating temporary files and directories. If set_default_tmp hasn't been called this is:

On POSIX, the value of the TMPDIR environment variable or Fpath.v "/tmp" if the variable is not set or empty.
On Windows, the value of the TEMP environment variable or Fpath.cur_dir if it is not set or empty

val set_default_tmp : Fpath.t -> unit

set_default_tmp p sets the value returned by default_tmp to p.

package bos

Existence, creation, deletion and contents

User and current working directory

Temporary directories

Default temporary directory