Module `Virtfs.Path`

A path Path.t is a lax representation of a file path in an abstract file system. It can be used to describe, abstractly, operations on file paths and to mock file systems.

The library does not focus on the correctness of paths, but aims to provide a simple and composable API for quickly expressing file paths in systems that abstract the execution target (e.g. in YOCaml).

Unlike Fpath, there is no distinction (in terms of representation) between directories and files.

The API is generally pure, which explains why when we talk about "changing a path", moving it, etc., we are referring to calculating a new path; no operations are performed on the disk.

Representation

type t

The type describing a file path, which can be absolute or relative.

val abs : string list -> t

abs ["foo"; "bar"] builds the path "/foo/bar".

val rel : string list -> t

rel ["foo"; "bar"] builds the path "./foo/bar".

val root : t

root is the root of the file system "/".

val cwd : t

cwd is the current working directory "./".

Manipulation of path

val dirname : t -> t

dirname p returns the parent of p. The parent of root is root and the parent of cwd is "../".

val basename : t -> string

basename p returns the basename of p. The basename of root is "/" and the basename of cwd is ".".

val basename_opt : t -> string option

basename_opt p returns the basename of p. The basename of root and cwd is None.

Path relocation

Set of functions that enable the description of path movements.

val append : t -> string list -> t

append p xs append xs at the end of the given path p.

val move : into:t -> t -> t

move ~into source calculate the path corresponding to the movement from path source to path into.

val relocate : 
  ?strategy:[ `Merge | `Force ] ->
  ?ignore_kind:bool ->
  into:t ->
  t ->
  t

relocate ?strategy ?ignore_kind ~into source is like move, but relocates the full source path instead of only its basename.

With `Merge (default), overlapping suffixes are merged:

  # open Virtfs.Path ;;

  # (rel [ "bar"; "index.md" ])
    |> relocate ~into:(rel [ "foo"; "bar"; "baz" ])
    |> to_string ;;
  - : string = "./foo/bar/index.md"

With `Force, source is appended as-is into into.

If into and source have different kinds (Relative vs Absolute), `Force is applied unless ignore_kind is true.

val concat : into:t -> t -> t

concat is relocate with force strategy.

val graft : ?ignore_kind:bool -> into:t -> t -> t

graft is relocate with merge strategy.

val rename : 
  ?preserve_extension:[ `Compound | `Ext ] ->
  new_name:string ->
  t ->
  t

rename ?preserve_extension ~new_name p calculate a new name for the given path p. The flag preserve_extension describes a strategy for preserving the extension of the source p. If it is not passed, the extension is ignored.

`Ext preserves the extension of the source (see extension)

`Compound preserves the extension of the source (see compound_extension)

val trim : ?ignore_kind:bool -> prefix:t -> t -> t

trim ?ignore_kind ~prefix p will remove the given prefix from the given path p. If the paths have different kinds (absolute vs relative), their prefixes are incompatible, unless the ignore_kind flag is set to true (and use the p kind as a main kind).

val resolve : from:t -> t -> t

resolve ~from p will resolve p from from's perspective. If p is absolute, it return p.

val scope : from:t -> t -> t

scope ~from p will share the scope of from and p. It is resolve ~from:(dirname from).

Extension

Dealing with file extensions. Since the library does not assume whether a file is a file or a directory, the functions generally work.

An extension (returned) is always prefixed with a ".".

val extension : t -> string

extension p returns the extension for the given path p. If the path has no extension, it returns an empty string.

val extension_opt : t -> string option

extension_opt p is like extension but wrap the result into an option. So if a path has no extension, it returns None.

val compound_extension : t -> string list

compound_extension p returns the list of compound extension for the given path p.

val has_extension : string -> t -> bool

has_extension ext p returns true if the path p has the extension ext. (It works on compound extension)

val has_any_extension : string list -> t -> bool

has_any_extension exts p returns true if the path p has one of the extensions in exts. (It works on compound extension)

val remove_extension : ?kind:[ `Compound | `Ext of string ] -> t -> t

remove_extension ?kind p remove the extension of the given p. The kind can change the extension removal strategy:

`Compound Removes the compound extension.
`Ext str Remove the given extension.

val add_extension : string -> t -> t

add_extension ext p add the ext to the given path p.

val replace_extension : 
  ?kind:[ `Compound | `Ext of string ] ->
  string ->
  t ->
  t

replace_extension ?kind ext p replace the extension of p by ext (the previous extension is removed using remove_extension) using the given kind).

val change_extension : ?kind:[ `Compound | `Ext of string ] -> string -> t -> t

change_extension is replace_extension.

Predicates

Predicates on file paths.

val is_absolute : t -> bool

is_absolute p returns true if p is defined as an absolute path, false otherwise.

val is_relative : t -> bool

is_relative p returns true if p is defined as a relative path, false otherwise.

val is_root : t -> bool

is_root p returns true if the path p seems to point "/".

val is_cwd : t -> bool

is_cwd p returns true if the path p seems to point "./".

Comparison

val equal : t -> t -> bool

equal p1 p2 returns true if p1 = p2, false otherwise.

val compare : t -> t -> int

compare p1 p2 returns 0 if p1 is equal to p2, a negative integer if p1 is less than p2, and a positive integer if p1 is greater than p2. It is always assumed that a relative path is shorter than an absolute path then the lexicographical order is chosen.

Conversion

val to_filename : t -> string

to_filename p returns the filename representation of the path p using Filename constants.

val to_string : t -> string

to_string p returns the representation of the path p.

val from_string : string -> t

from_string s returns a path from the given string s.

val of_string : string -> t

of_string is from_string - consistent with the OCaml ecosystem.

val fragments : t -> string list

fragments p returns the list of segments/fragments for a given path p.

val to_list : t -> string list

to_list p is fragments

Infix Operators

A set of infix operators.

module Infix : sig ... end

val (++) : t -> string list -> t

p ++ xs is an infix version of append.

val (/) : t -> string -> t

p / s adds s at the end of p.

val (~/) : string list -> t

~/["foo"; "bar"] is rel ["foo"; "bar"]. See rel.

val (^/) : string list -> t

^/["foo"; "bar"] is abs ["foo"; "bar"]. See abs.

Set

module Set : Set.S with type elt = t

Map

module Map : Map.S with type key = t

package virtfs

Module Virtfs.Path