Module OS.Path

Path operations.

These functions operate on files and directories equally. Similar and specific functions operating only on one kind of path can be found in the File and Dir modules.

Existence, move, deletion, information and mode

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

exists p is true if p exists for the file system and false otherwise.

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

must_exist p is Ok p if p exists for the file system and an error otherwise.

val move : ?force:bool -> Fpath.t -> Fpath.t -> (unit, 'e) result

move ~force src dst moves path src to dst. If force is true (defaults to false) the operation doesn't error if dst exists and can be replaced by src.

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

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

val stat : Fpath.t -> (Unix.stats, 'e) result

stat p is p's file information.

module Mode : sig ... end

Path permission modes.

link ~force target p hard links target to p. If force is true (defaults to false) and p exists, it is is rmdired or unlinked before making the link.

symlink ~force target p symbolically links target to p. If force is true (defaults to false) and p exists, it is rmdired or unlinked before making the link.

slink_target p is p's target iff p is a symbolic link.

symlink_stat p is the same as stat but if p is a link returns information about the link itself.

Matching path patterns against the file system

A path pattern pat is a path whose segments are made of named string patterns. Each variable of the pattern greedily matches a segment or sub-segment. For example the path pattern:

Fpath.(v "data" / "$(dir)" / "$(file).txt")

matches any existing path of the file system that matches the regexp data/.*/.*\.txt.

Warning. When segments with pattern variables are matched against the file system they never match "." and "..". For example the pattern "$(file).$(ext)" does not match ".".

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

matches ~dotfiles pat is the list of paths in the file system that match the path pattern pat. If dotfiles is false (default) segments that start with a pattern variable do not match dotfiles.

val query : ?dotfiles:bool -> ?init:Pat.defs -> Fpath.t -> ((Fpath.t * Pat.defs) list, 'e) result

query ~init pat is like matches except each matching path is returned with an environment mapping pattern variables to their matched part in the path. For each path the mappings are added to init (defaults to String.Map.empty).

Folding over file system hierarchies

type traverse = [
| `Any
| `None
| `Sat of Fpath.t -> (bool, Rresult.R.msg) result
]

The type for controlling directory traversals. The predicate of `Sat should only be called with directory paths, however this may not be the case due to OS races.

type elements = [
| `Any
| `Files
| `Dirs
| `Sat of Fpath.t -> (bool, Rresult.R.msg) result
]

The type for specifying elements being folded over.

type 'a fold_error = Fpath.t -> ('a, Rresult.R.msg) result -> (unit, Rresult.R.msg) result

The type for managing fold errors.

During the fold, errors may be generated at different points of the process. For example, determining traversal with traverse, determining folded elements or trying to readdir(3) a directory without having permissions.

These errors are given to a function of this type. If the function returns Error _ the fold stops and returns that error. If the function returns `Ok () the path is ignored for the operation and the fold continues.

val log_fold_error : level:Logs.level -> 'a fold_error

log_fold_error level is a fold_error function that logs error with level level and always returns `Ok ().

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

fold err dotfiles elements traverse f acc paths folds over the list of paths paths traversing directories according to traverse (defaults to `Any) and selecting elements to fold over according to elements (defaults to `Any).

If dotfiles if false (default) both elements and directories to traverse that start with a . except . and .. are skipped without being considered by elements or traverse's values.

err manages fold errors (see fold_error), defaults to log_fold_error ~level:Log.Error.