Module `Diskuvbox`

type box_error = string -> string

The type for managing errors during box operations.

During a box operation, any error messages are given to this function. This function can log the error, modify the error message, or raise the error immediately.

type walk_path =

| Root

| File of Fpath.t

| Directory of Fpath.t

The type of path seen during a walk_down operation

type path_attribute =

| First_in_directory

| Last_in_directory

Attributes of the path

module Path_attributes : Stdlib.Set.S with type elt = path_attribute

val walk_down : 
  ?err:box_error ->
  ?max_depth:int ->
  from_path:Fpath.t ->
  f:
    ( depth:int ->
      path_attributes:Path_attributes.t ->
      walk_path ->
      ( unit, string ) Stdlib.result ) ->
  unit ->
  ( unit, string ) Stdlib.result

walk_down ?err ?max_depth ~from_path ~f () visits the file from_path or walks down a directory tree file_path, executing f ~depth ~path_attributes path on every file and directory.

Symlinks are followed.

When from_path is a file, f will be called on from_path and that is the completion of the walk_down procedure.

When from_path is a directory, the traversal is pre-order, meaning that f is called on a directory "A" before f is called on any children of directory "A". All children in a directory are traversed in lexographical order.

The path in f ~depth ~path_attributes path will be Root if the current file or directory is from_path; otherwise the path = File relpath or path = Directory relpath has a relpath which is a relative path from from_path to the current file or directory.

The depth in f ~depth ~path_attributes path will be an integer from 0 to max_depth, inclusive.

At most max_depth descendants of from_path will be walked. When max_depth is 0 no descent into a directory is ever conducted. The default max_depth is 0.

Any error is passed to err if it is specified. The default err is the identity function Fun.id.

val find_up : 
  ?err:box_error ->
  ?max_ascent:int ->
  from_dir:Fpath.t ->
  basenames:Fpath.t list ->
  unit ->
  ( Fpath.t option, string ) Stdlib.result

find_up ?err ?max_ascent ~from_dir ~basenames () searches the directory from_dir for any file with a name in the list basenames. If not found, the parent directory of from_dir is searched for the file named in basenames.

At most max_ascent ancestors of from_dir will be searched until the file is found. The default max_ascent is 20. If the file is still not found, the function returns Ok None.

An error is reported if from_dir is not an existing directory.

An error is reported if any of the basenames names are not true basenames (there should be no directory components like "." or ".." or "/").

Any error is passed to err if it is specified. The default err is the identity function Fun.id.

val touch_file : 
  ?err:box_error ->
  file:Fpath.t ->
  unit ->
  ( unit, string ) Stdlib.result

touch_file ?err ~file () creates the file file if it does not exist, creating file's parent directories as necessary. If the file already exists its access and modification times are updated.

Any error is passed to err if it is specified. The default err is the identity function Fun.id.

val copy_file : 
  ?err:box_error ->
  ?bufsize:int ->
  ?mode:int ->
  ?basename_rewriter:( string -> string ) ->
  src:Fpath.t ->
  dst:Fpath.t ->
  unit ->
  ( unit, string ) Stdlib.result

copy_file ?err ?bufsize ?mode ~src ~dst () copies the file src to the file dst, possibly rewriting the destination filenames with basename_rewriter, creating dst's parent directories as necessary.

Copying the file is done through a memory buffer of size bufsize. The default buffer size is large and may vary version to version. We recommend setting the buffer size explicitly.

If mode is specified, the chmod mode will be applied to dst. Otherwise the chmod mode is copied from src.

The basename_rewriter operates on the basename of the source file. For example, if a source file was "dir1/file1" and let base_rewriter s = "rewritten-" ^ s then the destination file will be named "rewritten-file1" in the destination directory tree. Embedded subdirectories like let base_rewriter s = "new/" ^ s are accepted as well.

Any error is passed to err if it is specified. The default err is the identity function Fun.id.

val copy_dir : 
  ?err:box_error ->
  ?bufsize:int ->
  ?basename_rewriter:( string -> string ) ->
  src:Fpath.t ->
  dst:Fpath.t ->
  unit ->
  ( unit, string ) Stdlib.result

copy_dir ?err ?bufsize ~src ~dst () copies the contents of src into dst, possibly rewriting the filenames with basename_rewriter, creating dst and any parent directories as necessary.

Copying the files is done through a memory buffer of size bufsize. The default buffer size is large and may vary version to version. We recommend setting the buffer size explicitly.

The basename_rewriter operates on the basename of the source file. For example, if a source file was "dir1/file1" and let base_rewriter s = "rewritten-" ^ s then the destination file will be named "rewritten-file1" in the destination directory tree. Embedded subdirectories like let base_rewriter s = "new/" ^ s are accepted as well.

Any error is passed to err if it is specified. The default err is the identity function Fun.id.