Module Bos.OS.Path

module Path: sig .. end
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 Bos.OS.File and Bos.OS.Dir modules.



Existence, move, deletion, information and mode


val exists : Fpath.t -> (bool, [> Rresult.R.msg ]) Bos.OS.result
exists p is true if p exists for the file system and false otherwise.
val must_exist : Fpath.t -> (Fpath.t, [> Rresult.R.msg ]) Bos.OS.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, [> Rresult.R.msg ]) Bos.OS.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, [> Rresult.R.msg ]) Bos.OS.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, [> Rresult.R.msg ]) Bos.OS.result
stat p is p's file information.
module Mode: sig .. end
Path permission modes.

Path links


val link : ?force:bool ->
target:Fpath.t -> Fpath.t -> (unit, [> Rresult.R.msg ]) Bos.OS.result
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.
val symlink : ?force:bool ->
target:Fpath.t -> Fpath.t -> (unit, [> Rresult.R.msg ]) Bos.OS.result
symlink ~force target p symbolically links target to dst. If force is true (defaults to false) and p exists, it is rmdired or unlinked before making the link.
val symlink_target : Fpath.t -> (Fpath.t, [> Rresult.R.msg ]) Bos.OS.result
slink_target p is p's target iff p is a symbolic link.
val symlink_stat : Fpath.t -> (Unix.stats, [> Rresult.R.msg ]) Bos.OS.result
symlink_stat p is the same as Bos.OS.Path.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, [> Rresult.R.msg ]) Bos.OS.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:Bos.Pat.defs ->
Fpath.t -> ((Fpath.t * Bos.Pat.defs) list, [> Rresult.R.msg ]) Bos.OS.result
query ~init pat is like Bos.OS.Path.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) Bos.OS.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
| `Dirs
| `Files
| `Sat of Fpath.t -> (bool, Rresult.R.msg) Bos.OS.result ]
The type for specifying elements being folded over.
type 'a fold_error = Fpath.t ->
('a, Rresult.R.msg) Bos.OS.result -> (unit, Rresult.R.msg) Bos.OS.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 Bos.OS.Path.traverse, determining folded Bos.OS.Path.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 Bos.OS.Path.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, [> Rresult.R.msg ]) Bos.OS.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 Bos.OS.Path.fold_error), defaults to Bos.OS.Path.log_fold_error ~level:Log.Error.